Skip to content

Official Codebase of 3DCodeVerse

Python

record: an old run keeps its best_round across a record rewrite — caption / pick --texture no longer lose its GLB, GIF and meshes

gaoypeng7a65ca27abf6
diff --git a/harness/codeverse3d/addons/select.py b/harness/codeverse3d/addons/select.py
index 556ec077..28805f2b 100644
--- a/harness/codeverse3d/addons/select.py
+++ b/harness/codeverse3d/addons/select.py
@@ -242,8 +242,7 @@ def package(run_dir: Path | str, round_index: int, *, texture: bool = False, met
already started from those exact bytes (a paid pass is never bought twice); a pack
ships into the deliverable only when its judge gate shipped it, and the record is
re-packaged so its total takes the pass in (the run's money is its ledger's,
- ``record.package_run``). Otherwise the record is not rewritten: a record from before
- 2026-09-22 keeps the ``best_round`` its canonical build is found by."""
+ ``record.package_run``). Otherwise the record is not rewritten."""
ws = Workspace(run_dir)
rec = load_record(ws)
rnd = next((r for r in rec.rounds if r.index == round_index), None)
diff --git a/harness/codeverse3d/contracts/run.py b/harness/codeverse3d/contracts/run.py
index c7ece396..86cafbf0 100644
--- a/harness/codeverse3d/contracts/run.py
+++ b/harness/codeverse3d/contracts/run.py
@@ -346,10 +346,10 @@ class RunDeliverable(BaseModel):
class RunRecord(BaseModel):
- """One run. A record written before 2026-09-22 also names a best round, a baseline and a
- final score (``best_round`` / ``baseline_score`` / ``final_score``) and a round may carry a
- ``pairwise`` tie-break note: unknown keys, ignored — ``addons.select`` answers which round
- to hand over, after the run."""
+ """One run. A record written before 2026-09-22 also names a baseline and a final score
+ (``baseline_score`` / ``final_score``) and a round may carry a ``pairwise`` tie-break note:
+ unknown keys, ignored — ``addons.select`` answers which round to hand over, after the run.
+ Its ``best_round`` is kept (below): the only pointer to the round its ``artifacts/`` holds."""
spec: Spec
plan: StaticPlan | ArticulatedPlan | ScenePlan | GraphicsPlan | None = None
@@ -368,6 +368,12 @@ class RunRecord(BaseModel):
default=None, description="the run-level timed steps (plan, the prepare stages, best-of-N, the part of "
"an aborted round that ran); None = recorded before 2026-09-22")
extra: dict[str, Any] = Field(default_factory=dict)
+ best_round: int | None = Field(
+ default=None, exclude_if=lambda v: v is None,
+ description="LEGACY, read-only: written only by runs recorded before 2026-09-22 (pre-D80), whose "
+ "finalise rebuilt that round into artifacts/ — record.deliverable.round_outputs finds "
+ "the round's GLB/GIF/meshes by it. Kept so a record rewrite (flywheel caption, "
+ "pick --texture) does not drop it; never set by a new run, never a pick")
@property
def minutes(self) -> float | None:
diff --git a/harness/codeverse3d/record/deliverable.py b/harness/codeverse3d/record/deliverable.py
index eb105229..f099c83f 100644
--- a/harness/codeverse3d/record/deliverable.py
+++ b/harness/codeverse3d/record/deliverable.py
@@ -144,14 +144,27 @@ def _code_tree(ws: Workspace, rnd: RoundRecord | None) -> tuple[dict[str, bytes]
def round_outputs(ws: Workspace, rnd: RoundRecord | None) -> Path | None:
"""Where the round's build outputs are: ``artifacts/rNN/``, or — a run recorded before
rounds kept their own (2026-09-22) — ``artifacts/`` itself, but only for the round
- that run's finalise rebuilt there (the ``best_round`` its record.json still names)."""
+ that run's finalise rebuilt there: the legacy ``RunRecord.best_round``, or — a record
+ rewritten by a build that dropped that key — the round its old deliverable packaged."""
if rnd is None:
return None
kept = ws.round_artifacts(rnd.index)
if kept.is_dir():
return kept
+ return ws.artifacts if legacy_canonical_round(ws) == rnd.index else None
+
+
+def legacy_canonical_round(ws: Workspace) -> int | None:
+ """The round a run recorded before rounds kept ``artifacts/rNN/`` rebuilt into ``artifacts/``
+ (its record's ``best_round``, else its deliverable's round); None for a run that keeps its
+ rounds — there ``artifacts/`` is the LAST build's, no round's by name."""
legacy = (read_json_or_none(ws.record_path) or {}).get("best_round")
- return ws.artifacts if legacy == rnd.index else None
+ if isinstance(legacy, int):
+ return legacy
+ if any(ws.artifacts.glob("r[0-9][0-9]")):
+ return None
+ old = load_deliverable(ws)
+ return old.round if old is not None else None
def texture_report_for(ws: Workspace, glb: Path) -> dict | None:
@@ -167,8 +180,7 @@ def texture_report_for(ws: Workspace, glb: Path) -> dict | None:
return rep
-def _copy_artifacts(ws: Workspace, record: RunRecord, rnd: RoundRecord | None, w: _Writer) -> None:
- out = round_outputs(ws, rnd)
+def _copy_artifacts(ws: Workspace, record: RunRecord, rnd: RoundRecord | None, out: Path | None, w: _Writer) -> None:
if out is None:
return
for name, role in _ARTIFACT_ROLES:
@@ -227,6 +239,7 @@ def build_deliverable(ws: Workspace, record: RunRecord, round_index: int | None,
on an unchanged run produces byte-identical content."""
rnd = next((r for r in record.rounds if r.index == round_index), None)
previous = load_deliverable(ws) if ws.deliverable_manifest_path.is_file() else None
+ out = round_outputs(ws, rnd) # before the wipe: an old run may be found by its old manifest
if clean and ws.deliverable.exists():
shutil.rmtree(ws.deliverable)
ws.ensure_layout()
@@ -234,7 +247,7 @@ def build_deliverable(ws: Workspace, record: RunRecord, round_index: int | None,
files, code_source = _code_tree(ws, rnd)
for rel, data in sorted(files.items()):
w.add_bytes(rel, data, "code" if rel.startswith("src/") else "bundle")
- _copy_artifacts(ws, record, rnd, w)
+ _copy_artifacts(ws, record, rnd, out, w)
_copy_sheet(ws, rnd, w)
_copy_captions(ws, record, w)
entry = ENTRY_FILE.get(record.spec.language, "")
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 21abe7f9..bf5c0631 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -718,7 +718,9 @@ rubric, budget{elapsed_min, max_minutes} (the clock), aborted_rounds?, candidate
rounds/candidates.json payload), texturing?, captions?}. `total_usage` is the sum of telemetry/cost.jsonl at
list price — every billed row once, aborted rounds, retried sessions and billed-but-discarded round-trips
included; a texture pass a pick buys joins it when `select.package` re-packages the run. Δ 2026-09-22: no
-`cost_by_stage` / `rounds_summary` (written, never read), no `best_round` / `baseline_score` /
-`final_score` (old records carry them: ignored — `addons.select.summarise` answers), and `status` is only
+`cost_by_stage` / `rounds_summary` (written, never read), no `baseline_score` / `final_score` (old records
+carry them: ignored — `addons.select.summarise` answers), `best_round` only as a LEGACY read-only field (an old
+record's pointer to the round its `artifacts/` holds, `record.deliverable.round_outputs`; kept across a record
+rewrite, never written by a new run, absent from its JSON), and `status` is only
the stop reason: max_rounds | budget | agent_quota | no_change | no_refine_tasks | judge_unavailable |
failed (an old `passed` / `plateau` loads as `stopped`).
diff --git a/harness/docs/RUN_LAYOUT.md b/harness/docs/RUN_LAYOUT.md
index 9bb27afe..b0f211f7 100644
--- a/harness/docs/RUN_LAYOUT.md
+++ b/harness/docs/RUN_LAYOUT.md
@@ -153,7 +153,9 @@ The hand-over is described by `deliverable/manifest.json` (`RunDeliverable(round
code_source, entry, files[path, role, bytes, sha256], total_bytes, skipped, generated_at)`) and
`selection.json`, not by the record: since 2026-09-22 the record names no best round and
carries no `deliverable` block. A `record.json` written before that still validates — its
-`best_round` / `baseline_score` / `final_score` / `deliverable` keys are ignored, a
+`baseline_score` / `final_score` / `deliverable` keys are ignored, its `best_round` is kept as the legacy
+read-only `RunRecord.best_round` (the round its `artifacts/` holds: `record.deliverable.round_outputs`
+finds that round's GLB / GIF / meshes by it, else by the round its old deliverable packaged), a
`passed` / `plateau` status reads `stopped`, and a manifest that says `best_round` loads as
`round`.
diff --git a/harness/tests/flywheel_cli/test_captions.py b/harness/tests/flywheel_cli/test_captions.py
index a74990ba..6dd95ee9 100644
--- a/harness/tests/flywheel_cli/test_captions.py
+++ b/harness/tests/flywheel_cli/test_captions.py
@@ -14,6 +14,7 @@ from codeverse3d.addons.dataset.captions import (
)
from codeverse3d.contracts.chat import ChatRequest, ChatResponse, ImagePart
from codeverse3d.contracts.common import Usage
+from codeverse3d.record.deliverable import load_deliverable
from codeverse3d.record.record import load_record
GOOD = {
@@ -197,3 +198,54 @@ def test_caption_graphics_run_from_frames(tmp_path):
imgs = [p for p in req.messages[0].parts if isinstance(p, IP)]
assert len(imgs) == 3 # sheet + 2 frame views
+
+
+# --------------------------------------------------------------------------- a run recorded before artifacts/rNN/
+def _old_urdf_run(tmp_path):
+ """An urdf_blender run recorded before rounds kept ``artifacts/rNN/``: its finalise rebuilt
+ round 1 (the ``best_round`` its record.json names) into ``artifacts/`` and packaged it."""
+ from codeverse3d.addons import select
+ from codeverse3d.contracts.common import Language
+
+ from .conftest import make_fake_run
+
+ ws, rec = make_fake_run(tmp_path / "runs", "arm", language=Language.URDF_BLENDER)
+ for i in (0, 1):
+ (ws.round_artifacts(i) / "object.glb").unlink()
+ ws.round_artifacts(i).rmdir()
+ (ws.artifacts / "preview.gif").write_bytes(b"GIF89a")
+ (ws.artifacts / "meshes").mkdir()
+ (ws.artifacts / "meshes" / "base.glb").write_bytes(b"glTF-base")
+ ws.write_json(ws.record_path, {**json.loads(ws.record_path.read_text()), "best_round": 1})
+ select.package(ws.root, 1)
+ return ws, load_record(ws)
+
+
+def test_an_old_runs_caption_then_export_still_ships_its_glb_gif_and_meshes(tmp_path):
+ """`flywheel caption` rewrote record.json through RunRecord, which dropped the raw `best_round`
+ — the only pointer to the round artifacts/ holds — so the re-packaged deliverable and the
+ export lost the old run's object.glb, preview.gif and meshes/."""
+ from codeverse3d.addons.dataset.export import export_one
+
+ ws, rec = _old_urdf_run(tmp_path)
+ urdf = dict(GOOD, instruction="Write a URDF model of a simple robot arm with a base and one hinged link.")
+ caption_sample(ws, rec, "fake:fake", model=FakeModel([urdf]))
+ assert json.loads(ws.record_path.read_text())["best_round"] == 1 # the rewrite keeps the legacy key
+ handed = {f.path for f in load_deliverable(ws).files}
+ assert {"deliverable/object.glb", "deliverable/preview.gif", "deliverable/meshes/base.glb"} <= handed
+ sample = export_one(ws, load_record(ws), tmp_path / "ds")
+ assert {"renders/object.glb", "renders/preview.gif", "meshes/base.glb"} <= set(sample.file_hashes)
+
+
+def test_an_old_run_whose_record_lost_best_round_falls_back_to_its_deliverable(tmp_path):
+ """A record already rewritten without ``best_round``: its packaged deliverable names the round."""
+ from codeverse3d.addons import select
+
+ ws, rec = _old_urdf_run(tmp_path)
+ data = json.loads(ws.record_path.read_text())
+ del data["best_round"]
+ ws.write_json(ws.record_path, data)
+ assert select.round_file(ws, rec.rounds[1]) == ws.artifacts / "object.glb"
+ assert select.round_file(ws, rec.rounds[0]) is None
+ select.package(ws.root, 1) # the rebuild wipes the old manifest: resolved before the wipe
+ assert (ws.deliverable / "object.glb").is_file() and (ws.deliverable / "meshes" / "base.glb").is_file()