Official Codebase of 3DCodeVerse
Python
planner: every track through one loop dispatched on spec.track — graphics stops parameterising it with six hooks
gaoypengb99daf617c63
diff --git a/harness/codeverse3d/record/telemetry.py b/harness/codeverse3d/record/telemetry.pyindex 4e740f63..88a467a1 100644--- a/harness/codeverse3d/record/telemetry.py+++ b/harness/codeverse3d/record/telemetry.py@@ -86,15 +86,10 @@ def _judge_defaults() -> dict[str, Any]:def _planner_defaults(record: RunRecord) -> dict[str, Any]:- """The temperature THIS track plans at (``BaseTrack.plan_temperature``: graphics 0.5, the- rest 0.4). ``planner.plan()``'s own default is never the one used — every track passes- its own — so reading it reported 0.4 for every graphics run."""- try:- from codeverse3d.tracks import get_track+ """The temperature THIS track plans at (``planner.plan_temperature``: graphics 0.5, the rest 0.4)."""+ from codeverse3d.tracks.planner import plan_temperature- return {"temperature": get_track(record.spec.track).plan_temperature}- except Exception: # pragma: no cover- return {}+ return {"temperature": plan_temperature(record.spec.track)}def _generator_defaults(model_id: str) -> dict[str, Any]:diff --git a/harness/codeverse3d/tracks/graphics.py b/harness/codeverse3d/tracks/graphics.pyindex ffee83e4..ad28be46 100644--- a/harness/codeverse3d/tracks/graphics.py+++ b/harness/codeverse3d/tracks/graphics.py@@ -2,11 +2,12 @@Languages: glsl_shader (Shadertoy-style fragment shader) · opengl_python (rawmoderngl program). Reuses ``BaseTrack`` (lifecycle) and ``run_round`` (steps)-unchanged; the track-specific pieces are the planner hooks (template / example /-acceptance, below), the prompt context (no 3D frame), the-``gl_frames`` gate (frame statistics from the build) and the render step (the-sampled frames + contact sheet as the RenderSet the ``shader_v2`` judge sees).-Refinement is always one whole-program task.+unchanged; the track-specific pieces are the recipe seeding, the prompt context+(no 3D frame), the ``gl_frames`` gate (frame statistics from the build) and the render+step (the sampled frames + contact sheet as the RenderSet the ``shader_v2`` judge sees).+Planning is ``tracks/planner.py``'s, like every track's (template, worked example,+T = 0.5, acceptance: all dispatched on the track there). Refinement is always one+whole-program task."""from __future__ import annotations@@ -28,9 +29,8 @@ from codeverse3d.contracts.artifacts import (Severity,)from codeverse3d.contracts.common import HARNESS_OWNED_SRC, TRACK_INFO, Language, Track-from codeverse3d.contracts.plan import AcceptanceItem, GraphicsPlan, Plan+from codeverse3d.contracts.plan import GraphicsPlan, Planfrom codeverse3d.contracts.run import RoundRecord-from codeverse3d.contracts.spec import Specfrom codeverse3d.languages._gl_common import SHEET_NAME, read_metricsfrom codeverse3d.languages.glsl_shader import COMMON_GLSL, FUNC_DEF, strip_commentsfrom codeverse3d.orchestrator import TaskGroup@@ -39,7 +39,6 @@ from codeverse3d.prompts.sections import Section, split_sectionsfrom codeverse3d.tracks.common import RunContextfrom codeverse3d.tracks.generation import GenerationTaskfrom codeverse3d.tracks.lifecycle import BaseTrack, StageRunner-from codeverse3d.tracks.planner import add_acceptance_itemfrom codeverse3d.tracks.prompting import (base_prompt_context,is_always_chapter,@@ -276,57 +275,13 @@ def seed_recipes(ctx: RunContext) -> list[str]:return [r.name for r in new]-# ===================================================================== planner hooks + prompt context + frames-PLAN_TEMPLATE = "tracks/plan_graphics.j2"-PLAN_TEMPERATURE = 0.5-PLAN_MAX_OUTPUT_TOKENS = 65_536 # the model's declared output ceiling; unused tokens cost nothing+# ===================================================================== prompt context + framesEXPECTED_FILES: dict[Language, list[str]] = {Language.GLSL_SHADER: ["src/shader.frag", "src/common.glsl"],Language.OPENGL_PYTHON: ["src/program.py"],}-# ----------------------------------------------------------------------------- planner-def plan_example() -> dict[str, Any]: # the graphics worked example (planner hook)- return {- "title": "Neon rain on a window", "summary": "Looking through a rain-streaked window at a neon-lit street at night; "- "drops run down the glass, city lights turn into coloured bokeh discs that pulse.",- "style": "cyberpunk night: deep indigo/black base, magenta + cyan neon accents, warm sodium highlights; soft, filmic",- "resolution": [1280, 720], "duration_s": 8.0,- "passes": [- {"name": "CityBokeh", "kind": "fullscreen", "description": "background: 40-60 blurred bokeh discs (hash-placed, 3 depth layers, cyan/magenta/amber), slow horizontal parallax, pulsing brightness"},- {"name": "RainDrops", "kind": "fullscreen", "description": "grid-cell drops with hash offsets, running trails (fract(t) per cell), refraction offset applied when sampling the background"},- {"name": "Grade", "kind": "postprocess", "description": "vignette, slight chromatic aberration, tonemap + gamma"},- ],- "uniforms": ["u_time", "u_resolution"],- "motion": "drops slide down with gravity and wobble; bokeh drifts left 0.02/s and pulses at 0.5-1 Hz; no hard cuts",- "key_visuals": ["rain drops with trails on glass", "blurred neon bokeh discs", "dark night street behind", "magenta/cyan palette"],- "acceptance": [- {"id": "a1", "text": "Raindrops with trails visibly run down the glass (compare t=0 and t=1)", "how": "visual", "priority": "must"},- {"id": "a2", "text": "Blurred coloured bokeh lights are visible in the background", "how": "visual", "priority": "must"},- {"id": "a3", "text": "Frames change over time (no static image)", "how": "probe", "priority": "must"},- ],- }---def ensure_graphics_acceptance(plan: GraphicsPlan, spec: Spec) -> GraphicsPlan:- """Spec must_have / must_not → visual items; planned motion → a probe item (never 'ground contact')."""- items: list[AcceptanceItem] = list(plan.acceptance)- for m in spec.constraints.must_have:- add_acceptance_item(items, "must", f"Includes: {m}", "visual")- for m in spec.constraints.must_not:- add_acceptance_item(items, "not", f"Does NOT include: {m}", "visual")- if plan.motion.strip() and not any("static" in a.text.lower() or "motion" in a.text.lower() or "change over time" in a.text.lower() for a in items):- add_acceptance_item(items, "motion", "Frames change over time as planned (not a static image)", "probe")- plan.acceptance = items- return plan---def graphics_event_stats(plan: GraphicsPlan) -> dict[str, Any]:- """``plan.done`` payload for graphics (passes, not parts/zones)."""- return {"n_passes": len(plan.passes), "n_acceptance": len(plan.acceptance)}--# ----------------------------------------------------------------------------- prompt contextdef graphics_expected_files(ctx: RunContext) -> list[str]:return list(EXPECTED_FILES.get(ctx.language, ["src/shader.frag"]))@@ -424,26 +379,12 @@ class GraphicsTrack(BaseTrack):plan_model = GraphicsPlangenerate_template = "tracks/generate_graphics.j2"refine_template = "tracks/refine_graphics.j2"- # 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# refinement is always ONE whole-program taskallow_refine_fanout = Falsedef make_pipeline(self) -> GraphicsPipeline:return GraphicsPipeline()- # ------------------------------------------------------------------ planner hooks- def plan_example(self, spec: Spec) -> dict[str, Any]:- return plan_example()-- def finalise_plan(self, plan_obj: Any, spec: Spec) -> Any:- return ensure_graphics_acceptance(plan_obj, spec)-- def plan_event_stats(self, plan_obj: Any) -> dict[str, Any]:- return graphics_event_stats(plan_obj)-# ------------------------------------------------------------------ preparedef prepare(self, ctx: RunContext, runner: StageRunner) -> None:"""Skeleton, then the brief's verified cookbook recipes into the harness-owned, read-onlydiff --git a/harness/codeverse3d/tracks/lifecycle.py b/harness/codeverse3d/tracks/lifecycle.pyindex c3f18781..37257ff2 100644--- a/harness/codeverse3d/tracks/lifecycle.py+++ b/harness/codeverse3d/tracks/lifecycle.py@@ -1,9 +1,9 @@"""BaseTrack: the resumable plan → prepare → rounds → finalise lifecycle.Concrete tracks (static / articulated / scene / graphics) override the hooks-(``plan_model``, ``make_pipeline``, ``prepare``, ``baseline_tasks``, the planner-knobs ``plan_template``/``plan_example``/``finalise_plan`` and the refine-scaffold's ``_refine_task``). All bookkeeping — workspace, events, budget, run+(``plan_model``, ``make_pipeline``, ``prepare``, ``baseline_tasks`` and the refine+scaffold's ``_refine_task``); what differs per track at PLANNING time is+``tracks/planner.py``'s alone. All bookkeeping — workspace, events, budget, runstate, stage cache, the fixed round count, record — lives here once. Which round of afinished run to hand over is not the core's question: ``codeverse3d.addons.select``."""@@ -50,9 +50,7 @@ from codeverse3d.tracks.common import (load_prompt_or,)from codeverse3d.tracks.generation import GenerationTask, single_shot_model_id-from codeverse3d.tracks.planner import default_event_stats, ensure_acceptance, normalise_namesfrom codeverse3d.tracks.planner import plan as run_planner-from codeverse3d.tracks.planner import plan_example as default_plan_examplefrom codeverse3d.tracks.prompting import (base_prompt_context,expected_files,@@ -142,18 +140,13 @@ class SpecChanged(RuntimeError):class BaseTrack:"""Shared lifecycle. Subclasses set ``track``, ``rubric``, ``plan_model``- and parameterise the ONE planner loop / refine scaffold via the hook- attributes below (``plan_template``, ``plan_example``, ``_refine_task`` …)."""+ and parameterise the refine scaffold via the hooks below (``_refine_task`` …)."""track: Trackrubric: strplan_model: type[Plan]generate_template: str = ""refine_template: str = ""- #: 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#: refine fan-out (graphics is always ONE whole-program task)allow_refine_fanout: bool = True#: share of the run budget the BASELINE may use (1.0 = no soft cap). The scene@@ -213,19 +206,6 @@ class BaseTrack:still returns False."""return (ctx.ws.root / "rounds" / "candidates.json").is_file()- # ---- planner hooks (tracks/planner.py runs the one loop)- def plan_example(self, spec: Spec) -> dict[str, Any]:- """Worked example JSON for the plan system prompt."""- return default_plan_example(spec.track)-- def finalise_plan(self, plan_obj: Any, spec: Spec) -> Any:- """Post-validation fixup (names + deterministic acceptance items)."""- return ensure_acceptance(normalise_names(plan_obj), spec)-- def plan_event_stats(self, plan_obj: Any) -> dict[str, Any]:- """Extra ``plan.done`` payload (n_parts/n_zones… per track)."""- return default_event_stats(plan_obj)-# ---- refine hooks (the scaffold below is shared; tracks fill in the task)def refine_file_for_target(self, ctx: RunContext) -> Any:"""``target → [files]`` mapper for refine tasks (None = whole-object language)."""@@ -482,16 +462,11 @@ class BaseTrack:ctx.state.save(ctx.ws)try:plan = run_planner(ctx.spec, ctx.spec.backends.planner, self.plan_model, ctx.ws, model=self._planner_model,- events=ctx.events, budget=ctx.budget, runtime=ctx.runtime, **self._plan_kwargs(ctx.spec))+ events=ctx.events, budget=ctx.budget, runtime=ctx.runtime)finally:self._save_budget(ctx) # charged on success AND PlanningErrorreturn plan- def _plan_kwargs(self, spec: Spec) -> dict[str, Any]:- return {"template": self.plan_template, "example": self.plan_example(spec),- "temperature": self.plan_temperature, "max_output_tokens": self.plan_max_output_tokens,- "finalise": lambda p: self.finalise_plan(p, spec), "event_stats": self.plan_event_stats}-# ------------------------------------------------------------------ stagesdef stage_skeleton(self, ctx: RunContext, runner: StageRunner) -> list[str]:def _do() -> list[str]:diff --git a/harness/codeverse3d/tracks/planner.py b/harness/codeverse3d/tracks/planner.pyindex 67ee5545..723bcac2 100644--- a/harness/codeverse3d/tracks/planner.py+++ b/harness/codeverse3d/tracks/planner.py@@ -1,4 +1,10 @@-"""Planner: spec → validated Plan (StaticPlan / ArticulatedPlan / ScenePlan).+"""Planner: spec → validated Plan (StaticPlan / ArticulatedPlan / ScenePlan / GraphicsPlan).++The ONE owner of what differs per track at planning time — the system-prompt template+(``PLAN_TEMPLATES``), the worked example (``plan_example``), the sampling temperature+(``plan_temperature``), the output-token floor, the plan budget's unit (graphics counts+passes) and the deterministic acceptance items (``ensure_acceptance``): all dispatched on+``spec.track``, so no track class parameterises the loop.An optional cheap **brief expansion** (``expand_brief``, below) turns the one-linerequest into an engineering brief, which — together with a **plan budget derived@@ -20,7 +26,6 @@ import hashlibimport jsonimport loggingimport re-from collections.abc import Callablefrom dataclasses import dataclassfrom pathlib import Pathfrom typing import Any, TypeVar@@ -482,6 +487,26 @@ def enrich_plan(plan_obj: Any, brief: EngineeringBrief | None) -> Any:# ===================================================================== worked examplesdef plan_example(track: Track) -> dict[str, Any]:"""Compact, valid worked example per track (concrete beats abstract)."""+ if track is Track.GRAPHICS:+ return {+ "title": "Neon rain on a window", "summary": "Looking through a rain-streaked window at a neon-lit street at night; "+ "drops run down the glass, city lights turn into coloured bokeh discs that pulse.",+ "style": "cyberpunk night: deep indigo/black base, magenta + cyan neon accents, warm sodium highlights; soft, filmic",+ "resolution": [1280, 720], "duration_s": 8.0,+ "passes": [+ {"name": "CityBokeh", "kind": "fullscreen", "description": "background: 40-60 blurred bokeh discs (hash-placed, 3 depth layers, cyan/magenta/amber), slow horizontal parallax, pulsing brightness"},+ {"name": "RainDrops", "kind": "fullscreen", "description": "grid-cell drops with hash offsets, running trails (fract(t) per cell), refraction offset applied when sampling the background"},+ {"name": "Grade", "kind": "postprocess", "description": "vignette, slight chromatic aberration, tonemap + gamma"},+ ],+ "uniforms": ["u_time", "u_resolution"],+ "motion": "drops slide down with gravity and wobble; bokeh drifts left 0.02/s and pulses at 0.5-1 Hz; no hard cuts",+ "key_visuals": ["rain drops with trails on glass", "blurred neon bokeh discs", "dark night street behind", "magenta/cyan palette"],+ "acceptance": [+ {"id": "a1", "text": "Raindrops with trails visibly run down the glass (compare t=0 and t=1)", "how": "visual", "priority": "must"},+ {"id": "a2", "text": "Blurred coloured bokeh lights are visible in the background", "how": "visual", "priority": "must"},+ {"id": "a3", "text": "Frames change over time (no static image)", "how": "probe", "priority": "must"},+ ],+ }if track is Track.SCENE:return {"title": "Harbour at dusk", "summary": "Small fishing harbour: quay, two boats, lighthouse, calm water.",@@ -747,7 +772,16 @@ PLAN_TEMPLATES: dict[Track, str] = {Track.STATIC_OBJECT: "tracks/plan_static.j2",Track.ARTICULATED_OBJECT: "tracks/plan_articulated.j2",Track.SCENE: "tracks/plan_scene.j2",+ Track.GRAPHICS: "tracks/plan_graphics.j2", # no 3D frame: passes, uniforms, motion}+#: the output-token floor ``plan_tokens`` grows from; a graphics plan starts at the model's ceiling+PLAN_OUTPUT_FLOOR = 24_000+++def plan_temperature(track: Track) -> float:+ """What the planner samples at: 0.5 for a shader brief, 0.4 for everything else. THE value —+ ``record/telemetry`` reports this function, not a default it guesses."""+ return 0.5 if track is Track.GRAPHICS else 0.4class PlanningError(RuntimeError):@@ -761,12 +795,11 @@ class PlanningError(RuntimeError):self.usage = usage or Usage()-#: hook types (BaseTrack subclasses parameterise the ONE planner loop with these)-FinalisePlan = Callable[[Any], Any]-EventStats = Callable[[Any], dict[str, Any]]---def default_event_stats(plan_obj: Any) -> dict[str, Any]:+def plan_event_stats(plan_obj: Any) -> dict[str, Any]:+ """The ``plan.done`` payload: a graphics plan counts passes, every other plan parts and zones."""+ passes = getattr(plan_obj, "passes", None)+ if passes is not None:+ return {"n_passes": len(passes), "n_acceptance": len(plan_obj.acceptance)}parts = getattr(plan_obj, "parts", []) or []return {"n_parts": len(parts),"n_zones": len(getattr(plan_obj, "zones", []) or []),@@ -779,16 +812,11 @@ def default_event_stats(plan_obj: Any) -> dict[str, Any]:def plan[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P], ws: Workspace, *, model: Any | None = None,- events: Any | None = None, budget: Any | None = None, runtime: Any | None = None,- template: str | None = None, example: dict[str, Any] | None = None, temperature: float = 0.4,- max_output_tokens: int = 24000, finalise: FinalisePlan | None = None,- event_stats: EventStats | None = None) -> P:+ events: Any | None = None, budget: Any | None = None, runtime: Any | None = None) -> P:"""Plan and write ``ws.plan_path``: optional brief expansion → one structured plannercall → re-asks (schema, quality, a degenerate-plan restart). ``model`` may be injected (tests).-- Parameterised by the track hooks: ``template``/``example`` (system prompt),- ``finalise`` (post-validation fixup, default = ``ensure_acceptance(normalise_names(...))``)- and ``event_stats`` (extra ``plan.done`` payload).+ Everything that differs per track is looked up from ``spec.track`` (module docstring);+ the validated plan is finalised by ``ensure_acceptance(normalise_names(...))``.The two re-asks have SEPARATE budgets and different complaints:``MAX_VALIDATION_REASKS`` for a plan the schema rejects, ``MAX_QUALITY_REASKS`` for a@@ -821,7 +849,7 @@ def plan[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P], ws: Worksguard.add(usage, stage="plan")budget = plan_budget(spec, brief)unit = "passes" if spec.track is Track.GRAPHICS else "parts"- system = build_system_prompt(spec, plan_model, runtime=runtime, template=template, example=example, budget=budget)+ system = build_system_prompt(spec, plan_model, runtime=runtime, budget=budget)user = build_user_prompt(spec, brief=brief, budget=budget, unit=unit)images = [ImagePart(path=r.path, label=f"{r.role}: {r.note}".strip(": ")) for r in spec.references]messages = [ChatMessage.user(user, images=images or None)]@@ -829,13 +857,13 @@ def plan[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P], ws: Worksschema = plan_model.model_json_schema()last_error = ""invalid = requeried = grown = restarts = 0- tokens = plan_tokens(budget, max_output_tokens)+ tokens = plan_tokens(budget, PLAN_TOKENS_MAX if spec.track is Track.GRAPHICS else PLAN_OUTPUT_FLOOR)thinking = "medium"wait_scale = 1.0# 4 = the first call + truncation retries; it was 2 + the geometry re-ask's 2 (D49, code# removed 2026-09-21) — the total is kept so a default run has the attempts it always hadfor attempt in range(4 + MAX_VALIDATION_REASKS + MAX_QUALITY_REASKS + MAX_PLAN_RESTARTS):- req = ChatRequest(messages=messages, system=system, response_schema=schema, temperature=temperature,+ req = ChatRequest(messages=messages, system=system, response_schema=schema, temperature=plan_temperature(spec.track),thinking=thinking, max_output_tokens=tokens, label=f"planner{'-retry' if attempt else ''}",max_wait_s=plan_wait_s(tokens, guard, scale=wait_scale))try:@@ -921,12 +949,10 @@ def plan[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P], ws: Worksnormalised = list(getattr(result, "normalisations", None) or [])if normalised and events is not None:events.emit("plan.normalised", attempt=attempt, n=len(normalised), items=normalised[:8])- result = finalise(result) if finalise is not None else ensure_acceptance(normalise_names(result), spec)- result = enrich_plan(result, brief)+ result = enrich_plan(ensure_acceptance(normalise_names(result), spec), brief)ws.write_json(ws.plan_path, result)if events is not None:- stats = (event_stats or default_event_stats)(result)- events.emit("plan.done", model=model_id, **stats,+ events.emit("plan.done", model=model_id, **plan_event_stats(result),cost_usd=round(usage.cost_usd, 4), prompt_hash=prompt_hash(system), attempt=attempt,brief=brief is not None, quality_reasks=requeried, restarts=restarts, **budget.as_dict())if guard is not None:@@ -942,18 +968,16 @@ def _echo(raw: Any, text: str) -> ChatMessage:# ----------------------------------------------------------------------------- promptsdef build_system_prompt(spec: Spec, plan_model: type[BaseModel], *, runtime: Any | None = None,- template: str | None = None, example: dict[str, Any] | None = None,budget: PlanBudget | None = None) -> str:- template = template or PLAN_TEMPLATES[spec.track]lang: Language = spec.languagebudget = budget or plan_budget(spec)return render(- template,+ PLAN_TEMPLATES[spec.track],track=spec.track.value,language=lang.value,frame_doc=frame_doc(LANGUAGE_FRAME[lang.value]),contract=language_contract(lang, runtime),- example_json=json.dumps(example if example is not None else plan_example(spec.track), indent=1),+ example_json=json.dumps(plan_example(spec.track), indent=1),schema_fields=", ".join(plan_model.model_json_schema().get("properties", {}).keys()),target_parts=budget.target_parts,min_parts=budget.min_parts,@@ -1000,21 +1024,28 @@ def ensure_acceptance[P: BaseModel](plan_obj: P, spec: Spec) -> P:wishes were capping finished scenes at 0.60. The spec's ``must_have`` list is thecontract with the user, so on that track the plan's own items stay on the checklist as``should`` (the judge still answers them, the refine loop still reads them) and only the- spec-derived items keep ``must``."""+ spec-derived items keep ``must``. A shader has no size, triangle count or ground: the graphics+ track gets the spec's checklist and, when the plan animates, one probe item that the frames+ change (never 'ground contact')."""items: list[AcceptanceItem] = list(plan_obj.acceptance)if spec.track is Track.SCENE:items = [a if a.priority == "should" else a.model_copy(update={"priority": "should"}) for a in items]c = spec.constraints- if c.dimensions_m:+ solid = spec.track is not Track.GRAPHICS+ if solid and c.dimensions_m:dims = ", ".join(f"{k} = {v:.3f} m" for k, v in c.dimensions_m.items())add_acceptance_item(items, "dim", f"Overall dimensions match the request within 5%: {dims}", "measure")- if c.max_triangles:+ if solid and c.max_triangles:add_acceptance_item(items, "tri", f"Triangle count ≤ {c.max_triangles}", "measure")for m in c.must_have:add_acceptance_item(items, "must", f"Includes: {m}", "visual")for m in c.must_not:add_acceptance_item(items, "not", f"Does NOT include: {m}", "visual")- if spec.track is not Track.SCENE and not any(a.how == "measure" for a in items):+ if not solid:+ planned_motion = getattr(plan_obj, "motion", "").strip()+ if planned_motion and not any(w in a.text.lower() for a in items for w in ("static", "motion", "change over time")):+ add_acceptance_item(items, "motion", "Frames change over time as planned (not a static image)", "probe")+ elif spec.track is not Track.SCENE and not any(a.how == "measure" for a in items):add_acceptance_item(items, "ground", "Object stands on the ground plane (lowest point at up=0) with its footprint centred", "measure")items.extend(articulation_acceptance(plan_obj, items))plan_obj.acceptance = items@@ -1067,7 +1098,7 @@ def normalise_names[P: BaseModel](plan_obj: P) -> P:__all__ = ["MAX_PLAN_RESTARTS", "MAX_QUALITY_REASKS", "MAX_VALIDATION_REASKS","PLAN_RESTART_ENV", "PLAN_TOKENS_MAX", "PlanningError", "add_acceptance_item",- "articulation_acceptance", "build_system_prompt", "build_user_prompt", "default_event_stats",+ "articulation_acceptance", "build_system_prompt", "build_user_prompt", "plan_event_stats","ensure_acceptance", "missing_link_names", "normalise_names", "plan",- "degenerate_plan", "plan_example", "plan_tokens", "restart_enabled",+ "degenerate_plan", "plan_example", "plan_temperature", "plan_tokens", "restart_enabled","restart_note"]diff --git a/harness/codeverse3d/tracks/scene_assets.py b/harness/codeverse3d/tracks/scene_assets.pyindex 00ed321c..23cedd47 100644--- a/harness/codeverse3d/tracks/scene_assets.py+++ b/harness/codeverse3d/tracks/scene_assets.py@@ -492,13 +492,10 @@ def hero_plan(sub: RunContext, asset: AssetPlan) -> StaticPlan:demands, per-part bboxes, ``style_notes`` and an acceptance list — what a static_objectrun gets, from the code that gives it to them."""- from codeverse3d.tracks.static_object import StaticObjectTrack-- track = StaticObjectTrack(services=sub.services, settings=sub.settings)try:model = sub.services.chat_model(sub.spec.backends.planner)plan = run_planner(sub.spec, sub.spec.backends.planner, StaticPlan, sub.ws, model=model, events=sub.events,- budget=sub.budget, runtime=sub.runtime, **track._plan_kwargs(sub.spec))+ budget=sub.budget, runtime=sub.runtime)features = hero_features(asset.description)if len(plan.parts) <= HERO_THIN_PLAN_PARTS and len(features) > HERO_THIN_PLAN_PARTS:# a one-part answer for a prop whose sheet names several features (the windmill got@@ -508,7 +505,7 @@ def hero_plan(sub: RunContext, asset: AssetPlan) -> StaticPlan:sub.events.emit("asset.plan_thin", asset=asset.name, n_parts=len(plan.parts), features=features)spec2 = sub.spec.model_copy(update={"constraints": sub.spec.constraints.model_copy(update={"must_have": features})})plan = run_planner(spec2, spec2.backends.planner, StaticPlan, sub.ws, model=model, events=sub.events,- budget=sub.budget, runtime=sub.runtime, **track._plan_kwargs(spec2))+ budget=sub.budget, runtime=sub.runtime)except Exception as e: # noqa: BLE001 — PlanningError / outage: the sheet still says what the prop isif isinstance(e, BudgetExceeded):raisediff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 79e6147f..3b1df92f 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -189,12 +189,14 @@ codeverse3d/gates), articulated_object.py (+ the planned-motion gate),scene.py, scene_assets.py (+ cheap single-shot asset generation),zone_layout.py (L2 zone director: per-zone structured layout calls + deterministic validator),- graphics.py (the whole graphics track: planner hooks, prompt context, frame+ graphics.py (the whole graphics track: prompt context, frameRenderSet, and recipe seeding into the harness-owned, read-onlysrc/recipes.glsl — measured: flash calls a recipe on disk, not one it isshown; AgentJob.read_only, C3D_SEED_RECIPES),planner.py (the ONE planner loop + the cached EngineeringBrief- (C3D_PLAN_BRIEF), plan budgets and the worked examples),+ (C3D_PLAN_BRIEF), plan budgets and the worked examples — and the ONE owner of+ what differs per track when planning: template, example, temperature, output+ floor, acceptance, all dispatched on spec.track),plan_features.py (the A/B switch registry: LIVE_SWITCHES / DEAD_SWITCHES,+ pin_plan_blockers() deciding when two arms may share one plan —eval/docs/EVAL.md §8.1),diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 4e42f61a..e872930a 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -502,7 +502,13 @@ run_round(ctx, *, index, kind, tasks, pipeline, ..., previous_best=None) -> Roun# pipeline's render; candidates pass quick_render) and geometry_views=False (skips the clay/normals views)# emits cost.round {stages{}, judge_usd, total_usd, agent_turns, wasted, waste_reason}; on ANY exception it# records what the round burned (rounds/aborted_rNN.json, ctx.extra["aborted_rounds"]) and re-raises-from codeverse3d.tracks.planner import plan, ensure_acceptance # graphics too, through its hooks (GraphicsTrack.plan_template / plan_example)+from codeverse3d.tracks.planner import plan, ensure_acceptance, plan_example, plan_temperature+plan(spec, model_id, plan_model, ws, *, model=None, events=None, budget=None, runtime=None) -> Plan+ # Δ 2026-09-22: every track, graphics included, through ONE loop that dispatches on spec.track — PLAN_TEMPLATES,+ # plan_example(track), plan_temperature(track) (graphics 0.5, else 0.4; record/telemetry reports it), the output+ # floor (graphics PLAN_TOKENS_MAX, else PLAN_OUTPUT_FLOOR), plan_budget's unit (passes) and ensure_acceptance+ # (graphics: must_have / must_not + a motion probe item, never dimensions / triangles / ground). The six BaseTrack+ # planner hooks and plan()'s template / example / temperature / max_output_tokens / finalise / event_stats are gone````run_round` = generate → commit → `build_with_repair` → measure → gates → render →post-render gates → judge → commit. Post-render gates: static `reference_silhouette`diff --git a/harness/docs/RUN_LAYOUT.md b/harness/docs/RUN_LAYOUT.mdindex 0fa3080e..294c15b5 100644--- a/harness/docs/RUN_LAYOUT.md+++ b/harness/docs/RUN_LAYOUT.md@@ -127,7 +127,7 @@ produces no diff.hashes; tool versions (python, blender, node, three, chrome, puppeteer);harness version + git sha; key-pool size; **price-table hash**; resolvedrender and limit settings. Sampling values are read from the call sites'- typed defaults (`VlmJudge.__init__`, the track's `plan_temperature`, and+ typed defaults (`VlmJudge.__init__`, `tracks/planner.plan_temperature(track)`, and`record/telemetry.py::_generator_defaults` — a historical shim thatconfigures nothing, kept so old records still read back); avalue a call site hard-codes per task is left empty with `source` saying so,diff --git a/harness/tests/graphics/test_live.py b/harness/tests/graphics/test_live.pyindex 9b97a7d5..f966f34b 100644--- a/harness/tests/graphics/test_live.py+++ b/harness/tests/graphics/test_live.py@@ -41,7 +41,7 @@ def test_live_plan_generate_build_judge(tmp_path, keys_ok):ws = Workspace(tmp_path / "live_gfx").create()model = get_chat_model(MODEL)from codeverse3d.tracks.planner import plan as run_planner- plan = run_planner(spec, MODEL, GraphicsPlan, ws, model=model, **GraphicsTrack()._plan_kwargs(spec))+ plan = run_planner(spec, MODEL, GraphicsPlan, ws, model=model)assert isinstance(plan, GraphicsPlan) and plan.passes and plan.key_visuals and plan.motionrt = GlslShaderRuntime()rt.skeleton(ws, plan)diff --git a/harness/tests/graphics/test_track.py b/harness/tests/graphics/test_track.pyindex 53e4b198..608c92bc 100644--- a/harness/tests/graphics/test_track.py+++ b/harness/tests/graphics/test_track.py@@ -22,14 +22,9 @@ from codeverse3d.languages.glsl_shader import lint_workspace, write_skeletonfrom codeverse3d.proc import EventLogfrom codeverse3d.prompts import renderfrom codeverse3d.spatial.gl_render import GlFrame, GlResult, gif_times-from codeverse3d.tracks import get_track-from codeverse3d.tracks.graphics import (- GraphicsTrack,- ensure_graphics_acceptance,- graphics_prompt_context,- plan_example,-)-from codeverse3d.tracks.planner import PlanningError+from codeverse3d.tracks import get_track, planner+from codeverse3d.tracks.graphics import GraphicsTrack, graphics_prompt_context+from codeverse3d.tracks.planner import PlanningError, ensure_acceptancefrom codeverse3d.workspace import Workspacefrom tests.orchestrator_tracks.fakes import FakeAgent, FakeChatModel, FakeJudge, FakeServices@@ -101,14 +96,14 @@ def _services(**kw):return FakeServices(runtime_factory=lambda lang: FakeGlRuntime(), **kw)+def plan_example() -> dict[str, Any]:+ return planner.plan_example(Track.GRAPHICS)++def _plan(spec, ws, model, budget=None):- """What plan_graphics() used to be: run_planner with GraphicsTrack's own hooks.- The wrapper was a second spelling of _plan_kwargs and had no production caller,- so the tests go through the hooks the live path actually uses."""- from codeverse3d.tracks.graphics import GraphicsTrack- from codeverse3d.tracks.planner import plan as run_planner- return run_planner(spec, "fake:planner", GraphicsPlan, ws, model=model, budget=budget,- **GraphicsTrack()._plan_kwargs(spec))+ """The planner as the live path calls it: everything graphics-specific (template, worked+ example, T = 0.5, acceptance) is dispatched on ``spec.track`` inside it."""+ return planner.plan(spec, "fake:planner", GraphicsPlan, ws, model=model, budget=budget)def test_graphics_track_end_to_end(tmp_path, settings):@@ -237,15 +232,14 @@ def test_planner_reask_and_acceptance(tmp_ws):ids = [a.id for a in plan.acceptance]assert "must1" in ids and "a3" in ids # spec must_have appended, motion item already present in the example# a plan without a motion acceptance item gets one; no 'ground contact' ever- p2 = ensure_graphics_acceptance(GraphicsPlan.model_validate({**plan_example(), "acceptance": []}), spec)+ p2 = ensure_acceptance(GraphicsPlan.model_validate({**plan_example(), "acceptance": []}), spec)assert any(a.id.startswith("motion") for a in p2.acceptance) and not any("ground" in a.text.lower() for a in p2.acceptance)always_bad = FakeChatModel(lambda req: {"title": "x"})with pytest.raises(PlanningError):_plan(spec, tmp_ws, always_bad)- from codeverse3d.tracks.graphics import PLAN_TEMPLATE- from codeverse3d.tracks.planner import build_system_prompt- sys_prompt = build_system_prompt(spec, GraphicsPlan, template=PLAN_TEMPLATE, example=plan_example())+ sys_prompt = planner.build_system_prompt(spec, GraphicsPlan)assert "ART-DIRECTOR" in sys_prompt and "NeonRainWindow" in sys_prompt+ assert model.requests[0].temperature == 0.5 and model.requests[0].max_output_tokens == planner.PLAN_TOKENS_MAXdef test_templates_render_and_rubric_loads(tmp_path, settings):diff --git a/harness/tests/orchestrator_tracks/test_graphics_recipes.py b/harness/tests/orchestrator_tracks/test_graphics_recipes.pyindex a92aecd6..5aa5c380 100644--- a/harness/tests/orchestrator_tracks/test_graphics_recipes.py+++ b/harness/tests/orchestrator_tracks/test_graphics_recipes.py@@ -35,11 +35,11 @@ from codeverse3d.tracks.graphics import (graphics_prompt_context,is_skeleton_common,parse_functions,- plan_example,recipe_chapters,seed_recipes,seeded_on_disk,)+from codeverse3d.tracks.planner import plan_examplefrom codeverse3d.workspace import WorkspaceAURORA = "Aurora borealis over a mountain ridge with a frozen lake, dense stars, green and violet curtains"@@ -211,7 +211,7 @@ def test_brief_and_plan_visuals_select_recipes(tmp_path) -> None:assert "vec2 dropsLayer(vec2 uv, float t, float scale)" in text and "vec3 bokehSoft(vec2 p, float t)" in textws = _ws(tmp_path / "plan")- plan = GraphicsPlan.model_validate({**plan_example(), "key_visuals": ["an aurora curtain over the ridge"]})+ plan = GraphicsPlan.model_validate({**plan_example(Track.GRAPHICS), "key_visuals": ["an aurora curtain over the ridge"]})names = seed_recipes(_ctx(ws, "a landscape", plan=plan))assert "curtain" in names and "bokehSoft" not in names# the seed follows the prompt's selection exactly, budget included: for "a city at night" the Light +@@ -375,7 +375,7 @@ def test_lint_flags_a_redefinition_of_a_seeded_recipe(tmp_path) -> None:def test_prompt_block_lists_the_seeded_names(tmp_path) -> None:ws = _ws(tmp_path)- ctx = _ctx(ws, plan=GraphicsPlan.model_validate({**plan_example(), "key_visuals": ["green aurora curtains", "dense stars"]}))+ ctx = _ctx(ws, plan=GraphicsPlan.model_validate({**plan_example(Track.GRAPHICS), "key_visuals": ["green aurora curtains", "dense stars"]}))names = seed_recipes(ctx)d = graphics_prompt_context(ctx, skeleton_files={}, previous_error="")assert [r["name"] for r in d["seeded_recipes"]] == namesdiff --git a/harness/tests/orchestrator_tracks/test_planner_depth.py b/harness/tests/orchestrator_tracks/test_planner_depth.pyindex 413a9463..4ffefd1d 100644--- a/harness/tests/orchestrator_tracks/test_planner_depth.py+++ b/harness/tests/orchestrator_tracks/test_planner_depth.py@@ -27,7 +27,6 @@ from codeverse3d.tracks.planner import (MAX_QUALITY_REASKS,build_system_prompt,build_user_prompt,- plan_example,)from codeverse3d.tracks.planner import plan as run_plannerfrom codeverse3d.workspace import Workspace@@ -136,9 +135,7 @@ def test_plan_templates_render_the_budget_numbers():for track, language, model in ((Track.STATIC_OBJECT, Language.BLENDER, StaticPlan),(Track.GRAPHICS, Language.GLSL_SHADER, GraphicsPlan)):spec = _spec(must=9, track=track, language=language)- template = "tracks/plan_graphics.j2" if track is Track.GRAPHICS else None- out = build_system_prompt(spec, model, template=template, example=plan_example(Track.STATIC_OBJECT),- budget=B.plan_budget(spec))+ out = build_system_prompt(spec, model, budget=B.plan_budget(spec))assert str(B.plan_budget(spec).target_parts) in outdiff --git a/harness/tests/orchestrator_tracks/test_refactor_batch2.py b/harness/tests/orchestrator_tracks/test_refactor_batch2.pyindex 336a5ccb..96a6827c 100644--- a/harness/tests/orchestrator_tracks/test_refactor_batch2.py+++ b/harness/tests/orchestrator_tracks/test_refactor_batch2.py@@ -104,7 +104,6 @@ def test_graphics_planner_hooks_charge_budget_on_planning_error(tmp_ws):from codeverse3d.contracts.plan import GraphicsPlanfrom codeverse3d.contracts.spec import Budgetfrom codeverse3d.orchestrator import BudgetGuard- from codeverse3d.tracks.graphics import GraphicsTrackfrom codeverse3d.tracks.planner import PlanningErrorfrom codeverse3d.tracks.planner import plan as run_planner@@ -112,7 +111,6 @@ def test_graphics_planner_hooks_charge_budget_on_planning_error(tmp_ws):budget = BudgetGuard(Budget(max_minutes=10))always_bad = FakeChatModel(lambda req: {"title": "x"})with pytest.raises(PlanningError):- run_planner(spec, "fake:planner", GraphicsPlan, tmp_ws, model=always_bad, budget=budget,- **GraphicsTrack()._plan_kwargs(spec))+ run_planner(spec, "fake:planner", GraphicsPlan, tmp_ws, model=always_bad, budget=budget)assert budget.spent.cost_usd > 0, "a failed re-ask is still paid for"