Skip to content

Official Codebase of 3DCodeVerse

Python

docs: D53-D55 and the RUNBOOK rules the first scene battery produced

ziyaod686c8f23e3d
diff --git a/harness/docs/DECISIONS.md b/harness/docs/DECISIONS.md
index 79fa82f9..9569671d 100644
--- a/harness/docs/DECISIONS.md
+++ b/harness/docs/DECISIONS.md
@@ -787,6 +787,65 @@ written) that were accepted because the code works that way and the tests pin it
that the two read as one check with two dials; the fix belongs in what each is called
and documented to do, not in the numbers.
+* **D53 A gate never reports the machine as a defect, and a render is retried once when
+ the browser dies (2026-09-05).** The first recorded `scenes_v1` battery produced six
+ cells of which three built, passed every gate that does not need pixels, and kept ZERO
+ renders: `driver: Attempted to use detached Frame '<id>'` — Chrome reaping the render
+ tab on a box at load 93 with swap full and all eight GPUs at ~100 %. The judge was
+ skipped for want of images, so $6.75 of already-paid generation produced no verdict, and
+ `bench/scene_stats.py` attributed the whole thing to `render_console`. Three separate
+ rules came out of it, and they are the general form, not three patches:
+ 1. **A driver that lost its browser is retried once, on a browser of its own.** The
+ scene funnel (`spatial/render_scene.run_scene_script`) had no retry at all; the object
+ path had one since 2026-08-28 but its marker tuple knew only the "Target closed"
+ spelling. One vocabulary, `spatial/node.BROWSER_LOST_MARKERS`, now serves both, and
+ the retry runs with `CV3D_BROWSER_REUSE=off` because the shared browser advertised in
+ the cache is the suspect. Exactly one retry: a box out of memory stays out of memory.
+ 2. **Two runtime trees never share a browser.** The daemon endpoint, its spawn lock and
+ its failure file carry a digest of the `runtime_js` that spawned them, so a worktree
+ and the main checkout cannot advertise over each other inside one `CV3D_CACHE_DIR`.
+ RUNBOOK had asked operators to remember this since the coupled battery lost an arm to
+ it; nothing enforced it.
+ 3. **A finding that names a dead browser is reported apart from a defect.**
+ `scene_stats.py` puts it in a `lost to the box` column and does not count the gate as
+ failed. A battery whose report shows that column non-zero is not yet a statement
+ about the generator.
+ Consequence: a red browser test is checked against `uptime` and `free -g` before it is
+ believed, and `test_studio_render_is_reproducible_and_stamps_the_rig_version` is
+ documented as flaky-by-construction under CPU contention (SwiftShader is not
+ bit-reproducible when the box is busy) rather than weakened.
+
+* **D54 `scene_placement` measures matter, and matter writes depth (2026-09-05).** Two of
+ the first six recorded scene cells failed the gate on nothing but their own atmosphere:
+ "BlackPine_5 is sunken 3.46 m into AtmosphereHaze" and "WindowSnowView/Mesh_49 and
+ Environment/MoonlightShaft overlap (100 % of the smaller box)". Both scenes were
+ correct; both offenders are `MeshBasicMaterial` at opacity 0.035-0.04 with
+ `depthWrite: false`, and all nine recorded scenes use that idiom 34-42 times each. A
+ pass that writes no depth occludes nothing, so it cannot support an object, nothing can
+ sink into it, and passing through it is what it is for. `host_placement.nonSolid` keeps
+ such meshes out of the column index entirely; an asset made only of them is listed with
+ the exempt reason `volumetric` rather than dropped. **Opacity is deliberately not part
+ of the rule** — glass sits at 0.3-0.6 and keeps writing depth, and a greenhouse pane
+ really is a surface; a solid wall the model mistakenly marked `depthWrite: false` stops
+ being a support, which is the cheaper error and matches what the frame shows. Measured
+ on the recorded workspaces: cozy_cabin FAIL → PASS, japanese_garden's 3.46 m becomes a
+ 0.044 m embed and the gate now fails on a real defect it had been reporting alongside
+ the fog (`SubmergedRock_1 is sunken 0.48 m into ArchedBridge`).
+
+* **D55 A loaded GLB root is named after its asset (2026-09-05).** rooftop_garden's plan
+ asked for one `blender_glb` asset; the Blender sub-run built it, the assembler wrote the
+ loader, the browser loaded it and the census confirmed it was in the scene
+ (`meshes_in_scene: 1, in_scene: true`) — and `scene_placement` still reported
+ "zone PergolaLounge is missing planned contents: LoungeSofa", because the object was
+ called `Scene`. A glTF root carries whatever the exporter wrote and Blender writes
+ "Scene". The three assembled entry points that load GLBs (`render_scene_js`, the
+ assembler's probe module, and the plan-written `scene.js`) had drifted into three copies
+ of the same loop with three different error messages; they are now one emitter,
+ `_glb_preload_js`, which stamps `to_pascal(key)` on the loaded root. Consequence for the
+ Blender-scene question: **the cross-language seam is not what fails.** The Blender asset
+ path works end to end and only lost a name; an argument for a Blender assembly layer has
+ to be made on other grounds.
+
## Rejected / deferred
* A versioned `Spec`/`RunRecord`/`RunState` load-normaliser (rejected 2026-08-30: of the seven
diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.md
index 49aac9dc..9d6abfa1 100644
--- a/harness/docs/RUNBOOK.md
+++ b/harness/docs/RUNBOOK.md
@@ -175,13 +175,26 @@ Twice on 2026-09-04/05 that produced 11 and 21 spurious failures that vanished o
re-run (`tests/scene_runtime/lib/*` first, since those hold the renderer longest). A red
suite during a battery says nothing; re-run it when the battery is done.
-**Two arms at once need separate `CV3D_CACHE_DIR`, not just separate `--out`.** The
-browser daemon advertises its endpoint in `CACHE_DIR/browser_<backend>.json` and a newer
-daemon supersedes an older one, so two worktrees sharing a cache end up on ONE browser:
-the arm that did not launch it renders through a server rooted in the other tree, its GLB
-is outside that root, and `render_glb` returns "produced no result" — on one side only,
-looking like random flakiness (2026-09-04). Give each arm its own cache dir; the render
-cache separates with it, which an A/B wants anyway.
+The same holds for a box loaded by OTHER work. On 2026-09-05, with 12 `proseg` processes
+holding 528 GB, swap full and all eight GPUs at ~100 %, the offline suite failed 12, then
+44, then 17 tests in three runs at `-n 12 / 6 / 4`, every one of them a browser test
+reporting `Session closed` or `Target closed`; `tests/scene_runtime` alone at `-n 4` with
+its own cache dir passed 787/787. Check `uptime` and `free -g` before believing a red
+browser test. One test is flaky by construction under CPU contention and is NOT to be
+"fixed" by weakening it: `test_studio_render_is_reproducible_and_stamps_the_rig_version`
+compares two renders byte for byte, and SwiftShader is not bit-reproducible when the box
+is busy — it failed 2 runs in 3 on an unmodified tree at load 129.
+
+**Two arms at once still want separate `CV3D_CACHE_DIR`, though the browser no longer
+depends on it.** Until 2026-09-05 the daemon advertised its endpoint at
+`CACHE_DIR/browser_<backend>.json`, a newer daemon superseded an older one, and two
+worktrees sharing a cache ended up on ONE browser: the arm that did not launch it
+rendered through a server rooted in the other tree, its GLB was outside that root, and
+`render_glb` returned "produced no result" — on one side only, looking like random
+flakiness (2026-09-04). The endpoint, its lock and its failure file now carry a digest of
+the `runtime_js` that spawned the daemon, so two trees keep separate browsers inside one
+cache dir and neither can retire the other's. Give each arm its own cache dir anyway: the
+render cache separates with it, which an A/B wants.
Also halve each arm's `--parallel`: two arms at 3 workers is six concurrent renders, and a
round with no renders skips the judge, so the loop stops at `judge_unavailable` and the
@@ -189,6 +202,16 @@ cell is finished with no score (`bench run` will not re-run it: the row exists).
scoreless cells afterwards — delete the row from `results.jsonl` and the run directory,
then `bench run --id <prompt>`.
+**A cell can also lose its renders to the box rather than to itself.** When the machine
+runs out of memory Chrome reaps the render tab and the driver reports
+`Attempted to use detached Frame '<id>'`: the scene built, every gate ran, and the judge
+was skipped for want of pixels — three of six cells of `scenes_v1` on 2026-09-05, $6.75 of
+generation already paid for. The scene drivers now retry once on a browser of their own
+(`spatial/render_scene.run_scene_script`), and `bench/scene_stats.py` reports such rounds
+in a `lost to the box` column instead of counting them as gate failures. A battery whose
+report shows that column non-zero has to be re-run for those cells before it is read as a
+statement about the generator.
+
**A new worktree needs `runtime_js/node_modules` before it can run a battery.** Without it
`render_glb` dies on every round, the judge is skipped for want of renders, and the cells
come back `status=plateau` with `score=None` — an arm that reads as healthy and measures