Phase 0 / Asset Pipeline / Asset pipeline v0 (formats, codecs, cooker, async loader)

[guysenpai]

Brief

briefs/m0.6-assets.md (M0.6 — Asset pipeline v0). Status: CLOSED (2026-06-04).

Summary

Phase 0 asset pipeline v0: frozen on-disk formats + handle/registry, native DEFLATE+PNG/glTF/WAV codecs, importers/cookers, BLAKE3-keyed local cache, and an async runtime loader. Delivered across one branch / one PR with five review gates (E1–E5) plus an E4 uuid complement and E1/E2/E4 cleanups.

Stages

• E1 — intermediate <type>.asset.etch schema, runtime .<type>.bin 40-byte header (comptime offset guards, explicit LE), AssetHandle, Registry (refcount + generation).
• E2 — RFC 1951 inflate + zlib + ADLER32; foundation/simd/ skeleton + adler32 kernel.
• E3 — PNG decode (5 filters incl. paeth_filter_decode kernel, depths 1/2/4/8, palette+tRNS, Adam7) → RGBA8; glTF static via std.json; WAV RIFF PCM.
• E4 — importers + cookers + local cache; uuid complement (UUIDv7 + cook_settings + mandatory extracted.blob).
• E5 — async loader over std.Io (io.concurrent, never blocks the main thread) + lifecycle (load/retain/release/forced-unload/reload); plus the E1/E2/E4 cleanups (inflate over-total guard + 3 negative tests, adler32/hash comment fixes).

Recorded deviations (all in the brief)

• .bin header 32 → 40 bytes (calibration error; _reserved u32 @28, @sizeOf == 40).
• cache gate → robust differential (cached == cooked + miss ≫ hit); absolutes logged, not asserted.
• async loader uses std.Io, not the Chase-Lev job system (avoids widening its ECS-shaped surface — the brief's own Case 2 gate).
• intermediate read/written by an ad-hoc Etch-subset reader/writer (no weld_etch).

Acceptance / CI

• zig build clean · zig build test green (Debug + ReleaseSafe) · zig fmt --check · zig build lint
• All acceptance tests: png/gltf/wav round-trips, deflate vectors (+3 negative guards), adler32/paeth, handle_generation, cache_diff, loader_async (5 s watchdog). Suite: 426/443 (17 skips = pre-existing platform-gated render/Vulkan, none from M0.6).
• Observable behavior: zig build cook-demo produces 3 .bin; re-run = cache HIT, uuids preserved.
• commit-msg hook green on every commit; language closure (no French).

Documentation files modified

• briefs/m0.6-assets.md only. README.md and CLAUDE.md were NOT modified (the §3.4 CLAUDE.md update is left to the merge/tag step, at Guy's discretion).

Files beyond the brief's "Files to create or modify" (all justified, journaled)

• src/foundation/root.zig (foundation module root, needed for @import("foundation")).
• src/modules/asset_pipeline/{hash.zig, uuid.zig} (shared BLAKE3 util; UUIDv7 — the E4 Claude.ai complement).
• src/modules/asset_pipeline/importers/{common.zig, root.zig}, cookers/common.zig, codecs/root.zig (shared helpers + namespace roots within listed dirs).
• tools/asset_cook/main.zig (the thin offline cook entry the brief's Observable behavior + Out-of-scope call for).

🤖 Generated with Claude Code