Skip to content

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.py
index 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 Path
from typing import Any
from 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 census
census["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_ok
error_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__.py
index 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_noise
from codeverse3d.languages._docs import RuntimeDocs
-from codeverse3d.proc import run_subprocess, tail
+from codeverse3d.proc import run_subprocess
from 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 report
blender = 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 = False
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 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/scene
export+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 at
diff --git a/harness/tests/blender_cadquery/test_blender_multifile.py b/harness/tests/blender_cadquery/test_blender_multifile.py
index 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 line
leg.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 == 17
assert 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 hint
leg.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.py
index 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 annotations
import json
from pathlib import Path
+from codeverse3d.contracts.artifacts import BuildResult
from 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 too
def 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 again
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", "blend": tmp_path / "nope.blend"})
assert r.ok and r.glb_path == str(tmp_path / "o.glb") and r.duration_ms == 42
assert 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.py
index 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(