Phase 1 / Etch / Execute extension hooks

[guysenpai]

Milestone

Brief: briefs/M1.0.9-extension-hooks.md — Status CLOSED.

M1.0.9 founds the runtime text-execution surface M1.0.6 deferred: a cooked extension on_attach/on_detach hook is re-parsed and walked against the live world. Decision frozen at scoping: TEXT re-parse, not bytecode (the VM is Phase 2). The last Etch milestone.

Deliverables (Scope E1–E5)

• E1 — parser.parseStmtBlock: parse a cooked hook statement-run ("; "-joined, no braces) into a transient AstArena (reuses parseStmt via parseStmtFragment, skipping one optional .semicolon).
• E2 — interp.execHookText: transient-arena self.ast rebind + implicit entity bind + execStmtRun + observer-deferred routing; bindToWorld registers the real on_attach/on_detach trampolines so the loader's dispatchOnAttach reaches execution.
• E3 — world.zig on_detach seam (mirror) + loader runtime activate/deactivate + dispatchMethodOnValue activate_extension/deactivate_extension.
• E4 — per-entity active-extension side-table + has_extension/active_extensions Etch methods.
• E5 — CLAUDE.md §3.4.

✅ B1 + B2 round-trip (the two merge blockers — fixed)

Recorded as round-tripped FROZEN deltas in the brief (docs(brief): record B1+B2 round-trip).

• B1 — immediate structural mutation mid-iteration → deferred. iterateArchetype walks arch.chunks live; the Etch activate_extension/deactivate_extension previously did an immediate add/removeComponentDynamic → archetype migration mid-walk → corruption. Now dispatchMethodOnValue ENQUEUES a deferred op (pending_extensions, mirror of pending_tags, extension bytes resolved at the call), drained at the tick boundary by flushPendingExtensions (after iteration; snapshot → no recursive drain) via the loader's bytes-taking activateExtension / new deactivateExtension (both pub), which fire the Tier-0 on_attach/on_detach seam. The immediate runtimeActivate/runtimeDeactivate stay for the load + direct-programmatic paths (outside iteration). Realization note (Recorded deviations): the deferred queue is interp-side, not the Tier-0 CommandBuffer, because the ECS command-buffer apply path cannot reach scene/loader (the ecs → scene layering forbids it); the interpreter is the correct tier to own + flush it. +1 test: a multi-entity rule activates every matched entity with no corruption, effects applied after the flush.
• B2 — type-checker now recognizes the four methods. dispatchMethodOnType's entity arm (types.zig) rejected any non-inherent/trait method on an Entity, so a real rule body calling the methods failed weld check. The entity arm now recognizes activate_extension(string) -> unit, deactivate_extension(string) -> unit, has_extension(string) -> bool, active_extensions() -> [string] (arg-validated) before the "no method" error. This supersedes the first-close "interpreter-level only" position — tests no longer skip the checker. +1 test: a checked program calling all four passes clean; a wrong-typed arg is still rejected.

⚠️ One item still for review

The two B-flags are resolved. The only remaining point is surface-adaptation #1 (Recorded deviations): the "on_attach structural command drained before on_spawned" acceptance test uses a Tier-0 stand-in attach callback, NOT a cooked Etch hook issuing entity.add(...)/spawn — because the interpreter has no entity.add/spawn in bodies (S4 boundary) and tag mutation is not cookable, so a cooked hook cannot itself issue a deferred structural change today. The drain mechanism is built + correct (and now also exercised by B1's deferred extension ops). Happy to round-trip if the literal form is wanted (it needs interp structural-mutation support — a separate milestone). Four further surface-adaptations (tests location, trampolines location, { source: entity }, §30.5 warning out of scope) are documented in the brief.

Closing notes

• What worked: Recon-first caught, before any code: the ;-separator (cooked text is "; "-joined; the parser only consumes ; inside fill-arrays → parseStmtBlock needs its own separator-skipping loop), the brief's correct call that self.ast is rebindable (the rebind is required — the executor resolves identifiers via self.ast.strings), and the two-EntityId duality. execHookText mirrors runObserverBody; B1's pending_extensions mirrors pending_tags — both inherit proven discipline.
• What deviated: the round-trip closed the two first-close flags (B1 deferral, B2 type-checking). Remaining: five non-round-tripped surface-adaptations, only Phase -1 / Bootstrap / Repo and CI #1 touching a frozen acceptance test.
• Final measurements: N/A — correctness milestone. +14 tests (parser 2, interp 3, world 2, scene 6 incl. B1, types 1 B2); full suite green debug + ReleaseSafe (no leaks), test-extensions 14/14, zero build warnings, fmt/lint clean.
• Residual: a cooked hook can't issue a deferred structural change until the interp gains entity.add/spawn (drain wiring future-proofs it); §30.5 compile-time warning deferred; two out-of-scope "M1.0.9" doc-comment refs left untouched (ast.zig:647, prefab_integration_test.zig:6).

Validation (Étape 4, re-run after B1+B2)

• All Scope deliverables present (E1–E5 + B1 + B2)
• No drift into Out of scope (no bytecode; no last-wins; no @exclusive_with; no multi-entity; no weld extension reapply; no re-type-check of the fragment)
• Acceptance tests green in debug and ReleaseSafe (incl. the B1 multi-entity + B2 type-check tests)
• Benchmarks: N/A (correctness milestone)
• Observable behavior demonstrable: cooked scene + CombatModule → Health.max 100→150 at load; multi-entity activate round-trip
• zig build (zero warnings), zig build test, zig fmt --check, zig build lint green; commit-msg green on every commit; pre-push (build + test + test-release + test-tsan-wayland) green
• CLAUDE.md updated (§3.4 + B1/B2 reconciliation) and committed on the branch
• §3.6.1 language audit passed (no French in diff + brief)
• §3.6.1 drift audit passed (stale "execution is M1.0.9" comments refreshed; B1/B2 terms have no orphans; 2 out-of-scope residual refs recorded)
• Closing notes filled + reconciled; Status: CLOSED, Closed: 2026-06-30
• Final commit docs: reconcile CLAUDE.md for B1+B2 (M1.0.9)

Merge + tag (v0.10.9-extension-hooks) left to you.

🤖 Generated with Claude Code