Skip to content

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.py
index 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 run
lock, run_state, best-of-N candidates, the latest events. It needs no
diff --git a/harness/codeverse3d/cost/ledger.py b/harness/codeverse3d/cost/ledger.py
index 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_lines
log = 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.py
index 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 the
environment (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 not
the 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.py
index 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, thinking
level / temperature / judge samples, rounds + budget, rubric and its content
diff --git a/harness/codeverse3d/workspace.py b/harness/codeverse3d/workspace.py
index a43cd93c..b52305e3 100644
--- a/harness/codeverse3d/workspace.py
+++ b/harness/codeverse3d/workspace.py
@@ -24,7 +24,7 @@ from pydantic import BaseModel
from codeverse3d.contracts.agent import FileChange
from 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 evidence
DELIVERABLE_DIR = "deliverable" # (a) what the user asked for
TELEMETRY_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.md
index 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 the
3dcodeverse 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 --col
One 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.md
index 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 land
Everything 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 locally
diff --git a/harness/docs/RUN_LAYOUT.md b/harness/docs/RUN_LAYOUT.md
deleted file mode 100644
index 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.py
index 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