Skip to content

Official Codebase of 3DCodeVerse

Python

artifacts: canonical means the last OK build — staged, promoted, or gone

gaoypengecd572bed18c
diff --git a/harness/codeverse/flywheel/deliverable.py b/harness/codeverse/flywheel/deliverable.py
index d6f5a3cc..507a9792 100644
--- a/harness/codeverse/flywheel/deliverable.py
+++ b/harness/codeverse/flywheel/deliverable.py
@@ -21,7 +21,6 @@ from __future__ import annotations
import hashlib
import json
import logging
-import os
import shutil
from datetime import UTC, datetime
from pathlib import Path
@@ -37,11 +36,6 @@ log = logging.getLogger(__name__)
MAX_FILE_BYTES = 128 * 1024 * 1024
MAX_TOTAL_BYTES = 512 * 1024 * 1024
MANIFEST_NAME = "manifest.json"
-#: big binaries (frame stacks, GLBs, GIFs) are hard-linked to the evidence copy when the
-#: filesystem allows it — same bytes, one block on disk, and `cp`/`tar`/`rsync` still
-#: produce a standalone copy. Small files (all code) are always real copies so editing
-#: the hand-over folder can never touch the evidence.
-LINK_MIN_BYTES = 256 * 1024
#: artifact file → role, copied when present (object tracks / articulated / graphics)
_ARTIFACT_ROLES: tuple[tuple[str, str], ...] = (
@@ -105,13 +99,10 @@ class _Writer:
def _place(src: Path, dest: Path) -> None:
- """Hard-link big binaries, copy everything else (see ``LINK_MIN_BYTES``)."""
- if src.stat().st_size >= LINK_MIN_BYTES:
- try:
- os.link(src, dest)
- return
- except OSError: # cross-device, no hard links, already exists
- pass
+ """ALWAYS a real copy, never a hard link: a user editing the delivered file
+ would otherwise mutate the canonical evidence in ``artifacts/`` and silently
+ break the sha256 recorded in the manifest. The size caps above already bound
+ the copy cost."""
shutil.copy2(src, dest)
@@ -140,7 +131,12 @@ def _code_tree(ws: Workspace, rnd: RoundRecord | None) -> tuple[dict[str, bytes]
def _copy_artifacts(ws: Workspace, record: RunRecord, w: _Writer) -> None:
+ tex = record.extra.get("texturing") or {}
for name, role in _ARTIFACT_ROLES:
+ if name == "object_textured.glb" and not tex.get("shipped"):
+ # a texture pass that did not ship is not a deliverable, even if a stray
+ # canonical file exists (same gate flywheel/sample.copy_textured applies)
+ continue
w.add_file(ws.artifacts / name, name, role)
meshes = ws.artifacts / "meshes"
if record.spec.language is Language.URDF_BLENDER and meshes.is_dir():
@@ -150,7 +146,6 @@ def _copy_artifacts(ws: Workspace, record: RunRecord, w: _Writer) -> None:
if frames.is_dir():
for p in sorted(frames.glob("*.png")):
w.add_file(p, f"frames/{p.name}", "frames")
- tex = record.extra.get("texturing") or {}
if tex.get("shipped"):
tex_dir = ws.root / str(tex.get("textures_dir") or "artifacts/textures")
for p in sorted(tex_dir.glob("*.png")) if tex_dir.is_dir() else []:
diff --git a/harness/codeverse/gallery/index.py b/harness/codeverse/gallery/index.py
index fd30a863..57ccef4e 100644
--- a/harness/codeverse/gallery/index.py
+++ b/harness/codeverse/gallery/index.py
@@ -146,9 +146,13 @@ def entry_links(ws: Workspace, rec: RunRecord | None, best: int | None) -> list[
glb = _first_file(run, "deliverable/object.glb", "artifacts/object.glb")
if glb:
links.append(RunLink(label="glb", rel=glb, kind="viewer"))
- textured = _first_file(run, "deliverable/object_textured.glb", "artifacts/object_textured.glb")
- if textured:
- links.append(RunLink(label="textured glb", rel=textured, kind="viewer"))
+ # the textured GLB is a link only when the texture pass SHIPPED — a stray file
+ # from a rejected pass (or an older harness that leaked one) is not a deliverable
+ tex = (rec.extra.get("texturing") or {}) if rec is not None else {}
+ if tex.get("shipped"):
+ textured = _first_file(run, "deliverable/object_textured.glb", "artifacts/object_textured.glb")
+ if textured:
+ links.append(RunLink(label="textured glb", rel=textured, kind="viewer"))
urdf = _first_file(run, "deliverable/robot.urdf", "artifacts/robot.urdf", "src/robot.urdf")
if urdf:
links.append(RunLink(label="robot.urdf", rel=urdf))
diff --git a/harness/codeverse/languages/_gl_common.py b/harness/codeverse/languages/_gl_common.py
index f7de9204..17b65b50 100644
--- a/harness/codeverse/languages/_gl_common.py
+++ b/harness/codeverse/languages/_gl_common.py
@@ -25,7 +25,14 @@ from codeverse.config import get_settings
from codeverse.contracts.artifacts import BuildResult, GateReport
from codeverse.contracts.plan import GraphicsPlan
from codeverse.spatial.frame_stats import SequenceStats, frame_gate, sequence_stats
-from codeverse.spatial.gl_render import GlHost, GlResult, gif_times, write_contact_sheet, write_gif
+from codeverse.spatial.gl_render import (
+ RESULT_NAME,
+ GlHost,
+ GlResult,
+ gif_times,
+ write_contact_sheet,
+ write_gif,
+)
from codeverse.workspace import Workspace
JUDGE_TIMES: tuple[float, ...] = (0.0, 1.0, 2.5, 4.0, 6.0)
@@ -33,10 +40,27 @@ SHEET_NAME = "frames_sheet.png"
GIF_NAME = "preview.gif"
METRICS_NAME = "metrics.json"
BUILD_JSON = "build.json"
+FRAMES_DIR = "frames"
DEFAULT_RESOLUTION: tuple[int, int] = (1280, 720)
MAX_PIXELS = 1920 * 1080
+def invalidate_stale_outputs(ws: Workspace) -> None:
+ """Wipe the previous build's GL artifacts at the TOP of ``build()``.
+
+ Hoisted from ``GlHost._run`` (which still wipes its own out_dir) so the
+ ``MissingEntry`` early returns — which never reach the host — also clear
+ ``frames/`` and ``gl_result.json``; sheet/gif/metrics/build.json were never
+ cleared anywhere, so a failed build left the previous round's sheet looking
+ current to every bare-existence reader (``read_metrics``, the gallery)."""
+ ws.stage_artifacts(BUILD_JSON, SHEET_NAME, GIF_NAME, METRICS_NAME).invalidate()
+ (ws.artifacts / RESULT_NAME).unlink(missing_ok=True)
+ frames = ws.artifacts / FRAMES_DIR
+ if frames.is_dir():
+ for p in frames.glob("*.png"):
+ p.unlink(missing_ok=True)
+
+
def make_host(override: GlHost | None = None, timeout_s: float | None = None) -> GlHost:
"""The runtime's :class:`GlHost`: the injected one (tests) or one built from settings."""
if override is not None:
@@ -110,6 +134,10 @@ def finish_build(ws: Workspace, res: GlResult, *, language: str, error_file: str
)
if res.ok and not res.judge_frames:
result.error_type, result.error_message = "NoFrames", "the renderer produced no frames"
+ if not result.ok:
+ # a failed build must not leave the previous round's derived artifacts
+ # (sheet / gif / metrics are written only on ok above) looking current
+ ws.stage_artifacts(SHEET_NAME, GIF_NAME, METRICS_NAME).invalidate()
ws.write_json(art / BUILD_JSON, result)
return result
diff --git a/harness/codeverse/languages/blender/runtime.py b/harness/codeverse/languages/blender/runtime.py
index 105e22da..e68c29a2 100644
--- a/harness/codeverse/languages/blender/runtime.py
+++ b/harness/codeverse/languages/blender/runtime.py
@@ -20,7 +20,6 @@ from codeverse.contracts.plan import Plan, StaticPlan
from codeverse.conventions import MAX_TRIS_OBJECT
from codeverse.languages._common import (
compose_build_result,
- remove_stale,
run_subprocess,
strip_blender_noise,
)
@@ -118,17 +117,21 @@ class BlenderRuntime:
seed: int = 0, tri_limit: int = MAX_TRIS_OBJECT,
) -> BuildResult:
"""Run the wrapper; never raises for agent-code failures (typed BuildResult instead)."""
- entry = self.entry_file(ws)
- if not entry.is_file():
- return BuildResult(ok=False, language=self.language.value, error_type="MissingEntryFile",
- error_message=f"{ENTRY_REL} does not exist", error_file=ENTRY_REL)
ws.artifacts.mkdir(parents=True, exist_ok=True)
build_json = ws.artifacts / "build.json"
census_json = ws.artifacts / "census.json"
glb = ws.artifacts / "object.glb"
stl_path = ws.artifacts / "object.stl"
blend_path = ws.artifacts / "object.blend"
- remove_stale(build_json, census_json, glb, stl_path, blend_path)
+ # invalidate BEFORE the missing-entry early return: a deleted model.py must not
+ # leave the previous round's object.glb + build.json (ok: true) looking current
+ ws.stage_artifacts("build.json", "census.json", "object.glb", "object.stl", "object.blend").invalidate()
+ entry = self.entry_file(ws)
+ if not entry.is_file():
+ result = BuildResult(ok=False, language=self.language.value, error_type="MissingEntryFile",
+ error_message=f"{ENTRY_REL} does not exist", error_file=ENTRY_REL)
+ ws.write_json(build_json, result)
+ return result
cmd = self.build_command(ws, stl=stl, blend=blend, seed=seed, tri_limit=tri_limit)
proc = run_subprocess(
cmd, cwd=ws.root, env=blender_env(),
diff --git a/harness/codeverse/languages/cadquery/runtime.py b/harness/codeverse/languages/cadquery/runtime.py
index b1527c00..59428740 100644
--- a/harness/codeverse/languages/cadquery/runtime.py
+++ b/harness/codeverse/languages/cadquery/runtime.py
@@ -15,7 +15,7 @@ from codeverse.contracts.artifacts import BuildResult, GateReport
from codeverse.contracts.common import ENTRY_FILE, Language
from codeverse.contracts.plan import Plan, StaticPlan
from codeverse.conventions import MAX_TRIS_OBJECT
-from codeverse.languages._common import compose_build_result, remove_stale, run_subprocess
+from codeverse.languages._common import compose_build_result, run_subprocess
from codeverse.languages.cadquery.lint import lint_cadquery_file
from codeverse.languages.cadquery.skeleton import write_cadquery_skeleton
from codeverse.proc import scrub_secrets
@@ -70,14 +70,17 @@ class CadQueryRuntime:
def build(self, ws: Workspace, *, timeout_s: int | None = None, seed: int = 0,
tri_limit: int = MAX_TRIS_OBJECT) -> BuildResult:
- entry = self.entry_file(ws)
- if not entry.is_file():
- return BuildResult(ok=False, language=self.language.value, error_type="MissingEntryFile",
- error_message="src/model.py does not exist", error_file="src/model.py")
ws.artifacts.mkdir(parents=True, exist_ok=True)
build_json, census_json = ws.artifacts / "build.json", ws.artifacts / "census.json"
glb, step, stl = ws.artifacts / "object.glb", ws.artifacts / "object.step", ws.artifacts / "object.stl"
- remove_stale(build_json, census_json, glb, step, stl)
+ # invalidate BEFORE the missing-entry early return (same reasoning as BlenderRuntime.build)
+ ws.stage_artifacts("build.json", "census.json", "object.glb", "object.step", "object.stl").invalidate()
+ entry = self.entry_file(ws)
+ if not entry.is_file():
+ result = BuildResult(ok=False, language=self.language.value, error_type="MissingEntryFile",
+ error_message="src/model.py does not exist", error_file="src/model.py")
+ ws.write_json(build_json, result)
+ return result
proc = run_subprocess(self.build_command(ws, seed=seed, tri_limit=tri_limit), cwd=ws.root, env=cadquery_env(),
timeout_s=timeout_s or self._settings.limits.build_timeout_s)
return compose_build_result(language=self.language.value, proc=proc, build_json=build_json, census_json=census_json,
diff --git a/harness/codeverse/languages/glsl_shader/runtime.py b/harness/codeverse/languages/glsl_shader/runtime.py
index 3a6bab4a..66a004ca 100644
--- a/harness/codeverse/languages/glsl_shader/runtime.py
+++ b/harness/codeverse/languages/glsl_shader/runtime.py
@@ -17,6 +17,7 @@ from codeverse.contracts.common import ENTRY_FILE, Language
from codeverse.contracts.plan import Plan
from codeverse.languages._gl_common import (
finish_build,
+ invalidate_stale_outputs,
judge_times,
load_plan,
make_host,
@@ -80,6 +81,7 @@ class GlslShaderRuntime:
def build(self, ws: Workspace, *, timeout_s: int | None = None, times: list[float] | None = None,
preview: bool = True, width: int | None = None, height: int | None = None) -> BuildResult:
ws.artifacts.mkdir(parents=True, exist_ok=True)
+ invalidate_stale_outputs(ws) # BEFORE the MissingEntry return, so it also clears
if not (ws.root / SHADER).is_file():
res = GlResult(ok=False, mode="shader", stage="lint", error_type="MissingEntry", error_message=f"{SHADER} is missing")
return finish_build(ws, res, language=self.language.value, error_file=SHADER)
diff --git a/harness/codeverse/languages/opengl_python/runtime.py b/harness/codeverse/languages/opengl_python/runtime.py
index 2862dba3..5843714c 100644
--- a/harness/codeverse/languages/opengl_python/runtime.py
+++ b/harness/codeverse/languages/opengl_python/runtime.py
@@ -17,6 +17,7 @@ from codeverse.contracts.common import ENTRY_FILE, Language
from codeverse.contracts.plan import Plan
from codeverse.languages._gl_common import (
finish_build,
+ invalidate_stale_outputs,
judge_times,
load_plan,
make_host,
@@ -68,6 +69,7 @@ class OpenGLPythonRuntime:
def build(self, ws: Workspace, *, timeout_s: int | None = None, times: list[float] | None = None,
preview: bool = True, width: int | None = None, height: int | None = None) -> BuildResult:
ws.artifacts.mkdir(parents=True, exist_ok=True)
+ invalidate_stale_outputs(ws) # BEFORE the MissingEntry return, so it also clears
program = ws.root / PROGRAM
if not program.is_file():
res = GlResult(ok=False, mode="program", stage="lint", error_type="MissingEntry", error_message=f"{PROGRAM} is missing")
diff --git a/harness/codeverse/languages/scene_threejs/runtime.py b/harness/codeverse/languages/scene_threejs/runtime.py
index 4fb7e43c..b063e40d 100644
--- a/harness/codeverse/languages/scene_threejs/runtime.py
+++ b/harness/codeverse/languages/scene_threejs/runtime.py
@@ -42,8 +42,12 @@ class SceneThreeJsRuntime:
t0 = time.time()
tmo = min(float(timeout_s or get_settings().limits.build_timeout_s), 120.0)
- probe, shaders, census = _probe_and_preflight(ws, timeout_s=tmo)
ws.artifacts.mkdir(parents=True, exist_ok=True)
+ # a probe/driver crash must not leave the previous round's census or the root
+ # driver outputs (scene_probe.json / shader_preflight.json) looking current;
+ # census.json is only rewritten `if census:` below, so it MUST be wiped here
+ ws.stage_artifacts("census.json", "scene_probe.json", "shader_preflight.json", "build.json").invalidate()
+ probe, shaders, census = _probe_and_preflight(ws, timeout_s=tmo)
if census:
(ws.artifacts / "census.json").write_text(json.dumps(census, indent=1))
gates_dir = ws.artifacts / "gates"
diff --git a/harness/codeverse/languages/threejs/runtime.py b/harness/codeverse/languages/threejs/runtime.py
index d6f8ec23..813f16b4 100644
--- a/harness/codeverse/languages/threejs/runtime.py
+++ b/harness/codeverse/languages/threejs/runtime.py
@@ -63,8 +63,9 @@ class ThreeJsRuntime:
ws.artifacts.mkdir(parents=True, exist_ok=True)
glb = ws.artifacts / GLB_NAME
census = ws.artifacts / CENSUS_NAME
- for stale in (glb, census, ws.artifacts / "export_error.json"):
- stale.unlink(missing_ok=True)
+ # build.json is in the wipe too: the node-missing raise below returns before
+ # _write_build_json, and a stale ok:true build.json must not survive it
+ ws.stage_artifacts(GLB_NAME, CENSUS_NAME, BUILD_JSON, "export_error.json").invalidate()
self._ensure_module_type(ws)
t0 = time.time()
diff --git a/harness/codeverse/languages/urdf/runtime.py b/harness/codeverse/languages/urdf/runtime.py
index b33c0753..9694382c 100644
--- a/harness/codeverse/languages/urdf/runtime.py
+++ b/harness/codeverse/languages/urdf/runtime.py
@@ -21,11 +21,11 @@ import time
from pathlib import Path
from typing import Any
-from codeverse.config import get_settings
+from codeverse.config import Settings, get_settings
from codeverse.contracts.artifacts import BuildResult, GateReport
from codeverse.contracts.common import ENTRY_FILE, Language
from codeverse.contracts.plan import ArticulatedPlan, Plan
-from codeverse.languages._common import ProcResult, read_json_file, remove_stale, run_subprocess
+from codeverse.languages._common import ProcResult, read_json_file, run_subprocess
from codeverse.languages.urdf.consistency import check_fk_consistency
from codeverse.languages.urdf.lint import lint_workspace
from codeverse.languages.urdf.skeleton import write_skeleton
@@ -38,13 +38,17 @@ from codeverse.spatial.joints import (
sweep_findings,
urdf_to_glb,
)
-from codeverse.workspace import Workspace
+from codeverse.workspace import ArtifactStage, Workspace
WRAPPER = Path(__file__).resolve().parent / "wrappers" / "run_bpy_links.py"
CONTRACT_MD = Path(__file__).resolve().parent / "CONTRACT.md"
REST_PENETRATION_MAX_M = 0.005
FK_TOL_M = 0.001
+#: every canonical artifact this build owns — staged together so a failed build
+#: can never leave a previous round's output looking current
+STAGED_OUTPUTS = ("build.json", "census.json", "meshes", "robot.urdf", "articulation.json", "object.glb")
+
def _tail(s: str, n: int = 3000) -> str:
return s[-n:] if s else ""
@@ -74,17 +78,41 @@ class UrdfBlenderRuntime:
# ------------------------------------------------------------ build
def build(self, ws: Workspace, *, timeout_s: int | None = None) -> BuildResult:
+ """All six canonical outputs go through one :class:`ArtifactStage`: entering
+ it invalidates them BEFORE any early return can leak a previous round's
+ files, everything is written to staging, and only an ``ok=True`` build
+ promotes the full set. Every exit path publishes the FINAL BuildResult as
+ ``artifacts/build.json`` — the wrapper's own build.json used to stay on disk
+ saying ``ok: true`` while a post-wrapper check (UrdfError / FkInconsistent /
+ RestPenetration) failed the build."""
t0 = time.time()
settings = get_settings()
timeout_s = timeout_s or settings.limits.build_timeout_s
+ ws.artifacts.mkdir(parents=True, exist_ok=True)
+ with ws.stage_artifacts(*STAGED_OUTPUTS) as stage:
+ return self._build_staged(ws, stage, t0=t0, settings=settings, timeout_s=timeout_s)
+
+ def _build_staged(self, ws: Workspace, stage: ArtifactStage, *, t0: float, settings: Settings,
+ timeout_s: int) -> BuildResult:
art = ws.artifacts
- art.mkdir(parents=True, exist_ok=True)
+
+ def finish(res: BuildResult) -> BuildResult:
+ # disk never contradicts the returned result: build.json is ALWAYS the
+ # final BuildResult; the rest of the set is published only on ok
+ ws.write_json(stage.path("build.json"), res)
+ if res.ok:
+ stage.promote()
+ elif stage.path("census.json").is_file():
+ stage.promote("build.json", "census.json")
+ else:
+ stage.promote("build.json")
+ return res
def fail(error_type: str, message: str, *, file: str = "src/robot.urdf", line: int | None = None,
census: dict[str, Any] | None = None, **kw: Any) -> BuildResult:
- return BuildResult(ok=False, language=self.language.value, error_type=error_type, error_message=message,
- error_file=file, error_line=line, duration_ms=int((time.time() - t0) * 1000),
- census=census or {}, **kw)
+ return finish(BuildResult(ok=False, language=self.language.value, error_type=error_type,
+ error_message=message, error_file=file, error_line=line,
+ duration_ms=int((time.time() - t0) * 1000), census=census or {}, **kw))
# 1. lint (cheap, no Blender)
lint = self.lint(ws)
@@ -95,14 +123,12 @@ class UrdfBlenderRuntime:
return fail("LintError", f"{len(errs)} lint error(s):\n{msg}", file=str(errs[0].target or "src/robot.urdf"),
line=errs[0].data.get("line"), census=census)
- # 2. Blender wrapper
+ # 2. Blender wrapper (writes build.json / census.json / meshes/ into the staging dir)
blender = settings.resolve_blender()
if not blender:
return fail("BlenderNotFound", "no Blender binary (set CV3D_BINARIES__BLENDER)", file="", census=census)
- build_json, census_json = art / "build.json", art / "census.json"
- remove_stale(build_json, census_json)
- shutil.rmtree(art / "meshes", ignore_errors=True)
- proc = _run_blender(blender, ws, art, timeout_s, settings.limits.bpy_rlimit_gb)
+ build_json, census_json = stage.path("build.json"), stage.path("census.json")
+ proc = _run_blender(blender, ws, stage.staging_dir, timeout_s, settings.limits.bpy_rlimit_gb)
if proc.timed_out:
return fail("Timeout", f"Blender build exceeded {timeout_s}s (killed)", file="src/model.py", census=census,
stdout_tail=_tail(proc.stdout), stderr_tail=_tail(proc.stderr))
@@ -119,30 +145,28 @@ class UrdfBlenderRuntime:
stdout_tail=_tail(wb.get("stdout_tail", "") or proc.stdout),
stderr_tail=_tail(wb.get("stderr_tail", "") or proc.stderr))
- # 3. URDF copy + load
- urdf_out = art / "robot.urdf"
- shutil.copyfile(ws.root / "src" / "robot.urdf", urdf_out)
- extra = {"urdf": str(urdf_out), "meshes_dir": str(art / "meshes")}
+ # 3. URDF copy + load (staged files; extra_paths name the canonical homes)
+ urdf_staged = stage.path("robot.urdf")
+ shutil.copyfile(ws.root / "src" / "robot.urdf", urdf_staged)
+ extra = {"urdf": str(art / "robot.urdf"), "meshes_dir": str(art / "meshes")}
try:
- robot = load_urdf(urdf_out, art / "meshes")
+ robot = load_urdf(urdf_staged, stage.path("meshes"))
except UrdfError as e:
- return fail("UrdfError", str(e), census=census, extra_paths=extra)
+ return fail("UrdfError", str(e), census=census)
# 4. FK consistency
fk_findings = check_fk_consistency(robot, census.get("links") or {}, tol_m=FK_TOL_M)
census["fk_check"] = [f.model_dump(mode="json") for f in fk_findings]
if fk_findings:
msg = "\n".join(f"- {f.as_line()}" for f in fk_findings)
- return fail("FkInconsistent", f"URDF frames do not reproduce the authored geometry:\n{msg}", census=census,
- extra_paths=extra)
+ return fail("FkInconsistent", f"URDF frames do not reproduce the authored geometry:\n{msg}", census=census)
# 5. pose sweep
report = sweep_collisions(robot, pose_samples(robot, n_random=8, seed=0))
findings = sweep_findings(report, rest_max_m=REST_PENETRATION_MAX_M)
- art_json = art / "articulation.json"
- art_json.write_text(json.dumps({"report": report.model_dump(mode="json"),
- "findings": [f.model_dump(mode="json") for f in findings]}, indent=1))
- extra["articulation"] = str(art_json)
+ stage.path("articulation.json").write_text(json.dumps({"report": report.model_dump(mode="json"),
+ "findings": [f.model_dump(mode="json") for f in findings]}, indent=1))
+ extra["articulation"] = str(art / "articulation.json")
for name, n in report.summary.link_islands.items():
census.setdefault("links", {}).setdefault(name, {})["islands"] = n
census["articulation"] = {"summary": report.summary.model_dump(mode="json"),
@@ -150,9 +174,9 @@ class UrdfBlenderRuntime:
"n_joints": len(robot.joints), "movable_joints": [j.name for j in robot.movable_joints()]}
# 6. canonical GLB at rest
- glb = urdf_to_glb(robot, art / "object.glb", None)
- extra["object_glb"] = str(glb)
- res = BuildResult(ok=True, language=self.language.value, glb_path=str(glb), extra_paths=extra,
+ urdf_to_glb(robot, stage.path("object.glb"), None)
+ extra["object_glb"] = str(art / "object.glb")
+ res = BuildResult(ok=True, language=self.language.value, glb_path=str(art / "object.glb"), extra_paths=extra,
stdout_tail=_tail(wb.get("stdout_tail", "")), duration_ms=int((time.time() - t0) * 1000), census=census)
if report.summary.rest_max_penetration_m > REST_PENETRATION_MAX_M:
worst = [f for f in findings if f.data.get("pose") == {} and f.severity == "error"]
@@ -162,7 +186,9 @@ class UrdfBlenderRuntime:
res.error_message = (f"links interpenetrate by {report.summary.rest_max_penetration_m*1000:.1f} mm at the rest pose "
f"(max {REST_PENETRATION_MAX_M*1000:.0f} mm):\n" +
"\n".join(f"- {f.as_line()}" for f in worst[:8]))
- return res
+ res.glb_path = None # the fresh GLB is NOT published on a failed build
+ res.extra_paths = {}
+ return finish(res)
def _run_blender(blender: str, ws: Workspace, art: Path, timeout_s: int, rlimit_gb: int) -> ProcResult:
diff --git a/harness/codeverse/spatial/tool_common.py b/harness/codeverse/spatial/tool_common.py
index 62e4afdd..23ade17e 100644
--- a/harness/codeverse/spatial/tool_common.py
+++ b/harness/codeverse/spatial/tool_common.py
@@ -19,6 +19,7 @@ from pydantic import ValidationError
from codeverse.contracts.artifacts import RenderSet, Severity
from codeverse.contracts.plan import ArticulatedPlan, GraphicsPlan, Plan, ScenePlan, StaticPlan
from codeverse.conventions import OBJECT_VIEWS, ViewPreset
+from codeverse.proc import read_json_or_none
from codeverse.spatial.registry import ToolContext, ToolUnavailable, ToolUsageError
from codeverse.workspace import Workspace
@@ -90,10 +91,39 @@ def reference_path(ctx: ToolContext, index: int, *, tool: str) -> tuple[Path, di
return p, ref
+def _latest_build_status(ws: Workspace) -> dict[str, Any] | None:
+ """The newest of ``artifacts/build_last.json`` (written by the build tools) and
+ ``artifacts/build.json`` (written by the language runtimes), or None when
+ neither is readable — a workspace whose GLB was placed by hand (tests,
+ imports, first-measure flows) stays usable."""
+ newest: dict[str, Any] | None = None
+ newest_mtime = float("-inf")
+ for name in ("build_last.json", "build.json"):
+ p = ws.artifacts / name
+ try:
+ mtime = p.stat().st_mtime
+ except OSError:
+ continue
+ data = read_json_or_none(p)
+ if data is not None and mtime > newest_mtime:
+ newest, newest_mtime = data, mtime
+ return newest
+
+
def glb_path(ctx: ToolContext) -> Path:
+ """``artifacts/object.glb``, refusing when the LATEST build did not produce it.
+
+ Bare ``is_file()`` let every consumer (measure / render_views / compare /
+ texture tools) operate on the previous round's geometry as if it were current
+ after a failed or lint-blocked build."""
p = ctx.workspace.artifacts / "object.glb"
if not p.is_file():
raise ToolUsageError("artifacts/object.glb does not exist yet — run `build` first", "build()")
+ status = _latest_build_status(ctx.workspace)
+ if status is not None and not status.get("ok"):
+ raise ToolUsageError(
+ "the last build failed — artifacts/object.glb is from an earlier build; fix and build again",
+ "build()")
return p
diff --git a/harness/codeverse/spatial/tools.py b/harness/codeverse/spatial/tools.py
index abb6d9c1..1e98b3a0 100644
--- a/harness/codeverse/spatial/tools.py
+++ b/harness/codeverse/spatial/tools.py
@@ -139,6 +139,11 @@ def build(ctx: ToolContext, args: NoArgs) -> Observation:
lint_errors = lint_lines(lint, ws.root, errors_only=True)
lint_warns = lint_lines(lint, ws.root, errors_only=False)
if lint_errors:
+ # record the refusal as the LATEST build status: without this the previous
+ # round's build_last.json (ok: true) + object.glb stayed readable as current
+ ws.write_json(ws.artifacts / "build_last.json",
+ BuildResult(ok=False, language=language, error_type="LintError",
+ error_message="\n".join(lint_errors)[:4000]))
text = "LINT FAILED — fix these before building:\n" + "\n".join(lint_errors)
if lint_warns:
text += "\nwarnings:\n" + "\n".join(lint_warns[:10])
diff --git a/harness/codeverse/spatial/tools_graphics.py b/harness/codeverse/spatial/tools_graphics.py
index db7e61f0..c1f154dd 100644
--- a/harness/codeverse/spatial/tools_graphics.py
+++ b/harness/codeverse/spatial/tools_graphics.py
@@ -55,6 +55,10 @@ def _run_build(ctx: ToolContext, *, times: list[float], preview: bool, width: in
errs = lint_lines(lint, ws.root, errors_only=True)
warns = lint_lines(lint, ws.root, errors_only=False)
if errs:
+ # the refusal is the latest build status (same reasoning as tools.build)
+ ws.write_json(ws.artifacts / "build_last.json",
+ BuildResult(ok=False, language=language_of(ctx), error_type="LintError",
+ error_message="\n".join(errs)[:4000]))
text = "LINT FAILED — fix these before rendering:\n" + "\n".join(errs)
if warns:
text += "\nwarnings:\n" + "\n".join(warns[:8])
diff --git a/harness/codeverse/texturing/run.py b/harness/codeverse/texturing/run.py
index 3917bac0..a1708baa 100644
--- a/harness/codeverse/texturing/run.py
+++ b/harness/codeverse/texturing/run.py
@@ -9,6 +9,9 @@
Code stays the truth: ``artifacts/object.glb`` is never overwritten; the textured
GLB and ``artifacts/textures/`` are a derived asset pack recorded with the run.
+The textured GLB is built in an :class:`~codeverse.workspace.ArtifactStage` and
+promoted to ``artifacts/object_textured.glb`` only when the pass ships — a
+rejected pass leaves no canonical file for the deliverable/gallery to pick up.
"""
from __future__ import annotations
@@ -244,31 +247,37 @@ def texture_pass(
notes.append("no usable textures (all failed or seams too strong) — nothing applied")
return _finish(ws, report, t0, events, update_record)
- # 4. apply
- report.apply = apply_textures(texture_base, tplan, keep, glb_out)
- report.glb_out = str(glb_out)
- notes.extend(report.apply.warnings)
- events.emit("texture.applied", parts=len(report.apply.parts_textured), skipped=len(report.apply.parts_skipped),
- materials=report.apply.n_materials, warnings=len(report.apply.warnings))
- if not report.apply.parts_textured:
- notes.append("no part was textured")
+ # 4. apply — into staging: the canonical object_textured.glb exists on disk ONLY
+ # when the pass ships (entering the stage also removes any earlier pass's file)
+ with ws.stage_artifacts(TEXTURED_GLB) as stage:
+ staged_glb = stage.path(TEXTURED_GLB)
+ report.apply = apply_textures(texture_base, tplan, keep, staged_glb)
+ report.glb_out = str(glb_out) # the canonical home; a real file iff shipped
+ notes.extend(report.apply.warnings)
+ events.emit("texture.applied", parts=len(report.apply.parts_textured), skipped=len(report.apply.parts_skipped),
+ materials=report.apply.n_materials, warnings=len(report.apply.warnings))
+ if not report.apply.parts_textured:
+ notes.append("no part was textured")
+ return _finish(ws, report, t0, events, update_record)
+
+ # 5. gate
+ if not judge:
+ report.shipped = True
+ notes.append("judge gate skipped (--no-judge): shipped on seam gate only")
+ stage.promote()
+ return _finish(ws, report, t0, events, update_record)
+ gate_judge = judge_obj if judge_obj is not None else _make_judge(spec, rubric, judge_model_id)
+ gate = judge_gate(spec, plan, glb_in, staged_glb, tex_dir / "gate", judge=gate_judge, measurement=_measure(glb_in),
+ views=views, render=render)
+ report.gate, report.shipped, report.delta = gate, gate.shipped, gate.delta
+ report.usage = report.usage + gate.usage
+ events.emit("texture.gate", shipped=gate.shipped, delta=gate.delta, materials_delta=gate.materials_delta,
+ before=gate.overall_before, after=gate.overall_after, reason=gate.reason,
+ cost_usd=round(gate.usage.cost_usd, 4))
+ if report.shipped:
+ stage.promote()
return _finish(ws, report, t0, events, update_record)
- # 5. gate
- if not judge:
- report.shipped = True
- notes.append("judge gate skipped (--no-judge): shipped on seam gate only")
- return _finish(ws, report, t0, events, update_record)
- gate_judge = judge_obj if judge_obj is not None else _make_judge(spec, rubric, judge_model_id)
- gate = judge_gate(spec, plan, glb_in, glb_out, tex_dir / "gate", judge=gate_judge, measurement=_measure(glb_in),
- views=views, render=render)
- report.gate, report.shipped, report.delta = gate, gate.shipped, gate.delta
- report.usage = report.usage + gate.usage
- events.emit("texture.gate", shipped=gate.shipped, delta=gate.delta, materials_delta=gate.materials_delta,
- before=gate.overall_before, after=gate.overall_after, reason=gate.reason,
- cost_usd=round(gate.usage.cost_usd, 4))
- return _finish(ws, report, t0, events, update_record)
-
def _make_judge(spec: Spec, rubric: str | None, judge_model_id: str | None) -> Any:
from codeverse.judges.vlm_judge import VlmJudge
@@ -286,6 +295,10 @@ def _make_judge(spec: Spec, rubric: str | None, judge_model_id: str | None) -> A
def _finish(ws: Workspace, report: TextureReport, t0: float, events: EventLog, update_record: bool) -> TextureReport:
report.duration_s = round(time.time() - t0, 2)
+ if not report.shipped:
+ # a pass that did not ship leaves NO canonical textured GLB — including one
+ # left behind by an earlier shipped pass (the report keeps all its fields)
+ ws.stage_artifacts(TEXTURED_GLB).invalidate()
ws.write_json(ws.artifacts / TEXTURES_DIR / REPORT_NAME, report)
if update_record:
record_texturing(ws, report)
diff --git a/harness/codeverse/workspace.py b/harness/codeverse/workspace.py
index eb9a0f55..c59923e1 100644
--- a/harness/codeverse/workspace.py
+++ b/harness/codeverse/workspace.py
@@ -8,6 +8,7 @@ flywheel can replay any round.
from __future__ import annotations
+import contextlib
import json
import os
import shutil
@@ -260,6 +261,15 @@ class Workspace:
data = model.model_dump(mode="json") if isinstance(model, BaseModel) else model
write_json_atomic(path, data)
+ # ----------------------------------------------------------------- artifact staging
+ def stage_artifacts(self, *names: str) -> ArtifactStage:
+ """An :class:`ArtifactStage` over canonical ``artifacts/`` names.
+
+ Use as a context manager for the full stage-then-promote lifecycle, or
+ call ``.invalidate()`` on the returned stage for a bare wipe of the
+ canonical names (the ``remove_stale`` replacement)."""
+ return ArtifactStage(self, names)
+
def read_json(self, path: Path) -> dict[str, Any]:
return json.loads(path.read_text())
@@ -377,3 +387,138 @@ class Workspace:
if dest.exists():
shutil.rmtree(dest)
shutil.copytree(self.src, dest, ignore=shutil.ignore_patterns("node_modules", "__pycache__"))
+
+
+class ArtifactStage:
+ """Stage-then-promote lifecycle for a fixed set of canonical ``artifacts/`` names.
+
+ The invariant this enforces: a canonical artifact exists on disk ONLY when the
+ build/pass that owns it finished with that artifact as its result. Before this,
+ every runtime's early return (missing entry file, lint error, wrapper crash)
+ left the *previous* round's ``object.glb`` / ``build.json`` looking current, and
+ every downstream consumer (measure/render tools, deliverable packaging, the
+ gallery) trusted bare existence.
+
+ Lifecycle (``with ws.stage_artifacts("build.json", "object.glb") as stage:``):
+
+ * ``__enter__`` **invalidates** the canonical names immediately — before any
+ early return can leak — and claims a private staging directory under
+ ``artifacts/.staging/<pid>-<nonce>/``;
+ * ``path(name)`` is the staging location to write ``name`` to (wrappers taking
+ an ``--out`` directory can be pointed at ``staging_dir`` directly);
+ * ``promote(*names)`` publishes staged entries into ``artifacts/`` —
+ ``os.replace`` per file (atomic: staging lives on the same filesystem);
+ * exit without promote **discards** the staging directory — canonical stays absent.
+
+ ``invalidate()`` also works standalone (no ``with``) as the one-call
+ replacement for ``languages._common.remove_stale`` + ``shutil.rmtree``.
+
+ Directory promotion (``meshes/``) is NOT atomic: the old dir is renamed away
+ (parked inside the staging dir), the new one renamed in, then the parked copy
+ is removed. A reader can observe the name missing between the two renames, and
+ a SIGKILL between them leaves the old copy parked under ``artifacts/.staging/``
+ — inert, because every consumer reads canonical paths only, and the next stage
+ of the same names starts by invalidating them. Concurrent stages over the same
+ names (the scene track fans agents over one workspace) each use a private
+ staging dir; promotion follows the ``write_json_atomic`` precedent: last writer
+ to rename wins.
+ """
+
+ STAGING_ROOT = ".staging"
+
+ def __init__(self, ws: Workspace, names: tuple[str, ...] | Sequence[str]):
+ if not names:
+ raise ValueError("ArtifactStage needs at least one artifact name")
+ self._ws = ws
+ self.names: tuple[str, ...] = tuple(names)
+ self._dir: Path | None = None
+
+ # ------------------------------------------------------------------ lifecycle
+ def __enter__(self) -> ArtifactStage:
+ self.invalidate()
+ _ = self.staging_dir # claim it now so wrappers can be pointed at it
+ return self
+
+ def __exit__(self, *exc: object) -> None:
+ self.discard()
+
+ @property
+ def staging_dir(self) -> Path:
+ """The private staging directory (created on first use)."""
+ if self._dir is None:
+ d = self._ws.artifacts / self.STAGING_ROOT / f"{os.getpid()}-{os.urandom(4).hex()}"
+ d.mkdir(parents=True, exist_ok=True)
+ self._dir = d
+ return self._dir
+
+ def path(self, name: str) -> Path:
+ """Staging location for ``name`` (parent directories created)."""
+ self._check(name)
+ p = self.staging_dir / name
+ p.parent.mkdir(parents=True, exist_ok=True)
+ return p
+
+ # ------------------------------------------------------------------ operations
+ def invalidate(self, *names: str) -> None:
+ """Remove the canonical copies of ``names`` (default: every staged name)."""
+ for name in names or self.names:
+ self._check(name)
+ target = self._ws.artifacts / name
+ if target.is_dir() and not target.is_symlink():
+ shutil.rmtree(target, ignore_errors=True)
+ else:
+ target.unlink(missing_ok=True)
+
+ def promote(self, *names: str) -> list[Path]:
+ """Publish staged entries into ``artifacts/`` and return the canonical paths.
+
+ With explicit ``names``, every named entry must exist in staging
+ (``FileNotFoundError`` otherwise — a build that claims success without its
+ outputs is a bug, not a skip). With no arguments, every staged name that
+ was actually written is published and the rest are left invalidated."""
+ chosen = names or self.names
+ published: list[Path] = []
+ for name in chosen:
+ self._check(name)
+ src = self.staging_dir / name
+ if not src.exists():
+ if names:
+ raise FileNotFoundError(f"promote({name!r}): nothing staged at {src}")
+ continue
+ dest = self._ws.artifacts / name
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ if src.is_dir() and not src.is_symlink():
+ self._replace_dir(src, dest, name)
+ else:
+ os.replace(src, dest)
+ published.append(dest)
+ return published
+
+ def discard(self) -> None:
+ """Drop the staging directory (anything not promoted is gone)."""
+ if self._dir is not None:
+ shutil.rmtree(self._dir, ignore_errors=True)
+ with contextlib.suppress(OSError): # tidy the shared .staging parent when empty
+ self._dir.parent.rmdir()
+ self._dir = None
+
+ # ------------------------------------------------------------------ internals
+ def _check(self, name: str) -> None:
+ if name not in self.names:
+ raise ValueError(f"{name!r} is not staged here (staged: {list(self.names)})")
+
+ def _replace_dir(self, src: Path, dest: Path, name: str) -> None:
+ """Replace-dir strategy: rename old away (parked in staging), rename new in,
+ remove old. See the class docstring for the atomicity limits."""
+ parked: Path | None = None
+ if dest.exists():
+ parked = self.staging_dir / f"{name.replace('/', '_')}.old"
+ os.rename(dest, parked)
+ try:
+ os.rename(src, dest)
+ except OSError:
+ if parked is not None: # best effort: put the old dir back
+ os.rename(parked, dest)
+ raise
+ if parked is not None:
+ shutil.rmtree(parked, ignore_errors=True)
diff --git a/harness/tests/blender_cadquery/test_artifact_stage.py b/harness/tests/blender_cadquery/test_artifact_stage.py
new file mode 100644
index 00000000..102ac88d
--- /dev/null
+++ b/harness/tests/blender_cadquery/test_artifact_stage.py
@@ -0,0 +1,98 @@
+"""ArtifactStage: the stage-then-promote lifecycle every runtime's build outputs use.
+
+The invariant under test: a canonical artifact exists ONLY when the build that owns
+it finished with that artifact as its result — entering a stage invalidates the
+canonical names before any early return can leak, and exit-without-promote leaves
+them absent.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from codeverse.workspace import Workspace
+
+
+def _seed(ws: Workspace) -> None:
+ (ws.artifacts / "build.json").write_text('{"ok": true}')
+ (ws.artifacts / "object.glb").write_bytes(b"old glb")
+ meshes = ws.artifacts / "meshes"
+ meshes.mkdir(exist_ok=True)
+ (meshes / "old.glb").write_bytes(b"old mesh")
+
+
+def test_enter_invalidates_immediately_and_exit_discards(tmp_ws: Workspace) -> None:
+ _seed(tmp_ws)
+ with tmp_ws.stage_artifacts("build.json", "object.glb", "meshes") as stage:
+ # the previous round's outputs are gone BEFORE any work (or early return) happens
+ assert not (tmp_ws.artifacts / "build.json").exists()
+ assert not (tmp_ws.artifacts / "object.glb").exists()
+ assert not (tmp_ws.artifacts / "meshes").exists()
+ assert stage.staging_dir.is_dir() and stage.staging_dir.parent.name == ".staging"
+ stage.path("object.glb").write_bytes(b"half built") # never promoted
+ # exit without promote: canonical stays absent, staging discarded
+ assert not (tmp_ws.artifacts / "object.glb").exists()
+ staging_root = tmp_ws.artifacts / ".staging"
+ assert not staging_root.exists() or not any(staging_root.iterdir())
+
+
+def test_promote_publishes_files_and_dirs(tmp_ws: Workspace) -> None:
+ _seed(tmp_ws)
+ with tmp_ws.stage_artifacts("build.json", "object.glb", "meshes") as stage:
+ stage.path("build.json").write_text('{"ok": true}')
+ stage.path("object.glb").write_bytes(b"new glb")
+ stage.path("meshes").mkdir()
+ (stage.path("meshes") / "leg.glb").write_bytes(b"new mesh")
+ published = stage.promote()
+ assert {p.name for p in published} == {"build.json", "object.glb", "meshes"}
+ assert (tmp_ws.artifacts / "object.glb").read_bytes() == b"new glb"
+ assert (tmp_ws.artifacts / "meshes" / "leg.glb").read_bytes() == b"new mesh"
+ assert not (tmp_ws.artifacts / ".staging").exists() # fully cleaned up
+
+
+def test_selective_promote_leaves_the_rest_invalidated(tmp_ws: Workspace) -> None:
+ """The urdf failure paths publish build.json (the failed status) and nothing else."""
+ _seed(tmp_ws)
+ with tmp_ws.stage_artifacts("build.json", "object.glb") as stage:
+ stage.path("build.json").write_text('{"ok": false}')
+ stage.path("object.glb").write_bytes(b"fresh but unpublished")
+ stage.promote("build.json")
+ assert (tmp_ws.artifacts / "build.json").read_text() == '{"ok": false}'
+ assert not (tmp_ws.artifacts / "object.glb").exists()
+
+
+def test_default_promote_skips_names_never_written(tmp_ws: Workspace) -> None:
+ with tmp_ws.stage_artifacts("build.json", "object.stl") as stage:
+ stage.path("build.json").write_text('{"ok": true}')
+ published = stage.promote() # object.stl was never staged → skipped, not an error
+ assert [p.name for p in published] == ["build.json"]
+ assert not (tmp_ws.artifacts / "object.stl").exists()
+
+
+def test_promote_replaces_an_existing_dir(tmp_ws: Workspace) -> None:
+ meshes = tmp_ws.artifacts / "meshes"
+ meshes.mkdir()
+ (meshes / "old.glb").write_bytes(b"old")
+ stage = tmp_ws.stage_artifacts("meshes") # standalone (no enter → no invalidation)
+ stage.path("meshes").mkdir()
+ (stage.path("meshes") / "new.glb").write_bytes(b"new")
+ stage.promote()
+ stage.discard()
+ assert [p.name for p in meshes.iterdir()] == ["new.glb"] # old members do not survive
+
+
+def test_invalidate_standalone_and_name_validation(tmp_ws: Workspace) -> None:
+ _seed(tmp_ws)
+ tmp_ws.stage_artifacts("build.json", "object.glb", "meshes").invalidate() # the remove_stale replacement
+ for name in ("build.json", "object.glb", "meshes"):
+ assert not (tmp_ws.artifacts / name).exists(), name
+ stage = tmp_ws.stage_artifacts("build.json")
+ with pytest.raises(ValueError):
+ stage.path("other.json")
+ with pytest.raises(ValueError):
+ stage.invalidate("other.json")
+ with pytest.raises(FileNotFoundError):
+ stage.promote("build.json") # a named promote of something never staged is a bug
+ stage.discard()
+ with pytest.raises(ValueError):
+ tmp_ws.stage_artifacts()
diff --git a/harness/tests/blender_cadquery/test_blender_runtime.py b/harness/tests/blender_cadquery/test_blender_runtime.py
index f20fd90f..51799865 100644
--- a/harness/tests/blender_cadquery/test_blender_runtime.py
+++ b/harness/tests/blender_cadquery/test_blender_runtime.py
@@ -61,6 +61,22 @@ def test_missing_entry_file(tmp_ws, tmp_path) -> None:
assert not r.ok and r.error_type == "MissingEntryFile"
+def test_missing_entry_invalidates_previous_outputs(tmp_ws, tmp_path) -> None:
+ """Deleting model.py between rounds must not leave round N-1's object.glb +
+ build.json (ok: true) looking current — the invalidation runs BEFORE the
+ missing-entry early return, and build.json on disk says what build() returned."""
+ for name in ("object.glb", "object.stl"):
+ (tmp_ws.artifacts / name).write_bytes(b"stale")
+ tmp_ws.write_json(tmp_ws.artifacts / "build.json", {"ok": True})
+ tmp_ws.write_json(tmp_ws.artifacts / "census.json", {"tri_count": 3})
+ r = BlenderRuntime(blender=_fake_blender(tmp_path)).build(tmp_ws)
+ assert not r.ok and r.error_type == "MissingEntryFile"
+ for name in ("object.glb", "object.stl", "census.json"):
+ assert not (tmp_ws.artifacts / name).exists(), name
+ disk = json.loads((tmp_ws.artifacts / "build.json").read_text())
+ assert disk["ok"] is False and disk["error_type"] == "MissingEntryFile"
+
+
def test_build_command_and_env(tmp_ws, tmp_path, monkeypatch) -> None:
rt = BlenderRuntime(blender=_fake_blender(tmp_path))
cmd = rt.build_command(tmp_ws, stl=True, seed=3, tri_limit=1000)
diff --git a/harness/tests/blender_cadquery/test_cadquery_runtime.py b/harness/tests/blender_cadquery/test_cadquery_runtime.py
index cf78076e..48712d73 100644
--- a/harness/tests/blender_cadquery/test_cadquery_runtime.py
+++ b/harness/tests/blender_cadquery/test_cadquery_runtime.py
@@ -43,6 +43,21 @@ def test_missing_entry(tmp_ws) -> None:
assert not r.ok and r.error_type == "MissingEntryFile"
+def test_missing_entry_invalidates_previous_outputs(tmp_ws) -> None:
+ """Same invariant as BlenderRuntime: the invalidation runs BEFORE the
+ missing-entry early return and build.json agrees with the returned result."""
+ for name in ("object.glb", "object.step", "object.stl"):
+ (tmp_ws.artifacts / name).write_bytes(b"stale")
+ tmp_ws.write_json(tmp_ws.artifacts / "build.json", {"ok": True})
+ tmp_ws.write_json(tmp_ws.artifacts / "census.json", {"tri_count": 3})
+ r = CadQueryRuntime().build(tmp_ws)
+ assert not r.ok and r.error_type == "MissingEntryFile"
+ for name in ("object.glb", "object.step", "object.stl", "census.json"):
+ assert not (tmp_ws.artifacts / name).exists(), name
+ disk = json.loads((tmp_ws.artifacts / "build.json").read_text())
+ assert disk["ok"] is False and disk["error_type"] == "MissingEntryFile"
+
+
def test_fake_python_wrapper_crash(tmp_ws, tmp_path) -> None:
fake = tmp_path / "py"
fake.write_text("#!/bin/sh\necho 'ImportError: no cadquery' >&2\nexit 1\n")
diff --git a/harness/tests/flywheel_cli/test_run_layout_cli.py b/harness/tests/flywheel_cli/test_run_layout_cli.py
index 89a95374..c88747ad 100644
--- a/harness/tests/flywheel_cli/test_run_layout_cli.py
+++ b/harness/tests/flywheel_cli/test_run_layout_cli.py
@@ -137,6 +137,38 @@ def test_telemetry_degrades_when_the_cost_package_is_unavailable(fake_run, monke
assert tele.cost.n_calls == 0 and tele.settings is not None # settings never depend on the ledger
+def test_deliverable_files_are_real_copies_not_hardlinks(fake_run):
+ """Editing a delivered file must never mutate the canonical evidence: every
+ deliverable file is a real copy (st_nlink == 1), whatever its size — the old
+ ≥256 KiB hard-link fast path silently broke the recorded sha256."""
+ ws, rec = fake_run
+ (ws.artifacts / "object.glb").write_bytes(b"glTF" + b"\0" * (300 * 1024)) # past the old link floor
+ build_deliverable(ws, rec)
+ delivered = ws.deliverable / "object.glb"
+ assert delivered.is_file() and delivered.stat().st_nlink == 1
+ assert (ws.artifacts / "object.glb").stat().st_nlink == 1
+ delivered.write_bytes(b"user edited the hand-over copy")
+ assert (ws.artifacts / "object.glb").read_bytes().startswith(b"glTF") # evidence untouched
+
+
+def test_rejected_texture_pass_is_not_delivered_or_linked(fake_run):
+ """Belt and braces: a stray canonical object_textured.glb from a rejected pass
+ is skipped by the deliverable AND by the gallery links (both gate on shipped)."""
+ ws, rec = fake_run
+ (ws.artifacts / "object_textured.glb").write_bytes(b"glTF\x02" + b"\0" * 16)
+ rec.extra["texturing"] = {"shipped": False, "glb_textured": "artifacts/object_textured.glb"}
+ build_deliverable(ws, rec)
+ assert not (ws.deliverable / "object_textured.glb").exists()
+ entry = entry_from_record("runs", ws, rec)
+ assert "textured glb" not in {ln.label for ln in entry.links}
+ # ... and a SHIPPED pass is delivered and linked
+ rec.extra["texturing"] = {"shipped": True, "glb_textured": "artifacts/object_textured.glb"}
+ build_deliverable(ws, rec)
+ assert (ws.deliverable / "object_textured.glb").is_file()
+ entry = entry_from_record("runs", ws, rec)
+ assert "textured glb" in {ln.label for ln in entry.links}
+
+
# --------------------------------------------------------------------------- migration
def test_migrate_run_is_additive_and_idempotent(tmp_path: Path):
ws, _ = old_layout_run(tmp_path)
diff --git a/harness/tests/graphics/test_stale_invalidation.py b/harness/tests/graphics/test_stale_invalidation.py
new file mode 100644
index 00000000..9ed93201
--- /dev/null
+++ b/harness/tests/graphics/test_stale_invalidation.py
@@ -0,0 +1,73 @@
+"""GL builds must not leave the previous build's artifacts looking current (offline).
+
+frames_sheet.png / preview.gif / metrics.json are written only on ok and were never
+cleared; the MissingEntry early returns never reached GlHost._run's frames wipe.
+Both wipes now happen at the top of build() (``_gl_common.invalidate_stale_outputs``)
+plus a failure-path invalidation in ``finish_build``.
+"""
+
+from __future__ import annotations
+
+import json
+
+import codeverse.spatial.tools # noqa: F401 — registers the gl_* tools
+from codeverse.languages.glsl_shader.runtime import GlslShaderRuntime
+from codeverse.spatial.gl_render import GlResult
+from codeverse.spatial.registry import ToolContext, get_tool
+from codeverse.workspace import Workspace
+
+
+class _FailingHost:
+ """Stands in for GlHost: every render is a compile failure."""
+
+ def render_fragment_shader(self, frag_src: str, out_dir, **kw) -> GlResult:
+ return GlResult(ok=False, mode="shader", stage="compile", error_type="Error",
+ error_message="0:3(5): error: `nope' undeclared")
+
+
+def _seed_stale(ws: Workspace) -> None:
+ for name in ("frames_sheet.png", "preview.gif"):
+ (ws.artifacts / name).write_bytes(b"stale")
+ (ws.artifacts / "metrics.json").write_text('{"stale": true}')
+ ws.write_json(ws.artifacts / "build.json", {"ok": True})
+ frames = ws.artifacts / "frames"
+ frames.mkdir(exist_ok=True)
+ (frames / "f00_t000.00.png").write_bytes(b"stale frame")
+ (ws.artifacts / "gl_result.json").write_text("{}")
+
+
+def test_failed_build_invalidates_sheet_gif_metrics(tmp_ws: Workspace) -> None:
+ (tmp_ws.src / "shader.frag").write_text(
+ "void mainImage(out vec4 fragColor, in vec2 fragCoord) { fragColor = vec4(nope); }\n")
+ _seed_stale(tmp_ws)
+ br = GlslShaderRuntime(host=_FailingHost()).build(tmp_ws, preview=False)
+ assert not br.ok and br.error_type == "GlslCompileError"
+ for name in ("frames_sheet.png", "preview.gif", "metrics.json", "gl_result.json"):
+ assert not (tmp_ws.artifacts / name).exists(), name
+ assert not list((tmp_ws.artifacts / "frames").glob("*.png"))
+ assert json.loads((tmp_ws.artifacts / "build.json").read_text())["ok"] is False
+
+
+def test_missing_entry_clears_frames_and_result(tmp_ws: Workspace) -> None:
+ """The MissingEntry early return never reaches the host — the hoisted wipe must
+ still clear frames/ + gl_result.json (and the sheet/gif/metrics trio)."""
+ _seed_stale(tmp_ws)
+ br = GlslShaderRuntime(host=_FailingHost()).build(tmp_ws, preview=False)
+ assert not br.ok and br.error_type == "MissingEntry"
+ assert not list((tmp_ws.artifacts / "frames").glob("*.png"))
+ for name in ("gl_result.json", "frames_sheet.png", "preview.gif", "metrics.json"):
+ assert not (tmp_ws.artifacts / name).exists(), name
+ assert json.loads((tmp_ws.artifacts / "build.json").read_text())["ok"] is False
+
+
+def test_gl_tool_lint_fail_records_failed_build_last(tmp_ws: Workspace) -> None:
+ """A lint refusal in the gl tools is the LATEST build status — the previous
+ round's build_last.json (ok: true) must not stay readable as current."""
+ (tmp_ws.src / "shader.frag").write_text(
+ "#version 330 core\nvoid mainImage(out vec4 fragColor, in vec2 fragCoord) { fragColor = vec4(1.0); }\n")
+ tmp_ws.write_json(tmp_ws.artifacts / "build_last.json", {"ok": True})
+ ctx = ToolContext(workspace=tmp_ws, language="glsl_shader", track="graphics")
+ obs = get_tool("gl_probe").call(ctx, {})
+ assert not obs.ok and "LINT FAILED" in obs.text
+ last = json.loads((tmp_ws.artifacts / "build_last.json").read_text())
+ assert last["ok"] is False and last["error_type"] == "LintError"
diff --git a/harness/tests/scene_runtime/test_runtime.py b/harness/tests/scene_runtime/test_runtime.py
index 727ab30c..597d91c0 100644
--- a/harness/tests/scene_runtime/test_runtime.py
+++ b/harness/tests/scene_runtime/test_runtime.py
@@ -115,3 +115,25 @@ def test_build_interprets_combined_summary_offline(ws, monkeypatch):
assert not res2.ok
shaders2 = _json.loads((ws.artifacts / "gates" / "shader_preflight.json").read_text())
assert not shaders2["passed"] and shaders2["findings"] == []
+
+
+def test_probe_crash_leaves_no_stale_probe_outputs(ws, monkeypatch):
+ """A driver crash (SceneRenderError) must not leave the previous round's census
+ or the root driver outputs (scene_probe.json / shader_preflight.json) looking
+ current; build.json on disk says ok:false, never the previous round's ok:true."""
+ import codeverse.spatial.render_scene as rs_mod
+ from codeverse.spatial.render_scene import SceneRenderError
+
+ for name in ("census.json", "scene_probe.json", "shader_preflight.json"):
+ (ws.artifacts / name).write_text('{"stale": true}')
+ (ws.artifacts / "build.json").write_text('{"ok": true}')
+
+ def crash(script, args, **kw):
+ raise SceneRenderError("chrome went away")
+
+ monkeypatch.setattr(rs_mod, "run_scene_script", crash)
+ res = SceneThreeJsRuntime().build(ws)
+ assert not res.ok
+ for name in ("census.json", "scene_probe.json", "shader_preflight.json"):
+ assert not (ws.artifacts / name).exists(), name
+ assert json.loads((ws.artifacts / "build.json").read_text())["ok"] is False
diff --git a/harness/tests/spatial_tools/test_tools.py b/harness/tests/spatial_tools/test_tools.py
index c8900bc9..b821f8a6 100644
--- a/harness/tests/spatial_tools/test_tools.py
+++ b/harness/tests/spatial_tools/test_tools.py
@@ -147,6 +147,42 @@ def test_build_tool_lint_blocks(stool_ctx: ToolContext, monkeypatch: pytest.Monk
assert obs.numbers["stage"] == "lint"
+def test_build_failure_refuses_stale_glb(stool_ctx: ToolContext, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A failed build after a success: the old object.glb survives as evidence but
+ glb_path refuses to treat it as current (build_last.json says ok:false)."""
+ _patch_runtime(monkeypatch, _FakeRuntime(glb=stool_ctx.workspace.artifacts / "object.glb"))
+ assert get_tool("build").call(stool_ctx, {}).ok
+ assert get_tool("measure").call(stool_ctx, {}).ok # ok:true status → still usable
+ _patch_runtime(monkeypatch, _FakeRuntime(build_ok=False))
+ assert not get_tool("build").call(stool_ctx, {}).ok
+ assert json.loads((stool_ctx.workspace.artifacts / "build_last.json").read_text())["ok"] is False
+ assert (stool_ctx.workspace.artifacts / "object.glb").is_file() # evidence stays on disk
+ for name in ("measure", "render_views", "check_connectivity"):
+ obs = get_tool(name).call(stool_ctx, {})
+ assert not obs.ok and "last build failed" in obs.text, name
+
+
+def test_build_lint_fail_refuses_stale_glb(stool_ctx: ToolContext, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A lint refusal is the latest build status: the previous build_last.json
+ (ok: true) + object.glb are no longer readable as current."""
+ _patch_runtime(monkeypatch, _FakeRuntime(glb=stool_ctx.workspace.artifacts / "object.glb"))
+ assert get_tool("build").call(stool_ctx, {}).ok
+ _patch_runtime(monkeypatch, _FakeRuntime(lint_errors=True))
+ obs = get_tool("build").call(stool_ctx, {})
+ assert not obs.ok and obs.text.startswith("LINT FAILED")
+ last = json.loads((stool_ctx.workspace.artifacts / "build_last.json").read_text())
+ assert last["ok"] is False and last["error_type"] == "LintError"
+ obs = get_tool("measure").call(stool_ctx, {})
+ assert not obs.ok and "last build failed" in obs.text
+
+
+def test_hand_placed_glb_without_build_status_still_measures(stool_ctx: ToolContext) -> None:
+ """No build_last.json / build.json → glb_path stays permissive: first-measure
+ flows and hand-assembled (test/import) workspaces keep working."""
+ assert not (stool_ctx.workspace.artifacts / "build_last.json").exists()
+ assert get_tool("measure").call(stool_ctx, {}).ok
+
+
def test_build_unavailable_runtime(stool_ctx: ToolContext, monkeypatch: pytest.MonkeyPatch) -> None:
import codeverse.spatial.tool_common as tc
diff --git a/harness/tests/texturing/test_run.py b/harness/tests/texturing/test_run.py
index 1d104fe4..a0634b78 100644
--- a/harness/tests/texturing/test_run.py
+++ b/harness/tests/texturing/test_run.py
@@ -47,12 +47,16 @@ def test_texture_pass_ships_and_records(tmp_path, chair_glb, chair_spec, chair_p
assert latest_sheet(ws) is None and (ws.artifacts / "textures" / "planner_views" / "sheet.png").is_file()
-def test_texture_pass_not_shipped_keeps_report(tmp_path, chair_glb, chair_spec, chair_plan):
+def test_texture_pass_not_shipped_keeps_report_but_no_canonical_glb(tmp_path, chair_glb, chair_spec, chair_plan):
ws = _ws(tmp_path, chair_glb, chair_spec, chair_plan)
+ (ws.artifacts / "object_textured.glb").write_bytes(b"stale earlier pass") # e.g. a pass that DID ship before
judge = FakeJudge([(0.70, {"materials": 0.6}), (0.60, {"materials": 0.6})])
rep = texture_pass(ws, chair_spec, chair_plan, model_id="", image_model=FakeImageModel(), judge_obj=judge,
render=fake_render, cache_dir=tmp_path / "cache")
assert not rep.shipped and rep.gate is not None and rep.glb_out.endswith("object_textured.glb")
+ # not shipped → NO canonical object_textured.glb, not even the earlier pass's;
+ # the report keeps all its fields (glb_out names the canonical home)
+ assert not (ws.artifacts / "object_textured.glb").exists()
assert json.loads(ws.record_path.read_text())["extra"]["texturing"]["shipped"] is False
@@ -61,11 +65,14 @@ def test_texture_pass_no_judge_and_all_failed(tmp_path, chair_glb, chair_spec, c
rep = texture_pass(ws, chair_spec, chair_plan, model_id="", image_model=FakeImageModel(), judge=False, render=fake_render,
cache_dir=tmp_path / "cache")
assert rep.shipped and rep.gate is None and any("skipped" in n for n in rep.notes)
- # every image fails → nothing applied, not shipped, no crash
+ # every image fails → nothing applied, not shipped, no crash — and a stray
+ # canonical file from an earlier pass is removed even on this early-return path
ws2 = _ws(tmp_path / "b", chair_glb, chair_spec, chair_plan)
+ (ws2.artifacts / "object_textured.glb").write_bytes(b"stale earlier pass")
rep2 = texture_pass(ws2, chair_spec, chair_plan, model_id="", image_model=FakeImageModel(fail_on=("seamless",)), judge=False,
render=fake_render, cache_dir=tmp_path / "cache2")
assert not rep2.shipped and rep2.apply is None and rep2.glb_out == "" and rep2.textures.failed()
+ assert not (ws2.artifacts / "object_textured.glb").exists()
def test_texture_services_bundle_and_deprecated_judge_object(tmp_path, chair_glb, chair_spec, chair_plan):
diff --git a/harness/tests/threejs_render/test_stale_outputs.py b/harness/tests/threejs_render/test_stale_outputs.py
new file mode 100644
index 00000000..51e2279f
--- /dev/null
+++ b/harness/tests/threejs_render/test_stale_outputs.py
@@ -0,0 +1,54 @@
+"""ThreeJsRuntime.build stale-output invalidation (offline — node never runs).
+
+The node-missing raise used to happen AFTER the glb/census wipe but BEFORE any
+build.json write, so a previous round's build.json (ok: true) survived a harness
+failure and every bare-existence reader treated the old outputs as current.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+import codeverse.languages.threejs.runtime as rt_mod
+from codeverse.languages.threejs.runtime import ThreeJsRuntime
+from codeverse.spatial.node import NodeError, NodeResult
+from codeverse.workspace import Workspace
+
+
+def _ws_with_stale(tmp_path) -> Workspace:
+ ws = Workspace(tmp_path / "run").create()
+ (ws.src / "object.js").write_text("export function build() {}\n")
+ (ws.artifacts / "object.glb").write_bytes(b"stale glb")
+ ws.write_json(ws.artifacts / "build.json", {"ok": True})
+ ws.write_json(ws.artifacts / "census.json", {"tri_count": 3})
+ (ws.artifacts / "export_error.json").write_text("{}")
+ return ws
+
+
+def test_node_missing_raise_leaves_no_stale_outputs(tmp_path, monkeypatch):
+ ws = _ws_with_stale(tmp_path)
+
+ def no_node(*a, **k):
+ raise NodeError("node binary not found", None) # harness problem → re-raised
+
+ monkeypatch.setattr(rt_mod, "run_node", no_node)
+ with pytest.raises(NodeError):
+ ThreeJsRuntime().build(ws)
+ for name in ("build.json", "object.glb", "census.json", "export_error.json"):
+ assert not (ws.artifacts / name).exists(), name
+
+
+def test_node_failure_with_result_writes_failed_build_json(tmp_path, monkeypatch):
+ ws = _ws_with_stale(tmp_path)
+
+ def timeout(*a, **k):
+ raise NodeError("timed out", NodeResult(rc=-9, stdout="", stderr="killed",
+ last_json=None, duration_ms=5, timed_out=True))
+
+ monkeypatch.setattr(rt_mod, "run_node", timeout)
+ res = ThreeJsRuntime().build(ws)
+ assert not res.ok and res.error_type == "Timeout"
+ assert not (ws.artifacts / "object.glb").exists()
+ assert json.loads((ws.artifacts / "build.json").read_text())["ok"] is False
diff --git a/harness/tests/urdf_joints/test_runtime_offline.py b/harness/tests/urdf_joints/test_runtime_offline.py
index 61314163..8d8b9561 100644
--- a/harness/tests/urdf_joints/test_runtime_offline.py
+++ b/harness/tests/urdf_joints/test_runtime_offline.py
@@ -105,12 +105,62 @@ def test_build_fk_inconsistent(tmp_path, cabinet_plan, fake_blender):
assert 'xyz="0.29 0.2 0"' in res.error_message and res.census["fk_check"][0]["target"] == "door"
-def test_build_rest_penetration_fails(tmp_path, cabinet_plan, fake_blender):
+def test_build_rest_penetration_fails_and_publishes_nothing(tmp_path, cabinet_plan, fake_blender):
fake_blender["door"] = ((0, -0.19, 0.4), (0.58, 0.02, 0.78)) # authored 10 mm inside the body
ws = _ws(tmp_path, cabinet_plan)
res = UrdfBlenderRuntime().build(ws)
assert not res.ok and res.error_type == "RestPenetration"
- assert res.glb_path and res.census["articulation"]["summary"]["rest_max_penetration_m"] > 0.005
+ assert res.census["articulation"]["summary"]["rest_max_penetration_m"] > 0.005
+ # a failed build publishes NOTHING but its status: the fresh GLB stays unshipped
+ assert res.glb_path is None and res.extra_paths == {}
+ for name in ("object.glb", "robot.urdf", "articulation.json"):
+ assert not (ws.artifacts / name).exists(), name
+ assert not (ws.artifacts / "meshes").exists()
+ assert json.loads((ws.artifacts / "build.json").read_text())["ok"] is False
+
+
+def test_build_failure_invalidates_previous_success(tmp_path, cabinet_plan, fake_blender):
+ """Round N fails after round N-1 succeeded: every canonical output of the old
+ round is gone and build.json on disk agrees with the returned (failed) result."""
+ ws = _ws(tmp_path, cabinet_plan)
+ rt = UrdfBlenderRuntime()
+ assert rt.build(ws).ok
+ for name in ("object.glb", "robot.urdf", "articulation.json", "census.json", "meshes"):
+ assert (ws.artifacts / name).exists(), name
+ fake_blender["error"] = {"error_type": "NameError", "error_message": "boom",
+ "error_file": "src/model.py", "error_line": 3}
+ res = rt.build(ws)
+ assert not res.ok and res.error_type == "NameError"
+ for name in ("object.glb", "robot.urdf", "articulation.json"):
+ assert not (ws.artifacts / name).exists(), name
+ assert not (ws.artifacts / "meshes").exists()
+ disk = json.loads((ws.artifacts / "build.json").read_text())
+ assert disk["ok"] is False and disk["error_type"] == "NameError"
+
+
+def test_post_wrapper_failure_never_leaves_ok_true_build_json(tmp_path, cabinet_plan, fake_blender):
+ """The wrapper reports ok:true, then FkInconsistent fails the build — the
+ published build.json must say what the returned BuildResult says (the old code
+ left the wrapper's ok:true on disk while the run failed)."""
+ ws = _ws(tmp_path, cabinet_plan)
+ u = ws.src / "robot.urdf"
+ u.write_text(u.read_text().replace('xyz="0.29 0.2 0"', 'xyz="-0.29 -0.2 0"'))
+ res = UrdfBlenderRuntime().build(ws)
+ assert not res.ok and res.error_type == "FkInconsistent"
+ disk = json.loads((ws.artifacts / "build.json").read_text())
+ assert disk["ok"] is False and disk["error_type"] == "FkInconsistent"
+ assert not (ws.artifacts / "object.glb").exists() and not (ws.artifacts / "meshes").exists()
+
+
+def test_lint_fail_invalidates_stale_artifacts(tmp_path, cabinet_plan, fake_blender):
+ ws = _ws(tmp_path, cabinet_plan)
+ rt = UrdfBlenderRuntime()
+ assert rt.build(ws).ok
+ (ws.src / "robot.urdf").write_text("<robot name='x'><link name='a'>")
+ res = rt.build(ws)
+ assert not res.ok and res.error_type == "LintError"
+ assert not (ws.artifacts / "object.glb").exists() and not (ws.artifacts / "meshes").exists()
+ assert json.loads((ws.artifacts / "build.json").read_text())["error_type"] == "LintError"
def test_build_timeout(tmp_path, cabinet_plan, fake_blender, monkeypatch):