Persist OCI manifest content model per image digest

[chruffins]

summary

Stacked stage of the image-storage project. Persists one content model document per image digest at images/content/<digest>/manifest.json:

• manifest digest (immutable identity) and media type
• resolved platform (os/arch[/variant])
• config blob digest with its ordered rootfs.diff_ids
• ordered layer descriptors (compressed digest, size, media type) paired with diff ids by position
• a blobReferences() accessor listing config + layer digests for future GC

why

Stages 4/5 need the ordered layer list and diff ids to materialize per-layer artifacts and recompose rootfs without re-reading registries; GC needs to know which OCI cache blobs each ready image still references. Extracted from the existing OCI layout cache during the pull's metadata phase — no second blob downloader.

details

• extractManifestModel reads manifest + config from the shared layout cache (system/oci-cache), reusing already-downloaded blobs.
• Written atomically in finalizeImage beside the shared content; legacy images simply have no model (read returns nil).
• Metadata writes now share a single atomic temp-file-then-rename helper (writeJSONAtomic).

validation

• go test ./lib/images ./lib/paths -count=1 — new tests cover synthetic two-layer layouts (ordering, digest/diff-id pairing, platform), write/read roundtrip atomicity, missing-model reads, blob references, and an end-to-end import that lands a ready image with a correct model.
• Docker Hub-backed pull tests are rate-limited intermittently in this environment; they passed in the unthrottled window earlier in this work.

---

Note

Low Risk
Additive on-disk metadata on the image finalize path; no auth or API behavior changes, and missing models are handled for legacy images.

Overview
Adds a persisted OCI manifest content model at images/content/<digest>/manifest.json for each image that finishes the pull/build pipeline. The document captures manifest identity, platform, config blob digest with ordered diff_ids, and ordered layer descriptors (compressed digest, size, media type) so later work can rebuild rootfs from per-layer artifacts and GC can see which OCI cache blobs are still referenced via blobReferences().

During pull, extractManifestModel builds this structure from the shared OCI layout cache in the same metadata phase as existing inspection—no extra registry downloads. finalizeImage writes the model atomically next to shared content and overwrites platform with the resolved manifest platform. Images converted before this change simply have no file; readManifestModel returns nil without error.

Metadata JSON writes now share writeJSONAtomic (temp file + rename), including manifest persistence.

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

[github-actions]

-->

✱ stlc build

✅ go code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

116 files generated at cf7a47a (pushed)

go get github.com/kernel/hypeman-go-staging@cf7a47a8fe1d7812e008ec8d55a5496d3b4bd0e6

✅ python code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

232 files generated at 309c4c8 (pushed)

✅ typescript code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

138 files generated at fb43b25 (pushed)

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

Level	Code	Message	Targets

Build metadata

Build	bd_76FzwzCZ-flowery-drop
Timestamp	2026-08-31T22:04:44.266Z
stlc	8413509
Spec hash	1061c067fc80
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-08-31 22:05:15 UTC