@hraness/slopcamera 3.2.4

package/apps/desktop/studio/drivers/blender_driver.py

@@ -0,0 +1,466 @@
+"""Fixed SLOPCAMERA Blender adapter. Authored Python is explicitly trusted current-user code.
+
+Python bundles may execute at module scope or define build(context), followed by
+bake(context) for bake jobs. The adapter never infers or silently runs a bake for
+render jobs. Declared .blend snapshots preserve the authored scene and caches.
+"""
+
+import argparse
+import hashlib
+import json
+import math
+import os
+from pathlib import Path
+import runpy
+import sys
+
+
+def read_request(path):
+    with Path(path).open("rb") as stream:
+        data = stream.read(2 * 1024 * 1024 + 1)
+    if len(data) > 2 * 1024 * 1024:
+        raise ValueError("Driver request exceeds its byte bound")
+    request = json.loads(data)
+    for key in ("sourceRoot", "outputRoot", "workingRoot"):
+        root = Path(request[key])
+        if not root.is_absolute() or not root.is_dir() or root.is_symlink() or root.resolve() != root:
+            raise ValueError("Driver roots must be existing absolute physical directories")
+    roots = [Path(request[key]) for key in ("sourceRoot", "outputRoot", "workingRoot")]
+    if any(a == b or a in b.parents or b in a.parents for index, a in enumerate(roots) for b in roots[index + 1:]):
+        raise ValueError("Driver source, output and scratch roots must be disjoint")
+    if any(Path(request["outputRoot"]).iterdir()):
+        raise ValueError("Blender requires a fresh owned output directory")
+    if request["bundle"]["engine"] != "blender" or request["job"]["engine"]["engine"] != "blender":
+        raise ValueError("Blender driver requires a Blender bundle and job")
+    return request
+
+
+def child_path(root, relative):
+    if not isinstance(relative, str) or not relative or "\\" in relative:
+        raise ValueError("Expected a normalized relative artifact path")
+    parts = relative.split("/")
+    if any(part in ("", ".", "..") for part in parts) or Path(relative).is_absolute():
+        raise ValueError("Artifact path escapes its retained root")
+    path = Path(root).joinpath(*parts)
+    if not path.resolve().is_relative_to(Path(root).resolve()):
+        raise ValueError("Artifact path crosses an external symlink")
+    return path
+
+
+def verify_bundle(request):
+    for item in request["bundle"]["files"]:
+        path = child_path(request["sourceRoot"], item["path"])
+        if path.is_symlink() or not path.is_file():
+            raise ValueError("Retained source is not a regular file: " + item["path"])
+        digest = hashlib.sha256()
+        count = 0
+        with path.open("rb") as stream:
+            while data := stream.read(1024 * 1024):
+                digest.update(data)
+                count += len(data)
+        if count != item["bytes"] or digest.hexdigest() != item["sha256"]:
+            raise ValueError("Retained source bytes changed: " + item["path"])
+
+
+def context_for(request):
+    job = request["job"]
+    return json.loads(json.dumps({"parameters": job["parameters"], "stage": job["stage"],
+            "render": job.get("render"), "sourceRoot": request["sourceRoot"],
+            "outputRoot": request["outputRoot"], "workingRoot": request["workingRoot"]}))
+
+
+def spatial_camera_settings(camera, render=None):
+    """Map canonical top-origin calibrated pixels to Blender's horizontal fit.
+
+    Camera-local negative Z and local positive Y are shared. Only world space
+    rotates: canonical (x,y,z) becomes native (x,-z,y). No lens/look inference.
+    """
+    if not isinstance(camera, dict) or set(camera) != {"cameraId", "name", "pose", "projection"}:
+        raise ValueError("Expected an explicit canonical SpatialCamera")
+    pose, projection = camera["pose"], camera["projection"]
+    if not isinstance(pose, dict) or set(pose) != {"position", "rotation"} or not isinstance(projection, dict):
+        raise ValueError("Invalid camera pose or projection")
+
+    def number(value):
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+            raise ValueError("Camera values must be finite numbers")
+        return value
+
+    for field, length in (("position", 3), ("rotation", 4)):
+        values = pose[field]
+        if not isinstance(values, list) or len(values) != length or any(abs(number(v)) > (1000000 if field == "position" else 1) for v in values):
+            raise ValueError("Invalid camera pose vector")
+    if abs(sum(v * v for v in pose["rotation"]) - 1) > 1e-6:
+        raise ValueError("Camera requires a unit XYZW quaternion")
+    kind = projection.get("kind")
+    expected = {"kind", "width", "height", "near", "far"} | ({"fx", "fy", "cx", "cy"} if kind == "perspective" else {"left", "right", "top", "bottom"})
+    if kind not in ("perspective", "orthographic") or set(projection) != expected:
+        raise ValueError("Unsupported calibrated camera projection")
+    for key, value in projection.items():
+        if key != "kind":
+            number(value)
+    w, h = projection["width"], projection["height"]
+    if any(type(v) is not int or not 1 <= v <= 16384 for v in (w, h)) or w * h > 33554432:
+        raise ValueError("Camera image exceeds its bounds")
+    if render and (w != render["width"] or h != render["height"]):
+        raise ValueError("Calibrated camera image dimensions differ from the admitted render job")
+    if not 0.000001 <= projection["near"] < projection["far"] <= 1000000:
+        raise ValueError("Invalid camera clipping interval")
+    settings = {"type": "PERSP" if kind == "perspective" else "ORTHO", "sensor_fit": "HORIZONTAL",
+                "clip_start": projection["near"], "clip_end": projection["far"]}
+    if kind == "perspective":
+        if not 0.000001 <= projection["fx"] <= 1000000 or not 0.000001 <= projection["fy"] <= 1000000:
+            raise ValueError("Invalid camera focal lengths")
+        aspect = projection["fx"] / projection["fy"]
+        settings.update(sensor_width=36.0, lens=projection["fx"] * 36.0 / w,
+                        shift_x=(w / 2 - projection["cx"]) / w,
+                        shift_y=(projection["cy"] - h / 2) * aspect / w)
+    else:
+        span_x, span_y = projection["right"] - projection["left"], projection["top"] - projection["bottom"]
+        if span_x <= 0 or span_y <= 0:
+            raise ValueError("Orthographic camera extents must be positive")
+        aspect = span_y * w / (span_x * h)
+        settings.update(ortho_scale=span_x,
+                        shift_x=(projection["right"] + projection["left"]) / (2 * span_x),
+                        shift_y=(projection["top"] + projection["bottom"]) / (2 * span_x))
+    if not 1 / 200 <= aspect <= 200:
+        raise ValueError("Calibrated pixel aspect exceeds Blender's supported range")
+    return {"camera": settings, "render": {"resolution_x": w, "resolution_y": h, "resolution_percentage": 100,
+            "pixel_aspect_x": max(1.0, 1.0 / aspect), "pixel_aspect_y": max(1.0, aspect)}}
+
+
+def apply_spatial_camera(bpy, camera, camera_object=None, render=None):
+    """Apply one sampled camera, rejecting native clamps instead of changing framing."""
+    from mathutils import Matrix, Quaternion, Vector
+    settings = spatial_camera_settings(camera, render)
+    scene = bpy.context.scene
+    if camera_object is None:
+        data = bpy.data.cameras.new(camera["cameraId"])
+        camera_object = bpy.data.objects.new(camera["cameraId"], data)
+        scene.collection.objects.link(camera_object)
+    if camera_object.type != "CAMERA" or camera_object.parent is not None or len(camera_object.constraints) or camera_object.animation_data or camera_object.data.animation_data:
+        raise ValueError("Camera exchange requires an unconstrained, unparented camera without animation owners")
+    for target, values in ((camera_object.data, settings["camera"]), (scene.render, settings["render"])):
+        for key, value in values.items():
+            setattr(target, key, value)
+            actual = getattr(target, key)
+            if isinstance(value, (int, float)):
+                if not math.isclose(actual, value, rel_tol=2e-6, abs_tol=1e-7):
+                    raise ValueError("Blender cannot represent calibrated camera field " + key)
+            elif actual != value:
+                raise ValueError("Blender changed calibrated camera field " + key)
+    x, y, z, w = camera["pose"]["rotation"]
+    native_from_canonical = Matrix(((1, 0, 0, 0), (0, 0, -1, 0), (0, 1, 0, 0), (0, 0, 0, 1)))
+    camera_object.matrix_world = native_from_canonical @ Matrix.LocRotScale(Vector(camera["pose"]["position"]), Quaternion((w, x, y, z)), Vector((1, 1, 1)))
+    scene.camera = camera_object
+    return camera_object
+
+
+def check_output_budget(request):
+    count, size = 0, 0
+    for parent, directories, files in os.walk(request["outputRoot"], followlinks=False):
+        for name in directories:
+            if (Path(parent) / name).is_symlink():
+                raise ValueError("An output directory became a symlink")
+        for name in files:
+            path = Path(parent) / name
+            if path.is_symlink() or not path.is_file():
+                raise ValueError("An output is not a regular file")
+            count += 1
+            size += path.stat().st_size
+    limits = request["job"]["limits"]
+    if count > limits["maximumOutputFiles"] or size > limits["maximumOutputBytes"]:
+        raise ValueError("Blender exceeded the declared output budget")
+
+
+def configure_scene(bpy, job):
+    scene = bpy.context.scene
+    render = job.get("render")
+    if render:
+        scene.render.resolution_x = render["width"]
+        scene.render.resolution_y = render["height"]
+        scene.render.resolution_percentage = 100
+        numerator = render["frameRate"]["numerator"]
+        denominator = render["frameRate"]["denominator"]
+        # Blender stores integer FPS plus a floating base; retain the exact
+        # rational in result metadata, and use the ratio for scene evaluation.
+        fps = min(32767, max(1, round(numerator / denominator)))
+        scene.render.fps = fps
+        scene.render.fps_base = fps * denominator / numerator
+        scene.frame_start = render["startFrame"]
+        scene.frame_end = render["endFrameExclusive"] - 1
+        scene.frame_step = 1
+    options = job["engine"]
+    scene.render.engine = "CYCLES" if options["renderer"] == "cycles" else "BLENDER_EEVEE"
+    scene.render.film_transparent = options["transparent"]
+    scene.display_settings.display_device = "sRGB"
+    scene.view_settings.view_transform = options["viewTransform"]
+    scene.render.image_settings.color_management = "FOLLOW_SCENE"
+    if options["renderer"] == "cycles":
+        scene.cycles.samples = options["samples"]
+        scene.cycles.use_denoising = options["denoise"]
+        scene.cycles.seed = options["seed"]
+        scene.cycles.use_animated_seed = False
+    elif hasattr(scene, "eevee"):
+        scene.eevee.taa_render_samples = options["samples"]
+    return scene
+
+
+def select_device(bpy, options):
+    if options["renderer"] == "eevee":
+        if options["device"] != "gpu":
+            raise ValueError("EEVEE is a GPU renderer; select device gpu explicitly")
+        import gpu
+        gpu.init()
+        return {"requested": "gpu", "backend": gpu.platform.backend_type_get(),
+                "devices": [{"name": gpu.platform.renderer_get(), "type": "GPU"}],
+                "evidence": "initialized-eevee-gpu-context"}
+    scene = bpy.context.scene
+    preferences = bpy.context.preferences.addons["cycles"].preferences
+    if options["device"] == "cpu":
+        scene.cycles.device = "CPU"
+        for device in preferences.devices:
+            device.use = device.type == "CPU"
+        return {"requested": "cpu", "backend": "CPU", "devices": [],
+                "evidence": "configured-cycles-cpu"}
+    failures = []
+    for backend in ("METAL", "OPTIX", "CUDA", "HIP", "ONEAPI"):
+        try:
+            preferences.compute_device_type = backend
+            preferences.refresh_devices()
+            devices = [device for device in preferences.devices if device.type == backend]
+            if not devices:
+                continue
+            for device in preferences.devices:
+                device.use = device.type == backend
+            scene.cycles.device = "GPU"
+            return {"requested": "gpu", "backend": backend,
+                    "devices": [{"name": d.name, "id": d.id, "type": d.type} for d in devices],
+                    "evidence": "cycles-device-discovery-and-selection"}
+        except (TypeError, RuntimeError, ValueError) as error:
+            failures.append(type(error).__name__)
+    raise RuntimeError("Requested Cycles GPU is unavailable; no CPU fallback was authorized")
+
+
+def output_file(request, output, frame=None):
+    relative = output["pathPattern"].replace("%06d", f"{frame:06d}") if frame is not None else output["path"]
+    path = child_path(request["outputRoot"], relative)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def require_fresh(path):
+    if path.exists() or path.is_symlink():
+        raise ValueError("Refusing to overwrite a preexisting output: " + path.name)
+
+
+def export_models(bpy, request):
+    for output in request["job"]["outputs"]:
+        if output["role"] != "model":
+            continue
+        if output["kind"] != "file":
+            raise ValueError("Model export requires a file output")
+        path = output_file(request, output)
+        require_fresh(path)
+        if output["format"] == "glb":
+            if output["interpretation"].get("sourceSpace") != {"units": "meters", "upAxis": "y", "handedness": "right"}:
+                raise ValueError("Blender GLB export requires meter, right-handed Y-up declaration")
+            bpy.ops.export_scene.gltf(filepath=str(path), export_format="GLB", check_existing=False)
+        elif output["format"] in ("usd", "usda", "usdc"):
+            if output["interpretation"].get("sourceSpace") != {"units": "meters", "upAxis": "z", "handedness": "right"} or bpy.context.scene.unit_settings.scale_length != 1:
+                raise ValueError("Automatic USD export requires meter-scale, right-handed Z-up scene and declaration")
+            bpy.ops.wm.usd_export(filepath=str(path), check_existing=False,
+                                  export_animation=bool(request["job"].get("render")))
+        else:
+            raise ValueError("Blender automatic model export supports GLB and USD only")
+        check_output_budget(request)
+
+
+def render_outputs(bpy, request):
+    job = request["job"]
+    scene = bpy.context.scene
+    render = job["render"]
+    if scene.camera is None:
+        raise ValueError("The authored Blender scene has no active camera")
+    raster_outputs = [output for output in job["outputs"] if output["role"] == "beauty"]
+    if not raster_outputs and not any(output["role"] == "auxiliary" for output in job["outputs"]):
+        return []
+    for output in raster_outputs:
+        if output["format"] not in ("png", "exr") or output["kind"] not in ("file", "sequence"):
+            raise ValueError("Blender beauty output supports PNG/EXR files or sequences; encode video through SLOPCAMERA")
+        if output["kind"] == "file" and render["endFrameExclusive"] - render["startFrame"] != 1:
+            raise ValueError("A beauty file requires a single-frame interval; use a sequence for animation")
+        if output["interpretation"]["kind"] != "raster" or output["interpretation"]["semantic"] != "color":
+            raise ValueError("Automatic beauty outputs require color raster interpretation")
+        interpretation = output["interpretation"]
+        expected_alpha = ("straight" if output["format"] == "png" else "premultiplied") if job["engine"]["transparent"] else "opaque"
+        expected_channels = ["R", "G", "B", "A"] if job["engine"]["transparent"] else ["R", "G", "B"]
+        if interpretation["alpha"] != expected_alpha or interpretation["channels"] != expected_channels or interpretation["unit"] != "unitless":
+            raise ValueError("Beauty interpretation must match the selected encoding's channels and alpha convention")
+    captured = []
+    # Render once per frame; save each declared encoding from the same result.
+    # Compositor-authored auxiliary files remain explicit source-owned outputs.
+    for frame in range(render["startFrame"], render["endFrameExclusive"]):
+        scene.frame_set(frame)
+        bpy.ops.render.render(write_still=False)
+        image = bpy.data.images.get("Render Result")
+        if image is None:
+            raise RuntimeError("Blender did not produce Render Result")
+        for output in raster_outputs:
+            path = output_file(request, output, frame if output["kind"] == "sequence" else None)
+            require_fresh(path)
+            interpretation = output["interpretation"]
+            scene.render.image_settings.file_format = "PNG" if output["format"] == "png" else "OPEN_EXR"
+            scene.render.image_settings.color_mode = "RGBA" if job["engine"]["transparent"] else "RGB"
+            if output["format"] == "png":
+                scene.render.image_settings.color_management = "FOLLOW_SCENE"
+                if interpretation["colorSpace"] != "srgb" or interpretation["dataType"] not in ("uint8", "uint16"):
+                    raise ValueError("PNG beauty requires sRGB uint8 or uint16 interpretation")
+                scene.render.image_settings.color_depth = "16" if interpretation["dataType"] == "uint16" else "8"
+            else:
+                if interpretation["colorSpace"] != "linear-rec709" or interpretation["dataType"] not in ("float16", "float32"):
+                    raise ValueError("EXR beauty requires linear-rec709 float16 or float32 interpretation")
+                scene.render.image_settings.color_depth = "16" if interpretation["dataType"] == "float16" else "32"
+                scene.render.image_settings.exr_codec = "ZIP"
+                scene.render.image_settings.color_management = "OVERRIDE"
+                scene.render.image_settings.linear_colorspace_settings.name = "Linear Rec.709"
+            image.save_render(str(path), scene=scene)
+        check_output_budget(request)
+        captured.append(frame)
+    return captured
+
+
+def scene_summary(bpy):
+    scene = bpy.context.scene
+    objects = []
+    for obj in list(scene.objects)[:512]:
+        item = {"name": obj.name, "type": obj.type,
+                "location": [round(float(x), 7) for x in obj.matrix_world.translation],
+                "modifiers": [modifier.type for modifier in obj.modifiers]}
+        if obj.type == "MESH":
+            item["vertices"] = len(obj.data.vertices)
+            item["polygons"] = len(obj.data.polygons)
+            item["shapeKeys"] = [key.name for key in obj.data.shape_keys.key_blocks] if obj.data.shape_keys else []
+        elif obj.type == "ARMATURE":
+            item["bones"] = [bone.name for bone in obj.data.bones]
+        objects.append(item)
+    return {"objectCount": len(scene.objects), "objects": objects,
+            "activeCamera": scene.camera.name if scene.camera else None,
+            "frameStart": scene.frame_start, "frameEndInclusive": scene.frame_end,
+            "fps": scene.render.fps, "fpsBase": scene.render.fps_base,
+            "viewTransform": scene.view_settings.view_transform,
+            "workingSpace": bpy.data.colorspace.working_space,
+            "linearOutputSpace": "Linear Rec.709",
+            "displayDevice": scene.display_settings.display_device}
+
+
+def validate_blend_images(bpy, request):
+    # Blender can return exit 0 with missing external images and a wrong render.
+    # Native entrypoints therefore require packed image bytes or exact retained
+    # FILE dependencies. Trusted Python authors remain responsible for their
+    # wider, explicitly nonhermetic runtime dependencies.
+    root = Path(request["sourceRoot"])
+    declared = {item["path"] for item in request["bundle"]["files"]}
+    for image in bpy.data.images:
+        if image.source != "FILE" or image.packed_file:
+            continue
+        source = Path(os.path.normpath(bpy.path.abspath(image.filepath, library=image.library)))
+        if not source.is_absolute() or source.is_symlink() or not source.is_file() or source.resolve() != source:
+            raise ValueError("Native scene image requires a physical retained file or packed bytes: " + image.name)
+        if not source.is_relative_to(root) or source.relative_to(root).as_posix() not in declared:
+            raise ValueError("Native scene image is outside its declared source bundle: " + image.name)
+
+
+def run(bpy, request):
+    verify_bundle(request)
+    os.chdir(request["workingRoot"])
+    sys.dont_write_bytecode = True
+    job = request["job"]
+    context = context_for(request)
+    entrypoint = request["bundle"]["entrypoint"]
+    source = child_path(request["sourceRoot"], entrypoint["path"])
+    namespace = {}
+    def apply_declared_camera(camera, camera_object=None):
+        return apply_spatial_camera(bpy, camera, camera_object, job.get("render"))
+    if entrypoint["kind"] == "blend":
+        if job["stage"] != "render":
+            raise ValueError("Native .blend entrypoints support render only")
+        bpy.ops.wm.open_mainfile(filepath=str(source), load_ui=False, use_scripts=False)
+        validate_blend_images(bpy, request)
+    else:
+        configure_scene(bpy, job)
+        sys.path.insert(0, request["sourceRoot"])
+        namespace = runpy.run_path(str(source), init_globals={"SLOPCAMERA_CONTEXT": context,
+            "SLOPCAMERA_APPLY_SPATIAL_CAMERA": apply_declared_camera}, run_name="__slopcamera_studio__")
+        if callable(namespace.get("build")):
+            namespace["build"](context)
+    scene = configure_scene(bpy, job)
+    device = select_device(bpy, job["engine"])
+    native_outputs = [o for o in job["outputs"] if o["role"] == "native-source" and o["format"] == "blend"]
+    native_paths = []
+    bpy.context.preferences.filepaths.save_version = 0
+    for output in native_outputs:
+        if output["kind"] != "file":
+            raise ValueError("Native blend output must be a file")
+        path = output_file(request, output)
+        require_fresh(path)
+        bpy.ops.wm.save_as_mainfile(filepath=str(path), check_existing=False)
+        native_paths.append(path)
+    bake_hook_ran = False
+    if job["stage"] == "bake" and callable(namespace.get("bake")):
+        namespace["bake"](context)
+        bake_hook_ran = True
+        for path in native_paths:
+            bpy.ops.wm.save_as_mainfile(filepath=str(path), check_existing=False)
+    check_output_budget(request)
+    export_models(bpy, request)
+    captured = render_outputs(bpy, request) if job["stage"] == "render" else []
+    verify_bundle(request)
+    result = {"kind": "slopcamera.studio-blender-result", "schemaVersion": 1,
+              "version": bpy.app.version_string, "buildHash": bpy.app.build_hash.decode("ascii"),
+              "stage": job["stage"], "renderer": scene.render.engine, "device": device,
+              "render": job.get("render"), "renderedFrames": captured,
+              "bakeHookRan": bake_hook_ran, "scene": scene_summary(bpy),
+              "trust": "trusted-current-user", "hermetic": False}
+    result_path = Path(request["workingRoot"]) / "result.json"
+    with result_path.open("x", encoding="utf-8") as stream:
+        json.dump(result, stream, indent=2, allow_nan=False)
+        stream.write("\n")
+
+
+def main():
+    import bpy
+    parser = argparse.ArgumentParser()
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--probe", action="store_true")
+    group.add_argument("--request")
+    arguments = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else sys.argv[1:]
+    args = parser.parse_args(arguments)
+    if args.probe:
+        # The factory scene leaves the output-space enum unset until an EXR
+        # override is selected. Verify the adapter's actual supported selection.
+        settings = bpy.context.scene.render.image_settings
+        settings.file_format = "OPEN_EXR"
+        settings.color_management = "OVERRIDE"
+        settings.linear_colorspace_settings.name = "Linear Rec.709"
+        capabilities = ["python-authoring", "blend-authoring", "build", "bake", "render",
+                        "image-sequence", "model-export", "native-cache", "auxiliary-passes"]
+        packages = {"blender": bpy.app.version_string, "python": sys.version.split()[0],
+                    "working-space": bpy.data.colorspace.working_space,
+                    "linear-output-space": bpy.context.scene.render.image_settings.linear_colorspace_settings.name,
+                    "display-device": bpy.context.scene.display_settings.display_device}
+        try:
+            selected = select_device(bpy, {"renderer": "cycles", "device": "gpu"})
+            capabilities.append("gpu-render")
+            packages["cycles-backend"] = selected["backend"]
+            packages["cycles-devices"] = ", ".join(device["name"] for device in selected["devices"])
+        except RuntimeError:
+            packages["cycles-backend"] = "unavailable"
+        print("SLOPCAMERA_STUDIO_PROBE=" + json.dumps({"name": "Blender", "version": bpy.app.version_string,
+                          "packages": packages, "capabilities": capabilities}))
+        return
+    run(bpy, read_request(args.request))
+
+
+if __name__ == "__main__":
+    main()

