Official Codebase of 3DCodeVerse
Python
languages: compose_build_result publishes the final BuildResult as build.json, and urdf_blender reads its wrapper through it
gaoypeng2e7104e5d439
diff --git a/harness/codeverse3d/languages/_common.py b/harness/codeverse3d/languages/_common.pyindex 95de23a3..50ebd538 100644--- a/harness/codeverse3d/languages/_common.py+++ b/harness/codeverse3d/languages/_common.py@@ -5,11 +5,11 @@ harness python). The wrapper writes ``artifacts/build.json`` (+ ``census.json``and the runtime turns those into a :class:`BuildResult`. This module owns:* :func:`compose_build_result` — wrapper json + process outcome → BuildResult,- failing loud when the wrapper did not report;+ failing loud when the wrapper did not report, published as ``build.json``;* :func:`read_json_file` / :func:`strip_blender_noise`.-Wrappers themselves are standalone scripts (they never import ``codeverse3d``;-Blender's bundled python cannot see this package).+Wrappers themselves are standalone scripts in ``languages/wrappers/`` (they never+import ``codeverse3d``; Blender's bundled python cannot see this package)."""from __future__ import annotations@@ -20,7 +20,7 @@ from pathlib import Pathfrom typing import Anyfrom codeverse3d.contracts.artifacts import BuildResult-from codeverse3d.proc import ProcResult, tail+from codeverse3d.proc import ProcResult, tail, write_json_atomic#: The one spelling of every runtime's typed build failures — recorded in build.json /#: record.json / bench cells, so the strings stay as first recorded (2026-08-29: threejs,@@ -81,31 +81,33 @@ def compose_build_result(proc: ProcResult,build_json: Path,census_json: Path,- glb_path: Path,+ glb_path: Path | None,extra_paths: Mapping[str, Path],output_filter: Callable[[str], str] | None = None,) -> BuildResult:- """Merge the wrapper's ``build.json`` with the process outcome.-- Contract: success requires the wrapper to say ``ok`` AND a non-empty GLB on- disk. Timeouts / crashes before ``build.json`` exists become a failed- BuildResult with a typed error (``BUILD_TIMEOUT`` / ``WrapperCrash``) — never- an exception — so the orchestrator can route them to repair.+ """Merge the wrapper's ``build.json`` with the process outcome, and write the result+ over it: ``build.json`` is always the BuildResult, the one status file the tools read.++ Contract: success requires the wrapper to say ``ok`` AND — for a build that has one+ (``glb_path``) — a non-empty GLB on disk. Timeouts / crashes before ``build.json``+ exists become a failed BuildResult with a typed error (``BUILD_TIMEOUT`` /+ ``WrapperCrash``) — never an exception — so the orchestrator can route them to repair.+ The wrapper's own diagnostics (traceback, warnings, exports …) land in+ ``census["build_report"]``."""stdout_tail = tail(output_filter(proc.stdout) if output_filter else proc.stdout)stderr_tail = tail(output_filter(proc.stderr) if output_filter else proc.stderr)base = dict(language=language, stdout_tail=stdout_tail, stderr_tail=stderr_tail, duration_ms=proc.duration_ms)-if proc.timed_out:- return BuildResult(+ res = BuildResult(ok=False,error_type=BUILD_TIMEOUT,error_message=f"build exceeded the time limit ({proc.duration_ms // 1000}s); ""reduce geometry (subdivisions, array counts, boolean ops) so the script finishes quickly",**base,)- if not build_json.is_file():- return BuildResult(+ elif not build_json.is_file():+ res = BuildResult(ok=False,error_type="WrapperCrash",error_message=(@@ -114,7 +116,14 @@ def compose_build_result(),**base,)- data = read_json_file(build_json)+ else:+ res = _merge_report(read_json_file(build_json), census_json, glb_path, extra_paths, base)+ write_json_atomic(build_json, res.model_dump(mode="json"))+ return res+++def _merge_report(data: dict[str, Any], census_json: Path, glb_path: Path | None,+ extra_paths: Mapping[str, Path], base: dict[str, Any]) -> BuildResult:census: dict[str, Any] = {}if census_json.is_file():try:@@ -123,7 +132,7 @@ def compose_build_result(census = {}# keep the wrapper's extra diagnostics (traceback, warnings …) next to the censuscensus["build_report"] = {k: data[k] for k in ("traceback", "error_source", "warnings", "exported", "exec_ms") if k in data}- glb_ok = glb_path.is_file() and glb_path.stat().st_size > 0+ glb_ok = glb_path is None or (glb_path.is_file() and glb_path.stat().st_size > 0)ok = bool(data.get("ok")) and glb_okerror_type = str(data.get("error_type") or "")error_message = str(data.get("error_message") or "")@@ -134,12 +143,12 @@ def compose_build_result(line = data.get("error_line")return BuildResult(ok=ok,- glb_path=str(glb_path) if glb_ok else None,+ glb_path=str(glb_path) if glb_path is not None and glb_ok else None,extra_paths=extras,error_type=error_type,error_message=error_message,error_file=str(data.get("error_file") or ""),error_line=int(line) if isinstance(line, int) else None,census=census,- **{**base, "duration_ms": int(data.get("duration_ms") or proc.duration_ms)},+ **{**base, "duration_ms": int(data.get("duration_ms") or base["duration_ms"])},)diff --git a/harness/codeverse3d/languages/urdf/__init__.py b/harness/codeverse3d/languages/urdf/__init__.pyindex 036899b2..4ba61b05 100644--- a/harness/codeverse3d/languages/urdf/__init__.py+++ b/harness/codeverse3d/languages/urdf/__init__.py@@ -30,9 +30,9 @@ from codeverse3d.languages._ast_lint import (dotted,safe_parse,)-from codeverse3d.languages._common import BUILD_TIMEOUT, ProcResult, read_json_file+from codeverse3d.languages._common import ProcResult, compose_build_result, strip_blender_noisefrom codeverse3d.languages._docs import RuntimeDocs-from codeverse3d.proc import run_subprocess, tail+from codeverse3d.proc import run_subprocessfrom codeverse3d.spatial.joints import (UrdfError,load_urdf,@@ -814,27 +814,21 @@ class UrdfBlenderRuntime(RuntimeDocs):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 (writes build.json / census.json / meshes/ into the staging dir)+ # 2. Blender wrapper (writes build.json / census.json / meshes/ into the staging dir),+ # read like every other wrapper's reportblender = settings.resolve_blender()if not blender:return fail("BlenderNotFound", "no Blender binary (set C3D_BINARIES__BLENDER)", file="", census=census)- 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(BUILD_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))- if not build_json.is_file():- return fail("WrapperCrash", f"wrapper produced no build.json (exit {proc.returncode})", file="src/model.py",- census=census, stdout_tail=tail(proc.stdout), stderr_tail=tail(proc.stderr))- wb = read_json_file(build_json)- wcensus = read_json_file(census_json) if census_json.is_file() else {}- census.update({k: wcensus.get(k) for k in ("objects", "links", "unmatched_objects", "missing_links", "hints") if k in wcensus})- if not wb.get("ok"):- hints = "\n".join(f" hint: {h}" for h in (wcensus.get("hints") or {}).values())- return fail(wb.get("error_type") or "ScriptError", (wb.get("error_message") or "") + ("\n" + hints if hints else ""),- file=wb.get("error_file") or "src/model.py", line=wb.get("error_line"), census=census,- stdout_tail=tail(wb.get("stdout_tail", "") or proc.stdout),- stderr_tail=tail(wb.get("stderr_tail", "") or proc.stderr))+ wrapped = compose_build_result(language=self.language.value, proc=proc, build_json=stage.path("build.json"),+ census_json=stage.path("census.json"), glb_path=None, extra_paths={},+ output_filter=strip_blender_noise)+ census.update(wrapped.census)+ if not wrapped.ok:+ hints = "\n".join(f" hint: {h}" for h in (census.get("hints") or {}).values())+ return fail(wrapped.error_type or "ScriptError", wrapped.error_message + ("\n" + hints if hints else ""),+ file=wrapped.error_file or "src/model.py", line=wrapped.error_line, census=census,+ stdout_tail=wrapped.stdout_tail, stderr_tail=wrapped.stderr_tail)# 3. URDF copy + load (staged files; extra_paths name the canonical homes)urdf_staged = stage.path("robot.urdf")@@ -868,7 +862,8 @@ class UrdfBlenderRuntime(RuntimeDocs):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)+ stdout_tail=wrapped.stdout_tail, stderr_tail=wrapped.stderr_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"]res.ok = Falsediff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex fb484d29..9a4d4727 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -223,9 +223,16 @@ BuildResult.error_type spellings (languages/_common.py): MISSING_ENTRY = "Missin| `GlslShaderRuntime` | `src/shader.frag`, `src/common.glsl`, `src/buffer_a.frag` (+ the harness-owned `src/recipes.glsl` when seeded) | harness owns `#version`/uniforms/`out` (wrap.HEADER: u_time/u_resolution/u_mouse/u_frame/u_prev/u_noise + iTime/iChannel* aliases); `wrap.compose(shader, common, recipes_src=…)` pastes header < recipes < common < shader; build renders judge frames via GlHost; compile errors → GlslCompileError at mapped src file:line (recipes.glsl included); lint ERROR `redefines_recipe` when an agent file defines a recipes.glsl name; artifacts frames/, frames_sheet.png, preview.gif, metrics.json || `OpenGLPythonRuntime` | `src/program.py`, `src/*.glsl` | `setup(ctx,w,h)->state` + `render(ctx,state,t,frame,fbo)` run in a moderngl subprocess (`wrappers/run_gl.py`); exceptions map to src/program.py:line, in-string GLSL errors carry both line numbers |-Wrappers are standalone (never import codeverse3d): `blender/wrappers/run_bpy.py`-(+ sibling `_census.py` — copy both), `cadquery/wrappers/run_cq.py`,-`urdf/wrappers/run_bpy_links.py`, `opengl_python/wrappers/run_gl.py`; threejs/scene+Wrappers are standalone (never import codeverse3d). The three python build wrappers live+together in `languages/wrappers/` — `run_bpy.py`, `run_bpy_links.py` (Blender's python 3.11),+`run_cq.py` — beside the sibling modules they import from their own directory:+`_wrapper_common.py` (stdlib only: rlimit, seeding, running the script with `src/` on+`sys.path`, traceback → `src/<file>:<line>`, `sys.exit(0)` is not a failure, the atomic+report) and `_census.py` (the Blender census, blender AND urdf_blender); copy the directory+whole. Each writes its report as `build.json` + `census.json`, which the runtime reads+once through `_common.compose_build_result` and replaces with the final `BuildResult` — for+EVERY runtime `artifacts/build.json` is the BuildResult (urdf_blender after its post-wrapper+checks). `opengl_python/wrappers/run_gl.py` is the moderngl runner; threejs/sceneexport+render live in `runtime_js/` (`export_glb.mjs`, `render_glb.mjs`,`render_scene.mjs`, `probe_scene.mjs`, `check_shaders.mjs`, `lib/instances.mjs`).**Placement policy (all languages)**: nothing re-centres or drops to ground atdiff --git a/harness/tests/blender_cadquery/test_blender_multifile.py b/harness/tests/blender_cadquery/test_blender_multifile.pyindex 33efcf79..7bb32357 100644--- a/harness/tests/blender_cadquery/test_blender_multifile.py+++ b/harness/tests/blender_cadquery/test_blender_multifile.py@@ -127,8 +127,9 @@ def test_live_multifile_errors_map_to_part_file_and_line(tmp_ws, blender_bin) ->assert not lint.passed and any(f.target == "src/parts/leg.py" and "SyntaxError" in f.message for f in lint.errors)r = rt.build(tmp_ws, timeout_s=120)assert not r.ok and r.error_type == "SyntaxError" and r.error_file == "src/parts/leg.py" and r.error_line == 8- bj = json.loads((tmp_ws.artifacts / "build.json").read_text())- assert (bj["error_file"], bj["error_line"], bj["error_source"]) == ("src/parts/leg.py", 8, "for i in range(LEG_N)")+ bj = json.loads((tmp_ws.artifacts / "build.json").read_text()) # the BuildResult, not the wrapper's report+ assert (bj["error_file"], bj["error_line"]) == ("src/parts/leg.py", 8)+ assert bj["census"]["build_report"]["error_source"] == "for i in range(LEG_N)"# (b) runtime error deep in the part file → that frame, not model.py's import/call lineleg.write_text(LEG.replace(" obj.parent = parent", " obj.parent = parent\n obj.data.materials.append(None).foo"))@@ -136,7 +137,8 @@ def test_live_multifile_errors_map_to_part_file_and_line(tmp_ws, blender_bin) ->assert not r.ok and r.error_type == "AttributeError" and r.error_file == "src/parts/leg.py" and r.error_line == 17assert r.census["build_report"]["error_source"] == "obj.data.materials.append(None).foo"bj = json.loads((tmp_ws.artifacts / "build.json").read_text())- assert bj["error_file"] == "src/parts/leg.py" and bj["error_line"] == 17 and "leg.py" in bj["traceback"]+ assert bj["error_file"] == "src/parts/leg.py" and bj["error_line"] == 17+ assert "leg.py" in bj["census"]["build_report"]["traceback"] and "leg.py" in bj["stderr_tail"]# (c) missing builder → lint error; build reports model.py's import line with a hintleg.write_text(LEG.replace("def build_leg", "def build_legs"))diff --git a/harness/tests/blender_cadquery/test_common.py b/harness/tests/blender_cadquery/test_common.pyindex fc82b066..551cd0ed 100644--- a/harness/tests/blender_cadquery/test_common.py+++ b/harness/tests/blender_cadquery/test_common.py@@ -5,6 +5,7 @@ from __future__ import annotationsimport jsonfrom pathlib import Path+from codeverse3d.contracts.artifacts import BuildResultfrom codeverse3d.languages._common import (ProcResult,compose_build_result,@@ -28,6 +29,7 @@ def test_compose_timeout(tmp_path: Path) -> None:r = compose_build_result(language="blender", proc=_proc(timed_out=True, returncode=-9), build_json=tmp_path / "b.json",census_json=tmp_path / "c.json", glb_path=tmp_path / "o.glb", extra_paths={})assert not r.ok and r.error_type == "BuildTimeout"+ assert json.loads((tmp_path / "b.json").read_text())["error_type"] == "BuildTimeout" # a timeout is published toodef test_compose_wrapper_crash(tmp_path: Path) -> None:@@ -38,18 +40,31 @@ def test_compose_wrapper_crash(tmp_path: Path) -> None:def test_compose_ok_requires_glb(tmp_path: Path) -> None:b = tmp_path / "build.json"- write_json_atomic(b, {"ok": True, "error_type": "", "error_message": "", "duration_ms": 42, "warnings": ["w"]})+ report = {"ok": True, "error_type": "", "error_message": "", "duration_ms": 42, "warnings": ["w"]}+ write_json_atomic(b, report)write_json_atomic(tmp_path / "census.json", {"tri_count": 12})r = compose_build_result(language="blender", proc=_proc(), build_json=b, census_json=tmp_path / "census.json",glb_path=tmp_path / "o.glb", extra_paths={"stl": tmp_path / "o.stl"})assert not r.ok and r.error_type == "ExportEmpty"+ assert BuildResult.model_validate_json(b.read_text()) == r # the one status file: the final result, not the report(tmp_path / "o.glb").write_bytes(b"glTF" + b"\0" * 20)(tmp_path / "o.stl").write_bytes(b"solid")+ write_json_atomic(b, report) # the next build's wrapper reports againr = compose_build_result(language="blender", proc=_proc(), build_json=b, census_json=tmp_path / "census.json",glb_path=tmp_path / "o.glb", extra_paths={"stl": tmp_path / "o.stl", "blend": tmp_path / "nope.blend"})assert r.ok and r.glb_path == str(tmp_path / "o.glb") and r.duration_ms == 42assert r.extra_paths == {"stl": str(tmp_path / "o.stl")}assert r.census["tri_count"] == 12 and r.census["build_report"]["warnings"] == ["w"]+ assert BuildResult.model_validate_json(b.read_text()) == r+++def test_compose_without_a_glb_goes_by_the_report(tmp_path: Path) -> None:+ """The URDF wrapper exports meshes/, not object.glb: its report alone decides."""+ b = tmp_path / "build.json"+ write_json_atomic(b, {"ok": True, "duration_ms": 7})+ r = compose_build_result(language="urdf_blender", proc=_proc(), build_json=b, census_json=tmp_path / "c.json",+ glb_path=None, extra_paths={})+ assert r.ok and r.glb_path is None and r.error_type == ""def test_compose_script_error_fields(tmp_path: Path) -> None:diff --git a/harness/tests/urdf_joints/test_runtime_offline.py b/harness/tests/urdf_joints/test_runtime_offline.pyindex 1c797ba5..6caed13f 100644--- a/harness/tests/urdf_joints/test_runtime_offline.py+++ b/harness/tests/urdf_joints/test_runtime_offline.py@@ -40,8 +40,8 @@ def fake_blender(monkeypatch):box_glb(art / "meshes" / "door.glb", *state["door"])(art / "census.json").write_text(json.dumps({"objects": [], "links": {"body": _census_row(*BODY), "door": _census_row(*state["door"])},"unmatched_objects": [], "missing_links": [], "hints": {}}))- (art / "build.json").write_text(json.dumps({"ok": True, "stdout_tail": "built\n"}))- return ProcResult(returncode=0, stdout="", stderr="", timed_out=False, duration_ms=0)+ (art / "build.json").write_text(json.dumps({"ok": True}))+ return ProcResult(returncode=0, stdout="built\n", stderr="", timed_out=False, duration_ms=0)monkeypatch.setattr(rt_mod, "_run_blender", run)monkeypatch.setattr(rt_mod, "get_settings", lambda: SimpleNamespace(