Persist OCI manifest content model per image digest

[chruffins]

summary

This PR persists an OCI manifest content model for each image digest and updates local image tagging to support shared content, restart recovery, and later layer-level cleanup.

persisted manifest model

Ready images store images/content/<digest>/manifest.json containing:

• manifest digest and media type
• resolved platform (os/arch[/variant])
• config digest and ordered rootfs.diff_ids
• ordered layer descriptors (compressed digest, size, media type) paired with diff IDs

The model is extracted from the existing OCI layout cache during the pull's metadata phase, without additional registry downloads. Writes use the shared atomic JSON helper. blobReferences() exposes the config and layer digests for later cleanup.

Legacy images remain readable in their existing layout. They are promoted lazily when shared content is needed, and missing legacy models remain valid.

image tagging and recovery

• Pending tag claims are persisted and restored across restarts.
• Multiple pending tags can claim the same completed digest.
• Newer requests for a tag are not resurrected by an older build.
• Digest and tag requests retain credential-conflict checks.
• Tag and digest deletion keep metadata, symlinks, pending claims, and orphan cleanup consistent.
• Resource tags remain associated with individual references.

refactoring

The image manager and storage code now split large paths into focused helpers for:

• digest versus tag deletion
• interrupted-build recovery
• pending metadata creation
• finalization rollback and manifest persistence
• OCI runtime metadata versus manifest-model extraction
• filesystem metadata walking versus aggregation
• pending tag claim and cancellation handling

The main hotspots listAllMetadata, DeleteImage, claimRequestedTags, and cancelPendingTag are no longer high-complexity functions.

validation

• Targeted manifest-model, metadata-layout, tagging, recovery, deletion, legacy-promotion, and resource-tag tests pass.
• go test ./lib/images -run '^$' passes.
• go vet ./lib/images passes.
• git diff --check passes.
• The full image test suite remains environment-blocked where integration tests convert filesystems: mkfs.erofs is not installed. This is the same pre-existing environment limitation.

[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

[sjmiller609]

1. secondary tag stays stale

starting state

# stable currently resolves to digest A
kernel images create app:stable

# registry updates latest and stable to digest B
docker tag app@sha256:B app:latest
docker tag app@sha256:B app:stable
docker push app:latest
docker push app:stable

# start pulling B through latest
kernel images create app:latest

action

kernel images create app:stable

expected: both tags move to B.
actual: only latest moves; stable remains on A.

2. resource labels are ignored

starting state

kernel images create app:latest --tag team=platform
kernel images wait app:latest

action

kernel images create app:latest --tag team=payments

expected: app:latest reports team=payments.
actual: the reused image retains team=platform.

3. readiness returns too early

starting state

# A is ready
kernel images create app@sha256:A
kernel images tag app@sha256:A app:latest

# start B, then a newer C
kernel images create app@sha256:B --as app:latest
kernel images create app@sha256:C --as app:latest

# C subsequently fails; B remains in progress

action

kernel images wait app:latest

expected: wait for B.
actual: immediately succeeds using old ready image A.

4. eager migration potentially risky

If the migration fails for some reason, it's stuck in image not ready until content/A is manually removed.

Consider a no-op migration instead: leave existing images in the legacy layout, use the shared format only for new images, support reads from both layouts, and add lazy migration only when a future feature requires manifest.json.

[chruffins]

bugs addressed + found 1 more, re-running CI now