Official Codebase of 3DCodeVerse
Python
docs: D51 — the effect library is harness-owned starter code; post chain; ablation probe
gaoypengf2926e832dfd
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 30248ac4..fc947d40 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -119,6 +119,13 @@ codeverse/scene_placement.py (scene_placement gate + check_placement tool: floating / sunken /unsupported / interpenetration per placed asset from the probe census's placementtable, runtime_js/lib/host_placement.mjs; added 2026-08-26),+ ablation.py (effect_ablation tool + census.effect_ablation: the scene rendered as+ authored vs with every custom shader replaced by a neutral material of the same+ base colour — changed-pixel fraction per camera and per material,+ runtime_js/lib/host_ablation.mjs + ablate_scene.mjs; rebuilt 2026-09-01 as an+ instrument after the 08-28 cleanup deleted the unused counterfactual path.+ The scene build folds the field into its census only under CV3D_ABLATION=1 —+ a second browser boot, so opt-in; the tool always writes it to census.json),gl_render.py (GlHost), frame_stats.py (gl_frames),sheet.py (montage_2x2, crop_region), measure.py, connectivity.py,contract.py (authoring-frame hints), sections.py, silhouette.py, probes.py,@@ -240,6 +247,12 @@ runtime_js/ export_glb.mjs (placement policy, instance baking, selfcherender_scene.mjs probe_scene.mjs check_shaders.mjs gpu_launch.cjs serve.cjslib/{resolve_three, scene_host, host_coverage, host_census, host_placement, orbit, instances,census, glsl_audit, browser/…}+ browser/post.js — scene post chain: GTAO + SELECTIVE bloom (an emissive+ mask, not a luminance bright-pass: on our renderer the sky dome at 1.88+ linear outshines every authored emissive, so a threshold cannot separate+ them) + a colour grade that is the identity unless the scene sets+ `scene.userData.grade`. ON for scene renders, `CV3D_POST=0` / `--no-post`+ to disable; object renders never come through this driver.tests/ agents bench_prompts blender_cadquery compare_bench core cost flywheel_cli gallery graphicsinstall judges languages models orchestrator_tracks prompts reference scene_gatesscene_prompts scene_runtime skills spatial_tools texturing threejs_render urdf_joints@@ -313,6 +326,11 @@ summary:* **scene_threejs**: `src/scene.js` `createScene({THREE, renderer, loaders}) → {scene, cameras, update(t,dt)}`;`src/env.js`, `src/zones/*.js`, `src/assets/*.js`, `src/shaders/*.js`; GLBs at`public/assets/<name>.glb`. The harness assembles `scene.js` deterministically.+ Plus the harness-owned, read-only **effect library** `src/lib/*.js` — 52 modules,+ 28.8k lines, shipped into every workspace by BOTH skeleton paths and listed in+ `HARNESS_OWNED_SRC` so agent writes to it are reverted (D51). The starter tree is+ therefore 60 `.js` files / 29.3k lines, of which 8 are the example scene. The+ want → call table the prompts carry is `prompts/scene_threejs/effects_catalog.md`.* **glsl_shader**: `src/shader.frag` (+ optional `src/common.glsl`,`src/buffer_a.frag` for feedback; the harness-owned, read-only `src/recipes.glsl`is pasted above them when the track seeded recipes) — the agent never writesdiff --git a/harness/docs/DECISIONS.md b/harness/docs/DECISIONS.mdindex fa847637..3286f19c 100644--- a/harness/docs/DECISIONS.md+++ b/harness/docs/DECISIONS.md@@ -586,6 +586,73 @@ written) that were accepted because the code works that way and the tests pin itdeterministic-repairs bundle (axis flip + buried check) A/B'd at Δ −0.039 ± 0.105 over12 paired prompts, the flip firing in 1 cell of 12 — the aggregation ships on rationale,not on a resolved score delta.+* **D51 The effect library is HARNESS-OWNED STARTER CODE, not an SDK import+ (2026-09-01).** Context: `scene_multifile_graphics` shipped 52 three.js effect modules+ (21.7k lines) that this harness had no equivalent of — canopies, water, weather, aging,+ neon, night windows — and every scene run was re-deriving worse versions of them inside+ a 60-minute budget. Law 1 says generated code is raw language, never an SDK/helper+ import. **Decision — an amendment, not an exception**: law 1 forbids the AGENT from+ reaching outside its workspace for someone else's abstraction. Modules the HARNESS+ writes into `src/`, verifies on its own renderer, and forbids the agent to rewrite are+ not that: they are the same thing `src/recipes.glsl` already was for `glsl_shader`+ (D-precedent: `contracts.common.HARNESS_OWNED_SRC`, `AgentJob.read_only`), one order of+ magnitude larger. So `src/lib/*.js` ships into every scene workspace, is listed in+ `HARNESS_OWNED_SRC[SCENE_THREEJS]` (a new DIRECTORY-prefix entry form, predicate+ `is_harness_owned`), and a post-session write to it is reverted like any other+ harness-owned file. Generated code stays raw three.js + GLSL: the library IS raw+ three.js, and it is in the workspace, in the agent's git history, readable and+ debuggable.++ **What shipped.** 52 modules / 28.8k lines under+ `codeverse/languages/scene_threejs/starter/src/lib/`, ported module-by-module against+ the reference's own test per module, adapted to OUR renderer contract (their exposure+ 1.1 → our 1.0; their log-depth on → ours off, so their logdepth chunks are harmless+ no-ops; their renderer-contract assertions dropped). Every module was rendered through+ the real host on the showcase harness and LOOKED at, most of them twice (a `before` port+ and an `after` improvement pass): 53 modules carry a before/after pair on disk and 77+ night renders were taken. Aesthetic changes were measured, not asserted — linear albedo+ band 0.02–0.8, hue variance inside every effect, emissives re-scaled to a bloom-friendly+ 1.5–4, fresnel on water/glass, fog in the sky's hue family. 678 node-marked tests+ (`tests/scene_runtime/lib/`, one file per module) pin the physics claims, the shared-name+ contracts and the option-is-a-uniform law; the GPU compile in them is real+ (headless ANGLE/D3D12, e.g. godrays 21 programs / 6 custom materials).++ **Companion side track**: a post chain for scene renders+ (`runtime_js/lib/browser/post.js`, ON by default, `--no-post` / `CV3D_POST=0`):+ RenderPass → finite clamp → GTAO → SELECTIVE emissive bloom → grade → OutputPass, 18+ tests. The bloom is NOT the reference's luminance bright-pass: measured on this+ renderer every daylight scene tops out at 1.883 linear (the sky dome) while the+ brightest authored emissive in the whole library is 1.231, so a global bright-pass+ cannot separate a neon sign from the sky — at the reference's 0.85 threshold a daylit+ grass frame lost a quarter of its saturation (0.3132 → 0.0699). The mask is a second+ cheap render of emission only; a scene with nothing emissive pays nothing.++ **Consolidation (same day).** `_probe.shader_check` could never work — it staged only+ `src/fixture.js` while `check_shaders.mjs` boots the workspace's `src/scene.js` — so 32+ module tests had each hand-rolled the same 17-line workaround. Replaced by+ `_probe.compile_scene`; **843 lines deleted**, and two further inline copies+ (`test_lights`, `test_foliage_shade`) and `test_shader.compile_fixture` fold into it+ too. Also fixed: `scene_host.mjs` failed a camera-less boot with `info.error` EMPTY+ (message named no reason at all); plan-mode `write_skeleton` shipped `PATTERN_FILES`+ only, so a PLANNED run — the production path — would have got the catalog in its prompt+ and no `src/lib/` to import from; `signage.js` carried a `unpkg.com` CDN font pin that+ violates the no-network law (dead since `import.meta.resolve` landed); and both the+ workspace lint and the static shader audit now skip `src/lib/`, which was 3 hard lint+ ERRORs (signage's node-only font fallback) + 12 "large file" WARNs + a uTime+ false-positive pair that outranked the agent's own real shader error in the build report.+ `patchStandard` gained three opt-in injection hooks — `roughnessBody` / `metalnessBody`+ (after `<roughnessmap_fragment>` / `<metalnessmap_fragment>`) and `outputBody` (after+ `<opaque_fragment>`, where the colour is still linear) — the gap three module agents+ reported independently, since `<color_fragment>` reaches only the albedo and a 30 %+ rust crust could until now only be sold by dematting 100 % of the material.++ **Evidence label — honest.** Everything above is RENDERED AND EYEBALLED plus+ deterministic metrics and 2 809 offline tests green. It is **NOT yet A/B-judged**: no+ paired battery has scored scenes with the library against scenes without it, so the+ claim "this raises scene scores" is unproven. The shader.js hook change was isolated by+ rendering all six shader.js-dependent modules (grass, water, canopy, godrays, neon,+ clouds) against a control build with the hooks cut out: mean luminance identical to five+ decimals on all 12 frames. Funding the A/B is the next call.## Rejected / deferreddiff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 1a355f63..a726a272 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -185,9 +185,11 @@ sessions on one workspace are serialised, so there is no sibling filter),`edit_only` / `always_writable` (a scoped refine may overwrite only its hinted files +the entry file), `read_only: list[str]` (harness-owned files INSIDE the write roots thesession may read but never write — `contracts.common.HARNESS_OWNED_SRC[language]`, i.e.-`src/recipes.glsl` for glsl_shader; `tracks/generation.py` sets it on every job of the-run and `agents/cli_common._enforce_scope` reverts a post-session write to one and-fails that session). **Δ legacy lift**: the job keys (`round`, `kind`, `language`,+`src/recipes.glsl` for glsl_shader and `src/lib/` for scene_threejs; `tracks/generation.py`+sets it on every job of the run and `agents/cli_common._enforce_scope` reverts a+post-session write to one and fails that session. **Δ** an entry ending in `/` is a+DIRECTORY prefix — `contracts.common.is_harness_owned(rel, owned)` is the predicate, and+it is what names the 52-module effect library without listing 52 paths). **Δ legacy lift**: the job keys (`round`, `kind`, `language`,`track`, `files_hint`, `mcp_command`) passed inside `extra={...}` are lifted intothe typed fields at validation (extra itself is left untouched), so old constructorsand serialized jobs keep working; `extra` stays for one-off backend hints.