package/apps/desktop/studio/drivers/cadquery_driver.py

@@ -0,0 +1,176 @@
+"""Fixed SLOPCAMERA CadQuery adapter for explicitly trusted native source bundles."""
+
+import argparse
+import hashlib
+import importlib.metadata
+import json
+import os
+from pathlib import Path
+import runpy
+import sys
+
+
+def child_path(root, relative):
+    if not isinstance(relative, str) or not relative or "\\" in relative:
+        raise ValueError("Expected a normalized relative artifact path")
+    if any(part in ("", ".", "..") for part in relative.split("/")) or Path(relative).is_absolute():
+        raise ValueError("Artifact path escapes its retained root")
+    path = Path(root) / relative
+    if not path.resolve().is_relative_to(Path(root).resolve()):
+        raise ValueError("Artifact path crosses an external symlink")
+    return path
+
+
+def verify_bundle(request):
+    for item in request["bundle"]["files"]:
+        path = child_path(request["sourceRoot"], item["path"])
+        if path.is_symlink() or not path.is_file():
+            raise ValueError("Retained source is not a regular file")
+        digest = hashlib.sha256()
+        count = 0
+        with path.open("rb") as stream:
+            while data := stream.read(1024 * 1024):
+                digest.update(data)
+                count += len(data)
+        if digest.hexdigest() != item["sha256"] or count != item["bytes"]:
+            raise ValueError("Retained source bytes changed: " + item["path"])
+
+
+def shapes_for(cq, value):
+    if isinstance(value, cq.Assembly):
+        return [value.toCompound()]
+    if isinstance(value, cq.Workplane):
+        return [item for item in value.vals() if isinstance(item, cq.Shape)]
+    if isinstance(value, cq.Shape):
+        return [value]
+    raise ValueError("exportVariable must name a CadQuery Workplane, Shape, or Assembly")
+
+
+def export_meter_glb(assembly, path, tolerance, angular_tolerance):
+    # CadQuery 2.8's high-level GLTF writer rotates the assembly but leaves its
+    # millimeter numbers unchanged. Set OCCT's physical units explicitly while
+    # retaining CadQuery's colored assembly conversion and mesh tolerance in mm.
+    from cadquery.occ_impl.assembly import toCAF
+    from OCP.Message import Message_ProgressRange
+    from OCP.RWGltf import RWGltf_CafWriter
+    from OCP.RWMesh import RWMesh_CoordinateSystem_Zup, RWMesh_CoordinateSystem_Yup
+    from OCP.TCollection import TCollection_AsciiString
+    from OCP.TColStd import TColStd_IndexedDataMapOfStringString
+    _, document = toCAF(assembly, True, True, tolerance, angular_tolerance)
+    writer = RWGltf_CafWriter(TCollection_AsciiString(str(path)), True)
+    converter = writer.ChangeCoordinateSystemConverter()
+    converter.SetInputLengthUnit(0.001)
+    converter.SetOutputLengthUnit(1.0)
+    # Let OCCT transform both mesh positions and assembly translations. Rotating
+    # only the root location would leave a translated assembly's origin in Z-up.
+    converter.SetInputCoordinateSystem(RWMesh_CoordinateSystem_Zup)
+    converter.SetOutputCoordinateSystem(RWMesh_CoordinateSystem_Yup)
+    if not writer.Perform(document, TColStd_IndexedDataMapOfStringString(), Message_ProgressRange()):
+        raise RuntimeError("OCCT did not complete the declared meter-scale GLB export")
+
+
+def run(cq, request):
+    for key in ("sourceRoot", "outputRoot", "workingRoot"):
+        root = Path(request[key])
+        if not root.is_absolute() or not root.is_dir() or root.is_symlink() or root.resolve() != root:
+            raise ValueError("Driver roots must be existing absolute physical directories")
+    roots = [Path(request[key]) for key in ("sourceRoot", "outputRoot", "workingRoot")]
+    if any(a == b or a in b.parents or b in a.parents for index, a in enumerate(roots) for b in roots[index + 1:]):
+        raise ValueError("Source, output and scratch roots must be disjoint")
+    if any(Path(request["outputRoot"]).iterdir()):
+        raise ValueError("CadQuery requires a fresh owned output directory")
+    job = request["job"]
+    if request["bundle"]["engine"] != "cadquery" or job["engine"]["engine"] != "cadquery":
+        raise ValueError("CadQuery driver requires a CadQuery bundle and job")
+    if request["bundle"]["entrypoint"]["kind"] != "python":
+        raise ValueError("CadQuery requires a Python entrypoint")
+    verify_bundle(request)
+    context = json.loads(json.dumps({"parameters": job["parameters"], "stage": job["stage"], "render": job.get("render"),
+               "sourceRoot": request["sourceRoot"], "outputRoot": request["outputRoot"],
+               "workingRoot": request["workingRoot"]}))
+    os.chdir(request["workingRoot"])
+    sys.dont_write_bytecode = True
+    source = child_path(request["sourceRoot"], request["bundle"]["entrypoint"]["path"])
+    sys.path.insert(0, request["sourceRoot"])
+    namespace = runpy.run_path(str(source), init_globals={"SLOPCAMERA_CONTEXT": context}, run_name="__slopcamera_studio__")
+    if callable(namespace.get("build")):
+        built = namespace["build"](context)
+        if built is not None:
+            namespace[job["engine"]["exportVariable"]] = built
+    if job["stage"] == "bake" and callable(namespace.get("bake")):
+        namespace["bake"](context)
+    value = namespace.get(job["engine"]["exportVariable"])
+    shapes = shapes_for(cq, value)
+    if not shapes or any(not shape.isValid() for shape in shapes):
+        raise ValueError("CadQuery output is empty or geometrically invalid")
+    options = job["engine"]
+    exported = []
+    for output in job["outputs"]:
+        if output["role"] != "model":
+            continue
+        if output["kind"] != "file" or output["format"] not in ("step", "glb"):
+            raise ValueError("CadQuery automatic export supports STEP and GLB file outputs")
+        path = child_path(request["outputRoot"], output["path"])
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if path.exists() or path.is_symlink():
+            raise ValueError("Refusing to overwrite a preexisting CAD output")
+        if output["format"] == "step":
+            if output["interpretation"].get("sourceSpace") != {"units": "millimeters", "upAxis": "z", "handedness": "right"}:
+                raise ValueError("Automatic CadQuery STEP export requires millimeters, right-handed Z-up declaration")
+            if isinstance(value, cq.Assembly):
+                value.export(str(path), exportType="STEP", mode="default", unit="MM")
+            else:
+                cq.exporters.export(value, str(path), exportType="STEP")
+        else:
+            if output["interpretation"].get("sourceSpace") != {"units": "meters", "upAxis": "y", "handedness": "right"}:
+                raise ValueError("Automatic CadQuery GLB export requires meters, right-handed Y-up declaration")
+            assembly = value if isinstance(value, cq.Assembly) else cq.Assembly(value, name="model")
+            export_meter_glb(assembly, path, options["tolerance"], options["angularTolerance"])
+        exported.append({"id": output["id"], "format": output["format"], "path": output["path"]})
+        observed = [path for path in Path(request["outputRoot"]).rglob("*") if path.is_file()]
+        if any(path.is_symlink() for path in observed) or len(observed) > job["limits"]["maximumOutputFiles"] or sum(path.stat().st_size for path in observed) > job["limits"]["maximumOutputBytes"]:
+            raise ValueError("CadQuery exceeded its declared output budget or produced indirect output")
+    verify_bundle(request)
+    bounds = []
+    for shape in shapes:
+        box = shape.BoundingBox()
+        bounds.append({"minimum": [box.xmin, box.ymin, box.zmin],
+                       "maximum": [box.xmax, box.ymax, box.zmax],
+                       "volume": shape.Volume(), "solids": len(shape.Solids()),
+                       "faces": len(shape.Faces()), "valid": shape.isValid()})
+    result = {"kind": "slopcamera.studio-cadquery-result", "schemaVersion": 1,
+              "version": cq.__version__, "stage": job["stage"], "bounds": bounds,
+              "sourceSpace": {"units": "millimeters", "upAxis": "z", "handedness": "right"},
+              "tessellation": {"tolerance": options["tolerance"], "angularTolerance": options["angularTolerance"]},
+              "exports": exported, "trust": "trusted-current-user", "hermetic": False}
+    with (Path(request["workingRoot"]) / "result.json").open("x", encoding="utf-8") as stream:
+        json.dump(result, stream, indent=2, allow_nan=False)
+        stream.write("\n")
+
+
+def main():
+    import cadquery as cq
+    parser = argparse.ArgumentParser()
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--probe", action="store_true")
+    group.add_argument("--request")
+    args = parser.parse_args()
+    if args.probe:
+        packages = {"cadquery": cq.__version__, "python": sys.version.split()[0]}
+        for name in ("cadquery-ocp", "numpy", "vtk"):
+            try:
+                packages[name] = importlib.metadata.version(name)
+            except importlib.metadata.PackageNotFoundError:
+                pass
+        print("SLOPCAMERA_STUDIO_PROBE=" + json.dumps({"name": "CadQuery", "version": cq.__version__,
+                          "packages": packages, "capabilities": ["python-authoring", "build", "bake", "render", "model-export", "native-cache"]}))
+        return
+    with Path(args.request).open("rb") as stream:
+        data = stream.read(2 * 1024 * 1024 + 1)
+    if len(data) > 2 * 1024 * 1024:
+        raise ValueError("Driver request exceeds its byte bound")
+    run(cq, json.loads(data))
+
+
+if __name__ == "__main__":
+    main()