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.mdindex 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 everychild'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: anystdlib-only file / JSON / JSONL helper lives HERE; grep proc.py before writing atry/except read (the 2026-08-26 review found the same tolerant read writteneight 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 perrun dir: an fcntl.flock at <runs>/.locks/<slug>.lock whose record NAMES theholder, 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 backendthat 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, frameRenderSet, and recipe seeding into the harness-owned, read-onlysrc/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 eachcan 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, selfcherender_scene.mjs probe_scene.mjs check_shaders.mjs gpu_launch.cjs serve.cjslib/{resolve_three, scene_host, host_coverage, host_census, host_placement, orbit, instances,census, glsl_audit, browser/…}-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 MCPserver (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.mdindex 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 aredeterministic 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 anythingalready being sent — it was **duplicated into every prompt**, so the shared prefixit 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 prefixagainst 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 aknow, then sleeps on its own private backoff schedule. That is the 2 833 waits / 17.7 hin §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.mdindex 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` itselfholds a per-root lock + index.lock retry (workspace.py).* **D5 A refine round that changes no file is a plateau, not a crash.** Emitsdiff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 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, fallbaget_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_atomicrun_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 modulefrom 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_keysession_cache(rows) -> [SessionCache] # per session: cold first call, cached share, saved_usd, cold_usdfrom codeverse.cost.profiles import get_profile, PROFILES # economy | balanced | qualityget_settings().apply_profile(name, *, force=False) -> Profile@@ -321,8 +321,10 @@ python -m codeverse.spatial.mcp_server --workspace <ws> [--track X] [--languagefrom codeverse.judges.rubrics import load_rubric, Rubric # Rubric{…, defects: [DefectItem{id, text, penalty, cap}], caps[{…, when:, kinds}]}from codeverse.judges.vlm_judge import VlmJudgeVlmJudge(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.0VlmJudge.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 montagefrom codeverse.judges.prompt_builder import build_judge_messages, connectivity_error_pairs, PROVENANCE_ELICITATIONbuild_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 togeneration prompts.diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.mdindex 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 silentlysubstituted → 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 mapsevery 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)` anddiff --git a/harness/docs/RUN_LAYOUT.md b/harness/docs/RUN_LAYOUT.mdindex 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**; resolvedrender 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); avalue 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.mdindex 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: