Prototype content-addressed image storage

[chruffins]

summary

experimental stacked PR on top of #425 to try the content-addressed image layout discussed in the thread. This PR is intentionally isolated so it can be reviewed, tested, or closed without changing the main image-tag PR.

layout

Newly pulled/imported images use:

images/
├── content/
│   └── <digest>/
│       ├── metadata.json
│       └── rootfs.erofs
└── repositories/
    └── <repository>/
        └── <tag> -> ../../../content/<digest>

The implementation also supports the existing layout:

images/<repository>/<digest>/
├── metadata.json
└── rootfs.erofs

• reads resolve content-addressed data first and fall back to legacy paths
• existing legacy images are not eagerly migrated
• cross-repository tagging promotes legacy rootfs content into the shared content store using a hard link
• tag listing, deletion, disk accounting, VM disk lookup, and retention paths continue to handle legacy data
• shared content is retained while repository references still exist

cutover risk

The compatibility readers land in parent PR #425 before this child enables new writes. That makes rollback to #425 safe for existing content-layout images: it can resolve, boot, list, retag, delete, and account for both layouts, while continuing to write newly created legacy images.

The remaining risk is the layout lifecycle itself: reference deletion, shared-content garbage collection, and any code that constructs image paths directly instead of going through the storage helpers. There is no eager migration; legacy images are promoted only when cross-repository tagging needs shared content.

For now, this PR remains an experimental child of #425: close it without merging to discard the writer experiment, or continue it after the compatibility-reader layer is reviewed.

validation

• go test ./lib/images -run '^(TestWriteMetadataUsesContentWhenLegacyDirectoryIsEmpty|TestListAllMetadataContentLayout|TestTagImage|TestTagFollowsLastPull)$' -count=1
• go test ./lib/images ./lib/paths -run '^$'
• git diff --check

The full image test suite was not completed locally because the environment does not include the mkfs.erofs runtime binary required by integration tests.

---

Note

Medium Risk
Changes on-disk layout for new images and shared-content GC/ref counting; mis-precedence or deletion bugs could affect VM disk resolution, though legacy reads and parent compatibility readers mitigate rollout risk.

Overview
Enables content-addressed image storage for new writes by setting contentLayoutEnabled to true, so metadata and rootfs for new pulls land under images/content/<digest>/ with repository tags as symlinks, while existing per-repository digest trees keep working.

Fixes read-path precedence so a complete legacy image (metadata + rootfs under the repository digest dir) wins over a partial or failed content-layout record for the same digest hex—avoiding another repository’s pending/failed content metadata shadowing a ready legacy image. digestPath and metadataPath use the new legacyImageExists check before preferring content paths.

Cross-repo clone/tag behavior now routes through the content clone path whenever the layout flag is on (legacy clone only when the flag is off and the source is legacy-only).

Tests cover legacy-vs-content shadowing, metadata writes skipping empty legacy dirs, tag symlink resolution, cross-repo tagging into content store, and refcounted deletion of shared content. POST /images/{name}/tag is registered under image:write in route scopes.

^{Reviewed by Cursor Bugbot for commit a170537. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high 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 7f9c941. Configure here.}