Skip to content

Official Codebase of 3DCodeVerse

Python

tracks, orchestrator, record: comments that stopped being true

gaoypengcb4c664c8c21
diff --git a/harness/codeverse3d/orchestrator.py b/harness/codeverse3d/orchestrator.py
index 7d8fb606..a5248e31 100644
--- a/harness/codeverse3d/orchestrator.py
+++ b/harness/codeverse3d/orchestrator.py
@@ -945,10 +945,10 @@ class BudgetSnapshot(BaseModel):
"""What survives a resume (``run_state.extra["budget_snapshot"]``).
The four accumulator fields of :class:`BudgetGuard` plus cumulative ACTIVE
- seconds. Grace (``grace_minutes``) and config (ceilings, soft
- fraction, run, ledger) are EXCLUDED on purpose: grace is per-attempt salvage
- headroom — persisting it would ratchet the hard ceiling — and config always
- comes from the current spec/settings."""
+ seconds. Grace (``grace_minutes``) and config (ceilings, soft fraction) are
+ EXCLUDED on purpose: grace is per-attempt salvage headroom — persisting it
+ would ratchet the hard ceiling — and config always comes from the current
+ spec/settings."""
spent: Usage
billed_usd: float
diff --git a/harness/codeverse3d/record/deliverable.py b/harness/codeverse3d/record/deliverable.py
index 3b45abbd..b1e15651 100644
--- a/harness/codeverse3d/record/deliverable.py
+++ b/harness/codeverse3d/record/deliverable.py
@@ -118,7 +118,7 @@ def _copy_artifacts(ws: Workspace, record: RunRecord, w: _Writer) -> None:
for name, role in _ARTIFACT_ROLES:
if name == "object_textured.glb" and not tex.get("shipped"):
# a texture pass that did not ship is not a deliverable, even if a stray
- # canonical file exists (same gate flywheel/sample.copy_textured applies)
+ # canonical file exists (same gate addons/dataset/sample.copy_textured applies)
continue
w.add_file(ws.artifacts / name, name, role)
meshes = ws.artifacts / "meshes"
diff --git a/harness/codeverse3d/record/record.py b/harness/codeverse3d/record/record.py
index 914acf58..09a6b814 100644
--- a/harness/codeverse3d/record/record.py
+++ b/harness/codeverse3d/record/record.py
@@ -232,7 +232,7 @@ def complexity_block(record: RunRecord) -> dict[str, Any] | None:
The vector is the one measured on the BEST round — the round whose code is
restored and rebuilt at finalise, so it describes the artifact actually
shipped. ``plan_parts`` / ``parts_per_plan_part`` say whether the build
- reached the plan's ambition or collapsed it (docs/COMPLEXITY.md)."""
+ reached the plan's ambition or collapsed it (eval/docs/COMPLEXITY.md)."""
best = best_round_record(record)
cx = round_complexity(best) if best is not None else None
if cx is None:
@@ -330,7 +330,7 @@ def is_run_dir(p: Path) -> bool:
def battery_label(root: Path | str) -> str:
- """Label for a scan root: the battery name for ``bench/out/<battery>/runs``,
+ """Label for a scan root: the battery name for ``eval/bench/out/<battery>/runs``,
else the directory's own name (the same rule the gallery sections use)."""
root = Path(root)
if root.name == "runs" and root.parent.name and root.parent.parent.name == "out":
diff --git a/harness/codeverse3d/tracks/common.py b/harness/codeverse3d/tracks/common.py
index 279b6f92..4b5b9cff 100644
--- a/harness/codeverse3d/tracks/common.py
+++ b/harness/codeverse3d/tracks/common.py
@@ -1,7 +1,7 @@
"""Shared track machinery: the run context, the services seam, prompt context.
``Services`` is the tracks' injection seam: every call into a sibling package
-(models, agents, runtimes, spatial tools, judges, flywheel) goes through one
+(models, agents, runtimes, spatial tools, judges, record) goes through one
method here so a test can subclass it with fakes (``tests/orchestrator_tracks/
fakes.py``) and an articulated test double can synthesise joint sweeps from the
plan. The targets are modules of this same package — never optional — and are
diff --git a/harness/codeverse3d/tracks/depth.py b/harness/codeverse3d/tracks/depth.py
index 0864a1a6..f4a58530 100644
--- a/harness/codeverse3d/tracks/depth.py
+++ b/harness/codeverse3d/tracks/depth.py
@@ -20,7 +20,7 @@ Measured on the recorded corpus (183 judged rounds / 81 runs, see the wave's
machine were given the same numbers, so the number said nothing.
The *measurement* side of the same question — how much artifact actually got built,
-on eight objective axes — is ``codeverse3d/spatial/complexity.py`` + ``docs/COMPLEXITY.md``.
+on eight objective axes — is ``codeverse3d/spatial/complexity.py`` + ``eval/docs/COMPLEXITY.md``.
This module is the *target* side: what THIS plan should be allowed and asked to spend.
Hence: :func:`depth_budget` (how many triangles / how much build time this *plan*
@@ -307,8 +307,8 @@ def budget_gate(measurement: Any, build: Any, budget: DepthBudget) -> Any:
Deterministic, so the judge is never asked "does it look detailed enough" —
code answers it. Over the ceiling is an ERROR (the build is too heavy to ship);
under the floor and over the build-time budget are WARNs, because a thin object
- is a quality problem, not a broken one — the static track turns the thin WARN
- into a refine task through ``extra_refine_tasks``.
+ is a quality problem, not a broken one — the static track deliberately does NOT
+ turn the thin WARN into a refine task: density is the detail round's job.
"""
from codeverse3d.contracts.artifacts import GateFinding, GateReport, Severity
diff --git a/harness/codeverse3d/tracks/graphics.py b/harness/codeverse3d/tracks/graphics.py
index fb108620..b710a4ac 100644
--- a/harness/codeverse3d/tracks/graphics.py
+++ b/harness/codeverse3d/tracks/graphics.py
@@ -433,7 +433,7 @@ class GraphicsTrack(BaseTrack):
plan_model = GraphicsPlan
generate_template = "tracks/generate_graphics.j2"
refine_template = "tracks/refine_graphics.j2"
- # planner hooks: own template/example/acceptance, T=0.5, 16k tokens (no 3D frame)
+ # planner hooks: own template/example/acceptance, T=0.5, 65 536 tokens (no 3D frame)
plan_template = PLAN_TEMPLATE
plan_temperature = PLAN_TEMPERATURE
plan_max_output_tokens = PLAN_MAX_OUTPUT_TOKENS
diff --git a/harness/codeverse3d/tracks/lifecycle.py b/harness/codeverse3d/tracks/lifecycle.py
index b6ccb6c9..9ae14c0b 100644
--- a/harness/codeverse3d/tracks/lifecycle.py
+++ b/harness/codeverse3d/tracks/lifecycle.py
@@ -86,7 +86,7 @@ REFERENCE_RUBRIC = "reference_v1"
#: surface-detail rounds a track that implements one gets by default. ``RoundPolicy.detail_rounds``
#: is None (= this default) unless a caller chose a number; ``C3D_DETAIL_ROUNDS`` overrides both
-#: (0 = off — the A/B switch for docs/EVAL.md).
+#: (0 = off — the A/B switch for eval/docs/EVAL.md).
DEFAULT_DETAIL_ROUNDS = 1
@@ -191,7 +191,7 @@ class BaseTrack:
plan_model: type[Plan]
generate_template: str = ""
refine_template: str = ""
- #: planner knobs (GraphicsTrack: own template/example, T=0.5, 16k tokens)
+ #: planner knobs (GraphicsTrack: own template/example, T=0.5, 65 536 tokens)
plan_template: str | None = None # None → tracks/plan_<track>.j2
plan_temperature: float = 0.4
plan_max_output_tokens: int = 24000
diff --git a/harness/codeverse3d/tracks/plan_features.py b/harness/codeverse3d/tracks/plan_features.py
index 78ec7902..342e5dec 100644
--- a/harness/codeverse3d/tracks/plan_features.py
+++ b/harness/codeverse3d/tracks/plan_features.py
@@ -7,7 +7,7 @@ runtime (``parse_features`` / ``plan_feature_on``) was deleted 2026-08-28 per it
instruction, and the six names with it (2026-09-22); what remains is the guard rail —
:data:`LIVE_SWITCHES` / :data:`DEAD_SWITCHES` (kept honest by
``tests/orchestrator_tracks/test_plan_features.py``, which greps the tree) and the
-``--pin-plan`` blocker rule ``bench/ab_plan.py`` consults so a paired A/B cannot
+``--pin-plan`` blocker rule ``eval/bench/ab_plan.py`` consults so a paired A/B cannot
silently pin away the very thing it is testing.
"""
@@ -18,7 +18,7 @@ PLAN_FEATURES_ENV = "C3D_PLAN_FEATURES"
#: env switches that act AFTER planning — ``--pin-plan`` may share one plan across arms
#: that differ only by these. Anything not listed is treated as plan-side: refusing to
#: pin costs one noisy A/B, pinning wrongly costs a confident wrong answer
-#: (docs/EVAL.md §8.1 measured it — the A/A's worst pair differed 1 part vs 10).
+#: (eval/docs/EVAL.md §8.1 measured it — the A/A's worst pair differed 1 part vs 10).
GENERATION_SIDE_ENV: frozenset[str] = frozenset({"C3D_SKILLS", "C3D_SKILLS_MAX", "C3D_SKILLS_UNVERIFIED",
"C3D_SKILLS_ONLY",
"C3D_DETAIL_ROUNDS", "C3D_REFERENCE_DIFF",
diff --git a/harness/codeverse3d/tracks/planner.py b/harness/codeverse3d/tracks/planner.py
index 081a6d2c..67ee5545 100644
--- a/harness/codeverse3d/tracks/planner.py
+++ b/harness/codeverse3d/tracks/planner.py
@@ -5,10 +5,10 @@ request into an engineering brief, which — together with a **plan budget deriv
from the request** — goes into one structured ``ChatRequest`` (system prompt from
``prompts/tracks/plan_<track>.j2``, ``response_schema`` = the plan model's JSON
schema, reference images inline). The answer is validated IN CODE by the pydantic
-plan models; a plan the schema rejects is re-asked once with the exact validation
-errors (then ``PlanningError``), and a plan that validates but is
-boxes-at-different-sizes against its budget is re-asked once with that specific
-complaint (then shipped anyway — a mediocre plan beats no plan). The harness
+plan models; a plan the schema rejects is re-asked twice with the exact validation
+errors, plus one restart from the request when it is degenerate (then ``PlanningError``),
+and a plan that validates but is boxes-at-different-sizes against its budget is re-asked
+once with that specific complaint (then shipped anyway — a mediocre plan beats no plan). The harness
finally appends deterministic acceptance items derived from the spec constraints
and folds the brief + sub-parts into the plan's own text (generated artifacts are
weak links — framework-owned requirements never rely on the model remembering them).
@@ -698,7 +698,7 @@ def restart_enabled() -> bool:
#: an invalid plan attempt is written here, so a run that DIES at the plan stage still says
#: what the model wrote. Pydantic truncates the offending value in its message, so the
#: event log alone cannot answer "what did it actually write?" — the question every
-#: plan-stage failure class starts from (docs/PAPER_WRITING.md §5.1).
+#: plan-stage failure class starts from (eval/docs/PAPER_WRITING.md §5.1).
INVALID_PLAN_DIR = "stages/plan/invalid"
#: bound per file: a plan is a few kB; anything larger is a runaway answer and the head of
#: it is what says so
diff --git a/harness/codeverse3d/tracks/prompting.py b/harness/codeverse3d/tracks/prompting.py
index 92968935..2b77a941 100644
--- a/harness/codeverse3d/tracks/prompting.py
+++ b/harness/codeverse3d/tracks/prompting.py
@@ -274,7 +274,7 @@ def language_system_prompt(language: Language, *, role: str = "", tools: bool =
# gl_probe is instructing something it has no tools to do, and the self-check loop is
# the whole point of the graphics prompt. `tools` lets the file say so itself.
# (The v0 two-sentence arm of the system-prompt A/B was retired 2026-08-29: a
- # three-way null, docs/EVAL.md.)
+ # three-way null, eval/docs/EVAL.md.)
base = render(f"{d}/system.md", tools=tools).strip()
if not role:
return base
@@ -609,8 +609,7 @@ TURN_DISCIPLINE = """## Turn discipline (every tool call is a full round trip
calls in that same reply, then call `build` once. Do not write one file per turn.
- `build` already runs check_connectivity and check_contract: read its CONNECTIVITY / CONTRACT
sections, fix what they list, build again. Do not call those two tools separately.
-- Do not read a file back after writing or editing it: the write result reports its line count and
- syntax verdict.
+- Do not read a file back after writing or editing it: `build` reports what is wrong with it.
- Call `render_sheet` once before you finish; `measure` at most once."""
#: the refine prompt inlines the files a scoped task edits when they are few and small, so the
diff --git a/harness/codeverse3d/tracks/scene.py b/harness/codeverse3d/tracks/scene.py
index 87f42274..0945c12e 100644
--- a/harness/codeverse3d/tracks/scene.py
+++ b/harness/codeverse3d/tracks/scene.py
@@ -10,9 +10,8 @@ Cost/latency shaping (the baseline used to eat the whole budget, leaving the
refine rounds nothing):
* assets are single-shot by default (``scene_assets``);
-* **small zones are batched** — a zone that places ≤ 3 assets is written
- together with its neighbour in ONE session that exclusively owns both files,
- while big zones keep the parallel fan-out;
+* **one session writes every zone** (D70) and exclusively owns their files;
+ ``scene.js`` is assembled deterministically, without a session;
* every stage session gets a timeout clipped to the wall-clock actually left;
* the baseline runs against a **soft sub-budget** (``soft_budget_fraction``);
when it is spent the stages degrade (single-shot instead of an agent session,
@@ -281,9 +280,9 @@ class SceneTrack(BaseTrack):
"""Route this stage's bundles into the workspace and inline them if single-shot.
WHY this is not just ``steps.run_round``'s job. A scene builds its whole baseline
- in ``prepare()``: ``_env_stage`` writes the lighting, ``_zones_stage`` the contents,
- ``_assemble_stage`` the cameras — three real agent sessions that never passed
- through ``steps.run_round``, the ONE place that called ``attach_for_round``. The
+ in ``prepare()``: ``_env_stage`` writes the lighting and ``_zones_stage`` the
+ contents — agent sessions that never passed through ``steps.run_round``, the ONE
+ place that called ``attach_for_round`` (``scene.js`` is assembled, not written). The
router has always had ``kinds=("env", "zone", "compose")`` rows for the four scene
bundles (registry R14-R21), so they were selected for these very stages and then
delivered to nobody: measured 2026-08-25 at 0 opens out of 30 listings, while round
@@ -293,8 +292,8 @@ class SceneTrack(BaseTrack):
``index=0`` because these stages ARE round 0's generation; there is no earlier
round, so ``_previous_findings`` correctly returns nothing and only the plan-signal
- and kind rows can fire. Attaching once per stage (not once per task) keeps the
- parallel zone sessions from racing each other's AGENTS.md write.
+ and kind rows can fire. Attaching once per stage (not once per task) keeps it
+ to one AGENTS.md write per stage.
"""
skills_hook.attach_for_round(gen, index=0, kind=stage_kind)
return skills_hook.with_inlined_skill(gen, tasks)
diff --git a/harness/codeverse3d/tracks/scene_assets.py b/harness/codeverse3d/tracks/scene_assets.py
index 03670f32..00ed321c 100644
--- a/harness/codeverse3d/tracks/scene_assets.py
+++ b/harness/codeverse3d/tracks/scene_assets.py
@@ -3,10 +3,10 @@
* ``threejs`` assets → ``src/assets/<snake>.js`` exporting ``build<Pascal>`` —
generated **single-shot** (one chat call) + a deterministic node check + ONE
error-feedback repair; a full agent session is the escalation, not the default
- (see ``scene_asset_gen``: agent sessions cost 10× and 10 minutes per file).
+ (agent sessions cost 10× and 10 minutes per file).
* ``blender_glb`` assets are **heroes**: a sub-workspace under ``<ws>/_assets/<snake>``
- runs the Blender runtime (skeleton → generate → build+repair) with a real agent
- session and the GLB is copied to ``public/assets/<snake>.glb``.
+ runs the Blender runtime and climbs the SAME single-shot ladder (``_ladder``) before
+ an agent session; the GLB is copied to ``public/assets/<snake>.glb``.
Near-identical props are merged into one factory with an ``opts.variant``; the
list is capped at ``MAX_ASSETS`` in plan (= priority) order, and harder when the
@@ -383,7 +383,7 @@ def build_blender_asset(ctx: RunContext, asset: AssetPlan, *, judge: bool) -> As
climbs → the GLB checked like a module → ``public/assets/<snake>.glb``.
Until 2026-09-07 a hero got a one-part plan, a full agent session first, and no check
- of the GLB it produced. Measured over the 18 recorded heroes (bench/out, 2026-08-25 →
+ of the GLB it produced. Measured over the 18 recorded heroes (eval/bench/out, 2026-08-25 →
09-05): 15 first sessions killed at the asset timeout (booked at $0 — a killed CLI
reports no usage), 12 GLBs one joined mesh with vertex paint (the one-part plan plus
the Blender contract's "one object per plan part" leave no other way to colour it, so
diff --git a/harness/codeverse3d/tracks/static_object.py b/harness/codeverse3d/tracks/static_object.py
index 5ae3c942..0a01c08a 100644
--- a/harness/codeverse3d/tracks/static_object.py
+++ b/harness/codeverse3d/tracks/static_object.py
@@ -1,7 +1,7 @@
"""StaticObjectTrack: plan → skeleton → baseline → refine rounds → finalise.
Languages: blender (bpy) · cadquery · threejs. Per-part parallel refinement
-is used when the language owns one file per part (threejs) and ≥ 3
+is used when the language owns one file per part (threejs, blender) and ≥ 2
file-disjoint task groups exist; otherwise one whole-object refine task.
"""