feat: macOS machine-image build backend (PR5 groundwork)

[chruffins]

Stack / checkpoint

PR5 of the six-PR macOS stack. Base: #499 (feat/macos-oci-images, reviewed 66b5a59) for the complete-machine artifact contract. Concrete runtime integration additionally requires reviewed #500 and, for desktop provisioning, #501. Foundation only; keep draft. No HTTP build mode or recipe syntax is activated, and existing Linux builds/macOS-only rejection remain unchanged.

Implemented

• Internal machine build lifecycle/session/publisher contract using shared BuildPolicy and BuildProvenance.
• Require ready digest-pinned Darwin/arm64 installed base; inherit exact template resources, reject invalid/overflow/unaligned resource values, floating bases, domain-policy promises and invalid network modes/timeouts.
• Stream source into private server-owned staging with bounded compressed-input size, SHA256 verification/provenance and cancellation checks before VM start.
• Enforce provision → sanitize → graceful-stop + confirmed VMM exit → complete export validation → destroy stopped builder/remove source → publish. Forced/unconfirmed exit cannot publish; unknown VMM exit cannot delete instance storage.
• Independent bounded failure/cancellation cleanup, partial-start cleanup and explicit quarantine condition. Safe ordinary error text retains internal errors.Is/As without retaining raw guest error text in normal logs.
• Reuse/export structural complete-machine validator; reject changed identity/resources, extra export files and unknown platform credential fields; normalize private payload modes before publication.
• Server-owned publisher contract requires manifest-last streaming/verified immutable digest receipt. Ambiguous network effects are not claimed as a ready build.

Validation

Synthetic lifecycle/failure/cancellation/input/export tests pass with race detector, plus existing focused macOS OCI/platform/tag regressions. Expanded QA at f109add: source-read/partial-workspace failure, actual deadline expiry, ambiguous publication without retry, invalid/tag/mismatched receipts, empty/symlink/hardlink payloads, truncated/oversized platform metadata, invalid MAC and resource changes all pass three repeated race runs. Existing build queue/cache/storage/Dockerfile/secret-provider/registry-token tests also pass three repeated race runs; CGO-disabled machine tests and go vet -p1 ./lib/builds pass. No VM or real registry upload is exercised by this coverage. Allowlisted environment, private empty Docker config, nice=10, GOMAXPROCS=1, GOMEMLIMIT=256MiB, -p1, bounded test timeout. Fakes use tiny files; no actual VM, guest command or registry publication is performed by these tests.

Autoreview attempted on the local patch; reviewer authentication still fails 401. No independent automated review result.

Remaining before this is usable

• Concrete VZ/GuestService driver, exact identity/slot/resource admission, real graceful-stop receipt/teardown wait and quarantine recovery.
• Common build queue/API/status/log/secret integration and source archive validation; no host-shell provisioning or arbitrary host path API.
• Deliberate recipe selection (Packer versus restricted familiar provisioning), pinned toolchain-version provenance, guest/root/desktop provisioning and reusable-image credential/SSH/browser/TCC policy.
• Actual sanitation and secret redaction, quota/free-disk/cancellation enforcement, streamed large-layer upload/commit reconciliation, repeat builds and output cold boot through normal APIs.
• No macOS installation/bootstrap, memory fork, rekeying, BuildKit/Dockerfile compatibility, credential-free output or production-ready build claim from these interfaces alone.

[chruffins]

Actual full-size transport QA passed against lib/registry.New(...).Handler() with an empty filesystem-backed destination: streamed the real 28,150,700,918-byte (26.22GiB) compressed installed macOS machine layer plus config over loopback HTTP using monolithic POST /blobs/uploads/?digest=sha256:.... No disk seeding at destination. Server verified streaming digests, then the test independently rehashed persisted blobs, published the original manifest last and fetched it to verify the original manifest SHA256; tag was404 before publication.

Runner/supervisor exit0,47.96s total, sampled peak process-group RSS17.98MiB, minimum free disk491.61GiB. Bounded by1.5GiB RSS/60GiB free disk/20min deadline, nice10/GOMAXPROCS1/GOMEMLIMIT256MiB; no VM ran during upload. Sampled RSS does not include OS cache or account for physical APFS allocation.

This demonstrates a viable streamed transport for the concrete publisher, not a completed PR5 publisher/build API. Cache namespace avoided image conversion; registry auth middleware, remote credentials/redirect/retry/resume and ambiguous commit reconciliation were not exercised. Default go-containerregistry remote.Write PATCH still buffers upload data in0.20.6 even with a disk BlobPutHandler; it was not fixed or passed here. Separately, the earlier pulled artifact passed real normal-API cold boot/lifecycle/recovery; it was not freshly pulled from this upload destination, so these are not an end-to-end build→upload→pull→boot result.

[chruffins]

