macOS guests 2/6: OCI machine-image integration

[chruffins]

Summary

PR 2 of 6: OCI machine-image integration for macOS guests. Base: #498.

• Materializes darwin/arm64 machine images from OCI artifacts. Pulls are repository-scoped. Tag promotion is not supported.
• Config labels are validated before any layer is unpacked, so a malformed darwin artifact fails before disk work.
• Explicit platform requests are checked against both cached and freshly pulled images. A whitespace-only platform means "no explicit platform."
• Machine files are staged in a private 0700 directory, with 0600 files, before they appear at the canonical path. Finalization rollback keeps manifests whose files were not installed.
• The disk size field is boot disk plus aux. The aux file is about 33.6 MB against a 64 GB disk, so the boot-disk reservation is overstated by that amount. Recorded as a known follow-up.

Validation

• A real OCI pull of a 64 GiB raw machine image (26.22 GiB compressed) with exact hash, cache, and platform checks.
• A streaming upload of a 28.15 GB layer to the production registry, verified by an independent rehash and manifest-last commit. Large-layer PATCH uploads are not proven.
• Cold boot of a pulled image through the normal API, in the PR 1 QA runs.
• Unit tests: manifest and bundle validation, platform matching, staging, rollback.

Limitations

• Fixture disks in tests are not bootable images. Boot evidence comes from the live runs above.
• The registry client's default PATCH upload buffers large layers. Not fixed here.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fdc003f. Configure here.}

[cursor]

Empty platform fails cache reuse

Medium Severity

The new cached-reuse check calls ParsePlatform on stored cached.Platform and treats any parse error as a mismatch. Ready images from before platform tracking store an empty platform and are otherwise treated as the host. An explicit platform on CreateImage or instance create now fails reuse of those images with ErrInvalidPlatform instead of matching them as host-native.

 

^{Reviewed by Cursor Bugbot for commit fdc003f. Configure here.}

[chruffins]

QA update on reviewed head 66b5a59: real stopped installed macOS bundle OCI pull/materialization passed (test exit 0 plus the required roundtrip.json).

• 64-GiB raw disk; compressed OCI layer ~26.22 GiB; total test ~373 seconds.
• Normal image manager pulled through a loopback registry, reached ready on darwin/arm64, and verified disk/aux SHA256, complete platform metadata, manifest digest, canonical modes, cache reuse, same-repository aliasing, cross-repository rejection and wrong-platform rejection.
• Follow-up cached artifact list/get through authenticated generated HTTP image handlers also passes with race detector; unauthenticated requests rejected.
• Allowlisted environment with empty Docker config, nice=10, GOMAXPROCS=1, GOMEMLIMIT=256MiB. Sampled job-process-group RSS peak ~62 MiB; kernel file cache is not included. Free disk remained ~523 GiB, above the 60-GiB floor.

Important scope: the registry blobs were seeded via the disk-streaming handler, so this validates large real HTTP pull/materialization, not large-layer PATCH upload. It also does not prove cold boot or live GuestService provisioning/lifecycle. No existing instance was started, stopped or reprovisioned by these tests. Keep draft pending the remaining gates.

[chruffins]

Follow-up live QA: the artifact from the earlier real HTTP materialization run now passed normal authenticated API create/cold boot on Apple silicon with the source registry offline, actual macOS27.0.1/26A434 SSH readiness, template CPU/RAM inheritance, duplicate-identity409, live API restart recovery without guest reboot, and HTTP stop/start with persistent guest marker. Full immutable materialized base disk+aux SHA256 stayed identical after testing. Original instance/API/storage untouched; isolated QA VM/API ended stopped and QA slot released. Stop used system-agent-disabled fallback, not verified root-agent graceful shutdown. Combined reviewed PR1–3 + PR4 patches tested; reviewer branches not rewritten. See runtime issue/result detail: #498 (comment). Separately, actual26.22GiB streaming monolithic POST upload to empty production-registry-handler destination plus independent blob/manifest validation passed; default PATCH is still buffered/unproven, and that destination was not freshly pulled/booted: #503 (comment).

[chruffins]

Simplification update at 4888603: OCI uses the shared bounded bundle decoder; permanent TestFinalizationRollbackPreservesUninstalledManifest fixes the reproduced regression where rollback deleted an existing manifest that had never been installed. Focused image regressions passed 3 race runs; no new real upload/pull/boot claim.

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.