Shared-layer lifecycle: accounting, eviction, recovery, materialization

[chruffins]

summary

Adds the runtime consumer for shared image layers while preserving Hypeman's two-disk VM contract.

• Shared base disks: images with multiple layers compose every layer except the final layer into a content-addressed read-only base disk under images/bases/.
• Per-instance final layer: the final layer is materialized into the VM's writable overlay disk under upper/. The VM still receives one read-only rootfs disk and one writable overlay.
• Build fallback: unsupported hosts, single-layer images, corrupt artifacts, and failed materialization use the existing flattened rootfs path.
• Artifact lifecycle: final-layer artifacts and shared bases use in-flight leases, keyed singleflight, grace-period cleanup, reference scanning, startup recovery, and disk accounting.
• Overlay capacity: image data is added to the physical overlay allocation while the caller-facing writable capacity remains unchanged. Admission reservations use the physical size.
• Promotion and recovery: layered rootfs links are recreated relative to their destination during legacy-to-content promotion, and runtime manifest lookup follows the authoritative image layout.
• Observability: image build phases distinguish shared-base export from flattened filesystem export.
• CI reliability: EROFS artifacts are extracted with fsck.erofs instead of loop-mounted, layered overlay roots retain searchable 0755 permissions, and interrupted netlink dumps retry under parallel test load.

validation

• Full CI is green: Linux tests, Darwin tests, and install E2E pass.
• Targeted Linux end-to-end validation confirms nginx content is reachable through the layered rootfs and ingress path.
• Image package tests pass on a root-capable Linux host with EROFS support.
• Rootless local package tests cover manifest validation, shared-base hashing, lifecycle accounting, and legacy promotion; native mount tests require host privileges.
• Storage and disk-I/O benchmarks show the composition prerequisite does not increase the flattened path's disk footprint or I/O. Representative shared-base runtime benchmarks remain required before production rollout.

rollout

Do not enable this path in production until storage and disk-I/O benchmarks are run against representative multi-layer images. The flattened path remains the fallback for hosts without native layer-artifact support.

• Host-storage alert fix: runtime overlay preparation no longer creates transient read-only loop mounts for EROFS layer artifacts, avoiding false full-filesystem alerts on the host.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

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

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

[cursor]

Eviction can wipe in-flight layers

Medium Severity

Layer eviction decides freshness from the digest directory ModTime, and it runs concurrently with materialization. Unpack and mkfs.erofs write inside child temp dirs, so the parent mtime goes stale; DeleteImage can then RemoveAll that tree while a build is still using it, especially during the later unlocked ExportRootfs window before the manifest is written.

Additional Locations (2)

• lib/images/manager.go#L534-L569
• lib/images/manager.go#L865-L867

 

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

[cursor]

Layer bytes skipped after failed builds

Medium Severity

Materialized layer artifacts are written to the layer store before conversion, but refreshDiskUsageTotals only runs on successful finalize, delete, or startup. After a failed conversion the artifacts remain on disk while TotalImageBytes keeps the stale cached total, so capacity admission undercounts the real footprint.

Additional Locations (2)

• lib/images/manager.go#L900-L907
• lib/images/disk_usage.go#L110-L153

 

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