[B6] test(persistence): commit golden save-fixtures per format version, regression-test loads

[MichaelFisher1997]

Part of #834 (Production-Readiness Audit) — Batch B6 (engine-specific guardrails, parallel-safe).
Replaces audit item #26 (P3). Parallel with: audit-b6 sibling — this issue owns new golden save-fixtures + a load test in world-persistence.

Problem

modules/world-persistence has no "load a v0.1 save" golden fixture. A schema change can silently brick every existing world.

Acceptance criteria

• A small golden save file per supported format version committed under modules/world-persistence/test-fixtures/ (or similar).
• A regression test loads each golden fixture and asserts it deserializes correctly into the current data model.
• When a schema change intentionally breaks compatibility, the test is updated with a migration path + a new fixture (not just deleted).
• The test runs in the standard zig build test suite.
• Documentation note in modules/world-persistence/ on the fixture-update protocol.

Files in scope

• modules/world-persistence/test-fixtures/ (new — golden saves)
• modules/world-persistence/src/*.zig (new test block, no behavior change to production code)

Dependencies

• After: B3 (test matrix) is trustworthy.

Out of scope

• Save-file migration framework itself (only the compatibility test).
• Cross-engine save imports.

Branch / PR

• Branch: test/persistence-golden-fixtures · Targets: dev

[github-actions]

Audit-b6 / #882 — scope validation + implementation pointers

Treated as a trusted [audit-b6] finding. No duplicates in flight; sibling #881 (fuzz harnesses) is complementary, not overlapping. The scope is correctly bounded to world-persistence and only the compatibility test, not the migration framework.

Validation against current world-persistence state

• chunk_serializer.CHUNK_DATA_VERSION = 2 (modules/world-persistence/src/chunk_serializer.zig:43). Only one format version exists today — v0.1 is referenced in the issue title but no historical v0.1 implementation is present. The AC "golden save per supported format version" is currently satisfiable with a single v2 fixture plus the protocol for future versions.
• chunk_serializer.deserializeChunk returns UnsupportedVersion for any version ≠ 2 (chunk_serializer.zig). A v0.1 fixture will not load against current code unless either (a) a shim path is added or (b) the issue's "v0.1" wording is read as "the first/current versioned save the game ever shipped," i.e. v2. Recommendation: clarify in the AC whether a v1/v0 fixture is required or just a single canonical v2 fixture is acceptable for this PR.
• Tests are already wired into zig build test via src/tests.zig:89-92. New test "..." blocks inside modules/world-persistence/src/*.zig will be picked up automatically — no build.zig changes needed for the AC feat: worm cave system with connected underground networks #4 requirement.
• region_file.zig uses zlib-compressed MCA-style sectors. Golden fixtures are most useful as chunk-serialized payloads (chunk_serializer.serializeChunk output) embedded via @embedFile, with an optional full-region fixture layered on top.
• AC feat: voxel engine with worldgen, async streaming, and render stability #3 ("when a schema change intentionally breaks compatibility, the test is updated with a migration path + a new fixture") presupposes a migration framework that is explicitly out of scope. Recommend documenting this as: "On a breaking schema change, the old fixture stays as a known-bad-input test and a new fixture + migration shim are added." The old fixture becomes a negative-test for the version-rejection path.

Suggested implementation shape (smallest reviewable diff)

1. Create modules/world-persistence/test-fixtures/ containing:
   • chunk_v2_all_air.bin — minimal: header + 65536 zero bytes (no light/biome/heightmap flags).
   • chunk_v2_stone_with_light.bin — full header + flag combinations exercised (has_light + has_biome_data + has_heightmap).
   • level_dat_v1.json — canonical LevelData JSON.
   • README.md — fixture-update protocol (when to add a new fixture, what to assert on breaking changes, how to regenerate from serializeChunk).
2. Add one test file modules/world-persistence/src/golden_load_test.zig (or extend chunk_serializer.zig/level_data.zig test blocks) that:
   • Loads each fixture via @embedFile.
   • Calls the corresponding deserializer.
   • Asserts the deserialized struct equals a hand-constructed expected value (block types, light bytes, biome bytes, heightmap values, LevelData fields).
   • Adds a negative test asserting the v2 deserializer rejects version=1 with UnsupportedVersion (locks in the current contract).
3. Expose golden_load_test from src/tests.zig next to the existing imports (src/tests.zig:89-92) so zig build test picks it up.
4. Add a doc-comment header on each fixture file or in the test-fixtures/README.md documenting the protocol.

Suggested checklist addition to the AC

• Clarify in the issue whether "v0.1" refers to a historical format version or the current first-versioned save (v2). Only v2 currently exists.
• Negative test asserting UnsupportedVersion for non-current versions, locking in the rejection contract.

Dependencies / blockers

• B3 (test matrix trustworthy) is already a stated dependency — fine.
• No blocking work in dev for world-persistence currently; safe to pick up.
• Branch test/persistence-golden-fixtures already named in the issue; matches the feature/* / test/* convention and targets dev correctly.

No action needed from me beyond validation — this is well-scoped and ready for implementation.

[github-actions]

Comment posted on issue #882. Validation summary: scope is well-bounded, no duplicates (sibling #881 is complementary fuzz work), tests auto-wire via src/tests.zig:89-92. Flagged the v0.1/v2 ambiguity (only v2 exists today) and recommended the smallest reviewable diff shape (chunk-serialized fixtures via @embedFile + one negative UnsupportedVersion test).

opencode session  |  github run