Official Codebase of 3DCodeVerse
Python
Delete docs/RUN_LAYOUT.md (owner: redundant); workspace.py and `3dcode show` are the run layout
gaoypeng61d50f6dc2f5
diff --git a/harness/codeverse3d/cli/layout_cmd.py b/harness/codeverse3d/cli/layout_cmd.pyindex a9dcbae7..4fe950e1 100644--- a/harness/codeverse3d/cli/layout_cmd.py+++ b/harness/codeverse3d/cli/layout_cmd.py@@ -1,4 +1,4 @@-"""``3dcode show`` — THE single-run view, in four sections (docs/RUN_LAYOUT.md):+"""``3dcode show`` — THE single-run view, in four sections:* **STATUS** — where the run stands: the run, the rounds, the process holding the runlock, run_state, best-of-N candidates, the latest events. It needs nodiff --git a/harness/codeverse3d/cost/ledger.py b/harness/codeverse3d/cost/ledger.pyindex 32d79613..155d828a 100644--- a/harness/codeverse3d/cost/ledger.py+++ b/harness/codeverse3d/cost/ledger.py@@ -47,7 +47,7 @@ from codeverse3d.proc import iter_jsonl_lineslog = logging.getLogger(__name__)-#: the ledger of a run lives in its telemetry bucket (docs/RUN_LAYOUT.md §telemetry) — the+#: the ledger of a run lives in its telemetry bucket (``<run>/telemetry/``) — the#: one name it has: the root ``cost_ledger.jsonl`` and ``telemetry/usage.jsonl`` aliases went#: on 2026-09-22 (runs written before keep them as dangling-safe symlinks nobody reads)TELEMETRY_DIR = "telemetry"diff --git a/harness/codeverse3d/record/record.py b/harness/codeverse3d/record/record.pyindex 32cd99fa..82c59941 100644--- a/harness/codeverse3d/record/record.py+++ b/harness/codeverse3d/record/record.py@@ -2,8 +2,7 @@``finalize_record`` is the last step of every track run: it fills theenvironment (tool versions + harness git sha), reads the run's total off its cost ledger-(``telemetry/cost.jsonl``, the one record of money), writes ``telemetry/`` (see-docs/RUN_LAYOUT.md) and writes ``record.json`` atomically. ``deliverable/`` is not+(``telemetry/cost.jsonl``, the one record of money), writes ``telemetry/`` and writes ``record.json`` atomically. ``deliverable/`` is notthe run's: which round to hand over is ``codeverse3d.addons.select``'s question(2026-09-22). Telemetry is best-effort: a run is never failed by it."""diff --git a/harness/codeverse3d/record/telemetry.py b/harness/codeverse3d/record/telemetry.pyindex 5a49bac0..0a313998 100644--- a/harness/codeverse3d/record/telemetry.py+++ b/harness/codeverse3d/record/telemetry.py@@ -1,8 +1,7 @@"""Run telemetry: the resolved settings snapshot + the summary of the money ledger.Beside the ledger itself, ``telemetry/cost.jsonl`` (one priced row per model call, written-while the run happens — ``codeverse3d.cost``), two files under ``<run>/telemetry/`` (see-docs/RUN_LAYOUT.md):+while the run happens — ``codeverse3d.cost``), two files under ``<run>/telemetry/``:* ``settings.json`` — how the run was configured: model id per role, thinkinglevel / temperature / judge samples, rounds + budget, rubric and its contentdiff --git a/harness/codeverse3d/workspace.py b/harness/codeverse3d/workspace.pyindex a43cd93c..b52305e3 100644--- a/harness/codeverse3d/workspace.py+++ b/harness/codeverse3d/workspace.py@@ -24,7 +24,7 @@ from pydantic import BaseModelfrom codeverse3d.contracts.agent import FileChangefrom codeverse3d.proc import write_json_atomic-#: the top-level buckets of a run directory (docs/RUN_LAYOUT.md); ``artifacts/`` is the evidence+#: the top-level buckets of a run directory ; ``artifacts/`` is the evidenceDELIVERABLE_DIR = "deliverable" # (a) what the user asked forTELEMETRY_DIR = "telemetry" # (c) what it cost and how it was configured#: harness-owned read-only files inside the workspace (task images: ``tracks/generation.IMAGES_DIR``)@@ -211,7 +211,7 @@ class Workspace:def round_artifacts(self, round_index: int) -> Path:"""``artifacts/rNN/`` — the round's own copy of the build outputs a hand-over needs- (``codeverse3d.record.deliverable.keep_round_artifacts``; docs/RUN_LAYOUT.md)."""+ (``codeverse3d.record.deliverable.keep_round_artifacts``)."""return self.artifacts / f"r{round_index:02d}"def trajectory_dir(self, stage: str, round_index: int) -> Path:diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 4ba0143d..68e11a36 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -3,7 +3,7 @@Package `codeverse3d`, CLI `3dcodeverse` (short alias `3dcode`), repo location `harness/` in the3dcodeverse checkout. Backend only. Python 3.13 (one fixed version), a small Node runtime(`runtime_js/`) for everything Three.js / headless Chrome, and moderngl for the graphics track.-How-to is in `docs/RUNBOOK.md`, the run directory in `docs/RUN_LAYOUT.md`, the skill library in+How-to is in `docs/RUNBOOK.md`, the skill library in`docs/SKILLS.md`, the evaluation protocol in `eval/docs/EVAL.md`.## 0. What it is@@ -211,8 +211,8 @@ tests/ one directory per package area (the count is `pytest --colOne run is one directory, `runs/<slug>/`: `src/` is the code (git, one commit per round),`artifacts/` the last round's build plus every round's own `artifacts/rNN/`, and a pick writes-`deliverable/` + `selection.json`. The full tree and the three buckets are in-`docs/RUN_LAYOUT.md`, their one home.+`deliverable/` + `selection.json`; `telemetry/` holds the cost ledger and settings+(`workspace.py` names the buckets; `3dcode show <slug>` walks a run).## 4. Per-language authoring contracts (raw code; the harness owns export)diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.mdindex b656663b..ae92d47b 100644--- a/harness/docs/RUNBOOK.md+++ b/harness/docs/RUNBOOK.md@@ -103,8 +103,7 @@ How `agents/backends.py` runs agy (do not undo):## 4. Where outputs landEverything lands in `runs/<slug>/` — code in `src/` (git, one commit per round), each round's-build in `artifacts/rNN/`, and after a pick `deliverable/` + `selection.json`; the full tree is-`docs/RUN_LAYOUT.md`. `3dcode status <slug>` prints the stop reason, baseline → picked score,+build in `artifacts/rNN/`, and after a pick `deliverable/` + `selection.json`. `3dcode status <slug>` prints the stop reason, baseline → picked score,the rounds table, cost and the last events.### Looking at results locallydiff --git a/harness/docs/RUN_LAYOUT.md b/harness/docs/RUN_LAYOUT.mddeleted file mode 100644index bd6947b2..00000000--- a/harness/docs/RUN_LAYOUT.md+++ /dev/null@@ -1,165 +0,0 @@-# Run directory layout--One run = one directory (`runs/<slug>/`, `eval/bench/out/<battery>/runs/<slug>/`).-It answers three different questions and keeps them in three separate buckets:--| bucket | question | contents |-|---|---|---|-| `deliverable/` | **what did I get?** | ONE round, the one a pick chose (`3dcode pick`; `3dcode make` picks by score after the run): its code snapshot, its artifact (`object.glb` / `robot.urdf` + `meshes/` / `frames/` + `preview.gif` / the scene bundle), its contact sheet, `captions.json`, `manifest.json` |-| `artifacts/` | **why should I believe it?** | every round's own build (`rNN/`), `renders/rNN/`, `gates/rNN/`, `judge/rNN.json`, `measurement.json`, `census.json`, `tool_renders/` |-| `telemetry/` | **what did it cost and how was it configured?** | `cost.jsonl` (the ledger), `settings.json`, `cost.json` |--The run's **identity** stays at the root, where every tool has always looked for it.-This is the one full tree; every other doc points here:--```-runs/<slug>/- spec.json plan.json record.json identity: what was asked, planned, produced- selection.json which round deliverable/ holds and how it was chosen (after a pick)- run_state.json events.jsonl status + stages + the run-level step log (extra: budget_snapshot, the- clock's active seconds, and spec_fingerprint only — the round history is- rounds/rNN.json + each round's commit); the JSONL event log- src/ agent-authored RAW code, the live working tree (git; commits: spec, skeleton, pre:/agent:<label>- around every session, rNN <kind>; ends at the LAST round)- public/ (scene) compiled assets public/assets/<snake>.glb- deliverable/ (a) the hand-over — one round, written by a pick- artifacts/ (b) the proof: the LAST round's build: object.glb object.stl|step robot.urdf meshes/ build.json census.json- measurement.json …; graphics: frames/fNN_tT.png frames_sheet.png preview.gif metrics.json- rNN/ each round's own build, copied when it built (below)- renders/rNN/ view_<name>.png sheet.png views.json (judge flags) (+ poses/ articulated; <cam>_t<t>.png- metrics.json scenes; frame_t<t>.png metrics.json graphics — the round's own frame metrics)- gates/rNN/ lint_<lang>.json connectivity.json contract.json joint_sweep.json motion_direction.json … (+ *_tool.json)- judge/rNN.json (+ rNN_cli.json from `3dcode judge`; rAA_vs_rBB_pairwise.json from `3dcode pick --by pairwise`)- tool_renders/rNN_<name>/- telemetry/ (c) the accounting- cost.jsonl settings.json cost.json- stages/<name>.json each cached pre-round stage's result (keyed, ARCHITECTURE §7.1)- rounds/rNN.json rounds/candidates.json the round journal; best-of-N's summary (= record.extra["candidates"])- rounds/aborted_rNN.json a round the budget or a crash cut: what it burned, never resumed from- rounds/pre_force/ the journal + record.json `resume --force` archived (then pre_force_2/ …)- trajectories/<label>_rNN/ prompt.md transcript.jsonl stdout.json stderr.log result.json (+ gemini_settings.json- · mcp.json (claude) · agy.log); a retried label lands in <label>.a2_rNN- _assets/<snake>/ (scene) sub-workspaces for blender_glb assets (gitignored)- _cand/c<k>/ (--candidates N) 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)- AGENTS.md CLAUDE.md .antigravityignore (vendor-CLI context; no .3dcode/cookbook.md since D107)-```--`deliverable/`, `telemetry/settings.json` and `telemetry/cost.json` are *derived*: `telemetry/` is-rebuilt from the run's own artifacts, trajectories and events every time the run is finalised, and-`deliverable/` from a round's commit and its `artifacts/rNN/` every time a round is picked.-`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/cost.jsonl` is the ledger itself,-appended while the run happens.--`.gitignore` inside the run ignores `deliverable/`, `telemetry/` (as well as `artifacts/`,-`stages/`, `trajectories/`, …) so the derived buckets never enter the code snapshot.--## Every round, kept (`artifacts/rNN/`)--The run ends at its LAST round (`src/` and the canonical `artifacts/` files), and since-2026-09-22 no round is chosen during the run. So every round keeps what a hand-over of-it needs, the moment it builds (`record.deliverable.keep_round_artifacts`, called by-`tracks/steps._run_round` after the round's commit):--```-artifacts/rNN/ real copies, never hard links (the next build replaces the canonical files)- object.glb object.stl object.step (object tracks; whichever the language exports)- robot.urdf meshes/<link>.glb (articulated)- frames_sheet.png preview.gif (graphics)-```--The rest of a round is already per round: its code is its git commit (a scene's hand-over-— `src/` + `public/`, GLB assets included — is nothing else), its renders and contact sheet-are `renders/rNN/` (a graphics round's judged frames among them), its gates `gates/rNN/`,-its verdict `judge/rNN.json` and `rounds/rNN.json`. The census, `build.json`, the `.blend`-and the measurement are evidence of the LAST build only. A round that did not build keeps-nothing.--## `deliverable/`--Built for ONE round by `codeverse3d.addons.select.package(run_dir, round)` →-`record.deliverable.build_deliverable(ws, record, round)` — from that round's commit and its-`artifacts/rNN/`, never a rebuild. `3dcode make` / `resume` package `select.pick(by="score")`-after the run (highest effective judged score, ties → fewer gate errors → the earlier round;-`--no-pick` skips it); `3dcode pick <slug> [--by pairwise] [--round N]` re-packages-any round:--```-deliverable/- src/** raw code at the round's commit (public/** too, for scenes)- object.glb object.stl object.step- robot.urdf meshes/<link>.glb (articulated)- frames/*.png frames_sheet.png preview.gif (graphics: the round's judged frames)- sheet.png the round's contact sheet- captions.json {detailed, instruction, factory} when captioned- manifest.json every file with role, size, sha256-```--Beside `record.json`, `selection.json` says which round that is and why: `{round, method-(score | pairwise | round), scores (every round's effective score), selected_at}`.-`addons.select.summarise` reads it, so every reader reports the round that was handed over.--Every file is hashed with sha256 and is a real copy (never a hard link), so editing the-hand-over folder can never touch the evidence. Rebuilding is idempotent: the manifest-keeps its previous `generated_at` when the content is unchanged, so re-running the packager-produces no diff.--## `telemetry/`--* **`settings.json`** (`SettingsSnapshot`) — model id, thinking level,- temperature and judge sample count per role; rounds + budget; candidates;- seed; rubric name **and its content hash**; prompt / skill- 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 what the track stamped as it ran,- `record.extra["sampling"]` (the planner's `plan_temperature(track)`, the judge's own- temperature / thinking / samples; `source="run"`) — a vendor CLI owns its knobs.-* **`cost.jsonl`** — THE ledger: one priced row per model call or CLI session, in the- **`codeverse3d.cost` ledger format** (`CallCost`: tokens, unit prices, price- provenance, stage, role, outcome), written by the metered models and agents while the- run happens. It is the only record of money.-* **`cost.json`** (`CostSummary`) — the run-layout view of those rows, computed by the- ledger's own `summarise`: the total (= `record.total_usage`, the ledger's sum at list- price — post-run work a pick buys joins it the next time the run is packaged), tokens, per- stage (`plan / assets / env / zones / baseline / refine / repair / judge / pairwise /- …`), per role, per model, per round, and the run's minutes against- `max_minutes`.--## `record.json`--`record.telemetry` stores the settings snapshot and cost summary written at finalization.-The hand-over is described by `deliverable/manifest.json` and `selection.json`, not by-`record.json`. Round artifacts live in `artifacts/rNN/`.--## Reading a run--```-3dcode show <slug> # STATUS / DELIVERABLE / QUALITY EVIDENCE / COST & SETTINGS-3dcode show <slug> --section cost # just the token price + key step settings-3dcode status <slug> # = show --section status: the rounds, run_state, the lock holder, events-```--`3dcode show` can inspect a run before finalization: when it has no `telemetry/` yet the cost-and settings block is computed on the fly (read-only) from the trajectories,-judge verdicts and events already on disk. Its STATUS section needs no `record.json`, so it-also reads a run in flight (the other three sections wait for the record).--For the money itself across many runs — waste, $ per run, price provenance — use the cost-package's own command, `3dcode cost --runs-dir <root>`.-`3dcode show` is the single-run view; both read the same ledger rows.--## Reading artifacts--* Consumers resolve artifacts through- `record.deliverable.deliverable_path(ws, name)`: `deliverable/<name>` first,- `artifacts/<name>` second. A reader that wants a given ROUND's file asks- `addons.select.round_file(ws, rnd, name)` (`round_outputs`), never `artifacts/<name>`.-* `flywheel export` reads the packaged code snapshot only when git cannot answer- (`meta.code_source == "deliverable"`), and adds a compact `meta.telemetry`- digest when the run has one (`{}` otherwise).-* the gallery (`3dcode gallery build`) links the packaged- `deliverable/object.glb` and `cost.json` when they exist, else the picked round's- `artifacts/rNN/` copy, else `artifacts/`; the per-stage cost line appears only for- runs that carry telemetry.diff --git a/harness/tests/core/test_run_layout.py b/harness/tests/core/test_run_layout.pyindex 511789b0..6d256021 100644--- a/harness/tests/core/test_run_layout.py+++ b/harness/tests/core/test_run_layout.py@@ -1,4 +1,4 @@-"""The run layout (docs/RUN_LAYOUT.md): directories,+"""The run layout (workspace.py): directories,.gitignore and the additive record blocks. Pure filesystem + pydantic."""from __future__ import annotations