Skip to content

Official Codebase of 3DCodeVerse

Python

tracks/scene: scene.js is only ever assembled — compose-agent fallback, scene_compose.j2 and ServiceUnavailable deleted; the zone stage runs its one session without a fan-out of one

gaoypeng17df56ca1db3
diff --git a/harness/codeverse3d/prompts/tracks/scene_compose.j2 b/harness/codeverse3d/prompts/tracks/scene_compose.j2
deleted file mode 100644
index b7ba488c..00000000
--- a/harness/codeverse3d/prompts/tracks/scene_compose.j2
+++ /dev/null
@@ -1,53 +0,0 @@
-# Compose `{{ title }}` — write `src/scene.js`
-
-The environment (`src/env.js`), zones (`src/zones/*.js`) and assets (`src/assets/*.js`,
-`public/assets/*.glb`) exist. Write the entry module that wires them together.
-(The harness normally generates this file itself; you are writing the fallback, so match the
-generated shape exactly.)
-
-## Contract
-{{ frame_doc }}
-{{ contract }}
-`src/scene.js` must `export async function createScene({ THREE, renderer, loaders }) → { scene, cameras, update }`:
-- `scene`: a `THREE.Scene`; build `ctx = { THREE, scene, renderer, loaders, heightAt, assets: {} }`,
- call `const env = (await buildEnv(ctx)) || {}` from `./env.js` (ONE argument: ctx), set
- `ctx.env = env`, then add every zone group — `build(ctx)` imported from `./zones/<snake>.js`
- (the export is named `build`, one argument) — naming each group after its zone.
-- `cameras`: an array of PLAIN OBJECTS `{ name, position: [x,y,z], lookAt: [x,y,z], fov }` (the
- harness builds the PerspectiveCameras). Use the planned numbers literally. `cameras[0]` is the
- establishing shot: it looks at the SUBJECT point, not at the bounds centre, and its height is
- above anything standing between it and the subject.
-- `update(t, dt)`: calls `env.update(t, dt)` and every zone group's `userData.update(t, dt)`
- (collect the list once at creation; never traverse per frame). `tickEnv` and `userData.tick`
- are not part of the contract — do not call them.
-- Wrap each zone build in try/catch: a failing zone logs `console.error('[zone <name>] ' + err)` and is skipped.
-- Use a seeded mulberry32 `rand` (seed 1) so frames are reproducible.
-- GLB assets load via `loaders.gltf.loadAsync('/assets/<snake>.glb')` into `ctx.assets` before the
- zones build.
-
-## Plan
-Bounds: {{ bounds }}
-Zones:
-{{ zones_table }}
-Cameras (author EXACTLY these):
-{{ cameras }}
-Assets:
-{{ asset_api }}
-Animation: {{ animation }}
-
-## DON'T
-- No DOM, no window/document, no fetch, no CDN imports, no Math.random.
-- Do not rebuild env/zones/assets here; only import and place them.
-{% if tool_cards and not single_shot %}
-
-## Tools
-{{ tool_cards }}
-{% endif %}
-
-{% if effects_catalog is defined and effects_catalog %}
-
-{{ effects_catalog }}
-{% endif %}
-
-## Output
-{{ output_format }}
diff --git a/harness/codeverse3d/tracks/common.py b/harness/codeverse3d/tracks/common.py
index b7a84eaa..2ecb2646 100644
--- a/harness/codeverse3d/tracks/common.py
+++ b/harness/codeverse3d/tracks/common.py
@@ -6,8 +6,7 @@ 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
imported lazily only to keep ``tracks`` importable without loading Blender,
-Chrome or a model client. ``ServiceUnavailable`` is what a FAKE raises for a
-service the test did not provide. Nothing here touches a network.
+Chrome or a model client. Nothing here touches a network.
"""
from __future__ import annotations
@@ -42,11 +41,6 @@ from codeverse3d.workspace import Workspace
log = logging.getLogger(__name__)
-class ServiceUnavailable(RuntimeError):
- """A test double has no implementation for this service (``scene._assemble_stage``
- falls back to an agent compose session on it)."""
-
-
def _import(path: str, name: str) -> Any:
return getattr(importlib.import_module(path), name)
diff --git a/harness/codeverse3d/tracks/scene.py b/harness/codeverse3d/tracks/scene.py
index 213429eb..87f42274 100644
--- a/harness/codeverse3d/tracks/scene.py
+++ b/harness/codeverse3d/tracks/scene.py
@@ -47,8 +47,8 @@ from codeverse3d.spatial.frame_motion import motion_text_for
from codeverse3d.spatial.render_scene import perf_detail
from codeverse3d.texturing.plan import texture_pack_prompt
from codeverse3d.tracks import skills_hook
-from codeverse3d.tracks.common import RunContext, ServiceUnavailable, generate_for, single_shot_ctx
-from codeverse3d.tracks.generation import GenerationResult, GenerationTask
+from codeverse3d.tracks.common import RunContext, generate_for, single_shot_ctx
+from codeverse3d.tracks.generation import GenerationTask
from codeverse3d.tracks.lifecycle import BaseTrack
from codeverse3d.tracks.prompting import (
SCENE_FILES,
@@ -348,38 +348,28 @@ class SceneTrack(BaseTrack):
plan: ScenePlan = ctx.plan # type: ignore[assignment]
t0 = time.time()
# one author for the whole world (D70; the fan-out control arm was removed 2026-09-21)
- batches = [list(plan.zones)]
- if any(len(b) > 1 for b in batches):
- ctx.events.emit("zones.batched", batches=[[z.name for z in b] for b in batches])
-
- # once, before the fan-out: every zone session shares one workspace, so three
- # parallel attaches would race the same AGENTS.md. The zone rows (R3 "zone",
- # R14/R18 "zone") are identical for every batch, so one route is the right route.
+ zones = list(plan.zones)
+ if len(zones) > 1:
+ ctx.events.emit("zones.batched", batches=[[z.name for z in zones]])
zone_gen = self._strategy(ctx, "zones")
skills_hook.attach_for_round(zone_gen, index=0, kind="zone")
-
- def _one(batch: list[ZonePlan]) -> GenerationResult:
- task = skills_hook.with_inlined_skill(zone_gen, [self._zone_task(zone_gen, batch)])[0]
- return generate_for(zone_gen, task)
-
- results = fan_out(batches, _one, max_workers=ctx.settings.limits.max_parallel_agents, label="zones",
- item_name=lambda b: "+".join(z.name for z in b))
out: dict[str, Any] = {}
- for batch, r in zip(batches, results, strict=True):
- if isinstance(r, Exception):
- # BudgetExceeded included: the sibling zones' paid modules are still
- # recorded + committed; the guard's boundary check below stops the run.
- for zone in batch:
- out[zone.name] = {"ok": False, "notes": f"{type(r).__name__}: {r}"}
- else:
- written = {c.path for c in r.files_changed}
- for zone in batch:
- rel = zone_file(zone)
- # a batched session must have produced EVERY file it owns; the skeleton
- # left a stub at every zone path, so existence proves nothing — the file
- # must have been reported as changed or actually rewritten in this stage
- ok = r.ok and (len(batch) == 1 or rel in written or _touched(ctx.ws.root / rel, t0))
- out[zone.name] = {"ok": ok, "files": [rel] if ok else [], "notes": r.notes}
+ try:
+ task = skills_hook.with_inlined_skill(zone_gen, [self._zone_task(zone_gen, zones)])[0]
+ r = generate_for(zone_gen, task)
+ except Exception as e: # noqa: BLE001 — BudgetExceeded included: the stage is still
+ # recorded + committed; the guard's boundary check below stops the run
+ log.warning("zones session failed: %s: %s", type(e).__name__, e)
+ out = {zone.name: {"ok": False, "notes": f"{type(e).__name__}: {e}"} for zone in zones}
+ else:
+ written = {c.path for c in r.files_changed}
+ for zone in zones:
+ rel = zone_file(zone)
+ # a session that owns several zones must have produced EVERY file; the skeleton
+ # left a stub at every zone path, so existence proves nothing — the file
+ # must have been reported as changed or actually rewritten in this stage
+ ok = r.ok and (len(zones) == 1 or rel in written or _touched(ctx.ws.root / rel, t0))
+ out[zone.name] = {"ok": ok, "files": [rel] if ok else [], "notes": r.notes}
self._record_skills(zone_gen, "zone")
ctx.ws.commit("zones")
ctx.events.emit("zones.done", ok=[k for k, v in out.items() if v["ok"]], failed=[k for k, v in out.items() if not v["ok"]])
@@ -428,22 +418,10 @@ class SceneTrack(BaseTrack):
timeout_s=ctx.budget.timeout_s(ZONE_TIMEOUT_S * max(1, len(batch)), floor_s=180))
def _assemble_stage(self, ctx: RunContext) -> dict[str, Any]:
- try:
- result = ctx.services.assemble_scene(ctx.ws, ctx.plan)
- ctx.ws.commit("assemble")
- ctx.events.emit("assemble.done", deterministic=True)
- return {"ok": True, "deterministic": True, "result": result} # StageRunner.stage jsonables it
- except ServiceUnavailable as e:
- ctx.events.emit("assemble.fallback", reason=str(e))
- prompt = render("tracks/scene_compose.j2", **self._ctx(ctx))
- ctx.record_prompt("scene_compose", prompt)
- task = GenerationTask(label="compose", prompt=prompt, system=self.system_prompt(ctx), files_hint=["src/scene.js"], round=0,
- kind="compose", temperature=0.4, owns_entry=True, images=reference_images(ctx))
- task = self._deliver_skills(ctx, "compose", [task])[0]
- res = generate_for(ctx, task)
- self._record_skills(ctx, "compose")
- ctx.ws.commit("compose")
- return {"ok": res.ok, "deterministic": False, "files": [c.path for c in res.files_changed], "notes": res.notes}
+ result = ctx.services.assemble_scene(ctx.ws, ctx.plan)
+ ctx.ws.commit("assemble")
+ ctx.events.emit("assemble.done", deterministic=True)
+ return {"ok": True, "deterministic": True, "result": result} # StageRunner.stage jsonables it
def prepare_salvage(self, ctx: RunContext) -> bool:
"""The budget stopped a stage before round 0: assemble whatever the stages DID
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 5b612f38..25703f58 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -476,7 +476,7 @@ GenerationTask.phase: int = 0 # tasks run in parallel WITHIN a phase, phases i
generate(ws, *, agent_id, task, ..., budget=BudgetGuard, max_turns=0, wrapup_turns=6) -> GenerationResult
# GenerationResult.storm: every session died on a transient streak (AgentResult.transient) and wrote nothing
tracks.common.generate_for(ctx: RunContext, task: GenerationTask) -> GenerationResult
- # THE call every stage makes (env, zones, compose, rounds, repairs, asset ladder, judged fix): generate()
+ # THE call every stage makes (env, zones, rounds, repairs, asset ladder, judged fix): generate()
# with everything ctx knows, and a storm-dead task retried through single_shot_ctx(ctx) (D68)
tracks.common.single_shot_agent_id(agent_id, chat_model_id='') -> str · single_shot_ctx(ctx) -> RunContext | None
# moved from tracks.scene_assets 2026-09-07 (never scene-specific)
diff --git a/harness/docs/SKILLS.md b/harness/docs/SKILLS.md
index 203bd8ba..1a9e6b76 100644
--- a/harness/docs/SKILLS.md
+++ b/harness/docs/SKILLS.md
@@ -538,9 +538,10 @@ so; the rest are live.
generated the whole baseline (`_env_stage`, `_zones_stage`, `_assemble_stage`) without ever
reaching `skills_hook.attach_for_round`, which lived only in `steps.run_round`; and
`baseline_tasks` returned `[]`, so round 0 listed four bundles to a session that did not
- exist. Measured at **0 opens / 30 listings**. The three stages now attach and record with
- their own kind. `tests/skills/test_delivery_reaches_the_session.py` runs a real
- two-zone-session scene and proves env/zone/compose attach exactly once, before generation,
+ exist. Measured at **0 opens / 30 listings**. The generating stages now attach and record with
+ their own kind (`scene.js` is assembled without a session since the compose fallback went,
+ 2026-09-22). `tests/skills/test_delivery_reaches_the_session.py` runs a real
+ two-zone-session scene and proves env/zone attach exactly once, before generation,
with matching telemetry. **The scene bundles' read rate against working delivery
is UNMEASURED — that is the next wave's first experiment.**
* ~~**`api-agent` has no skill affordance.**~~ **FIXED earlier**, and re-measured here: with
diff --git a/harness/tests/orchestrator_tracks/fakes.py b/harness/tests/orchestrator_tracks/fakes.py
index c12dd290..d04607c5 100644
--- a/harness/tests/orchestrator_tracks/fakes.py
+++ b/harness/tests/orchestrator_tracks/fakes.py
@@ -31,12 +31,16 @@ from codeverse3d.contracts.common import Language, Usage
from codeverse3d.contracts.plan import Plan
from codeverse3d.contracts.run import RunRecord
from codeverse3d.conventions import to_snake
-from codeverse3d.tracks.common import Services, ServiceUnavailable
+from codeverse3d.tracks.common import Services
from codeverse3d.workspace import Workspace
FAIL_MARK = "RAISE_BUILD_ERROR"
+class ServiceUnavailable(RuntimeError):
+ """This fake has no implementation for the service (the test did not provide one)."""
+
+
# ----------------------------------------------------------------------------- runtime
class FakeRuntime:
"""Writes a tiny GLB (one box per part) on build; fails when a src file contains FAIL_MARK."""
@@ -257,7 +261,7 @@ def _png(path: Path, size: int = 32) -> None:
class FakeServices(Services):
def __init__(self, *, runtime_factory: Callable[[Language], Any] | None = None, judge: Any | None = None,
- contract_errors: int = 0, assemble: bool = False, sweep_errors: int = 0, pairwise: Any | None = None,
+ contract_errors: int = 0, assemble: bool = True, sweep_errors: int = 0, pairwise: Any | None = None,
silhouette_iou: float | None = None, motion_errors: int = 0):
self.runtime_factory = runtime_factory or (lambda lang: FakeRuntime(lang))
self._judge = judge
diff --git a/harness/tests/orchestrator_tracks/test_prompts_assets.py b/harness/tests/orchestrator_tracks/test_prompts_assets.py
index 7f8df13c..38ef9355 100644
--- a/harness/tests/orchestrator_tracks/test_prompts_assets.py
+++ b/harness/tests/orchestrator_tracks/test_prompts_assets.py
@@ -22,7 +22,7 @@ from tests.orchestrator_tracks.fakes import FakeAgent, FakeJudge, FakeRuntime, F
TEMPLATES = {"plan_static", "plan_articulated", "plan_scene", "generate_static", "generate_articulated", "refine_object", "repair",
"generate_static_part", "assemble_static", "detail_object",
- "scene_asset", "scene_env", "scene_zone", "scene_compose", "scene_refine"}
+ "scene_asset", "scene_env", "scene_zone", "scene_refine"}
def _asset_module(job) -> str:
@@ -117,7 +117,7 @@ def test_scene_templates_render_and_asset_stage_with_blender(tmp_ws, settings):
from codeverse3d.tracks.scene import SceneTrack
st = SceneTrack(services=services)
- for tpl, extra in (("scene_env", {}), ("scene_compose", {}),
+ for tpl, extra in (("scene_env", {}),
("scene_zone", dict(zone_name="Quay", zone_description="d", zone_bbox="b", zone_contents=["Bollard"], zone_file="src/zones/quay.js", neighbours=["Water: x"])),
("scene_refine", dict(round_index=1, tasks=["t"], targets=["Quay"], files=["src/zones/quay.js"], edit_only_these=False, judge_summary="j", current_files={}))):
out = render(f"tracks/{tpl}.j2", **st._ctx(ctx, **extra))
diff --git a/harness/tests/orchestrator_tracks/test_tracks.py b/harness/tests/orchestrator_tracks/test_tracks.py
index 9cfb3a93..61529e69 100644
--- a/harness/tests/orchestrator_tracks/test_tracks.py
+++ b/harness/tests/orchestrator_tracks/test_tracks.py
@@ -187,8 +187,6 @@ def _scene_writer(job, ws):
return {rel: f"export function build(){{}} // {label}\n" for rel in job.files_hint}
if label.startswith("zone_"):
return {f"src/zones/{label[5:]}.js": f"export function build(){{}} // {label}\n"}
- if label == "compose":
- return {"src/scene.js": "export function createScene(){}\n"}
if label.startswith("refine"):
return {f: f"// refined by {label}\n" for f in job.prompt.split("EDIT ONLY THESE FILES")[-1].splitlines() if False} or {"src/scene.js": f"// {label}\n"}
return {"src/scene.js": "// x\n"}
@@ -202,7 +200,7 @@ def test_scene_track_stages_and_rounds(tmp_path, settings):
spec = make_spec(Track.SCENE, Language.SCENE_THREEJS, max_rounds=1, prompt="a small harbour at dusk")
ws = Workspace(tmp_path / "runs" / "harbour")
agent = FakeAgent(_scene_writer)
- services = FakeServices(assemble=False)
+ services = FakeServices()
track = SceneTrack(services=services, judge=FakeJudge(scores=(0.6, 0.7), targets=("Quay", "Water")), agent=agent,
planner_model=_planner(plan.model_dump(mode="json")), settings=settings, runtime=FakeRuntime(Language.SCENE_THREEJS))
rec = track.run(spec, ws)
@@ -210,8 +208,7 @@ def test_scene_track_stages_and_rounds(tmp_path, settings):
# Quay and Water are both small zones (≤ 3 placements) → ONE batched session owning both files
# assets ∥ env: the combined stage's three sessions interleave freely; order resumes at zones
assert set(labels[:3]) == {"asset_fishing_boat", "asset_bollard", "env"} and "zones_quay_water" in labels
- assert "compose" in labels # assembler unavailable → composer agent fallback
- assert labels.index("env") < labels.index("zones_quay_water") < labels.index("compose")
+ assert "compose" not in labels and labels.index("env") < labels.index("zones_quay_water") # scene.js is assembled
assert (ws.src / "assets" / "fishing_boat.js").is_file() and (ws.src / "zones" / "quay.js").is_file() and (ws.src / "scene.js").is_file()
zone_prompt = next(j.prompt for j in agent.jobs if j.label == "zones_quay_water")
assert "buildFishingBoat" in zone_prompt and "8.00×3.50×3.00" in zone_prompt and "Neighbouring zones" in zone_prompt
diff --git a/harness/tests/scene_runtime/test_skeleton.py b/harness/tests/scene_runtime/test_skeleton.py
index 1b68e8b6..767abd48 100644
--- a/harness/tests/scene_runtime/test_skeleton.py
+++ b/harness/tests/scene_runtime/test_skeleton.py
@@ -139,7 +139,7 @@ def test_the_effects_catalog_reaches_the_scene_prompts_and_only_those():
assert effects_catalog_text(Language.GLSL_SHADER) == ""
tpl = PROMPTS_DIR / "tracks"
- for name in ("scene_env.j2", "scene_zone.j2", "scene_refine.j2", "scene_compose.j2"):
+ for name in ("scene_env.j2", "scene_zone.j2", "scene_refine.j2"):
assert "effects_catalog" in (tpl / name).read_text(), name
# the asset session authors BLENDER bpy, so it must NOT carry the table
assert "effects_catalog" not in (tpl / "scene_asset.j2").read_text()
diff --git a/harness/tests/skills/test_delivery_reaches_the_session.py b/harness/tests/skills/test_delivery_reaches_the_session.py
index 034db05b..66933613 100644
--- a/harness/tests/skills/test_delivery_reaches_the_session.py
+++ b/harness/tests/skills/test_delivery_reaches_the_session.py
@@ -2,14 +2,14 @@
The read loop measured c3d-scene-composition / -lighting / -motion at 0 opens out of 3
listings each and read it as a wording problem. It was not: the scene track did all of
-its baseline generation in ``prepare()`` — the env, zones and compose stages called
+its baseline generation in ``prepare()`` — the env and zones stages called
``tracks.generation.generate`` directly — while ``skills_hook.attach_for_round`` was only
reached from ``steps.run_round``. ``SceneTrack.baseline_tasks`` returns ``[]``, so round 0
listed the bundles to a round that had no generation task to consume them. That was
exactly "listed 3, opened 0", and no rewrite of a SKILL.md could have fixed it.
-CLOSED 2026-08-25 (curate wave): ``SceneTrack._env_stage`` / ``_zones_stage`` /
-``_assemble_stage`` now go through ``_deliver_skills`` + ``_record_skills``. These tests
+CLOSED 2026-08-25 (curate wave): ``SceneTrack._env_stage`` / ``_zones_stage`` now go
+through the skill hook + ``_record_skills`` (``scene.js`` is assembled, no session). These tests
keep every agent-driving module on the hook, so the gap cannot reopen quietly. The scene
bundles' read rate is UNMEASURED against this delivery — that is the next wave's first
experiment, and until it runs their ledger rows stay ``mixed``/``inherited``, not
@@ -46,7 +46,7 @@ def scene_run(tmp_path, monkeypatch):
prompt="a small harbour at dusk")
ws = Workspace(tmp_path / "runs" / "harbour_skills")
agent = FakeAgent(_scene_writer)
- track = SceneTrack(services=FakeServices(assemble=False), judge=FakeJudge(scores=(0.6,)),
+ track = SceneTrack(services=FakeServices(), judge=FakeJudge(scores=(0.6,)),
agent=agent, planner_model=_planner(plan.model_dump(mode="json")),
settings=Settings(), runtime=FakeRuntime(Language.SCENE_THREEJS))
rec = track.run(spec, ws)
@@ -58,17 +58,14 @@ def test_every_scene_generation_stage_gets_skills_before_its_sessions(scene_run)
rec, agent, ws = scene_run
events = EventLog(ws.events_path).read()
attachments = [e for e in events if e.get("event") == "skills.attached"]
- by_kind = {e["kind"]: e for e in attachments if e.get("kind") in {"env", "zone", "compose"}}
+ by_kind = {e["kind"]: e for e in attachments if e.get("kind") in {"env", "zone"}}
- assert Counter(e.get("kind") for e in attachments) >= Counter(
- {"env": 1, "zone": 1, "compose": 1}
- )
+ assert Counter(e.get("kind") for e in attachments) >= Counter({"env": 1, "zone": 1})
assert all(sum(e.get("kind") == kind for e in attachments) == 1 for kind in by_kind)
assert {"c3d-scene-composition", "c3d-scene-lighting"} <= set(by_kind["env"]["skills"])
assert {"c3d-scene-composition", "c3d-scene-motion", "c3d-bbox-contract"} <= set(
by_kind["zone"]["skills"]
)
- assert {"c3d-scene-composition", "c3d-scene-motion"} <= set(by_kind["compose"]["skills"])
def belongs(kind: str, event: dict) -> bool:
label = str(event.get("label", ""))
@@ -81,7 +78,7 @@ def test_every_scene_generation_stage_gets_skills_before_its_sessions(scene_run)
generated_at = [i for i, event in enumerate(events) if belongs(kind, event)]
assert generated_at and all(attach_at < i for i in generated_at), kind
assert sum(belongs("zone", event) for event in events) == 1 # D70: one session owns every zone file
- assert Counter(job.kind for job in agent.jobs) >= Counter({"env": 1, "zone": 1, "compose": 1})
+ assert Counter(job.kind for job in agent.jobs) >= Counter({"env": 1, "zone": 1})
telemetry_path = ws.root / "telemetry" / "skills.jsonl"
assert telemetry_path.is_file()