Materialize per-layer artifacts with explicit whiteout handling

lib/images/README.md

@@ -65,6 +65,10 @@ Content-addressable storage with tag symlinks (similar to Docker/Unikraft):
         rootfs.erofs
       latest -> abc123def456...   # Tag symlink to digest
       3.18 -> def456abc123...     # Another tag
+    layers/                       # Shared materialized layer artifacts
+      abc123def456.../
+        layer.erofs
+        artifact.erofs.json
   system/
     oci-cache/              # Shared OCI layout for all images
       index.json            # Manifest index with digest-based tags
@@ -82,6 +86,7 @@ Content-addressable storage with tag symlinks (similar to Docker/Unikraft):
 - Natural hierarchy: All versions of an image grouped under repository
 - Easy inspection: Clear which digest belongs to which image
 - Layer caching: All images share the same blob storage, layers deduplicated automatically
+- Materialized layer artifacts are reference-protected and reconciled by the layer lifecycle manager; stale temporary trees are age-gated before removal.
 
 **Design:**
 - Images stored by manifest digest (content hash)
@@ -92,6 +97,8 @@ Content-addressable storage with tag symlinks (similar to Docker/Unikraft):
 - Shared blob storage enables automatic layer deduplication across all images
 - Orphaned digests are automatically deleted when the last tag referencing them is removed
 - Symlinks only created after successful build (status: ready)
+- One Hypeman process owns a data directory at a time; the image manager holds `images/.lock` for its lifetime and rejects a second owner.
+- Disk accounting uses logical file sizes, matching image metadata and storage admission rather than filesystem block allocation.
 
 ## Reference Handling (reference.go)
 

lib/images/disk.go

@@ -1,6 +1,7 @@
 package images
 
 import (
+	"context"
 	"fmt"
 	"os"
 	"os/exec"
@@ -29,23 +30,28 @@ var DefaultImageFormat = func() ExportFormat {
 	return FormatErofs
 }()
 
-// ExportRootfs exports rootfs directory in specified format (public for system manager)
+// ExportRootfs exports rootfs directory in specified format (public for system manager).
 func ExportRootfs(rootfsDir, outputPath string, format ExportFormat) (int64, error) {
+	return ExportRootfsWithContext(context.Background(), rootfsDir, outputPath, format)
+}
+
+// ExportRootfsWithContext exports rootfs directory and cancels external formatters with ctx.
+func ExportRootfsWithContext(ctx context.Context, rootfsDir, outputPath string, format ExportFormat) (int64, error) {
 	switch format {
 	case FormatExt4:
-		return convertToExt4(rootfsDir, outputPath)
+		return convertToExt4(ctx, rootfsDir, outputPath)
 	case FormatErofs:
-		return convertToErofs(rootfsDir, outputPath)
+		return convertToErofs(ctx, rootfsDir, outputPath)
 	case FormatCpio:
-		return convertToCpio(rootfsDir, outputPath)
+		return convertToCpio(ctx, rootfsDir, outputPath)
 	default:
 		return 0, fmt.Errorf("unsupported export format: %s", format)
 	}
 }
 
 // convertToCpio packages directory as uncompressed cpio archive (initramfs format)
 // Uses uncompressed format for faster boot (kernel loads directly without decompression)
-func convertToCpio(rootfsDir, outputPath string) (int64, error) {
+func convertToCpio(ctx context.Context, rootfsDir, outputPath string) (int64, error) {
 	// Ensure parent directory exists
 	if err := os.MkdirAll(filepath.Dir(outputPath), 0755); err != nil {
 		return 0, fmt.Errorf("create output dir: %w", err)
@@ -66,6 +72,9 @@ func convertToCpio(rootfsDir, outputPath string) (int64, error) {
 
 	// Walk the rootfs directory and add all files
 	err = filepath.Walk(rootfsDir, func(path string, info os.FileInfo, err error) error {
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return ctxErr
+		}
 		if err != nil {
 			return err
 		}
@@ -128,9 +137,9 @@ func alignToSector(size int64) int64 {
 }
 
 // convertToExt4 converts a rootfs directory to an ext4 disk image using mkfs.ext4
-func convertToExt4(rootfsDir, diskPath string) (int64, error) {
+func convertToExt4(ctx context.Context, rootfsDir, diskPath string) (int64, error) {
 	// Calculate size of rootfs directory
-	sizeBytes, err := dirSize(rootfsDir)
+	sizeBytes, err := dirSizeWithContext(ctx, rootfsDir)
 	if err != nil {
 		return 0, fmt.Errorf("calculate dir size: %w", err)
 	}
@@ -168,7 +177,7 @@ func convertToExt4(rootfsDir, diskPath string) (int64, error) {
 	// -O ^has_journal: Disable journal (not needed for read-only VM mounts)
 	// -d: Copy directory contents into filesystem
 	// -F: Force creation (file not block device)
-	cmd := exec.Command(mkfsExt4Binary(), "-b", "4096", "-O", "^has_journal", "-d", rootfsDir, "-F", diskPath)
+	cmd := exec.CommandContext(ctx, mkfsExt4Binary(), "-b", "4096", "-O", "^has_journal", "-d", rootfsDir, "-F", diskPath)
 	output, err := cmd.CombinedOutput()
 	if err != nil {
 		return 0, fmt.Errorf("mkfs.ext4 failed: %w, output: %s", err, output)
@@ -193,7 +202,7 @@ func convertToExt4(rootfsDir, diskPath string) (int64, error) {
 }
 
 // convertToErofs converts a rootfs directory to an erofs disk image using mkfs.erofs
-func convertToErofs(rootfsDir, diskPath string) (int64, error) {
+func convertToErofs(ctx context.Context, rootfsDir, diskPath string) (int64, error) {
 	// Ensure parent directory exists
 	if err := os.MkdirAll(filepath.Dir(diskPath), 0755); err != nil {
 		return 0, fmt.Errorf("create disk parent dir: %w", err)
@@ -202,7 +211,7 @@ func convertToErofs(rootfsDir, diskPath string) (int64, error) {
 	// Create erofs image with LZ4 fast compression
 	// -zlz4: LZ4 fast compression (~20-25% space savings, faster builds)
 	// erofs doesn't need pre-allocation, creates file directly
-	cmd := exec.Command("mkfs.erofs", "-zlz4", diskPath, rootfsDir)
+	cmd := exec.CommandContext(ctx, "mkfs.erofs", "-zlz4", diskPath, rootfsDir)
 	output, err := cmd.CombinedOutput()
 	if err != nil {
 		return 0, fmt.Errorf("mkfs.erofs failed: %w, output: %s", err, output)
@@ -226,13 +235,20 @@ func convertToErofs(rootfsDir, diskPath string) (int64, error) {
 	return stat.Size(), nil
 }
 
-// dirSize calculates the total size of a directory
+// dirSize is used by layer-store reconciliation.
 func dirSize(path string) (int64, error) {
+	return dirSizeWithContext(context.Background(), path)
+}
+
+func dirSizeWithContext(ctx context.Context, path string) (int64, error) {
 	var size int64
 	err := filepath.Walk(path, func(_ string, info os.FileInfo, err error) error {
 		if err != nil {
 			return err
 		}
+		if err := ctx.Err(); err != nil {
+			return err
+		}
 		if !info.IsDir() {
 			size += info.Size()
 		}