Official Codebase of 3DCodeVerse
Python
docs: harness-owned src/recipes.glsl — GRAPHICS_LOOP §3 (seed_v1 readout), INTERFACES (AgentJob.read_only, compose, seed_recipes), ARCHITECTURE
gaoypenge5654e458bb8
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 648d50e4..b15ee427 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -163,8 +163,9 @@ codeverse/common.py (RunContext, Services), motion.py, reference.py, static_object.py,articulated_object.py, scene.py, scene_assets.py, graphics.py + graphics_steps.py,graphics_recipes.py (the brief's verified cookbook recipes + their helpers written into- src/common.glsl before the session — measured: flash calls a recipe on disk, not one it- is shown; CV3D_SEED_RECIPES, docs/GRAPHICS_LOOP.md §3),+ the harness-owned, read-only src/recipes.glsl before the session — measured: flash calls+ a recipe on disk, not one it is shown, and overwrites one seeded into its own common.glsl;+ AgentJob.read_only, CV3D_SEED_RECIPES, docs/GRAPHICS_LOOP.md §3),brief.py (cached EngineeringBrief: one cheap call turns a one-line prompt intoreal dimensions / sub-assemblies / signature features; never fatal, CV3D_PLAN_BRIEF),plan_budget.py (plan size derived from the request, capped per language),@@ -278,8 +279,9 @@ summary:`src/env.js`, `src/zones/*.js`, `src/assets/*.js`, `src/shaders/*.js`; GLBs at`public/assets/<name>.glb`. The harness assembles `scene.js` deterministically.* **glsl_shader**: `src/shader.frag` (+ optional `src/common.glsl`,- `src/buffer_a.frag` for feedback) — the agent never writes `#version`, uniform- declarations or `out vec4`; the harness header provides+ `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 writes+ `#version`, uniform declarations or `out vec4`; the harness header provides`u_time/u_resolution/u_mouse/u_frame/u_prev/u_noise/u_buffer_a` (+ Shadertoy`iTime/iResolution/iChannel*` aliases). Feedback shaders are simulated at 30 fps.* **opengl_python**: `src/program.py` with `setup(ctx, w, h) -> state` anddiff --git a/harness/docs/GRAPHICS_LOOP.md b/harness/docs/GRAPHICS_LOOP.mdindex 6204178a..54f0950b 100644--- a/harness/docs/GRAPHICS_LOOP.md+++ b/harness/docs/GRAPHICS_LOOP.md@@ -82,16 +82,29 @@ Eye scores: `scratchpad/gfx_eye.json` → copied to `bench/out/judge_calib_graphdefault ON) — measured 2026-08-26 on `refs_v2_graphics` (aurora brief, flash api-agent, shader_v2): thebaseline prompt carried the cookbook's Light chapter with `curtain()` five times and `src/shader.frag` calledit zero times in both finished runs — round 0 a comb of bars (0.33), a later round a wash (0.12). Showing- flash a recipe is not flash using it, so the harness now writes the recipes the brief selects (the same+ flash a recipe is not flash using it, so the harness writes the recipes the brief selects (the samechapters `select_cookbook_chapters` puts in the prompt, minus the always-on helper chapters and the- raymarching template) into `src/common.glsl` before the session — function definitions only, plus exactly- the `hash / noise / fbm` helpers they call, under `// ---- harness-seeded verified recipes` — and the- baseline prompt names them ("call them, do not rewrite them"); the refine prompt carries a one-line- reminder; a resume appends only names the file does not define. The aurora brief seeds `skyGrad, sun,- stars, waterHeight, curtain, auroraCol, aurora` on top of the skeleton's helpers; the neon-rain brief- `dropsLayer, bokehSoft`; a brief matching no chapter seeds nothing and the prompt has no block. The event- is `recipes.seeded`; `CV3D_SEED_RECIPES=0` is the control arm. The number to watch stays the- `comb_artefact` firing rate — and now also `grep -c "curtain(" src/shader.frag`.+ raymarching template) to disk before the session — function definitions only, plus exactly the+ `hash / noise / fbm` helpers they call. **Measured again 2026-08-26 (`bench/out/seed_v1`, same brief /+ model, seeding ON into `src/common.glsl`)**: `recipes.seeded` fired and the finished run's `common.glsl`+ had NO seeded block and no `curtain(` — the agent overwrote the file with its own helpers — and+ `shader.frag` called neither `aurora(` nor `curtain(` nor `stars(`. Seeding into a file the agent owns+ is not sticky, so the file is now the **harness-owned `src/recipes.glsl`**: `AgentJob.read_only` makes+ `write_file` / `edit_file` refuse it ("harness-owned — call its functions instead"; `read_file` works),+ `wrap.compose` pastes it harness header < `recipes.glsl` < `common.glsl` < `shader.frag` (a compile error+ inside it is reported as `src/recipes.glsl:LINE`), it is self-contained (its helpers travel with it, so+ nothing the agent does to `common.glsl` breaks a recipe), and a name it defines redefined in an agent file+ is the lint ERROR `redefines_recipe` ("`name` is already provided by src/recipes.glsl — call it instead of+ redefining it"). The only `common.glsl` the harness edits is the untouched skeleton, which loses the+ helpers `recipes.glsl` now provides (else the first build fails on `hash12` twice); once the agent has+ written it, a duplicate is its own to remove. The baseline prompt names the recipes ("call these, do not+ redefine them, do not copy them into common.glsl"); the refine prompt carries a one-line reminder; a resume+ appends only names `recipes.glsl` does not define. The aurora brief seeds `skyGrad, sun, stars,+ waterHeight, curtain, auroraCol, aurora` + `hash12, hash22, noise, fbm`; the neon-rain brief `dropsLayer,+ bokehSoft`; a brief matching no chapter seeds nothing, creates no file and the prompt has no block. The+ event is `recipes.seeded {file, names, present, chapters, trimmed}`; `CV3D_SEED_RECIPES=0` is the control+ arm. The number to watch stays the `comb_artefact` firing rate — and now `grep -c "aurora(\|curtain(\|stars("+ src/shader.frag` (a call into `recipes.glsl` is the only way those names can appear in a passing build).* **Measuring the turn** — `bench/judge_calib_graphics.py` re-judges the corpus under v1 and v2(pro, n=2, no planner acceptance so the rubric is measured on its own) and printsSpearman(judge, eye), means, defect firing rates and the biggest disagreements. The result of@@ -160,9 +173,13 @@ first turn took 60–77 min for 1–2): same-judge scores with photos 0.258 / 0.0.441 / 0.169 / 0.000; paired +0.187, sd 0.41, sign 2/3. **All six still fired `comb_artefact`**:the prompt carried `curtain()` five times and no run called it (`grep -c "curtain(" src/shader.frag`= 0). A recipe shown is not a recipe used. Third turn: `tracks/graphics_recipes.py` seeds the-brief's matched recipes into `src/common.glsl` before the session and the prompt says "call them,-do not rewrite them" (`CV3D_SEED_RECIPES`, default ON; A/B `bench/out/seed_v1`, three photo-prompts, plan-pinned, variant = seeding OFF; readout = comb_artefact rate and `curtain(` calls).+brief's matched recipes to disk before the session and the prompt says "call them, do not rewrite+them" (`CV3D_SEED_RECIPES`, default ON; A/B `bench/out/seed_v1`, three photo prompts, plan-pinned,+variant = seeding OFF; readout = comb_artefact rate and `curtain(` calls). **First `seed_v1` read+out** (aurora brief, seeding ON): the seed fired and was gone — the agent rewrote `src/common.glsl`,+seeded block included, and called none of `aurora( / curtain( / stars(`. A recipe the agent can+overwrite is not a recipe kept: the seed now lives in the harness-owned, read-only `src/recipes.glsl`+(§3 "Seeded recipes"); the same A/B re-runs against it.**The track default is `shader_v2`** since c032700 (the switch waited for the first referenceA/B to finish so both of its arms were judged in-loop by one rubric).diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 0c4ea740..a91ec63f 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -156,7 +156,13 @@ res.files_changed (git-derived, attributed per session), res.usage, res.transcri`AgentJob` carries typed job context: `round`, `kind`, `language`, `track`,`mcp_command` (override), `files_hint` (workspace-relative files/dirs the task isexpected to touch — used to attribute `files_changed` between concurrent sessions in-one workspace; harness-owned paths and sibling sessions' hinted files are dropped)+one workspace; harness-owned paths and sibling sessions' hinted files are dropped),+`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 the+session 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 `FileTools(read_only=…)` answers a `write_file` / `edit_file` on one with+`PathDenied("… is harness-owned and read-only … call them from your own files")`)and `job.api: ApiAgentOptions(max_usd, temperature, thinking, allow_shell)` (api-agentonly). **Δ legacy lift**: the same keys passed inside `extra={...}` are lifted intothe typed fields at validation (extra itself is left untouched), so old constructors@@ -196,7 +202,7 @@ rt.contract_doc() -> str ; rt.cookbook_path() -> Path| `ThreeJsRuntime` | `src/object.js`, `src/parts/*.js` | **Δ export as authored** (`--normalise` opt-in, never passed by the runtime; census `placement_offset`/`normalised_offset`); InstancedMesh baked to `<Name>_<i>` meshes (`instanced_meshes_baked`); exported `selfcheck(THREE, root)` is called (throw → SelfCheckError); NaN geometry errors name mesh/part → routed to `src/parts/<snake>.js` || `UrdfBlenderRuntime` | `src/model.py`, `src/robot.urdf` | object.glb (Y-up, node=link, joint extras), meshes/<link>.glb (raw Z-up link frames); link name `world` is reserved (lint ERROR + UrdfError); robot GLB root gets `__root` suffix on name clash || `SceneThreeJsRuntime` | `src/scene.js`, `src/zones/*.js`, `src/assets/*.js`, `src/env.js`, `src/shaders/*.js` | glb_path=None; ok iff `probe_scene` + `check_shaders` pass |-| `GlslShaderRuntime` | `src/shader.frag`, `src/common.glsl`, `src/buffer_a.frag` | harness owns `#version`/uniforms/`out` (wrap.HEADER: u_time/u_resolution/u_mouse/u_frame/u_prev/u_noise + iTime/iChannel* aliases); build renders judge frames via GlHost; compile errors → GlslCompileError at mapped src file:line; artifacts frames/, frames_sheet.png, preview.gif, metrics.json |+| `GlslShaderRuntime` | `src/shader.frag`, `src/common.glsl`, `src/buffer_a.frag` (+ the harness-owned `src/recipes.glsl` when seeded) | harness owns `#version`/uniforms/`out` (wrap.HEADER: u_time/u_resolution/u_mouse/u_frame/u_prev/u_noise + iTime/iChannel* aliases); `wrap.compose(shader, common, recipes_src=…)` pastes header < recipes < common < shader; build renders judge frames via GlHost; compile errors → GlslCompileError at mapped src file:line (recipes.glsl included); lint ERROR `redefines_recipe` when an agent file defines a recipes.glsl name; artifacts frames/, frames_sheet.png, preview.gif, metrics.json || `OpenGLPythonRuntime` | `src/program.py`, `src/*.glsl` | `setup(ctx,w,h)->state` + `render(ctx,state,t,frame,fbo)` run in a moderngl subprocess (`wrappers/run_gl.py`); exceptions map to src/program.py:line, in-string GLSL errors carry both line numbers |Wrappers are standalone (never import codeverse): `blender/wrappers/run_bpy.py`@@ -349,13 +355,15 @@ from codeverse.tracks.prompting import base_prompt_context, reference_images, fifrom codeverse.tracks.prompting import select_cookbook_chapters, select_cookbook_excerpt, is_always_chapter# select_cookbook_chapters(ctx, brief, *, budget=9000, always=COOKBOOK_ALWAYS) -> list[Section]: the header +# always-on chapters + the brief's chapters (whole, cookbook order, inside budget); the excerpt joins them-from codeverse.tracks.graphics_recipes import seed_recipes, graphics_brief, cookbook_functions, EXTRA_KEY- # seed_recipes(ctx) -> list[str]: glsl_shader + seed_recipes_enabled() only. Appends the selected chapters'+from codeverse.tracks.graphics_recipes import seed_recipes, graphics_brief, cookbook_functions, EXTRA_KEY, RECIPES_REL+ # seed_recipes(ctx) -> list[str]: glsl_shader + seed_recipes_enabled() only. Writes the selected chapters'# function definitions (minus always-on chapters and the raymarching template) + the helpers they call to- # src/common.glsl under "// ---- harness-seeded verified recipes"; returns the names written THIS call;- # ctx.extra["seeded_recipes"] = [{name, signature, purpose}] for every seeded recipe on disk (the prompt- # block); emits recipes.seeded {names, present, chapters}. GraphicsTrack.prepare() runs it after the- # skeleton and commits "recipes" when it wrote something.+ # the HARNESS-OWNED src/recipes.glsl (RECIPES_REL; header "// harness-owned: … READ-ONLY …"; a resume appends+ # only names the file lacks); returns the names written THIS call; ctx.extra["seeded_recipes"] =+ # [{name, signature, purpose}] for every seeded recipe on disk (the prompt block); emits recipes.seeded+ # {file, names, present, chapters, trimmed}. Never writes src/common.glsl — except the untouched skeleton,+ # which loses the helpers recipes.glsl now provides (trim_skeleton_common; recipes are pasted first).+ # GraphicsTrack.prepare() runs it after the skeleton and commits "recipes" when it wrote something.from codeverse.tracks.common import RunContext, Services # common.pyfrom codeverse.tracks.generation import generate, run_agent_task, parse_multifile, is_single_shotGenerationTask.phase: int = 0 # tasks run in parallel WITHIN a phase, phases in ascending order