Phase 1 / Scene / Prefabs, entity cross-references & extensions

[guysenpai]

Milestone brief: briefs/M1.0.6-prefabs-crossrefs-extensions.md

Third and final sub-milestone of the scene track (M1.0.4–6): prefab flattening, entity→entity cross-references, and extension activation. One branch, one tag (v0.10.6-prefabs-crossrefs-extensions).

Scope delivered (E1–E6)

• E2 — .prefab.bin cook: standalone + of variants (field-merge over the base's flattened components, read back through the accessor). tools/scene_cook drives .prefab.etch → .prefab.bin (--prefab-dir resolver).
• E3 — instance of flattening at scene cook: both override forms (Comp { field: v } field-merge + Comp.field = v per-field); an override-free instance is byte-identical to the hand-authored equivalent. Mono-entity prefabs (MultiEntityInstanceUnsupported).
• E4 — entity→entity cross-references via new FieldKind.entity_ (8 B EntityId, component-only, default dead = 0xFF). By name (like parent:), two-phase cook (forward refs), resolved at load (resolveCrossRefs, bounds-checked → MalformedScene). Absent target → UnresolvedCrossRef at cook.
• E5 — extensions binary + cook: extensions: grammar clause (entity + instance, by name) + the extensions_offset region (Entity Extensions Table + dedup Prefab ID Table + hooks sub-section, SHAPE A); extends cook (components + requires validated against X + on_attach/on_detach rendered as text). format_version 1 → 2 (region restructured; v1 → BadVersion, re-cook).
• E6 — extension activation infra at load: applyExtensions (resolve by name → addComponentDynamic, conflict → ExtensionComponentConflict) + the Tier-0 on_attach dispatch seam (World.registerOnAttach/dispatchOnAttach; the loader never calls the VM).

Re-scoped out (→ M1.0.9)

• on_attach/on_detach hook EXECUTION — the interpreter is compile-once from the AST with no runtime text-execution surface, and the text-vs-bytecode storage choice is unsettled. E6 fires the seam; the cooked hook text is the metadata M1.0.9 consumes. The E6 test asserts the boundary (Health.max stays 100).
• §30.5 additive-conflict compile-time warning — the cook has no non-fatal warning channel; open decision (E6-vs-M1.0.9). The dangerous runtime case is caught (ExtensionComponentConflict at load).

Closing notes

What worked: E1 seam-reconfirmation caught the extensions: parse-gap + grounded D-B before coding; the M1.0.4/5 codec was reusable verbatim (.prefab.bin = .scene.bin); the cross-ref side-table mirrored the resource-string pass; the gate-split surfaced both frozen-format decisions to review instead of improvising.

What deviated: extensions: clause added (grammar amendment, option a); hooks-section SHAPE A + format_version 1→2 (the day-1 "additive" prediction held for cross-refs, not for the Entity Extensions Table); E6 hook execution re-scoped → M1.0.9; of override = Component { field: v } field-merge; mono-entity prefab instantiation.

Flag in review: the format_version 1→2 break (no v1 back-compat — re-cook; deterministic, no Phase-1 prod files); the M1.0.9 boundary (seam fires, hook not executed); the §30.5 warning decision; registry.zig (FROZEN) gained FieldKind.entity_ (sanctioned by the E4 file-list); mechanical out-of-list edits (diff_runner.zig switch arms; parser/ast/descriptor/lower for the clause), all journaled.

Final measurements: scene load median 1.111 ms / 10k (M4 Pro, ReleaseFast, 50 runs) vs M1.0.5 ~1.05 ms — +~6%, within noise; resolveCrossRefs/applyExtensions are O(entries) and no-op for extension-free scenes.

Residual debt (deliberate): hook execution → M1.0.9; §30.5 warning (open); multi-entity prefab instantiation + hierarchy (D-D) → hierarchy milestone; Entity on extension-added components / resource→entity / cross-scene refs → future additive.

Validation (all green)

• All Scope deliverables present (E1–E6; hook execution explicitly re-scoped → M1.0.9)
• No out-of-scope drift
• Tests pass in Debug and ReleaseSafe
• Benchmarks: none new; load time noted (1.111 ms/10k, no material regression)
• Observable behaviour demonstrable (capstone prefab_integration_test.zig)
• zig build, zig build test (844/861, 17 skip, 0 fail), zig fmt --check, zig build lint green
• Closing notes filled; Status: CLOSED, close date set
• Final commit docs(brief): close M1.0.6

🤖 Generated with Claude Code