Simplification update at ed21906: standalone production MachineBuildRunner replaced by internal MachineBuildBackend executing machine-specific phases through ordinary CreateBuild/runBuild. Normal manager owns queue, persisted request, deadline, private source staging/hash verification, status/log completion, provenance and image-readiness gate. Machine resources inherit base; unsupported Linux builder/cache/secret options fail admission; recovered source is verified before start. Source helper is shared without adding a Linux source-size cap. Normal-manager synthetic tests prove ready/failed status, source consumption and no publication after provision failure. Build race suite passed 3 runs excluding exactly five existing Linux config-volume tests requiring unavailable mkfs.ext4; focused image/machine tests, CGO0 machine/source tests and vet pass. CGO0 VZ OCI round-trip remains unsupported. No concrete VZ/GuestService driver, streamed publisher, recipe, secret/log stream or public HTTP machine mode: still a foundation.

All PRs remain draft. This is source-level/synthetic validation, not a new live boot or production build proof. Default Codex independent review was attempted but is still blocked by authentication (HTTP401). Published atomically after checking reviewer heads with explicit per-ref force-with-lease; prior heads preserved locally.

[chruffins]

Published 951e8f68, restacked on #500 (base updated), with explicit lease against prior ed219069. Still draft.

Implemented concrete GuestService/VZ machine driver, bounded tar.gz/versioned JSON recipe admission, instance-locked strict stop/export, normal-job cancellation/quarantine, and scoped-auth streaming publisher with independent persisted blob verification and manifest-last digest verification. Darwin shutdown now schedules power-off after acceptance so vsock teardown cannot race the reply.

Native isolated QA passed: ordinary queued build → root provisioning → source sanitation → acknowledged no-force shutdown + owned VMM exit → matching export → authenticated28.85GB streaming publication → shared image-readiness gate → fresh empty destination/cache HTTP pull → cold boot → root exec marker + source-absence check. Run483.74s, sampled test-process peak36.875MiB, minimum free313.17GiB. First attempt correctly refused export/publication when shutdown acknowledgement was lost. Final cold-boot test cleanup used ordinary short-timeout forced fallback; that stop was not used for export.

Evidence limits: activation remains internal Go CreateBuild, not HTTP POST /builds/SDK. Base was a manually installed isolated development template, not an automatically provisioned or credential-sanitized production image. Identity exclusivity preserved; no rekey/fork/parallel claim. Common safe recipe logs, clean-base policy, storage quotas, native repeat/cancel/recovery and Linux runtime regressions remain gates.

Repeated focused race regressions and supported full build suite pass; exactly five existing mkfs.ext4-dependent tests excluded on Darwin. Selected CGO0 synthetic tests and vet pass. Default independent autoreview remains401 authentication-blocked, not a completed clean review. All QA VMMs stopped/storage closed; original API and identity slot preserved. See updated docs/macos-builds.md for contracts and remaining gates.

[chruffins]

Published 0983495e, explicit lease against 951e8f68, still draft/base#500.

Default-off macos_builds now wires the concrete backend into the actual server provider. Requires macos_only and an explicit host registry URL. Existing authenticated POST /builds accepts machine_base_image (installed SHA256-pinned base), source, timeout_seconds, memory_mb, cpus and tags. Source64MiB/fields64KiB/full HTTP body65MiB (before OpenAPI validation); duplicate/unknown/Linux/cache/secret fields and malformed numbers rejected. Linux source parser remains unchanged; Linux servers explicitly reject the machine selector. OpenAPI and generated Go multipart request types updated; external language SDK release pipelines were not operated.

**Real HTTP/provider QA passed:**401 missing/invalid auth,403 read-only scope,202 POST /builds, ordinary queue → real guest provisioning/sanitation → acknowledged no-force export → verified scoped streaming publication → shared readiness → Ready. POST /instances cold-booted the returned image_ref; normal authenticated exec WebSocket verified UID0, the new marker and source absence. New output cold boot used converted cache; previous native run separately proved fresh pull. Private development template remains unsuitable for external distribution without credential sanitation. All QA storage closed/API stopped/slot released; original instance preserved.

Repeated focused API/config/provider/scopes race tests, full config/provider/scopes race tests and vet pass. Default independent autoreview remains401-blocked; no clean review claim. Still gates: external SDK releases, safe recipe logs, clean-base policy, storage quotas, native cancellation/recovery/repeat and Linux runtime validation. Updated docs/macos-builds.md includes opt-in configuration and curl example.

[github-actions]

-->

✱ stlc build

✅ go code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

116 files generated at 478fdf4 (pushed)

go get github.com/kernel/hypeman-go-staging@478fdf41042762c2490077cb93b5e58c318bea3e

✅ python code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

232 files generated at f4a98c1 (pushed)

✅ typescript code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

138 files generated at fdde767 (pushed)

Diagnostics: ❗ 0 new / 1 total error, 💡 0 new / 5 total note

Level	Code	Message	Targets

Build metadata

Build	bd_76WgXwsx-short-gold
Timestamp	2026-10-11T04:46:29.360Z
stlc	8413509
Spec hash	87e5b504aef0
Config hash	659c3687c3f0

---

This comment is auto-generated by stlc and is kept up to date as you push.
If you push new commits, re-run this workflow to update this comment.
Last updated: 2026-10-11 04:46:59 UTC