Skip to content

Official Codebase of 3DCodeVerse

Python

docs: the map matches the code again, and D44 records what was rejected

gaoypeng3c24811edf06
diff --git a/harness/CLAUDE.md b/harness/CLAUDE.md
index 0a99c28d..c5503492 100644
--- a/harness/CLAUDE.md
+++ b/harness/CLAUDE.md
@@ -41,7 +41,7 @@ python **3.13** (one fixed version — owner's decision 2026-08-26; no floor, no
node **20.6+** · Blender 4.2+ · Linux x86_64. **There is no CI** (removed 2026-08-26 by the
owner): run `ruff check codeverse bench tests` and the offline suite locally BEFORE every
push, with `set -o pipefail` so a `| tail` cannot swallow a red exit. The version lives in
-`pyproject` `requires-python` + ruff `target-version` + `scripts/setup.sh`, and
+`pyproject` `requires-python` + ruff `target-version` + `setup.sh`, and
`spatial/node.py:NODE_MIN` + `runtime_js/package.json` `engines` for node, pinned together by
`tests/core/test_portability.py`. Details: `docs/INSTALL.md` §2.1.
@@ -100,8 +100,8 @@ cd /home/yipeng/3dcodeverse/harness
python -m codeverse.judges.calibration runs/<slug>... --model gemini:gemini-3.1-pro-preview --n 3 --out out/
python bench/complexity_report.py bench/out --recursive # score-vs-complexity + $/complexity point (docs/COMPLEXITY.md)
python bench/compare_backends.py --prompts bench/prompts/compare_v1.yaml --arms harness:gemini-cli:gemini-3.6-flash,oneshot:claude-code --judge gemini:gemini-3.1-pro-preview --out bench/out/compare_v1
-python -m pytest tests -q -m "not live" # 2 740 tests, ~37 s (real Blender + headless Chrome + CadQuery)
-python -m pytest tests -q -m "not live and not blender and not node" # pure python: 2 627 tests, ~31 s
+python -m pytest tests -q -m "not live" # 1 928 tests, ~58 s (real Blender + headless Chrome + CadQuery)
+python -m pytest tests -q -m "not live and not blender and not node" # pure python: 1 809 tests, ~47 s
# both run PARALLEL by default (pytest-xdist, -n auto --dist worksteal, in pyproject addopts).
# A nested pytest inside a test MUST pass -n0 or it forks another full set of workers.
```
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index b98e8a24..6eae7b7a 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -92,15 +92,16 @@ codeverse/
2026-08-28, to the JSONL event log (Events), the run lock (ONE writer per
run dir: an fcntl.flock at <runs>/.locks/<slug>.lock whose record NAMES the
holder, printed by `3dcv status`) and the bounded parallel fan-out
- (fan_out, split_results, FanOutReport) — still a leaf: imports nothing
- from codeverse
+ (fan_out); sha256_file and version_line live here too — still a leaf:
+ imports nothing from codeverse
models/ ChatModel (base.py), parts.py; gemini.py (the whole Gemini stack:
request/response shapes, dead-key + free 429 rotation, the image model);
anthropic.py openai.py (each with its own request/response shapes);
- retry.py (the scheduling machine: key pool with 'dead' outcome + TPM
- reservation/reconcile, rotation with MAX_WAIT_S ≤ 3 s single waits, the
- shared 503 storm gate — ships OFF, docs/COST.md §21 — and the prompt-token
- estimate); pricing.py (version-suffix-only fallback), health.py (preflight
+ retry.py (the scheduling machine: KeyPool with outcomes ok | 429 | 5xx |
+ error | dead | skip + TPM reservation/reconcile, StormGate — ships OFF,
+ docs/COST.md §21 — with_retries / rotate_with_retries, both bounded by
+ max_total_s ≤ RETRY_DEADLINE_S with MAX_WAIT_S ≤ 3 s single waits, and the
+ prompt-token estimate); pricing.py (version-suffix-only fallback), health.py (preflight
probe: no retries, no backoff), schema_utils.py (strict schema), registry.py
agents/ registry.py (the CodingAgent protocol + dispatch — every backend is a
vendor CLI; the in-process api-agent died 2026-08-28), backends.py
@@ -110,20 +111,26 @@ codeverse/
languages/ LanguageRuntime (base.py); one merged module per language since 2026-08-28 —
blender/ cadquery/ threejs/ urdf/ scene_threejs/ glsl_shader/ opengl_python/ are each
a single __init__.py (lint → skeleton → runtime, in dependency order) beside their
- data (wrappers/, starter/, CONTRACT.md — Path(__file__) assets unchanged);
+ data (wrappers/, starter/ — Path(__file__) assets unchanged; the contract text
+ is prompts/<lang>/contract.md, read through RuntimeDocs);
file_lint.py (one just-written file → syntax/lint verdict for write_file, COST.md §29)
- spatial/ node.py, render.py, tool_common.py (shared tool plumbing),
+ spatial/ node.py, render.py, observe.py, tool_common.py (shared tool plumbing),
render_scene.py (judge view subset, content-fitted orbit),
frame_metrics.py (scene_frames gate), frame_motion.py (measured inter-frame motion),
scene_placement.py (scene_placement gate + check_placement tool: floating / sunken /
unsupported / interpenetration per placed asset from the probe census's placement
table, runtime_js/lib/host_placement.mjs; added 2026-08-26),
gl_render.py (GlHost), frame_stats.py (gl_frames),
- sheet.py (montage_2x2, crop_region), turntable.py, measure.py, connectivity.py,
+ sheet.py (montage_2x2, crop_region), measure.py, connectivity.py,
contract.py (authoring-frame hints), sections.py, silhouette.py, probes.py,
complexity.py (objective complexity vector -> Measurement.extra, docs/COMPLEXITY.md),
joints*.py + joints_collide.py (deterministic penetration), registry.py,
- tools.py (every @tool registration since 2026-08-28), mcp_server.py (MCP name: 3dcv)
+ tools.py (every @tool registration since 2026-08-28, the joint_sweep body included;
+ spatial siblings are plain imports — lazy() guards only codeverse.languages /
+ codeverse.texturing and tool_common's node renderer), mcp_server.py (MCP name: 3dcv).
+ Render modes are contracts.artifacts.RENDER_MODES (shaded wire normals silhouette
+ clay — no 'depth'); build error_type spellings are languages/_common.MISSING_ENTRY
+ ("MissingEntryFile") and BUILD_TIMEOUT ("BuildTimeout") for every runtime
skills/ registry.py (typed ROUTES + the router that evaluates them),
model.py (Skill/Selection + the SKILL.md loader), prompting.py
(per-backend delivery policy + the index/mandate text),
@@ -138,22 +145,29 @@ codeverse/
billing.py (SUBSCRIPTION_BACKENDS/bills_usd — which backends take real dollars,
so the ledger bills real money and not list price; docs/COST.md §25)
guard.py routing.py reconstruct.py (old runs) audit.py report.py
- judges/ base.py (Judge protocol + the pure round-replay pieces `3dcv judge` and
+ judges/ base.py (JudgeInput/Judgment helpers + the pure round-replay pieces `3dcv judge` and
calibration share), rubrics.py + rubrics/*.yaml (defect checklists, the wire
schema, caps and scoring), prompt_builder.py (image prep, montages, the
judge messages), vlm_judge.py (+ the reference/likeness judges),
- pairwise.py (compare_many), calibration.py
- reference/ reference GROUNDING — give the pipeline a picture of what it is building:
- one module: synthesis, THE plausibility gate that makes a synthesized
+ pairwise.py (compare_many), calibration.py. No Judge Protocol: a judge is
+ duck-typed `.judge(JudgeInput) -> Judgment`
+ reference.py reference GROUNDING — give the pipeline a picture of what it is building:
+ synthesis, THE plausibility gate that makes a synthesized
reference safe to use, Spec attachment + honesty guards, proportions
(does the picture agree with the brief?), render-vs-reference diff,
the content-addressed cache and ground_spec (the one call the CLI makes)
texturing/ plan.py (VLM material plan + the scene texture pack), generate.py
(generation + the tileable seam fix + the seam/judge gate), apply.py
(world-metre unwrap, PBR map set, application + material normalisation),
- materials.py (named material library), run.py (texture_pass)
- orchestrator.py stage runner with resume, run state, round loop (RoundPolicy,
- StopPolicy, BestSelector), refine-task compilation + grouping, budget
+ materials.py (named material library), run.py (texture_pass); __init__.py is
+ docstring-only — import from the submodules
+ orchestrator.py the round loop's LIBRARY, not the loop: round POLICIES (RoundPolicy /
+ StopPolicy / BestSelector), refine-task compilation + grouping,
+ StageRunner + RunState (resume), BudgetGuard. The loop itself is
+ tracks/lifecycle.py:_round_loop → tracks/steps.py:run_round. A best-of-N
+ candidate IS steps._run_round(kind='candidate') in a _cand/c<k> sub-workspace
+ with two knobs (render=candidates.quick_render, geometry_views=False), its
+ own _cand/c<k>/events.jsonl and a one-sample judge
tracks/ __init__.py (get_track(track, **options) + the TrackPipeline protocol),
lifecycle.py, steps.py, candidates.py (best-of-N + the pure candidate/pairwise
decision logic), generation.py (agent + single-shot strategies + the file
@@ -173,7 +187,7 @@ codeverse/
depth.py,
skills_hook.py (the round's view of codeverse/skills: attach before generating,
probe reads after — a no-op unless CV3D_SKILLS is on)
- flywheel/ record.py, export.py, pack.py, sample.py, pairs.py, migrate.py (schema moves),
+ flywheel/ record.py (+ best_round_record), export.py, pack.py, sample.py, pairs.py,
deliverable.py, telemetry.py, captions.py, quality.py (tiers + dedupe + code/mesh fingerprints), index.py,
code_quality.py (the delivered CODE's own vector — magic numbers per 100 LOC,
function length, dead functions, duplication, docstrings → record.extra
@@ -236,9 +250,15 @@ runs/<slug>/
src/ agent-authored RAW code (git repo; commits: spec, skeleton, pre:/agent:<label>, rNN <kind>)
public/ (scene) compiled assets public/assets/<snake>.glb; (textured scenes) public/textures/*.png + manifest.json
_assets/<snake>/ (scene) sub-workspaces for blender_glb assets (gitignored)
- _cand/c<k>/ (--candidates N) throw-away best-of-N sub-workspaces (gitignored, kept for the flywheel)
+ _cand/c<k>/ (--candidates N) throw-away best-of-N sub-workspaces (gitignored, kept for the flywheel):
+ each is a round of kind "candidate" — its own events.jsonl, rounds/r00.json, gates/,
+ judge/r00.json (one-sample judge on quick_render views)
stages/<name>.json rounds/rNN.json rounds/candidates.json rounds/aborted_rNN.json (a round the
- budget/a crash cut: what it burned, never resumed from) cost_ledger.jsonl (live ledger)
+ budget/a crash cut: what it burned, never resumed from)
+ telemetry/cost.jsonl live ledger: one row per metered call / CLI session, opened by BaseTrack.run
+ (cost_ledger.jsonl at the root is a relative symlink to it, kept for the run-layout
+ alias; runs before 2026-08-23 have the root file only)
+ run_state.json stages + rounds done; extra carries budget_snapshot and spec_fingerprint only
artifacts/ object.glb object.stl|step robot.urdf meshes/ articulation.json build.json census.json
measurement.json … ; graphics: frames/fNN_tT.png frames_sheet.png preview.gif metrics.json
texturing: object_textured.glb textures/{<id>.png, texture_plan.json, texturing.json, gate/}
@@ -336,7 +356,8 @@ in-loop option with `n_samples ≥ 2` for decisions.
```
plan (structured output, one re-ask) → skeleton (buildable placeholder) → materialise workspace
-[scene only] assets (parallel; blender_glb assets get a sub-workspace + asset_v1 judge + one fix pass)
+[scene only] assets (parallel; blender_glb assets get a sub-workspace + asset_v1 judge + one fix pass; a degraded asset verdict leaves
+ score None / judged False, emits asset.judge_degraded and skips the fix pass)
→ env → zones (parallel) → assemble (deterministic scene.js)
round 0 "baseline": generate → build_with_repair → measure → gates → render → post-render gates → judge
(object tracks, ≥ 8 plan parts, a language with one file per part, an agent backend: the baseline FANS OUT
@@ -355,7 +376,8 @@ repeat while StopPolicy says continue (≤ max_rounds refine rounds, plateau_win
refine tasks = gate ERRORS (fix hints, authoring-frame numbers) ∪ failed must-acceptance ∪ judge improvement plan
(≤ 6 tasks, ≤ 6 compacted instruction lines each; reference runs add an IoU task when silhouette IoU < 0.6)
fan out when ≥ 2 file-disjoint groups AND every task maps to files (threejs/blender parts, scene zones/assets/env)
- generate (NO turn cap by default — 28 was A/B'd and rejected, +$0.02/−0.21 score, docs/COST.md §17;
+ generate (no HARNESS turn cap by default — claude-code runs under AgentJob.max_turns=60 (+6-turn wrap-up),
+ the other vendor CLIs have no turn cap at all; 28 was A/B'd and rejected, +$0.02/−0.21 score, docs/COST.md §17;
a cap a caller sets (CV3D_AGENT_MAX_TURNS / task; no profile sets one) still buys a wrap-up session
that lands a final build + summary instead of being killed) → build+repair (error-focused,
escalates on identical signatures) → gates → … → judge (SKIPPED only where the verdict is never
@@ -448,8 +470,8 @@ $0.02–0.03 (flash) / ~$0.2 (pro); api-agent generation 3–6 min per object ro
trips the budget is not promoted to best — give scenes `--max-minutes 60`.
* Gemini flash 503 storms happen; dead keys and 429s rotate freely now, but a
sustained outage can still fail a round (`3dcv resume` re-uses cached stages).
-* `ffmpeg` absent here → turntables fall back to GIF. A few single-file wrappers
- were once over the old ~400-line guideline; the rule is now a 2 000-line cap (3 000 absolute).
+* A few single-file wrappers were once over the old ~400-line guideline; the rule
+ is now a 2 000-line cap (3 000 absolute).
## 11. Flywheel
diff --git a/harness/docs/COST.md b/harness/docs/COST.md
index 6b193406..f3a1cd26 100644
--- a/harness/docs/COST.md
+++ b/harness/docs/COST.md
@@ -287,9 +287,11 @@ made:**
| verified (no change) | – | every other gemini / anthropic / openai row | now flagged `verified` rather than "approximate" |
| still `inferred` / `unverified` | – | `claude-haiku-4`, `o1-mini`, `gpt-5-codex`, `gpt-5.1-codex`, `gpt-5.2-codex`, `gemini-2.5-flash-image` | not listed on the pricing pages; `3dcv cost prices --unverified` lists them |
-Per-image prices now live in the price table (`Price.image_usd`,
-`IMAGE_USD_BY_SIZE`, `per_image_usd()`), and a test asserts they never drift from
-`models/gemini_image.IMAGE_USD`.
+Per-image prices live in the price table only (`Price.image_usd`,
+`IMAGE_USD_BY_SIZE`, `per_image_usd()`); the duplicate table in the image model is
+gone (2026-08-29) and `GeminiImageModel` prices with `per_image_usd(size=<generated
+px>)` directly — a 2K image was billed 0.067 (the 1K rate) instead of 0.134 until then,
+and a 512 request is billed as the 1K image it actually generates.
**Two costing bugs the audit surfaced** (both in files owned by other engineers —
see the hand-off notes):
@@ -349,7 +351,7 @@ Savings are estimated **on this data set** (61 runs, $86.30) unless stated.
| # | change | est. saving | confidence | where |
|---|---|---|---|---|
| 1 | **Stop refining after r01 unless the last delta ≥ 0.05.** r02+r03 cost $12.16 and bought +1.44 score points across 8 of 20 rounds. | **$9–12 (10–13%)** | high (measured) | `RoundPolicy` (min_delta 0.02 → 0.05 from r02, or plateau_window 1 after r01) |
-| 2 | **Check the budget *before* starting a round, against the estimated round cost**, not only between steps. | **$8.76 (9.7%)** | high (measured waste) | `orchestrator/budget.py` + `tracks/steps.py`; use `codeverse.cost.estimate_call` / median round cost |
+| 2 | **Check the budget *before* starting a round, against the estimated round cost**, not only between steps. | **$8.76 (9.7%)** | high (measured waste) | `orchestrator.py` (`BudgetGuard`) + `tracks/steps.py`; use `codeverse.cost.estimate_call` / median round cost |
| 3 | ~~**Cap agent turns at ~25 and compact old tool results.** 39.3% of the agent bill is turn ≥20; 19 of the 33 sessions that ran ≥50 turns were cut off by their own budget.~~ **Tested, rejected: +$0.02 and −0.21 score** (A/B, n=3 per arm, §17) — the cap is off by default. | est. $8–15, **measured $0** | high (A/B) | `RoundPolicy.agent_max_turns=0`; still settable per caller |
| 4 | **Fold the off-record spend into the budget** (cut rounds, post-hoc texture passes). | $0 saved, **$1.22 of blindness removed** | high | §6; the ledger (`codeverse.cost.record_call`) makes it automatic |
| 5 | **Scene track: 73% of scene spend is assets+zones, 0/5 passed.** Trim the per-zone context (each zone session re-sends the whole scene contract) and judge assets before zones start. | ~$1/run of $2.83 | medium | `tracks/scene*.py` |
@@ -370,11 +372,11 @@ the model, is what makes the artifact), and cheaper judges (§8).
```python
from codeverse.cost import record_call, load_ledger, summarise
-record_call(res.usage, run=ws.slug, round=idx, stage="refine", role="generator",
- label=job.label, outcome=res.exit_reason,
- ledger=ws.root / "cost_ledger.jsonl") # one append-only JSONL row
+with run_ledger(ws.root): # <run>/telemetry/cost.jsonl (cost_ledger.jsonl = symlink alias)
+ record_call(res.usage, run=ws.slug, round=idx, stage="refine", role="generator",
+ label=job.label, outcome=res.exit_reason) # one append-only JSONL row
-rows = load_ledger(ws.root / "cost_ledger.jsonl")
+rows = load_ledger(ws.root) # telemetry/cost.jsonl, else the pre-2026-08-23 root file
summarise(rows).dimension("stage")["judge"].cost_usd
```
@@ -434,9 +436,7 @@ out not to pay.
captioner, texturing and single-shot generation.
* **`MeteredAgent`** wraps everything `agents.get_coding_agent` hands out: it sets
the ambient round/stage for the session (so the rows above land in the right
- bucket), applies whatever turn cap the settings name (only ever *lowering*
- `job.max_turns`; no profile names one — §17)
- and, for a backend whose calls we cannot see (gemini-cli / claude-code / codex /
+ bucket) and, for a backend whose calls we cannot see (gemini-cli / claude-code / codex /
agy), records one session row from `AgentResult.usage`.
**Which backends those are is a property of the backend, not a guess.** The
@@ -457,7 +457,14 @@ label that names a job of its own (`judge:…`, `planner`, `texture_gate`,
bills a model inside a refine session used to land on `stage=refine /
role=generator`; it now lands on its own stage. A *generation* label still yields
to the session, which knows more (best-of-N runs `job.kind="candidate"` while the retired api-agent's
-recorded turns were labelled `api-agent:baseline:tN`).
+recorded turns were labelled `api-agent:baseline:tN`). A session row is filed by the task
+KIND through `cost.types.stage_for_label` (candidate → candidate, zone → zones, compose →
+assemble, rebuild → repair, asset / asset_fix → assets); before 2026-08-29 the scene kinds
+landed in `other`. Candidate generation sessions carry `stage=candidate` with labels
+`baseline_c<k>`; candidate judge money is booked `stage=judge role=judge round_index=0`
+and the pairwise tie-break `stage=judge label=pairwise`. `audit.lost_candidate` counts
+generator sessions only and reads both label forms — `baseline_c<k>` (live) and
+`c<k>:baseline` (reconstructed).
**Who opens a ledger.** `3dcv make` / `3dcv resume` (`cli.main._run_track`),
`3dcv texture pass` (with `create=False`), **and the bench drivers** —
@@ -482,9 +489,12 @@ working — one physical copy. A call made with no run context (a `3dcv judge`
outside a run, a bench script, a notebook) goes to a per-process log under
`<cache_dir>/cost/`; `CV3D_COST_LEDGER=off` disables writing entirely.
-**No double counting.** `BudgetGuard.spend` also knows how to write rows; while
-`cost.instrument.per_call_metering()` is true it skips its own, because the
-per-call rows *are* that dollar with the tokens, cache hits and latency attached.
+**No double counting.** `BudgetGuard` only buckets and enforces; `MeteredAgent` /
+`MeteredChatModel` are the one writer of `telemetry/cost.jsonl`, and `BaseTrack.run`
+opens the run ledger itself. The guard's own aggregate writer and its
+`per_call_metering()` sentinel were deleted 2026-08-29: every production entry point
+(`3dcv make`, the bench drivers) opened `run_ledger` first, so it never wrote there —
+and with `CV3D_COST_LEDGER=off` it wrote anyway, which is now really off.
**Reading it.** `cost.reconstruct.reconstruct_run` prefers a live ledger and
falls back to rebuilding from trajectories / verdicts / events, so
@@ -1241,8 +1251,9 @@ sessions overshot their timeout by 182 s median / 1 154 s p90); a judge sample g
`SAMPLE_BUDGET_S = 240` for all its attempts (the verdict is 42 s p50 / 73 s p90, 50 / 103 s under
the storm; two rounds lost 1 162 s and 927 s to 3 × 300 s timeouts before a second sample answered
in 128 s); the planner 300 s (13.7 s p50 / 32 s p90, max 76 s; the storm-day plan stage waited
-492 s median for 39 s of model time). Anthropic / OpenAI go through `with_retries`, which has no
-deadline (≈ 20 s of backoff at most), so the field is a no-op there.
+492 s median for 39 s of model time). Anthropic / OpenAI go through `with_retries`, which
+since 2026-08-29 takes the same `max_total_s = ChatRequest.max_wait_s` (clipped to
+`RETRY_DEADLINE_S`) and stamps `ModelError.attempts` — the field is honoured on every provider.
*The retry of a 503 is hedged across keys* (`rotate_with_retries(hedge=2)`; `Settings.rate.hedge`,
diff --git a/harness/docs/DECISIONS.md b/harness/docs/DECISIONS.md
index 0359df23..01d5d843 100644
--- a/harness/docs/DECISIONS.md
+++ b/harness/docs/DECISIONS.md
@@ -51,21 +51,29 @@ written) that were accepted because the code works that way and the tests pin it
restored from `run_state.extra.budget_snapshot` (`BudgetSnapshot`: spent usage, billed
USD, call count, per-stage/per-round buckets, cumulative ACTIVE seconds — grace is
deliberately NOT persisted). Prior spend and active minutes still count after a
- resume, so a raised `--max-minutes` grants only the difference; `spent_usage` is mirrored
- for one release, and old run dirs without a snapshot fall back to it (spent only).
+ resume, so a raised `--max-minutes` grants only the difference. The `spent_usage`
+ mirror in `run_state.extra` was dropped 2026-08-29 (write side); the read fallback
+ stays because 531 of 739 `bench/out` run dirs predate `budget_snapshot`.
+ `run_state.extra` carries `budget_snapshot` and `spec_fingerprint` only: the
+ candidate count lives in `spec.options.candidates`, the candidate table in
+ `rounds/candidates.json` (which `record.extra.candidates` is read from).
* **D8 Events carry `event`, not `kind` (Δ).** `EventLog.emit(event, **data)` so payloads
may include `kind=` (round kind). `3dcv status` and tests follow.
-* **D9 `materialize_workspace` returns `Materialized` (Δ).** Callers need codex `-c`
- overrides and the agy fallback text; callers that ignore the return are unaffected.
+* **D9 `materialize_workspace` returns `Materialized` (Δ).** Body files, ignore files,
+ the cookbook path, the MCP command and warnings; callers that ignore the return are
+ unaffected. The codex `-c` overrides are NOT on it (`codex_overrides` was deleted
+ 2026-08-29): the codex backend builds `codex_mcp_overrides(mcp_command)` per session.
The cookbook is copied to `ws/.3dcv/cookbook.md` (gemini-cli cannot read outside the
- workspace); MCP argv uses `sys.executable`.
+ workspace); the MCP argv defaults to `cli_common.default_mcp_command(ws)`, i.e.
+ `sys.executable`, for every backend (the track-side bare-`python` literals are gone).
* **D10 gemini-cli needs a system-settings file (Δ).** api-key auth +
`dynamicModelConfiguration` (else silent model substitution) + `folderTrust.enabled=false`
(else workspace MCP servers are silently disabled even with `--skip-trust`). Served
model is checked; mismatch → `exit_reason=model_substituted`.
-* **D11 AgentJob carries typed fields; `extra` is back-compat only (Δ, revised 2026-08-27).**
- `round`, `kind`, `files_hint`, `language`, `track` are typed `AgentJob` fields;
- `contracts/agent.py::_lift_legacy_extra` lifts old `extra` payloads into them.
+* **D11 AgentJob carries typed fields only (Δ, revised 2026-08-29).**
+ `round`, `kind`, `files_hint`, `language`, `track`, `read_only`, `mcp_command` … are
+ typed `AgentJob` fields; the `extra` dict and its `_lift_legacy_extra` shim (and the
+ unused `model` field) were deleted 2026-08-29 — nothing in the tree built one.
* **D12 api-agent exposes `build` under its real name; `run_build` is an alias (Δ).**
* **D13 Node ESM resolution via an import hook (Δ).** `NODE_PATH` cannot resolve bare ESM
specifiers; `run_node(three_hook=True)` adds `--import runtime_js/lib/resolve_three.mjs`;
@@ -233,7 +241,30 @@ written) that were accepted because the code works that way and the tests pin it
generated bpy file made CPython 3.11's `ast.parse` raise `SystemError` and the round died
in `build_once`. Decision: `_ast_lint.safe_parse` catches SyntaxError / RecursionError /
SystemError / MemoryError / ValueError; every python lint reports a lint ERROR with a
- flatten-the-literal hint instead.
+ flatten-the-literal hint instead. The forbidden-import floor is one set:
+ `_ast_lint.BASE_FORBIDDEN_IMPORTS` (pickle, threading, importlib, webbrowser, ftplib,
+ smtplib, …) — since 2026-08-29 urdf's `model.py` lint is on it too (those became
+ ERRORs there) plus an explicit allow-list `{bpy, bmesh, mathutils, math, random, numpy}`;
+ anything else imported is a WARN, a `codeverse` self-import an ERROR.
+* **D44 The 2026-08-29 cleanup: delete, do not relocate (owner).** Context: an external
+ review of `codeverse` proposed executor / policy abstractions (a `RoundExecutor`, a
+ `CandidateRunner`, a metering seam, a per-track prompt-policy object). Decision: all
+ rejected — each moved code between files without deleting any (L4: a merge must delete).
+ What was done instead: (a) **candidates are rounds** — `run_candidate` / `quick_judge`
+ went, a best-of-N candidate is `steps._run_round(kind="candidate")` in its sub-workspace
+ with two knobs (`render=quick_render`, `geometry_views=False`), its own `events.jsonl`
+ and a one-sample judge; (b) **one ledger writer** — `BudgetGuard` buckets and enforces
+ only, `MeteredAgent` / `MeteredChatModel` write `telemetry/cost.jsonl`, and
+ `BaseTrack.run` opens the run ledger itself (`per_call_metering`, `_ledger_row`,
+ `run_ledger_path` deleted; `CV3D_COST_LEDGER=off` now really writes nothing);
+ (c) **a garbage env flag is OFF** — `config.env_flag` reads on/off/1/0/true/false/yes/no;
+ unset or empty is the caller's fallback (usually the Settings value), but an unparseable
+ value warns and reads as OFF, so a typo in a bench command is a control run, never a
+ silent arm (and never the variant, which a fallback of `True` would have handed it); (d) one MCP command (`default_mcp_command`, `sys.executable`),
+ one JSON-envelope finder, one union-find, one sha256, one `ask_structured`, one
+ `RENDER_MODES`; the retired mechanisms (`3dcv migrate-runs`, turntables + ffmpeg, the
+ `CV3D_SYSPROMPT=v0` arm, `shader_presence` / counterfactual renders, the in-process
+ turn-cap backstop, the concurrent-session registry) are gone with their docs.
## Rejected / deferred
diff --git a/harness/docs/EVAL.md b/harness/docs/EVAL.md
index 9a33c0df..121a4132 100644
--- a/harness/docs/EVAL.md
+++ b/harness/docs/EVAL.md
@@ -526,9 +526,18 @@ under `bench/out/`.
## Judge experiments log
+**2026-08-29 — profiles and the detail round.** `RoundPolicy.detail_rounds` is tri-state
+(`None` = the track default, `lifecycle.DEFAULT_DETAIL_ROUNDS=1` where supported; `0` = off).
+Until this date a profile that injected a `judge_samples>1` policy (economy, quality)
+silently zeroed the static track's surface-detail round while balanced kept it; all
+three profiles now get it, and `CV3D_DETAIL_ROUNDS` remains the A/B switch. Any
+economy/quality-vs-balanced comparison straddling this commit compares different
+round counts.
+
**2026-08-29 — per-language system prompts: NULL, three independent A/Bs.** The
one-line system prompts were replaced with evidence-grounded ones mined from each
-language's recorded failure corpus (`CV3D_SYSPROMPT=v0` keeps the old ones). Three
+language's recorded failure corpus (the `CV3D_SYSPROMPT=v0` arm kept the old ones for
+the A/B; arm and `system_v0.md` files were deleted 2026-08-29 after the null). Three
paired A/Bs all read null: glsl CLI (n=10/arm, Δ+0.003, within-arm σ 0.18), blender
single-shot (8 pairs, paired Δ−0.027), blender CLI on 3.6-flash (10/10 pairs, paired
Δ−0.036, 4W/2T/4L, paired σ 0.403 — per-brief swings up to ±0.9 dwarf any prompt
diff --git a/harness/docs/INSTALL.md b/harness/docs/INSTALL.md
index d6dcdf65..201b8752 100644
--- a/harness/docs/INSTALL.md
+++ b/harness/docs/INSTALL.md
@@ -26,10 +26,10 @@ Once installed, read `docs/RUNBOOK.md` (how to run), `docs/ARCHITECTURE.md`
git clone <repo> 3dcodeverse && cd 3dcodeverse
python3 -m venv .venv && source .venv/bin/activate # see §3 — a distro python3 is
# PEP 668 and pip will refuse it
-bash harness/scripts/setup.sh # python + node deps + chrome + doctor
+bash harness/setup.sh # python + node deps + chrome + doctor
```
-`scripts/setup.sh` is idempotent — it checks the interpreter versions, runs
+`setup.sh` is idempotent — it checks the interpreter versions, runs
`pip install -e 'harness[all,dev]'`, runs `npm ci` in `runtime_js/` **only when the
lockfile actually moved**, makes sure puppeteer's Chrome is downloaded, and
finishes by printing `3dcodeverse doctor`. Useful flags:
@@ -61,13 +61,13 @@ workflow, so the offline suite and `ruff` are run locally before every push (see
| component | version | how it is enforced | notes |
|---|---|---|---|
-| **python** | **3.13** | `requires-python = ">=3.13"`; ruff `target-version = "py313"`; `PY_FLOOR` in `tests/core/test_portability.py`; `MIN_PY_MINOR` in `scripts/setup.sh` | the four places are pinned together by the portability test |
+| **python** | **3.13** | `requires-python = ">=3.13"`; ruff `target-version = "py313"`; `PY_FLOOR` in `tests/core/test_portability.py`; `MIN_PY_MINOR` in `setup.sh` | the four places are pinned together by the portability test |
| **node** | **20.6.0+** (developed on 24 LTS) | `runtime_js/package.json` `engines.node`; `codeverse.spatial.node.NODE_MIN` fails every node workload with an actionable message | 20.6 is the `--import` module-hook floor |
| **Blender** | 4.2+ (developed on 5.0.1) | runtime probe only (`Settings.resolve_blender()`) | `blender` / `urdf_blender` are the only users |
| **OS** | Linux x86_64 (WSL2 Ubuntu here) | — | macOS should work (nothing is Linux-specific except `resource.setrlimit` guards) but is not tested |
-The offline suite on this box, 2026-08-29: **2615 passed of the 2627 selected** (12 skipped are
-data-dependent, 28 deselected are `live`).
+The offline suite on this box, 2026-08-29: **1928 passed of the 1928 selected**
+(25 deselected are `live`).
Moving to another Python later is the same four-line change (`requires-python`, ruff
`target-version`, `PY_FLOOR`, `MIN_PY_MINOR`).
@@ -77,11 +77,10 @@ Moving to another Python later is the same four-line change (`requires-python`,
| what | required? | verified here | how it degrades without it |
|---|---|---|---|
| **Python 3.13** | yes | 3.13.9 (`/home/yipeng/miniconda3/bin/python`) | nothing runs; `requires-python = ">=3.13"` (§2.1) |
-| **pip + venv** | yes | pip 25.3, `python -m venv` | `scripts/setup.sh` cannot install the package. A stock Debian/Ubuntu `/usr/bin/python3` ships **without** pip and is PEP 668 `EXTERNALLY-MANAGED`, so `pip install -e harness` refuses even once pip is present: `sudo apt install python3-venv python3-pip`, then use a virtualenv |
+| **pip + venv** | yes | pip 25.3, `python -m venv` | `setup.sh` cannot install the package. A stock Debian/Ubuntu `/usr/bin/python3` ships **without** pip and is PEP 668 `EXTERNALLY-MANAGED`, so `pip install -e harness` refuses even once pip is present: `sudo apt install python3-venv python3-pip`, then use a virtualenv |
| **git** | yes | 2.53.0 | run workspaces are git repos (one commit per round); `Workspace.create()` and the flywheel trajectory/pair miners fail |
| **node ≥ 20.6** | yes, except for the `graphics` track | v24.14.0 (npm 11.9.0) | the `threejs` / `scene_threejs` languages disappear **and no object renders happen at all**: `spatial/render.py` renders *every* GLB (Blender-built and CadQuery-built included) with three.js in headless Chrome. Only `graphics` (moderngl) is node-free |
| **Blender 4.2+ / 5.x** | optional | 5.0.1 (`~/.local/bin/blender-5.0`) | `blender` and `urdf_blender` languages unavailable → the `static_object` default language and the whole `articulated_object` track cannot build (`BlenderNotFoundError`); scenes lose planner-chosen bpy GLB assets |
-| **ffmpeg** | optional | **not installed** | `render_turntable` silently writes an animated **GIF** via PIL instead of `.mp4` (`spatial/turntable.py`); nothing else changes |
| **EGL-capable GPU stack** | optional | ANGLE / D3D12 / RTX 5090 Laptop | headless Chrome falls back to **SwiftShader** and moderngl to **llvmpipe** — everything still renders, just several times slower; no correctness change |
| C toolchain | usually no | — | only if pip has to build a wheel from source (`python-fcl`, `manifold3d` ship wheels for cp310–cp313 x86_64) |
@@ -105,7 +104,7 @@ import package `codeverse`, CLIs `3dcodeverse` and `3dcv`). See the repo
Use a virtualenv (or a conda env — this box installs into a conda base env). It is
only optional when your interpreter already owns its site-packages: a distro
`/usr/bin/python3` is PEP 668 `EXTERNALLY-MANAGED` and pip will refuse to install into
-it. `scripts/setup.sh` checks for pip and for that marker up front and tells you which
+it. `setup.sh` checks for pip and for that marker up front and tells you which
of the two you hit.
```bash
@@ -210,7 +209,7 @@ You need to re-run it when:
* you pulled a change to `runtime_js/package.json` / `package-lock.json`, or
* `3dcodeverse doctor` reports `three` or `puppeteer` FAIL.
-`scripts/setup.sh` automates exactly that test: it compares the mtime of
+`setup.sh` automates exactly that test: it compares the mtime of
`package-lock.json` against `node_modules/.package-lock.json` and skips the
reinstall when nothing moved (`--force-npm` overrides).
@@ -408,7 +407,6 @@ runs_dir: /data/runs
cache_dir: /data/cache/codeverse
binaries:
blender: /home/yipeng/.local/bin/blender-5.0
- ffmpeg: ffmpeg
render:
gpu: auto # auto | on | off
width: 768
@@ -465,7 +463,6 @@ Real output on this box (exit code 0; any FAIL row makes it exit 1):
│ codex │ OK │ codex-cli 0.149.0 │
│ agy │ OK │ 1.1.19 │
│ git │ OK │ git version 2.53.0 │
-│ ffmpeg │ WARN │ not found (turntable mp4 disabled) │
│ mcp │ OK │ mcp + codeverse.spatial.mcp_server importable │
└───────────────┴────────┴─────────────────────────────────────────────────────┘
```
@@ -497,7 +494,6 @@ that the keys work end to end):
| `anthropic key` / `openai key` | WARN | not set | expected unless you use `anthropic:*` / `openai:*`; export the key to clear it |
| `gemini-cli` / `claude` / `codex` / `agy` | WARN | CLI not on `PATH` | optional (§8.2); only that `--generator` is unavailable |
| `git` | FAIL | git missing | install git — run workspaces are git repos |
-| `ffmpeg` | WARN | not found | optional; turntables become GIFs. `sudo apt-get install ffmpeg` (or `conda install -c conda-forge ffmpeg`) |
| `mcp` | WARN | `mcp` package or the server module missing | `pip install -e 'harness[mcp]'`; only affects the agentic CLI backends |
| `gemini live call` (`--live`) | FAIL | key rejected / no network | check the key value and outbound access; a `503 … high demand` is transient, not an install problem |
| `gemini quota` | OK | always informational | the per-key RPM/TPM the pool schedules against x the number of keys (`Settings.rate`, docs/COST.md Part III); tune with `CV3D_RATE__TPM_PER_KEY` / `CV3D_RATE__MAX_IN_FLIGHT` |
@@ -600,6 +596,5 @@ those by hand (`npm rm -g @google/gemini-cli @anthropic-ai/claude-code @openai/c
| Chrome (puppeteer) | 148.0.7778.97 (+ headless-shell) | `~/.cache/puppeteer` |
| Blender | 5.0.1 (2025-12-16) | `~/.local/bin/blender-5.0` → `~/3dcodeverse_data/tools/blender-5.0.1-linux-x64` |
| git | 2.53.0 | `/usr/bin/git` |
-| ffmpeg | not installed | — |
| gemini-cli / claude / codex / agy | 0.53.0 / 2.1.241 / 0.149.0 / 1.1.19 | npm global / `~/.local/bin` |
| GPU (Chrome WebGL) | ANGLE · D3D12 · NVIDIA GeForce RTX 5090 Laptop GPU · OpenGL ES 3.1 | via `--use-angle=gl-egl` + Mesa d3d12 |
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 177d4271..aa3d4e21 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -2,7 +2,8 @@
This file lists the signatures other packages may rely on. Types live in
`codeverse/contracts/`; protocols in `models/base.py`, `agents/base.py`,
-`languages/base.py`, `spatial/registry.py`, `judges/base.py`, `tracks/__init__.py`.
+`languages/base.py`, `spatial/registry.py`, `tracks/__init__.py` (judges are
+duck-typed `.judge(JudgeInput) -> Judgment`; `judges/base.py` defines no protocol).
Where the build deviated from the original plan the deviation is called out as
**Δ** — see `docs/DECISIONS.md` for the why. When in doubt the code wins; this
file was reconciled against it on 2026-08-23 (waves 2–3 + fix batch 1).
@@ -17,8 +18,10 @@ file was reconciled against it on 2026-08-23 (waves 2–3 + fix batch 1).
inside `tracks/generation.py` (`is_single_shot`, `single_shot_model_id`); never
registered in `agents/`. `Spec.backends.generator` accepts any of the three.
* Image models: `models/gemini.py::GeminiImageModel` (default
- `gemini-3.1-flash-image`, fallback `gemini-2.5-flash-image`) behind the
- `ImageModel` protocol (`generate`, `generate_with_usage` → `(images, Usage)`).
+ `gemini-3.1-flash-image`, fallback `gemini-2.5-flash-image`); the one entry point
+ is `generate_with_usage(prompt, *, size=1024, n=1, seed=None, reference_images=(),
+ max_wait_s=None) -> (images, Usage)`, priced per GENERATED image via
+ `pricing.per_image_usd(size=<generated px>)` (no `ImageModel` protocol, no `generate`).
## core (contracts · config · proc)
@@ -30,7 +33,8 @@ GateFinding.as_line(with_gate=False, with_severity=False, with_target=False, wit
# "GATE <gate>: [<sev>] <message> [<target>] FIX: <hint>" — flags opt in; no leading "- "
RenderView.judge: bool | None # stamped True/False at render time; None = legacy round (fall back to select_judge_views)
RenderSet.out_dir: str # directory the views (+ views.json/metrics.json) were written to ("" on old rounds)
-from codeverse.config import get_settings
+from codeverse.config import get_settings, env_flag # env_flag(env, fallback) -> bool: on/off/1/0/true/false/yes/no;
+ # unset/empty -> fallback; garbage -> warning + fallback (Settings value), never a silent switch
get_settings().backends(planner=..., generator=..., judge=..., captioner=...) -> Backends
# settings defaults (default_planner/... mirror contracts Backends literals; + default_captioner);
# truthy keyword overrides win, None/"" falls through, unknown role -> TypeError
@@ -63,9 +67,15 @@ from codeverse.models.retry import KeyPool, KeyPoolExhausted
KeyPool(keys, *, rpm_per_key=900, tpm_per_key=None, cooldown_s=30, dead_cooldown_s=3600)
pool.acquire(*, tokens_hint=0, exclude=None, timeout_s=120) -> key # raises immediately when every key is dead/cooling past the deadline
pool.try_acquire(*, tokens_hint=0, exclude=None) -> key | None # never waits (a hedged retry's extra key); holds a slot like acquire
-pool.report(key, "ok"|"429"|"5xx"|"error"|"dead", *, tokens=0, retry_after_s=None) # Δ "dead": health 0, benched dead_cooldown_s, re-probed after
+pool.report(key, "ok"|"429"|"5xx"|"error"|"dead"|"skip", *, tokens=0, retry_after_s=None) # Δ "dead": health 0, benched dead_cooldown_s,
+ # re-probed after; "skip" (a content failure the key did not cause) reconciles tokens only — health and counters untouched
+from codeverse.models.retry import with_retries, rotate_with_retries, RETRY_DEADLINE_S
+with_retries(fn, *, is_retryable, attempts=6, base_delay=1.0, max_delay=3.0, max_total_s=None, ...) # max_total_s =
+ # ChatRequest.max_wait_s clipped to RETRY_DEADLINE_S on every provider; stops before a backoff would cross it, stamps ModelError.attempts
from codeverse.models.pricing import estimate_cost # (provider, model, usage) -> usd (unknown model -> 0.0 + one warning)
from codeverse.models.schema_utils import to_gemini_schema, to_openai_strict_schema, to_anthropic_schema, parse_json_lenient
+from codeverse.models.schema_utils import ask_structured # (model, Schema, *, system, text, images=(), temperature, label)
+ # -> (obj | None, Usage, err): one schema-bound call; call failure and parse failure are the same `err` family
```
Backends: `GeminiModel(model, *, keys=None, pool=None, ...)` (one shared KeyPool per
key list), `AnthropicModel(model, *, json_mode="tool"|"output_config")`,
@@ -98,20 +108,22 @@ record_call(usage, *, run="", round=None, stage=None, role=None, label="", backe
outcome="ok", latency_ms=None, n_calls=1, source="live", ledger=None, reprice=False) -> CallCost
# Δ everything left out is resolved from the ambient context + the call label (cost.context);
# unknown model -> $0 and price_source="unknown" (flagged, never silently dropped); never raises.
-from codeverse.cost.instrument import (run_ledger, metered_chat_model, metered_agent,
- per_call_metering, meters_own_calls, IN_PROCESS_AGENT_KINDS)
+from codeverse.cost.instrument import (run_ledger, metered_chat_model, metered_agent, meters_own_calls,
+ MeteredAgent, MeteredChatModel, metering_enabled)
with run_ledger(ws.root, run=slug): # binds the run, points record_call at <run>/telemetry/cost.jsonl
... # (+ a <run>/cost_ledger.jsonl symlink for the run-layout alias)
# NESTS (restores the outer ledger + run binding on exit) and is context-local first, so
- # bench.run_bench / compare_backends can hold one ledger per prompt across N threads
+ # bench.run_bench / compare_backends can hold one ledger per prompt across N threads.
+ # BaseTrack.run opens `run_ledger(ws.root, run=ws.root.name)` ITSELF, so a track run started
+ # outside the CLI/bench still meters; the CLI/bench ledger for the same run dir is the same file.
# models.get_chat_model returns a MeteredChatModel → ONE row per ChatModel.generate
- # agents.get_coding_agent returns a MeteredAgent → ambient round/stage for the session, the
- # profile's turn cap (only ever LOWERS job.max_turns), and — iff NOT meters_own_calls(agent),
- # a declaration no shipped backend makes — one session row.
+ # agents.get_coding_agent returns a MeteredAgent (registry wrap, from the first call) → ambient
+ # round/stage for the session and — iff NOT meters_own_calls(agent), a declaration no shipped
+ # backend makes — one source='session' row (n_calls, latency, outcome, AgentResult.turns).
+ # These two are the ONLY ledger writers; BudgetGuard writes no row.
# The rule is the BACKEND, never "did a row get written while it ran": a CLI session with one
# in-process tool call used to be dropped entirely, an in-process session whose turns ran in
# another thread used to be counted twice. A backend may declare `meters_own_calls`.
-per_call_metering() -> bool # aggregate writers (BudgetGuard) skip their row while True
from codeverse.cost.context import CallContext, call_context, bind_run, context_from_label, SELF_DESCRIBING
# precedence: explicit > a label naming a job of its OWN (SELF_DESCRIBING = plan/judge/pairwise/
# texture/caption) > ambient (call_context) > the rest of the label > nothing. A judge or a
@@ -145,24 +157,27 @@ reconstructed, so all 61 recorded runs keep auditing.
```python
from codeverse.agents import get_coding_agent # (agent_id) -> CodingAgent .run(job) .available() .id .kind .model
from codeverse.agents.materialize import materialize_workspace, Materialized, codex_mcp_overrides
-materialize_workspace(ws, *, agent_kind, contract_md, cookbook_rel, spatial_tools, mcp_command) -> Materialized
+materialize_workspace(ws, *, agent_kind, contract_md, cookbook_rel, spatial_tools, mcp_command=None) -> Materialized
+# mcp_command defaults to cli_common.default_mcp_command(ws) = [sys.executable, -m codeverse.spatial.mcp_server --workspace …]
+# (None/[] = the default — no ValueError); tracks/common.Services.materialize takes no mcp_command
# writes AGENTS.md + GEMINI.md + CLAUDE.md (same body), ws/.3dcv/cookbook.md (Δ copied in: gemini-cli cannot read
# outside the workspace), .geminiignore/.aiexclude, and MCP wiring:
# gemini-cli → ws/.gemini/settings.json only gets context.fileFiltering.respectGitIgnore=false; the 3dcv server
# and mcp.allowed live in the per-session system settings (Δ that file is agent-writable — audit 2026-08-27)
-# claude-code → trajectories/<label>_rNN/mcp.json codex → Materialized.codex_overrides:
+# claude-code → trajectories/<label>_rNN/mcp.json codex → codex_mcp_overrides(mcp_command) built PER SESSION:
# -c mcp_servers.3dcv.command=… -c mcp_servers.3dcv.args=[…] -c mcp_servers.3dcv.default_tools_approval_mode="approve"
# (Δ without the approval mode every MCP tool call is elicited and auto-cancelled)
# agy → no per-workspace MCP; body documents `3dcv tools <name> --json … --workspace .` as the fallback
res = agent.run(AgentJob(workspace=..., prompt=..., label="baseline", timeout_s=1800, max_turns=60,
- spatial_tools=True, write_roots=["src","public"], extra={...}))
+ spatial_tools=True, write_roots=["src","public"])) # typed kwargs only: no extra=, no model=
res.ok, res.exit_reason # completed | timeout | error | budget | model_substituted
+res.turns # claude-code num_turns · codex turn.completed count · agy num_turns · gemini-cli 0 (not on the wire)
res.files_changed (git-derived, attributed per session), res.usage, res.transcript_path, res.tool_calls, res.errors
```
`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),
+expected to touch — used to attribute `files_changed`; harness-owned paths are dropped;
+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 the
session may read but never write — `contracts.common.HARNESS_OWNED_SRC[language]`, i.e.
@@ -191,11 +206,13 @@ rt.language; rt.entry_globs
rt.lint(ws) -> GateReport # gate = "lint:<language>"
rt.build(ws, *, timeout_s=None, **per_runtime) -> BuildResult # Δ BuildResult.error_file is WORKSPACE-relative for
rt.skeleton(ws, plan) -> list[Path] # every runtime ("src/model.py", "src/parts/leg.py", "src/helpers.py")
-rt.contract_doc() -> str ; rt.cookbook_path() -> Path
+rt.contract_doc() -> str # cookbook path: tracks/common.cookbook_rel_for (no runtime hook)
+BuildResult.error_type spellings (languages/_common.py): MISSING_ENTRY = "MissingEntryFile" (every runtime, threejs'
+ export_glb.mjs included) · BUILD_TIMEOUT = "BuildTimeout" (compose_build_result, threejs, urdf)
```
| runtime | entry_globs | notes / artifacts |
|---|---|---|
-| `BlenderRuntime` | `src/model.py`, `src/parts/*.py` | **Δ multi-file**: `file_for_part(name) -> "src/parts/<snake>.py"` (`def build_<snake>()`), `file_for_target(target) -> list[str]`; lint = `layout.lint_workspace` over every src/*.py; skeleton writes model.py + per-part files; object.glb/stl, build.json, census.json |
+| `BlenderRuntime` | `src/model.py`, `src/parts/*.py` | **Δ multi-file**: `file_for_part(name) -> "src/parts/<snake>.py"` (`def build_<snake>()`); lint = `layout.lint_workspace` over every src/*.py; skeleton writes model.py + per-part files; object.glb/stl, build.json, census.json |
| `CadQueryRuntime` | `src/model.py` | trailing selector on the stack → parent solid exported + warning (ExportError when no solid exists); helper-module errors map to `src/<file>.py:line`; object.glb/stl/step |
| `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 |
@@ -226,7 +243,8 @@ are the pure helpers `3dcv doctor` reuses for its `node` row.
`build_last.json`/`build.json` says the last build failed — tools never measure or
texture a stale GLB; missing/unreadable status stays permissive (hand-placed GLBs).
```python
-from codeverse.spatial.render import render_glb, render_turntable
+from codeverse.spatial.render import render_glb
+from codeverse.contracts.artifacts import RENDER_MODES # ('shaded','wire','normals','silhouette','clay') — THE mode tuple (no 'depth')
render_glb(glb, out_dir, *, views=None, mode="shaded|wire|normals|silhouette|clay", width=768, height=768,
isolate=None, explode=0.0, sheet=True, background=..., anim_time=None, shadow=True, gpu=None,
timeout_s=None, use_cache=True) -> RenderSet
@@ -243,7 +261,7 @@ frame_gate_from_renders(renders) -> GateReport # gate "scene_frames"; da
from codeverse.spatial.measure import measure_glb # link-hierarchy rule: metadata["links"] → each link is its own part
# Δ Measurement.extra["complexity"] = ComplexityVector.model_dump() (additive, best-effort, never raises)
from codeverse.spatial.complexity import (ComplexityVector, COMPLEXITY_WEIGHTS, COMPLEXITY_VERSION,
- complexity_of_glb, complexity_of_parts, complexity_summary_line, band_of)
+ complexity_of_glb, complexity_of_parts, band_of)
complexity_of_glb(glb) -> ComplexityVector # part_count, assembly_depth, tri_count, materials, silhouette,
# feature_density, symmetry_groups, hollowness, + index 0-1 (documented weights) and band
# (trivial|simple|moderate|complex|intricate). Deterministic, no VLM/render. docs/COMPLEXITY.md
@@ -255,8 +273,11 @@ check_placement(ws, *, indoor=None, force_probe=False) -> GateReport # gate "s
# unsupported | interpenetration | summary | probe_failed; target "Zone/Asset" (routes to src/zones/<zone>.js);
# messages carry the scene_v1 floating_part cap words; reads artifacts/census.json["placement"] (host_placement.mjs)
placement_gate_safe(census, *, plan=None) -> GateReport | None # round gate: None without a table, WARN on failure, never raises
+from codeverse.spatial.scene_placement import setting_text # (plan: dict | model) -> the indoor/outdoor setting line
from codeverse.spatial.silhouette import compare_silhouette
from codeverse.spatial.joints import load_urdf, fk, sweep_collisions, urdf_to_glb, render_poses # RESERVED_LINK_NAMES={'world'}
+from codeverse.spatial.joints_collide import components # (names, edges) -> list[set[str]]: THE union-find (connectivity + sweep)
+# the joint_sweep TOOL body lives in spatial/tools.py (no joint_sweep_observation helper; render_poses takes no renderer=)
# joints_collide.py: deterministic penetration (oriented islands + fixed-direction parity ray test; python-fcl is a
# core dependency, the trimesh fallback is deterministic too)
from codeverse.spatial.gl_render import GlHost, GlResult, GlHostError, write_contact_sheet, write_gif
@@ -279,7 +300,7 @@ from codeverse.judges.vlm_judge import VlmJudge
VlmJudge(rubric="static_object_v1", model_id=None (settings.default_judge = gemini-3.1-pro-preview), n_samples=1,
temperature=0.2, *, thinking="low", max_attempts=3, max_montages=3, detail_crops=2, max_px=1024, sample_budget_s=240,
chat_model=None, cache_dir=None, label="judge") # Δ max_images is GONE → montage budget
-VlmJudge.judge(inp, *, geometry_views: RenderSet | None = None) -> Judgment # also reads inp.geometry_views
+VlmJudge.judge(inp) -> Judgment # clay/normals views travel ONLY as JudgeInput.geometry_views (no kwarg)
from codeverse.judges.base import JudgeInput # (spec, renders, measurement=None, gates=[], acceptance=[], plan_summary="",
# round_index=0, previous=None, extra_context="", geometry_views=None)
from codeverse.judges.prompt_builder import plan_montages, render_montage, Montage # ≤3 2×2 montages (shaded/geometry/poses) + ≤2 detail
@@ -309,7 +330,8 @@ must-acceptance`; gate authors set `GateFinding.data["kind"]` so caps match prec
from codeverse.tracks import get_track
rec = get_track(spec.track, **options).run(spec, ws, resume=False) -> RunRecord # Δ kwargs forwarded to the constructor:
# services=, judge=, agent=, model=, runtime=, policy=RoundPolicy, settings=, planner_model=, n_candidates=
-# (CLI --candidates > run_state.extra > settings.default_candidates); StaticObject | Articulated | Scene | Graphics
+# (CLI --candidates > spec.options.candidates > settings.default_candidates); StaticObject | Articulated | Scene | Graphics
+TrackPipeline.run(spec, ws, *, resume=False, force=False) -> RunRecord
from codeverse.orchestrator import RoundPolicy, StopPolicy, StopDecision, BestSelector, judge_sigma, \
best_score, last_gain, REWRITE_KIND, build_refine_instructions, compact_instructions
RoundPolicy(max_rounds=4, plateau_window=2, min_delta=0.02, target=0.8, judge_on_gate_errors=True, max_refine_tasks=6,
@@ -317,29 +339,36 @@ RoundPolicy(max_rounds=4, plateau_window=2, min_delta=0.02, target=0.8, judge_on
pairwise_min_confidence=0.6, judge_samples=1,
judge_model="", regression_sigma=1.0, regression_allow_switch=True, # money stops (docs/COST.md §5)
marginal_sigma=1.5, marginal_from_round=3, # r03+ must beat 1.5σ
- agent_max_turns=0, agent_wrapup_turns=6, # 0 = UNCAPPED: a 28-turn cap was A/B'd
- # and rejected (+$0.02, −0.21 score, docs/COST.md §17); wrapup applies to a cap a caller sets
- detail_rounds=0, detail_min_score=0.45, detail_bbox_tol_m=0.005 # surface-detail round;
- # 0 here, raised to 1 by lifecycle.detail_round_budget for tracks with supports_detail_round
- # ($CV3D_DETAIL_ROUNDS overrides both — the A/B switch)
- ).with_candidates(n).with_judge(spec.backends.judge)
+ agent_max_turns=0, agent_wrapup_turns=6, # 0 = the backend's own AgentJob.max_turns (claude-code 60
+ # +6 wrap-up; gemini-cli/codex/agy no turn cap); a 28-turn cap was A/B'd and rejected (+$0.02, −0.21
+ # score, docs/COST.md §17); wrapup applies to a cap a caller sets
+ detail_rounds=None, detail_min_score=0.45, detail_bbox_tol_m=0.005 # surface-detail round, tri-state:
+ # None = the track default (lifecycle.DEFAULT_DETAIL_ROUNDS=1 when supports_detail_round, else 0),
+ # 0 = off, N = N; $CV3D_DETAIL_ROUNDS overrides all (the A/B switch). Injected policies keep it.
+ ) # lifecycle.build_context binds n_candidates + judge_model with ONE dataclasses.replace;
+ # RoundPolicy.target is ALWAYS overridden by the rubric pass threshold in BaseTrack.after_plan
policy.sigma / .regression_delta / .marginal_delta # judge_sigma() reads cost.routing.JUDGE_NOISE — THE σ table
StopPolicy(policy).evaluate(history, budget_ok=True) -> StopDecision(reason, strategy="same"|"switch"|"detail", detail)
- # .decide(...) -> StopReason is unchanged; strategy "switch" = ONE whole-artifact rewrite round (kind REWRITE_KIND),
+ # (.reason is the StopReason); strategy "switch" = ONE whole-artifact rewrite round (kind REWRITE_KIND),
# "detail" = ONE surface-detail round (kind DETAIL_KIND) — a plateau/diminishing stop is converted into it
# only when detail_blocked(history, policy) == "" (clean gates, built, judged, within σ of best, budget left)
-from codeverse.orchestrator import DETAIL_KIND, kind_for_strategy, detail_blocked # THE strategy → kind map
+from codeverse.orchestrator import DETAIL_KIND, KIND_FOR_STRATEGY, detail_blocked # THE strategy → kind dict
from codeverse.orchestrator import BudgetGuard, usage_delta
-BudgetGuard(budget, *, soft_fraction=1.0, run="", ledger=None)
- .spend(usage, *, stage="other", role=None, label="", round_index=None, outcome="ok", enforce=True)
- # THE door every dollar goes through: accumulate → bucket by stage/round → one priced ledger row
- # (skipped when cost.instrument.per_call_metering() already writes them) → enforce the ceilings.
- # charge(...) = spend(enforce=True); add(...) = spend(enforce=False) — "not enforced" never means "not seen".
- .by_stage / .by_round / .round_costs(i) / .stage_summary() / .mark() # what a round burned, live
+BudgetGuard(budget, start_time=None, *, soft_fraction=1.0) # no run= / ledger=
+ .charge(usage, *, stage="other", role=None, label="", round_index=None, outcome="ok", enforce=True)
+ # THE door every dollar goes through: accumulate → bucket by stage/round → enforce the ceilings.
+ # It writes NO ledger row: cost.instrument.MeteredAgent (one source='session' row per CLI session) and
+ # MeteredChatModel (one row per call) are the only writers of telemetry/cost.jsonl.
+ # add(...) = charge(enforce=False) — "not enforced" never means "not seen".
+ .by_stage / .by_round[i] / .stage_summary() / .mark() # what a round burned, live
from codeverse.tracks.candidates import CandidateRecord, rank_candidates, decide_best # pure decision logic
-from codeverse.tracks.candidates import run_best_of_n, choose_best_round # N parallel baselines in <ws>/_cand/c<k>
-# (quick 4-view judge, crashed candidate retried once; selection by build_ok → quick score → fewer gate errors, pairwise
-# within margin); winner copied back, normal r00 pipeline follows; rounds/candidates.json + record.extra["candidates"]
+from codeverse.tracks.candidates import run_best_of_n, choose_best_round, quick_render # N parallel baselines in <ws>/_cand/c<k>
+# each candidate IS steps._run_round(kind="candidate") in its sub-workspace: render=quick_render(ctx, round_index, build,
+# measurement, *, pipeline) (4 views + the articulated pose views), geometry_views=False, its own events.jsonl and a
+# one-sample judge → _cand/c<k>/judge/r00.json (a degraded verdict stays score None); crashed candidate retried once;
+# selection by build_ok → quick score → fewer gate errors, pairwise within margin (booked stage=judge label="pairwise");
+# winner copied back, normal r00 pipeline follows; rounds/candidates.json IS record.extra["candidates"] (n, selected,
+# candidates[], pairwise)
from codeverse.tracks.articulated_object import default_motion_checks, expected_direction # gate "motion_direction"
from codeverse.tracks.static_object import silhouette_gate, reference_refine_tasks # gate "reference_silhouette" (IoU<0.6 → WARN + refine task)
from codeverse.tracks.depth import depth_budget, DepthBudget, scope_groups, PartScope, interfaces_text, \
@@ -358,7 +387,7 @@ from codeverse.tracks.prompting import base_prompt_context, reference_images, fi
from codeverse.tracks.prompting import select_cookbook_chapters, 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)
-from codeverse.tracks.graphics_recipes import seed_recipes, graphics_brief, cookbook_functions, EXTRA_KEY, RECIPES_REL
+from codeverse.tracks.graphics 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
# the HARNESS-OWNED src/recipes.glsl (RECIPES_REL; header "// harness-owned: … READ-ONLY …"; a resume appends
@@ -367,7 +396,11 @@ from codeverse.tracks.graphics_recipes import seed_recipes, graphics_brief, cook
# {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.common import RunContext, Services # common.py; RunContext.single_shot / .agent_kind
+from codeverse.tracks.generation import write_files # (ws, files, *, allowed_roots, only=None, frozen=(), on_skip=None):
+ # frozen = harness-owned paths a single-shot envelope may not rewrite (skipped with a reason, never an error)
+from codeverse.agents.cli_common import find_json_object, default_mcp_command # THE one JSON-envelope finder behind
+ # parse_gemini_json / parse_claude_json / parse_agy_json; default_mcp_command(ws, *, language, track, round_index)
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
# (tracks.steps.run_generation_tasks). Only user: the scoped baseline — phase 0 = one session per
@@ -386,7 +419,9 @@ skip_judge_reason(ctx, *, gates, renders) -> str # "" = judge it. ONLY state
# never bought at all: no judge / no renders / budget already exceeded / gate errors with
# policy.judge_on_gate_errors=False. rejudge_round honours the last one too, so a policy skip is
# never re-bought (docs/COST.md §17 — "no file change" and "build not repaired" were removed)
-run_round(ctx, *, index, kind, tasks, pipeline, ..., previous_best=None) -> RoundRecord
+run_round(ctx, *, index, kind, tasks, pipeline, ..., previous_best=None, render=None, geometry_views=True) -> RoundRecord
+ # render: RenderFn | None swaps the pipeline's render (candidates pass quick_render); geometry_views=False skips
+ # the clay/normals views
# emits cost.round {stages{}, judge_usd, total_usd, agent_turns, wasted, waste_reason}; on ANY exception it
# records what the round burned (rounds/aborted_rNN.json, ctx.extra["aborted_rounds"]) and re-raises
from codeverse.tracks.planner import plan, plan_model_for, ensure_acceptance # graphics uses tracks/graphics.plan_graphics
@@ -419,7 +454,8 @@ from codeverse.texturing.plan import scene_texture_pack, texture_pack_prompt #
## flywheel/ + cli/
```python
-from codeverse.flywheel.record import finalize_record, load_record, iter_runs, best_round_index
+from codeverse.flywheel.record import finalize_record, load_record, iter_runs, best_round_index, best_round_record
+from codeverse.gallery.index import hero_view # (ws, rec) -> (rel, label, n_views): the card image, rebased via ws
from codeverse.flywheel.record import complexity_block, round_complexity # objective complexity of what shipped
# finalize_record fills record.extra["complexity"] = the BEST round's vector + plan_parts /
# parts_per_plan_part / by_round; every rounds_summary row gains "complexity" (the index or None)
@@ -456,7 +492,7 @@ Event names: `run.start`, `stage.start/done`, `plan.done`, `workspace.materializ
`texture.start/plan/generated/applied/gate/done`, `budget.exceeded`,
`finalise.rebuild`, `stop`, `run.done` / `run.failed`.
Cost events: **`cost.round`** (per round: `stages{stage → $}`, `judge_usd`, `total_usd`,
-`agent_turns`, `score`, `previous_best`, `wasted`, `waste_reason` ∈ aborted | build_failed |
+`agent_turns` (= AgentResult.turns), `score`, `previous_best`, `wasted`, `waste_reason` ∈ aborted | build_failed |
unjudged | regression | zero_delta, `run_usd`) — emitted for aborted rounds too;
`judge.skipped` (reason), `generate.turn_cap` (label, max_turns, turns, cost_usd),
`strategy.switch` (regression → whole-artifact rewrite), `budget.overrun` (a post-loop
@@ -464,6 +500,6 @@ texture pass crossed the ceiling; the loop is already finished, so not `budget.e
`RunRecord` (record.json): spec, plan, workspace, status, rounds[RoundRecord],
best_round, baseline_score, final_score, total_usage, environment,
prompt_hashes{contract, cookbook, generate, refine}, error, extra{stop_reason,
-rubric, budget, cost_by_stage, aborted_rounds?, rounds_summary, n_candidates?,
-candidates?, texturing?, captions?}. `total_usage` is the BudgetGuard total whenever it
+rubric, budget, cost_by_stage, aborted_rounds?, rounds_summary, candidates? (the
+rounds/candidates.json payload), texturing?, captions?}. `total_usage` is the BudgetGuard total whenever it
exceeds the sum of the rounds (aborted rounds, retried sessions, texture pass).
diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.md
index d7494aa9..a13d96fa 100644
--- a/harness/docs/RUNBOOK.md
+++ b/harness/docs/RUNBOOK.md
@@ -10,7 +10,7 @@ are relative to `/home/yipeng/3dcodeverse/harness` unless absolute. The CLI is
```bash
pip install -e /home/yipeng/3dcodeverse/harness # once; entry points 3dcodeverse and 3dcv
cd /home/yipeng/3dcodeverse/harness/runtime_js && npm install # [email protected], puppeteer (chrome cached)
-3dcv doctor # python deps (incl. python-fcl, moderngl), blender, node/three/puppeteer, chrome WebGL, keys, CLIs, git, ffmpeg, mcp
+3dcv doctor # python deps (incl. python-fcl, moderngl), blender, node/three/puppeteer, chrome WebGL, keys, CLIs, git, mcp
3dcv doctor --live # + one tiny Gemini call ("pong", ~$0.00001)
python -m pytest tests -q # offline suite; live tests are opt-in (blender/node/GL run when the binaries exist)
python -m pytest tests -q -m "not live and not blender and not node" # pure-python subset
@@ -240,12 +240,12 @@ model, produced the zero — check `cell.json`'s `error`).
* **New language**: enum in `contracts/common.py::Language` (+ `TRACK_LANGUAGES`,
`ENTRY_FILE`, `LANGUAGE_LABEL`), frame in `conventions.LANGUAGE_FRAME`;
- `languages/<lang>/{runtime.py, lint.py, skeleton.py, CONTRACT.md, wrappers/}`
- implementing `LanguageRuntime`; branch in `languages/base.py::get_runtime`;
+ `languages/<lang>/{__init__.py, wrappers/}` (one merged module per language;
+ the contract text is `prompts/<lang>/contract.md`) implementing `LanguageRuntime`; branch in `languages/base.py::get_runtime`;
`prompts/<lang>/contract.md` + `cookbook.md` (every snippet must run —
`tests/prompts` executes them); part→file mapping via `runtime.file_for_part`
- (blender and threejs have it; `tracks/prompting.file_for_target_factory` picks
- it up).
+ (blender has it; `tracks/prompting.file_for_target_factory` picks it up and maps
+ every whole-object target to `[entry]` — no runtime `file_for_target` hook).
* **New spatial tool**: pydantic args + `@tool("name", Args, "…", tracks=(…),
languages=(…), cost_hint=…)` in `spatial/tools*.py` (imported from
`spatial/tools.py`); available to tracks, MCP and prompt cards at once.
@@ -258,7 +258,10 @@ model, produced the zero — check `cell.json`'s `error`).
* **New backend**: ChatModel → `models/<provider>.py` + registry + prices;
CodingAgent → `agents/<kind>.py` using `cli_common` + registry + `materialize.py`.
* **New track**: subclass `tracks/lifecycle.py::BaseTrack` (hooks: `make_pipeline`,
- `prepare`, `baseline_tasks`, `refine_tasks`, `round_files_hint`), a `RoundPipeline`,
+ `prepare`, `baseline_tasks`, `refine_tasks`, `round_files_hint`; `system_prompt`
+ defaults to `language_system_prompt(ctx.language, tools=not ctx.single_shot)` and
+ `refine_file_for_target` to `file_for_target_factory(ctx)` — override only for
+ role-specific prompts), a `RoundPipeline`,
plan model in `contracts/plan.py`, `.j2` prompts, branch in `tracks/__init__.py`
(`get_track` forwards `**options` to constructors). `tracks/graphics.py` is the
template for a track with its own planner and no GLB.
diff --git a/harness/docs/RUN_LAYOUT.md b/harness/docs/RUN_LAYOUT.md
index bed4b2e3..6f46dc1d 100644
--- a/harness/docs/RUN_LAYOUT.md
+++ b/harness/docs/RUN_LAYOUT.md
@@ -50,12 +50,15 @@ symlink. Which side is physical was not a matter of taste:
must be on the alias side, never on the side that gets written.
* **`deliverable/`, `telemetry/settings.json` and `telemetry/cost.json` are real
files.** They are *derived*: rebuilt from the run's own git history,
- artifacts, trajectories and events every time the run is finalised or
- migrated. `deliverable/` is self-contained so it can be zipped and handed to
+ artifacts, trajectories and events every time the run is finalised, and on
+ the fly by `3dcv show` / the exporters for a run that predates them — old
+ runs are read as-is, never rewritten. `deliverable/` is self-contained so it can be zipped and handed to
someone (the flywheel exporter only falls back to it when git cannot answer).
`telemetry/usage.jsonl` is the one file that can be either: a real
- reconstructed ledger, or a symlink to the run's live `cost_ledger.jsonl` when
- it has one — same rule as everywhere else, one physical copy.
+ reconstructed ledger, or a symlink to the run's live `telemetry/cost.jsonl`
+ when it has one (the root `cost_ledger.jsonl` is itself a symlink alias; a
+ real root file exists only in runs before 2026-08-23) — same rule as
+ everywhere else, one physical copy.
`.gitignore` inside the run ignores `deliverable/`, `telemetry/` and `evidence`
(as well as `artifacts/`, `stages/`, `trajectories/`, …) so the derived buckets
@@ -103,7 +106,8 @@ the packager produces no diff.
* **`usage.jsonl`** — one priced row per model call, in the
**`codeverse.cost` ledger format** (`CallCost`: tokens, unit prices, price
provenance, stage, role, outcome). There is exactly one ledger in the
- harness: when the run wrote a live one (`<run>/cost_ledger.jsonl`)
+ harness: when the run wrote a live one (`<run>/telemetry/cost.jsonl`; the root
+ `cost_ledger.jsonl` is a symlink alias, a real root file only in pre-2026-08-23 runs)
`telemetry/usage.jsonl` is a symlink to it, otherwise
`cost.reconstruct.reconstruct_run` rebuilds the rows from the trajectories,
the recorded judge verdicts and the priced events. This bucket never
@@ -145,20 +149,6 @@ For the money itself across many runs — waste, $ per passing artifact, price
provenance — use the cost package's own command, `3dcv cost show <runs-dir>`.
`3dcv show` is the single-run view; both read the same ledger rows.
-## Migrating existing runs
-
-```
-3dcv migrate-runs runs/ --dry-run # report only, touches nothing
-3dcv migrate-runs runs/ # in place, idempotent
-3dcv migrate-runs runs/<slug> # a single run directory
-```
-
-The migration only **adds**: it creates the buckets and aliases, builds
-`deliverable/` and `telemetry/`, and writes the two new record blocks. It never
-moves or deletes evidence, never rewrites `src/`, never touches git history. A
-second pass reports `up_to_date`. Runs without a `record.json` (interrupted
-runs) get the layout only.
-
## Back-compatibility contract
* Old runs load unchanged — `load_record`, `3dcv status`, `3dcv judge`,
diff --git a/harness/docs/SKILLS.md b/harness/docs/SKILLS.md
index 24d2fa04..bdf3a917 100644
--- a/harness/docs/SKILLS.md
+++ b/harness/docs/SKILLS.md
@@ -98,7 +98,7 @@ not mean that.** Two independent causes, both reproduced:
So a fourth signal was added: `materialize.write_control` puts one **never-routed,
never-indexed** bundle beside the real ones. Nothing should ever open it. When it comes
back opened, `SkillsUsage.control_read` is set, `probe_trustworthy` is false and
-`deep_read_rate` returns **`None`** — not 100%, not 0. `3dcv skills report` excludes those
+the session's deep-read rate is **`None`** — not 100%, not 0. `3dcv skills report` excludes those
sessions from the rate and prints how many it dropped.
This is the difference between a metric and a number that would have read 100% forever.
@@ -245,7 +245,9 @@ Two things this also says, and neither is comfortable:
## 5. What the tests guarantee
-`tests/skills/` — 712 tests: 650 that run in the default suite, 58 marked `slow` (they recompute from `bench/out` or build a wheel), 4 marked `live` (they drive a real CLI).
+`tests/skills/` keeps the default checks hermetic. The two `slow`-marked cases
+build a wheel (still selected by default; use `-m "not slow"` to omit them), and
+the `live` cases drive a real CLI.
| file | guarantees |
|---|---|
@@ -255,7 +257,6 @@ Two things this also says, and neither is comfortable:
| `test_freshness.py` | every tool, gate kind, rubric criterion, constant, switch, sibling skill and cookbook section a bundle names still exists |
| `test_router.py` / `test_routing_property.py` | the four routing laws, by row and over the whole input space |
| `test_budget.py` | the index cost, re-measured against the shipped descriptions |
-| `test_corpus.py` | evidence labels and corpus claims recomputed from `bench/out` |
| `test_telemetry.py` | the read probe, **including the control that catches git reading the tree** |
| `test_packaging.py` | **a built wheel contains all 14 `SKILL.md`, all 14 `references/`, all 9 `_claims`** |
| `test_live_discovery.py` | §7 — a real CLI actually finds and opens a bundle |
@@ -546,8 +547,9 @@ so; the rest are live.
reaching `skills_hook.attach_for_round`, which lived only in `steps.run_round`; and
`baseline_tasks` returned `[]`, so round 0 listed four bundles to a session that did not
exist. Measured at **0 opens / 30 listings**. The three stages now attach and record with
- their own kind. `tests/skills/test_delivery_reaches_the_session.py` holds every
- agent-driving module to the hook. **The scene bundles' read rate against working delivery
+ their own kind. `tests/skills/test_delivery_reaches_the_session.py` runs a real
+ two-zone-session scene and proves env/zone/compose attach exactly once, before generation,
+ with matching telemetry. **The scene bundles' read rate against working delivery
is UNMEASURED — that is the next wave's first experiment.**
* ~~**`api-agent` has no skill affordance.**~~ **FIXED earlier**, and re-measured here: with
`read_skill` it opens **58%** of listed bundles (51/88) across sessions that are offered
diff --git a/harness/docs/SKILLS_LEDGER.md b/harness/docs/SKILLS_LEDGER.md
index 05ac369b..ef05ea5d 100644
--- a/harness/docs/SKILLS_LEDGER.md
+++ b/harness/docs/SKILLS_LEDGER.md
@@ -230,7 +230,7 @@ it lands these four rows stay `mixed`, not `measured`.
intact; but any A/B straddling this commit compares two different metrics.
`cv3d-scene-lighting` must be re-baselined against the new gate before it is paired.
* **`shader_preflight` is not a gate at all.** It appears in **zero** `record.json` files
- corpus-wide: `check_shaders` is an agent-invocable tool (`spatial/tools_scene.py`), never a
+ corpus-wide: `check_shaders` is an agent-invocable tool (`spatial/tools.py`), never a
pipeline gate, so no round appends its report. The only evidence is 8 per-run
`artifacts/shader_preflight.json` files, all clean. "Not instrumented" and "measured,
always clean" must not print the same number — the readout now returns `None` when the