Skip to content

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.md
index 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 into
real 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` and
diff --git a/harness/docs/GRAPHICS_LOOP.md b/harness/docs/GRAPHICS_LOOP.md
index 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_graph
default ON) — measured 2026-08-26 on `refs_v2_graphics` (aurora brief, flash api-agent, shader_v2): the
baseline prompt carried the cookbook's Light chapter with `curtain()` five times and `src/shader.frag` called
it 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 same
chapters `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 prints
Spearman(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 reference
A/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.md
index 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 is
expected 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-agent
only). **Δ legacy lift**: the same keys passed inside `extra={...}` are lifted into
the 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, fi
from 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.py
from codeverse.tracks.generation import generate, run_agent_task, parse_multifile, is_single_shot
GenerationTask.phase: int = 0 # tasks run in parallel WITHIN a phase, phases in ascending order