perf: drain initial wall builds within the time budget (charter row 6)

[wass08]

Metric

Maxi 8× time-to-first-clean after load (charter backlog row 6; the row's settled < 8 s target contains a 3 s runner quiet window, so the runner now reports firstCleanMs alongside it).

Three back-to-back PR-vs-main pairs, same machine (a fourth under load average 21–24 discarded as starved); third pair = this tip:

fixture	first clean	settled	same-gesture endpoint-drag settle	idle frame
Maxi 8× (472 walls)	4 900 → 3 930 ms (−20 %); 4 836 → 4 251 (−12 %); 5 639 → 4 283 (−24 %)	8 441 → 7 312; 8 681 → 7 608; 9 534 → 7 633	420 → 435 ms	6.8 → 6.3; 8.7 → 6.6 ms
Maxi 4×	−8 % / −14 % / −4 %	6 775 → 6 117	342 → 365; 349 → 370 ms	flat
rich 4×	−13 % / −5 % / −11 %	7 815 → 6 942	window 308 → 292; wall body 510 → 516	11.3 → 9.0 ms

What changed

• Initial-build state for the wall system, entered from setScene's hydration token and left on the first frame with no dirty wall and an empty pending-neighbour queue (a document write, live override/transform, or canvas pointer/wheel ends it early). Exposed read-only via isWallInitialBuildActive().
• While active: walls are consumed by the existing 8 ms time budget without the 8-per-frame count cap (heavy ≥ 6-opening walls still get their own frame), and a wall's first build does not enqueue neighbour re-invalidation — every neighbour is itself queued for its own first build, and a test proves junction geometry identical to the capped path. Opening-completion re-dirtying is unchanged. After initial build everything returns to today's scheduling.
• Counters under __pascalPerf.batchStats().wallDrain (walls consumed per frame, exit reasons, pending-neighbour length, first-build vs re-invalidation) and a wall-initial-build span.
• Fix found by the receipt sensor (1137afc): the first cut's hydration invalidation was a nested scene write, so the first edit after load reached space reconciliation twice and re-invalidated the whole level (same-gesture endpoint drag 422 → 1 598 ms). Invalidation now happens atomically with the document write; the regression fixture rebuilds 4 walls instead of 48.
• Batching during the drain (bounded join waves while walls are dirty) is deliberately left for a follow-up.

Gates

• e2e: 9/9 against the PR dists (perf-regression pack ×5, batched-wall click, hidden-wall click, undo/redo graph, floor placement)
• Unit: core 1 430 / viewer+nodes 2 681 pass (--randomize --seed=1); tsc --noEmit core/viewer/nodes clean; biome clean.
• No rendering change → no pixel/bake gate. Independent audit: no blocker, four should-fixes closed in the second round (token published after normalization; interaction capture spans the lazy mount and remounts; bounded stall exit for never-registering walls; ?perf-gated, allocation-free diagnostics) plus a pre-existing core test-fixture ordering flake fixed (three seeds green).
• Docs: wiki/architecture/systems.md describes the initial-build scheduling.

Charter: plans/performance/editor-scalable-scene-runtime.md row 6 (private PR follows with the evidence row and the runner's first-clean / undo-phase sampling).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jmmz2AMwTzcnKsSHHPEMhN

---

Note

High Risk
Changes core scene load/hydration, undo-adjacent store wrapping, and wall rebuild scheduling—security-adjacent correctness for large imports and first-edit behavior, with many interaction edge cases.

Overview
Introduces a scene hydration boundary around setScene: elevator opening sync runs synchronously, stair rise/opening normalization is queued via microtasks, and a hydrationToken is published only after that work completes. Ordinary document writes (including the first edit after load) atomically cancel pending publication or clear an issued token; live overrides/transforms and canvas pointer/wheel also end hydration early.

The wall system enters initial build when the token is active: rebuilds follow the existing 8 ms frame budget but without the 8-walls-per-frame cap, heavy walls still get a dedicated frame, and each wall’s first build skips neighbour re-invalidation. Lifecycle state lives in wall-build-lifecycle (eager canvas subscription + isWallInitialBuildActive()), with optional ?perf wallDrain stats. Stair auto-sync and snapshot apply are wired into the same normalization/hydration rules.

Includes broad regression tests (hydration ordering, interruptions, batching quiet clock during initial build) and wiki/architecture/systems.md updates.

^{Reviewed by Cursor Bugbot for commit 52b1b5b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pascal]

I hit an error while handling your request (Model unavailable on AI Gateway free tier: Free tier users do not have access to this model. Upgrade to paid credits at https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%3Fmodal%3Dtop-up for unrestricted…).

Please try again, rephrase, or reach out if it keeps failing.

Error id: d08da89a-c471-4f51-ab16-816f2435e6c2