Skip to content

Official Codebase of 3DCodeVerse

Python

docs: correct the statements that are false about the code as it is

gaoypeng4f73898a81ba
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index 59a0e583..8503c86f 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -83,13 +83,13 @@ codeverse/
node, GPU probe, keys, pool admission, vendor CLIs, MCP, skills)
proc.py stdlib-only subprocess + atomic-JSON primitives (ManagedProcess owns every
child's lifecycle: group kill on ANY exception, bounded pumps, stdin writer;
- run_subprocess, kill_group, tail, write_json_atomic, scrub_secrets) and the tolerant readers/writer
+ run_subprocess, tail, write_json_atomic, scrub_secrets) and the tolerant readers/writer
(read_json_or_none, iter_jsonl_lines, read_jsonl_lenient, append_jsonl_line) —
shared by languages/spatial/cli/cost/flywheel/gallery/bench. RULE: any
stdlib-only file / JSON / JSONL helper lives HERE; grep proc.py before writing a
try/except read (the 2026-08-26 review found the same tolerant read written
eight times because this module had not grown it). Also home, since
- 2026-08-28, to the JSONL event log (Events), the run lock (ONE writer per
+ 2026-08-28, to the JSONL event log (EventLog), 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); sha256_file and version_line live here too — still a leaf:
@@ -140,7 +140,7 @@ codeverse/
MeteredAgent — one row per ChatModel.generate; one session row only for a backend
that does NOT meter itself; run_ledger nests + is context-local so bench --parallel works)
profiles.py (economy|balanced|quality; cli._common.resolve_dial is THE resolver)
- caching.py (Block/order_blocks/session_cache — measurement only, docs/COST.md §13)
+ caching.py (session_cache/session_key — measurement only, docs/COST.md §13)
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
@@ -178,12 +178,12 @@ codeverse/
graphics.py (the whole graphics track: planner hooks, prompt context, frame
RenderSet, and recipe seeding into the harness-owned, read-only
src/recipes.glsl — measured: flash calls a recipe on disk, not one it is
- shown; AgentJob.read_only, CV3D_SEED_RECIPES, docs/GRAPHICS_LOOP.md §3),
+ shown; AgentJob.read_only, CV3D_SEED_RECIPES),
planner.py (the ONE planner loop + the cached EngineeringBrief
(CV3D_PLAN_BRIEF), plan budgets and the worked examples),
plan_features.py (CV3D_PLAN_FEATURES: one switch per plan-loop change, so each
can be A/B'd alone, + pin_plan_blockers() deciding when two arms may share
- one plan — docs/PLAN_LOOP.md, docs/EVAL.md §8.1),
+ one plan — docs/EVAL.md §8.1),
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)
@@ -237,8 +237,10 @@ runtime_js/ export_glb.mjs (placement policy, instance baking, selfche
render_scene.mjs probe_scene.mjs check_shaders.mjs gpu_launch.cjs serve.cjs
lib/{resolve_three, scene_host, host_coverage, host_census, host_placement, orbit, instances,
census, glsl_audit, browser/…}
-tests/ core models agents blender_cadquery threejs_render urdf_joints scene_runtime scene_gates
- spatial_tools judges orchestrator_tracks flywheel_cli graphics texturing prompts (~860 offline)
+tests/ agents bench_prompts blender_cadquery compare_bench core cost flywheel_cli gallery graphics
+ install judges languages models orchestrator_tracks prompts reference scene_gates
+ scene_prompts scene_runtime skills spatial_tools texturing threejs_render urdf_joints
+ (24 dirs; 2 077 offline, 1 950 of them pure python)
```
## 3. Workspace layout (one run, as observed)
@@ -325,11 +327,11 @@ summary:
`@tool(name, ArgsModel, description, *, tracks=(), languages=(), cost_hint)` registers
`fn(ctx, args) -> Observation` → (a) direct call from tracks, (b) the stdio MCP
server (name `3dcv`) for the vendor CLIs, (c) a native tool schema for any embedder
-(`ToolDef.schema()`), (d) a prompt card. Tools: `build`, `measure`, `render_views`,
-`render_sheet`, `isolate`, `cross_section`, `check_connectivity`, `check_contract`,
-`compare_silhouette`, `joint_sweep` (articulated), `shader_probe`, `scene_probe`,
-`scene_views` (scene), `gl_probe`, `gl_frames` (graphics), `texture_pass`,
-`texture_preview` (object tracks).
+(`ToolDef.schema()`), (d) a prompt card. The 19 tools: `build`, `measure`,
+`render_views`, `render_sheet`, `isolate`, `cross_section`, `check_connectivity`,
+`check_contract`, `check_placement`, `compare_silhouette`, `compare_reference`,
+`joint_sweep` (articulated), `shader_probe`, `scene_probe`, `scene_views` (scene),
+`gl_probe`, `gl_frames` (graphics), `texture_pass`, `texture_preview` (object tracks).
## 6. Judging (protocol v2)
diff --git a/harness/docs/COST.md b/harness/docs/COST.md
index 83c299d6..70a4037c 100644
--- a/harness/docs/COST.md
+++ b/harness/docs/COST.md
@@ -70,7 +70,7 @@ cheaper judge" is optimising 7% of the bill — and, as §8 shows, would lose mo
`skeleton`, `assemble`, `gates` and `render` cost **$0.00**: they are
deterministic harness work. Blender build 0.13 s, gates ~2 s, an 8-view GPU
-render ~1.5 s — the "cheap first" law is holding.
+render ~1.5 s (that battery's rig; 14 views since D47) — the "cheap first" law is holding.
## 3. Per role, track, backend, model
@@ -532,7 +532,8 @@ tool cards and the output format were hoisted into one shared include
**That include is gone (2026-08-23).** The head was not *shared* with anything
already being sent — it was **duplicated into every prompt**, so the shared prefix
it created was paid for four times over. Measured with `cost.prefix_report` on
-the real templates (one baseline + three refine prompts of one run, same context):
+the real templates (one baseline + three refine prompts of one run, same context;
+the helper has been deleted since — `caching.py` keeps only the session-cache half):
| | shared prefix | per-prompt tokens | mean per call |
|---|---|---|---|
@@ -558,10 +559,8 @@ i.e. by buying the cache block with more tokens than it returns.
| **total, already first in every request** | **6,570** |
6.6k is still under the floor, and it is already at position 0 — there is no
-reordering left to do there. `codeverse/cost/caching.py` keeps `Block` /
-`order_blocks` / `prefix_report` / `prefix_signature` as **measurement helpers**
-with these numbers in its docstring, and `3dcv cost cache <slug>` still reports
-what a run's sessions actually cached. The rule they encode: measure the prefix
+reordering left to do there. `3dcv cost cache <slug>` still reports
+what a run's sessions actually cached. The rule that measurement encodes: measure the prefix
against the floor *before* reordering a prompt family, and never pad to reach it.
## 14. The judge payload — 768 px saves bytes, not dollars
@@ -798,8 +797,8 @@ run, a bench arm or `$CV3D_AGENT_MAX_TURNS` asks for it by name.
### `skip_judge_reason` — two of four branches removed
-A skip only saves money if the verdict is never bought. Reproductions in
-`verifier/test_rejudge_defer.py`:
+A skip only saves money if the verdict is never bought. Reproductions were run
+out of tree (no such test ships here):
| branch | verdict | why |
|---|---|---|
@@ -970,7 +969,7 @@ storm independently spends a full failed round-trip to learn what its siblings a
know, then sleeps on its own private backoff schedule. That is the 2 833 waits / 17.7 h
in §18.
-`codeverse/models/storm.py` adds a process-wide `StormGate` per model:
+`codeverse/models/retry.py` adds a process-wide `StormGate` per model (`retry.py:449`):
* the first worker to see a 503 calls `hit()`, which closes the gate for a short,
escalating window (never longer than `MAX_WAIT_S` — patience comes from the *number*
diff --git a/harness/docs/DECISIONS.md b/harness/docs/DECISIONS.md
index 0d2ed206..9518776e 100644
--- a/harness/docs/DECISIONS.md
+++ b/harness/docs/DECISIONS.md
@@ -37,8 +37,9 @@ written) that were accepted because the code works that way and the tests pin it
* **D3 `RoundPolicy.max_rounds` counts refine rounds after the baseline.** `3dcv make
--rounds 2` = baseline + up to 2 refine rounds. The rubric's `pass_threshold`
overrides `RoundPolicy.target` when no explicit policy is injected.
-* **D4 Parallel refine only when it is safe.** Fan out only when ≥ 3 file-disjoint
- groups exist and every task maps to a file (threejs parts, scene zones/assets/env);
+* **D4 Parallel refine only when it is safe.** Fan out only when at least
+ `RoundPolicy.parallel_min_tasks` (default 2) file-disjoint groups exist and every task
+ maps to a file (threejs parts, scene zones/assets/env);
single-file languages get one whole-object task. Consequence: `Workspace` itself
holds a per-root lock + index.lock retry (workspace.py).
* **D5 A refine round that changes no file is a plateau, not a crash.** Emits
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 241aa856..1a355f63 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -38,7 +38,7 @@ from codeverse.config import get_settings, env_flag # env_flag(env, fallba
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
-from codeverse.proc import ProcResult, run_subprocess, kill_group, tail, write_json_atomic
+from codeverse.proc import ProcResult, run_subprocess, tail, write_json_atomic
run_subprocess(cmd, *, cwd, timeout_s, env=None, stdin_text=None, preexec_fn=None) -> ProcResult
# own session/process group, group-kill on timeout, never raises on rc != 0; stdlib-only module
from codeverse.proc import read_json_or_none, iter_jsonl_lines, read_jsonl_lenient, append_jsonl_line
@@ -135,7 +135,7 @@ from codeverse.cost.ledger import bound_ledger, process_ledger_path # (Δ 2026
# session's; a generation label yields to the session (best-of-N: kind="candidate" beats
# label="baseline"); Stage.OTHER means "the label said nothing" and displaces nothing.
# labels understood: judge:<rubric>:r<NN>:s<k> · planner · pairwise:… · texture… · caption… (api-agent:<label>:t<turn> in historical ledgers only)
-from codeverse.cost.caching import Block, order_blocks, prefix_report, session_cache, session_key
+from codeverse.cost.caching import session_cache, session_key
session_cache(rows) -> [SessionCache] # per session: cold first call, cached share, saved_usd, cold_usd
from codeverse.cost.profiles import get_profile, PROFILES # economy | balanced | quality
get_settings().apply_profile(name, *, force=False) -> Profile
@@ -321,8 +321,10 @@ python -m codeverse.spatial.mcp_server --workspace <ws> [--track X] [--language
from codeverse.judges.rubrics import load_rubric, Rubric # Rubric{…, defects: [DefectItem{id, text, penalty, cap}], caps[{…, when:, kinds}]}
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
+ temperature=0.2, *, thinking="low", max_attempts=3, max_montages=None, detail_crops=None, max_px=None,
+ sample_budget_s=None, fixed_order=False, chat_model=None, cache_dir=None, label="judge")
+ # Δ max_images is GONE → montage budget. The four None params resolve through Settings.judge
+ # (montages=5 since D47, detail_crops=2, max_px=1024) and SAMPLE_BUDGET_S=900.0
VlmJudge.judge(inp) -> Judgment # clay/normals views travel ONLY as JudgeInput.geometry_views (no kwarg)
VlmJudge.slice_payload(inp) -> (list[(label, png_path)], provenance_elicitation: bool) # (D48) ([], False) unless
# Settings.judge.slices=="on-error" AND spec.track in judges.base.SLICE_TRACKS AND inp.glb_path exists AND the
@@ -330,8 +332,8 @@ VlmJudge.slice_payload(inp) -> (list[(label, png_path)], provenance_elicitation:
from codeverse.judges.base import JudgeInput # (spec, renders, measurement=None, gates=[], acceptance=[], plan_summary="",
# round_index=0, previous=None, extra_context="", geometry_views=None,
# glb_path=None (D48: the round's canonical GLB; object tracks + 3dcv judge fill it))
-from codeverse.judges.prompt_builder import plan_montages, render_montage, Montage # ≤3 2×2 montages (shaded/geometry/poses) + ≤2 detail
- # crops @≤1024px replace sheet+9 views; clay/normals views (RenderView.mode) auto-route to the GEOMETRY montage
+from codeverse.judges.prompt_builder import plan_montages, render_montage, Montage # ≤5 2×2 montages (shaded/geometry/poses) + ≤2 detail
+ # crops @≤1024px replace the sheet + the 14-view rig (D47); clay/normals views (RenderView.mode) auto-route to the GEOMETRY montage
from codeverse.judges.prompt_builder import build_judge_messages, connectivity_error_pairs, PROVENANCE_ELICITATION
build_judge_messages(inp, rubric, *, …, extra_images=None (PREpended: references), extra_text="",
slice_images=None, provenance_elicitation=False) -> (system, [ChatMessage]) # (D48) slice_images
@@ -472,13 +474,13 @@ run_round(ctx, *, index, kind, tasks, pipeline, ..., previous_best=None, render=
# 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
+from codeverse.tracks.planner import plan, ensure_acceptance # graphics uses tracks/graphics.plan_graphics
```
`run_round` = generate → commit → `build_with_repair` → measure → gates → render →
post-render gates → judge → commit. Post-render gates: static `reference_silhouette`
(when references), articulated `joint_sweep` + `motion_direction`, scene
-`render_console` (`scene_frames` via `frame_gate_from_renders` is built but not yet
-wired into `ScenePipeline.post_render_gates`), graphics `gl_frames`. Reference specs get a
+`render_console` + `scene_frames` (via `ctx.services.frame_gate` ->
+`frame_gate_from_renders`; advisory, a failure is logged not raised), graphics `gl_frames`. Reference specs get a
`ReferenceJudge` (rubric `reference_v1` for static_object) and images attached to
generation prompts.
diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.md
index cb465e0c..c4bb679a 100644
--- a/harness/docs/RUNBOOK.md
+++ b/harness/docs/RUNBOOK.md
@@ -81,7 +81,7 @@ round, then ≈ $0.36 / ~7 min per refine (give scenes `--max-minutes 60`).
| `agy:<model>` | `agy --print … --add-dir ws` | no per-workspace MCP: tools via `3dcv tools <name> --json … --workspace .`; no served-model or cost reporting |
| `gemini:* / anthropic:* / openai:*` | ChatModel for planner / judge / captioner / single-shot | Anthropic/OpenAI untested live here |
-### gemini-cli gotchas (handled by `agents/gemini_cli.py`; do not undo)
+### gemini-cli gotchas (handled by `agents/backends.py`; do not undo)
* System settings file via `GEMINI_CLI_SYSTEM_SETTINGS_PATH`: api-key auth,
`experimental.dynamicModelConfiguration=true` (else unknown models are silently
substituted → checked, `exit_reason=model_substituted`), `security.folderTrust.enabled=false`
@@ -253,16 +253,15 @@ model, produced the zero — check `cell.json`'s `error`).
(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.
+ languages=(…), cost_hint=…)` in `spatial/tools.py`; available to tracks, MCP and prompt cards at once.
Update `tests/spatial_tools` EXPECTED_TOOLS.
* **New rubric**: `judges/rubrics/<name>.yaml` with `pass_threshold`,
`criteria[{id, weight, floor, title, description, anchors, kind}]`,
`caps[{id, cap, when: gate|acceptance|console|missing_views, gate, severity, kinds}]`,
`defects[{id, text, penalty, cap}]`. Tracks pick rubrics in `tracks/*.py`;
- `3dcv judge` maps track → rubric in `cli/main.py`.
+ `3dcv judge` maps track → rubric in `cli/_judge.py::rubric_for`.
* **New backend**: ChatModel → `models/<provider>.py` + registry + prices;
- CodingAgent → `agents/<kind>.py` using `cli_common` + registry + `materialize.py`.
+ CodingAgent → `agents/backends.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`; `system_prompt`
defaults to `language_system_prompt(ctx.language, tools=not ctx.single_shot)` and
diff --git a/harness/docs/RUN_LAYOUT.md b/harness/docs/RUN_LAYOUT.md
index 6f46dc1d..08c46af3 100644
--- a/harness/docs/RUN_LAYOUT.md
+++ b/harness/docs/RUN_LAYOUT.md
@@ -99,7 +99,9 @@ the packager produces no diff.
hashes; tool versions (python, blender, node, three, chrome, puppeteer);
harness version + git sha; key-pool size; **price-table hash**; resolved
render and limit settings. Sampling values are read from the call sites'
- typed defaults (`ApiAgentOptions`, `VlmJudge.__init__`, `planner.plan`); a
+ typed defaults (`VlmJudge.__init__`, `planner.plan`, and
+ `flywheel/telemetry.py::_generator_defaults` — a historical shim that
+ configures nothing, kept so old records still read back); a
value a call site hard-codes per task is left empty with `source` saying so,
never guessed. A track may publish real values as
`record.extra["sampling"][<role>]` and they win (`source: observed`).
diff --git a/harness/docs/SKILLS.md b/harness/docs/SKILLS.md
index 13a69c2c..725af960 100644
--- a/harness/docs/SKILLS.md
+++ b/harness/docs/SKILLS.md
@@ -157,7 +157,7 @@ requires (design §5.2 law 3).
## 3. Routing
`codeverse/skills/registry.py` holds the typed table (R1–R24) and `finding_kind()`, the one
-place a gate message is pattern-matched. `codeverse/skills/router.py` turns
+place a gate message is pattern-matched; its router half (`select()`, `skills_for()`) turns
`(track, language, kind, plan signals, findings)` into a ranked, capped, reasoned set.
Four laws, all tested:
@@ -258,7 +258,7 @@ the `live` cases drive a real CLI.
| `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_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_packaging.py` | **a built wheel contains all 13 `SKILL.md`, all 13 `references/`, all 9 `_claims`** |
| `test_live_discovery.py` | §7 — a real CLI actually finds and opens a bundle |
Two contradiction checks are worth separating, because they answer different questions: