@genex-ai/cli-demo 1.31.1 → 1.32.0-dev.650

package/templates/blender-service/supervisor.py

@@ -0,0 +1,221 @@
+"""PID 1. Spawns Blender, holds the clock, restarts it when a request overruns.
+
+WHY THIS EXISTS: bpy cannot be interrupted from inside its own process. It is
+not thread-safe, and a watchdog thread that touches bpy produces crashes in
+unrelated drawing code, minutes later, that get blamed on the GPU driver. So a
+runaway `bpy.ops.mesh.subdivide` on a 100M-poly mesh can only be stopped by
+killing the process -- which means the clock has to live outside it.
+
+The deadline is a FILE the server writes per request, not a heartbeat. A
+heartbeat cannot tell a wedged process from a legitimate 15-minute bake; a
+per-route deadline can, because the route names its own budget.
+
+Runs under Blender's bundled Python (there is no system python3 in the image),
+so: stdlib only, and no bpy -- this process must never import it.
+"""
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+
+RUN_DIR = os.environ.get("GENEX_BLENDER_RUN_DIR", "/run/genex")
+DEADLINE = os.path.join(RUN_DIR, "deadline")
+RESTART_REASON = os.path.join(RUN_DIR, "restart-reason")
+BLENDER = os.environ.get("GENEX_BLENDER_BIN", "blender")
+SERVER = os.environ.get("GENEX_BLENDER_SERVER", "/app/server.py")
+POLL_S = 1.0
+# Blender has a documented history of hanging on exit in background mode, so a
+# TERM that is ignored must not become a wedged supervisor.
+TERM_GRACE_S = 5.0
+# A crash loop should be loud and finite, not an infinite restart that burns a
+# GPU pod for hours while every /health probe fails.
+MAX_CONSECUTIVE_FAILURES = 5
+FAST_FAIL_S = 20.0
+
+
+def log(msg):
+    sys.stderr.write("[sup] %s\n" % msg)
+    sys.stderr.flush()
+
+
+# Set by the /destroy path via the sentinel file below, and ONLY there.
+#
+# WHY THIS EXISTS: exit code 0 was being read as "the operator asked to stop".
+# But `/exec` runs arbitrary Python, and `sys.exit()` inside a script exits
+# Blender with code 0 too -- so one session could shut the whole service down
+# by accident, and the supervisor would report success. Intent has to be
+# recorded by the thing that has it, not inferred from a number anyone can
+# produce. With seats this stops being a curiosity and becomes one tenant
+# terminating everyone else's work.
+DESTROY_SENTINEL = os.path.join(RUN_DIR, "destroy-requested")
+
+
+def destroy_requested():
+    return os.path.exists(DESTROY_SENTINEL)
+
+
+def clear_destroy_request():
+    try:
+        os.unlink(DESTROY_SENTINEL)
+    except FileNotFoundError:
+        pass
+
+
+def spawn():
+    os.makedirs(RUN_DIR, exist_ok=True)
+    argv = [
+        BLENDER,
+        "--background",
+        "--factory-startup",
+        "-noaudio",
+        # Measured: without this a raising --python script exits 0 and the
+        # container looks healthy. See the Dockerfile comment.
+        "--python-exit-code",
+        "1",
+        "--python",
+        SERVER,
+    ]
+    extra = os.environ.get("GENEX_BLENDER_ARGS", "").split()
+    if extra:
+        # e.g. --gpu-backend vulkan, kept as one variable so the backend is a
+        # config experiment rather than an image rebuild.
+        argv[1:1] = extra
+    log("spawn: %s" % " ".join(argv))
+    return subprocess.Popen(argv)
+
+
+def clear_deadline():
+    try:
+        os.unlink(DEADLINE)
+    except FileNotFoundError:
+        pass
+
+
+def overrun():
+    """The route whose deadline has passed, or None. Never raises: a partially
+    written file is a race with the server, not a reason to kill Blender."""
+    try:
+        with open(DEADLINE) as f:
+            d = json.load(f)
+    except (FileNotFoundError, ValueError, OSError):
+        return None
+    try:
+        if time.time() > float(d["deadline"]):
+            return d
+    except (KeyError, TypeError, ValueError):
+        return None
+    return None
+
+
+def stop(proc, why):
+    log("killing Blender: %s" % why)
+    try:
+        proc.terminate()
+    except OSError:
+        pass
+    deadline = time.time() + TERM_GRACE_S
+    while time.time() < deadline:
+        if proc.poll() is not None:
+            return
+        time.sleep(0.1)
+    log("SIGTERM ignored, sending SIGKILL")
+    try:
+        proc.kill()
+    except OSError:
+        pass
+    proc.wait()
+
+
+def main():
+    os.makedirs(RUN_DIR, exist_ok=True)
+    clear_deadline()
+    clear_destroy_request()
+    failures = 0
+    stopping = {"v": False}
+
+    def forward(signum, _frame):
+        # Container stop: pass it on and do not restart.
+        stopping["v"] = True
+        log("got signal %s, shutting down" % signum)
+
+    signal.signal(signal.SIGTERM, forward)
+    signal.signal(signal.SIGINT, forward)
+
+    while not stopping["v"]:
+        started = time.time()
+        proc = spawn()
+        killed_for = None
+
+        while True:
+            if stopping["v"]:
+                stop(proc, "supervisor shutting down")
+                return 0
+            code = proc.poll()
+            if code is not None:
+                break
+            hit = overrun()
+            if hit:
+                killed_for = hit
+                stop(proc, "%s exceeded its %ss budget" % (hit.get("route"), hit.get("budget")))
+                clear_deadline()
+                break
+            time.sleep(POLL_S)
+
+        ran_for = time.time() - started
+        code = proc.poll()
+
+        if killed_for is not None:
+            # Tell the next boot that the scene it restores is a recovery, so
+            # the agent is TOLD a step may be missing. A silent restore reads as
+            # the model forgetting what it was just asked to do.
+            with open(RESTART_REASON, "w") as f:
+                json.dump({"route": killed_for.get("route"), "at": time.time(),
+                           "reason": "deadline_exceeded"}, f)
+            # A killed RUNAWAY REQUEST is not a crash loop -- the next boot
+            # restores and carries on. A killed BOOT is: it means the process
+            # cannot come up at all (a hung GPU probe is the measured case), and
+            # without counting it the supervisor would respawn forever on a pod
+            # that bills at full rate and never serves.
+            if killed_for.get("route") == "/boot":
+                failures += 1
+                log("boot exceeded its budget (%d consecutive)" % failures)
+                if failures >= MAX_CONSECUTIVE_FAILURES:
+                    log("FATAL: boot never completed — giving up")
+                    return 1
+            else:
+                failures = 0
+        elif code == 0 and destroy_requested():
+            log("Blender exited 0 after a routed /destroy — done")
+            clear_destroy_request()
+            return 0
+        elif code == 0:
+            # Exit 0 WITHOUT the sentinel: a script called sys.exit(). That is a
+            # crashed session, not a shutdown request -- restart it.
+            failures = failures + 1 if ran_for < FAST_FAIL_S else 1
+            log("Blender exited 0 with no destroy request (a script called "
+                "sys.exit?) after %.1fs — restarting (%d)" % (ran_for, failures))
+            with open(RESTART_REASON, "w") as f:
+                json.dump({"at": time.time(), "reason": "unexpected_clean_exit"}, f)
+            if failures >= MAX_CONSECUTIVE_FAILURES:
+                log("FATAL: %d consecutive fast exits — giving up" % failures)
+                return 1
+        else:
+            failures = failures + 1 if ran_for < FAST_FAIL_S else 1
+            with open(RESTART_REASON, "w") as f:
+                json.dump({"at": time.time(), "reason": "crashed", "exitCode": code}, f)
+            log("Blender exited %s after %.1fs (consecutive fast failures: %d)"
+                % (code, ran_for, failures))
+            if failures >= MAX_CONSECUTIVE_FAILURES:
+                # Exit loudly rather than restarting forever: on a GPU pod an
+                # infinite loop here bills at full rate while nothing works.
+                log("FATAL: %d consecutive fast failures — giving up" % failures)
+                return 1
+        time.sleep(0.5)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/blender-service/views.py

@@ -0,0 +1,281 @@
+"""Deterministic verification renders.
+
+The contact sheet is the whole point of this service: every /exec answers with a
+picture, from FIXED cameras, so an agent never has to remember to look and two
+steps are comparable pixel-for-pixel. Cameras are derived from scene bounds
+only -- never from whatever camera a script happened to leave behind -- because
+a moving camera makes before/after diffs meaningless.
+"""
+
+import os
+import sys
+import tempfile
+
+import bpy
+import numpy as np
+from mathutils import Vector
+
+# One constant, shared with the witness: the engine was renamed in 4.2 and
+# renamed BACK in 5.0, so a literal here would rot on the next LTS.
+try:
+    from gpu_witness import EEVEE_ENGINE
+except Exception:  # noqa: BLE001 - views.py must work without the GPU module
+    EEVEE_ENGINE = "BLENDER_EEVEE_NEXT"
+
+TILE = 512
+
+# MEASURED 2026-09-01 on the real 46-object castle sheet, 1024x1024:
+#
+#            PNG        WebP q80              JPEG q80
+#   solid    451,498    16,542  (27.3x)       40,780  (11.1x)
+#   lit      995,523    12,630  (78.8x)       37,525  (26.5x)
+#   normals  470,629    22,044  (21.3x)       44,835  (10.5x)
+#
+# WebP q80 wins on every mode. JPEG is REJECTED and the numbers say why: on
+# synthetic flat-region content it came out LARGER than PNG (35,102 vs 23,240),
+# because flat regions are what PNG is good at and what JPEG adds noise to.
+#
+# `normals` was checked by eye at q80 -- a matcap colour boundary is exactly
+# what chroma subsampling softens -- and facing directions stay legible, so
+# there is no per-mode format rule.
+SHEET_FORMATS = {"webp": ("WEBP", "image/webp"), "png": ("PNG", "image/png")}
+# MEASURED 2026-09-02, same scene mutated per call so the repeat guard never
+# fired: webp 22,067 B / 3.03 s wall / 1,600 ms server; png 1,437,529 B /
+# 28.02 s wall / 1,367 ms server. The whole 25 s saving is transport -- server
+# time moved by -0.23 s -- and note the sign of that: WebP costs MORE server CPU
+# than PNG. The win is bytes, and only bytes. That run was laptop-driven over a
+# ~54 KB/s link; an API server in a datacenter sees a far smaller absolute
+# saving, which is why the repeat guard beside this, not the codec, is the
+# load-bearing half for the hosted lane.
+SHEET_QUALITY = 80
+# Order is display order, reading left-to-right, top-to-bottom.
+VIEWS = (
+    ("front", Vector((0.0, -1.0, 0.0))),
+    ("side", Vector((1.0, 0.0, 0.0))),
+    ("top", Vector((0.0, 0.0, 1.0))),
+    ("hero", Vector((1.0, -1.0, 0.7))),
+)
+_FOV = 0.7  # radians, ~40 deg
+_MARGIN = 1.18
+
+
+def scene_bounds():
+    """World-space (center, radius) over every evaluated mesh. Never raises."""
+    lo = Vector((1e18, 1e18, 1e18))
+    hi = Vector((-1e18, -1e18, -1e18))
+    found = False
+    for obj in bpy.context.scene.objects:
+        if obj.type not in {"MESH", "CURVE", "SURFACE", "META", "FONT"}:
+            continue
+        # RENDER visibility, not viewport: the sheet is a render, and a hidden
+        # object still framed the shot (review finding).
+        if obj.hide_render or not obj.visible_get():
+            continue
+        for corner in obj.bound_box:
+            p = obj.matrix_world @ Vector(corner)
+            lo = Vector((min(lo[i], p[i]) for i in range(3)))
+            hi = Vector((max(hi[i], p[i]) for i in range(3)))
+            found = True
+    if not found:
+        return Vector((0.0, 0.0, 0.0)), 1.0
+    center = (lo + hi) * 0.5
+    radius = max((hi - lo).length * 0.5, 1e-3)
+    return center, radius
+
+
+class _RenderState:
+    """Save/restore what we touch, so a script's own engine choice survives."""
+
+    _KEYS = (
+        "engine", "resolution_x", "resolution_y", "resolution_percentage", "filepath",
+    )
+
+    def __enter__(self):
+        r = bpy.context.scene.render
+        self._render = {k: getattr(r, k) for k in self._KEYS}
+        self._fmt = r.image_settings.file_format
+        self._camera = bpy.context.scene.camera
+        d = bpy.context.scene.display.shading
+        self._shading = (d.type, d.light, d.color_type, d.studio_light)
+        return self
+
+    def __exit__(self, *exc):
+        r = bpy.context.scene.render
+        for k, v in self._render.items():
+            setattr(r, k, v)
+        r.image_settings.file_format = self._fmt
+        bpy.context.scene.camera = self._camera
+        d = bpy.context.scene.display.shading
+        try:
+            d.type, d.light, d.color_type, d.studio_light = self._shading
+        except Exception:
+            pass  # a studio_light can become invalid if the shading type moved
+        return False
+
+
+def _ensure_preview_light():
+    """EEVEE on a scene with no lights renders BLACK, which reads as a broken
+    GPU rather than an unlit scene. Add a sun + a grey world only when the scene
+    has neither, and hand back an undo so the caller's scene is unchanged."""
+    scene = bpy.context.scene
+    added = []
+    if not any(o.type == "LIGHT" for o in scene.objects):
+        data = bpy.data.lights.new("__genex_preview_sun", type="SUN")
+        data.energy = 3.0
+        obj = bpy.data.objects.new("__genex_preview_sun", data)
+        obj.rotation_euler = (0.9, 0.0, 0.8)
+        scene.collection.objects.link(obj)
+        added.append((obj, data))
+
+    world = scene.world
+    made_world = False
+    if world is None:
+        world = bpy.data.worlds.new("__genex_preview_world")
+        scene.world = world
+        made_world = True
+        world.use_nodes = True
+        world.node_tree.nodes["Background"].inputs[0].default_value = (0.05, 0.05, 0.06, 1)
+
+    def undo():
+        for obj, data in added:
+            bpy.data.objects.remove(obj, do_unlink=True)
+            bpy.data.lights.remove(data)
+        if made_world:
+            scene.world = None
+            bpy.data.worlds.remove(world)
+
+    return undo
+
+
+def _apply_shading(mode):
+    d = bpy.context.scene.display.shading
+    if mode == "wireframe":
+        d.type = "WIREFRAME"
+        d.color_type = "SINGLE"
+    elif mode == "normals":
+        # A matcap that paints +Y green and inverted faces magenta-ish: the
+        # cheapest way to SEE flipped normals, which survive every numeric check.
+        d.type = "SOLID"
+        d.light = "MATCAP"
+        try:
+            d.studio_light = "check_normal+y.exr"
+        except Exception:
+            d.light = "STUDIO"
+    else:
+        d.type = "SOLID"
+        d.light = "STUDIO"
+        d.color_type = "MATERIAL"
+
+
+def _render_view(cam, direction, center, radius, out_path):
+    dist = radius / max(np.sin(_FOV * 0.5), 1e-6) * _MARGIN
+    cam.location = center + direction.normalized() * dist
+    cam.rotation_euler = (center - cam.location).to_track_quat("-Z", "Y").to_euler()
+    cam.data.angle = _FOV
+    cam.data.clip_start = max(dist * 1e-4, 1e-4)
+    cam.data.clip_end = dist * 10.0
+    bpy.context.scene.render.filepath = out_path
+    bpy.ops.render.render(write_still=True)
+
+
+def _load_tile(path):
+    img = bpy.data.images.load(path)
+    try:
+        buf = np.empty(len(img.pixels), dtype=np.float32)
+        img.pixels.foreach_get(buf)
+        return buf.reshape(img.size[1], img.size[0], 4)
+    finally:
+        bpy.data.images.remove(img)
+
+
+def _save_sheet(img, out_path, fmt):
+    """Write the composited sheet. Returns the mime type.
+
+    `quality=` is passed OPTIONALLY rather than gated on a Blender version: the
+    local lane accepts 4.2+ and we can only test what is installed, so a
+    TypeError falls back to the format's default rather than raising in a user's
+    face. A version check would have to be maintained against builds nobody here
+    can run.
+    """
+    blender_fmt, mime = SHEET_FORMATS[fmt]
+    img.filepath_raw = out_path
+    img.file_format = blender_fmt
+    if fmt == "png":
+        img.save()
+        return mime
+    try:
+        img.save(quality=SHEET_QUALITY)
+    except TypeError:
+        sys.stderr.write("[views] Image.save(quality=) unsupported; using the "
+                         "format default\n")
+        img.save()
+    return mime
+
+
+def contact_sheet(out_path, mode="solid", fmt="png"):
+    """Render the 4 fixed views into one 1024x1024 sheet at out_path.
+
+    Returns the MIME TYPE written, not the path — the caller already has the
+    path, and the format is negotiated so it cannot assume one.
+
+    Uses BLENDER_WORKBENCH via render.render(), NOT render.opengl -- the latter
+    is guarded on G.background and cannot run headless. Workbench needs no GL
+    stack, no llvmpipe and no Xvfb; it is the one preview engine that does.
+    """
+    center, radius = scene_bounds()
+    undo_light = None
+    mime = SHEET_FORMATS[fmt][1]
+    with _RenderState():
+        scene = bpy.context.scene
+        if mode == "lit":
+            # The GPU tier's whole point. EEVEE needs a real GPU (Blender's gate
+            # is < 12 SSBO blocks; a software rasterizer either fails or, worse,
+            # passes on a modern Mesa and renders this on the CPU). The GPU
+            # image asserts at boot, so reaching here means a GPU is present.
+            scene.render.engine = EEVEE_ENGINE
+            undo_light = _ensure_preview_light()
+        else:
+            scene.render.engine = "BLENDER_WORKBENCH"
+        scene.render.resolution_x = TILE
+        scene.render.resolution_y = TILE
+        scene.render.resolution_percentage = 100
+        scene.render.image_settings.file_format = "PNG"
+        if mode != "lit":
+            _apply_shading(mode)
+
+        cam_data = bpy.data.cameras.new("__genex_verify_cam")
+        cam = bpy.data.objects.new("__genex_verify_cam", cam_data)
+        scene.collection.objects.link(cam)
+        scene.camera = cam
+
+        tmp = tempfile.mkdtemp(prefix="genex-sheet-")
+        try:
+            # Blender image buffers are BOTTOM-UP, so display row 0 (the top of
+            # the sheet) is the HIGHEST band in the array. Getting this backwards
+            # silently produces a vertically mirrored sheet that still "looks
+            # fine" until you compare it against the game.
+            sheet = np.zeros((TILE * 2, TILE * 2, 4), dtype=np.float32)
+            sheet[..., 3] = 1.0
+            for i, (name, direction) in enumerate(VIEWS):
+                p = os.path.join(tmp, f"{i}_{name}.png")
+                _render_view(cam, direction, center, radius, p)
+                tile = _load_tile(p)
+                disp_row, col = divmod(i, 2)
+                r0 = (1 - disp_row) * TILE
+                sheet[r0:r0 + TILE, col * TILE:(col + 1) * TILE] = tile
+
+            out = bpy.data.images.new("__genex_sheet", TILE * 2, TILE * 2, alpha=True)
+            try:
+                out.pixels.foreach_set(sheet.ravel())
+                mime = _save_sheet(out, out_path, fmt)
+            finally:
+                bpy.data.images.remove(out)
+        finally:
+            bpy.data.objects.remove(cam, do_unlink=True)
+            bpy.data.cameras.remove(cam_data)
+            if undo_light:
+                undo_light()
+            for f in os.listdir(tmp):
+                os.unlink(os.path.join(tmp, f))
+            os.rmdir(tmp)
+    return mime

package/templates/controllers/character/follow-camera.ts

@@ -376,7 +376,22 @@ export class FollowCamera {
       if (this._aimState === "unlocked" && e.pointerType === "mouse" && e.button === 0) {
         this._requestLock();
       }
-      this._domElement.setPointerCapture(e.pointerId);
+      // Capture may be REFUSED, and a refusal must not throw out of the
+      // handler. MEASURED 2026-09-04 across five graded games (`Uncaught
+      // InvalidStateError: Failed to execute 'setPointerCapture'`): the click
+      // above requests pointer lock, and once the lock lands Chromium retires
+      // the pointer, so the capture call on that same pointerdown throws — an
+      // uncaught exception on the first click of every game with this camera,
+      // which failed the eval prober's no-errors check while the drag path
+      // beneath it still worked. Same guard the touch kit uses (drag-zone.ts).
+      if (typeof this._domElement.setPointerCapture === "function") {
+        try {
+          this._domElement.setPointerCapture(e.pointerId);
+        } catch {
+          // the pointer is already gone (pointer lock took it, or it was released
+          // between the event and the call) — the drag works without capture
+        }
+      }
       this._pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
       if (this._pointers.size === 1) {
         this._orbiting = true;

package/templates/controllers/character/meshy/meshy-loader.ts

@@ -23,7 +23,8 @@ export interface MeshyCharacterManifest {
   characterId: string;
   revision: number;
   manifestVersion: number;
-  rig: "meshy-biped";
+  /** `meshy-biped`, or `uthana-biped` for a body imported with `genex character import` (same manifest shape). */
+  rig: "meshy-biped" | "uthana-biped";
   controllerPack?: {
     key: string;
     version: number;
@@ -95,7 +96,7 @@ function validateManifest(value: unknown): MeshyCharacterManifest {
   if (
     !manifest ||
     manifest.schema !== 1 ||
-    manifest.rig !== "meshy-biped" ||
+    (manifest.rig !== "meshy-biped" && manifest.rig !== "uthana-biped") ||
     !manifest.model?.url ||
     !manifest.model.skeletonSignature ||
     !Array.isArray(manifest.clips) ||

package/templates/controllers/quality/deadline.ts

@@ -0,0 +1,117 @@
+// Genex adaptive-quality: BOUNDED loading.
+//
+// WHY THIS EXISTS. Before 2026-09-07 there was no timeout anywhere in the
+// vendored kits — `grep -rn "setTimeout|AbortController|AbortSignal|timeout"`
+// across quality/ and character/ returned NOTHING. Every fallback in
+// `pick-asset.ts` lives inside a `catch`, so it advances on a REJECTION and
+// never on silence: a rung that hangs rather than 404s parks the boot forever,
+// and the player watches a black canvas with no error in the console. The one
+// local Opus run that shipped had to hand-write its own `withDeadline` in
+// `src/main.ts` to get around exactly this, which is the clearest possible
+// signal that the kit owed it.
+//
+// WHAT THIS BOUNDS, HONESTLY. `withDeadline` bounds the WAIT, not the fetch.
+// The abandoned request keeps running in the background until the browser gives
+// up on it; what changes is that the fallback chain ADVANCES instead of
+// stalling, which is the failure being fixed. Real cancellation needs the
+// caller to own the request (`fetchArrayBufferWithDeadline` below is that door,
+// for callers that can hand bytes to `loader.parse`).
+//
+// Zero dependencies and browser-only APIs, because this ships inside a player's
+// game bundle.
+
+/** Thrown when a load outlives its deadline. Distinct so a caller can tell a
+ *  timeout from a genuine 404 — they mean different things about the asset. */
+export class DeadlineError extends Error {
+  readonly label: string;
+  readonly ms: number;
+  constructor(label: string, ms: number) {
+    super(`[genex-quality] ${label} exceeded ${ms}ms`);
+    this.name = "DeadlineError";
+    this.label = label;
+    this.ms = ms;
+  }
+}
+
+/**
+ * Resolve `work`, or reject with `DeadlineError` after `ms`.
+ *
+ * The timer is always cleared, including on the success path: a pending timer
+ * keeps a closure over the promise alive, and twenty of them per boot is a leak
+ * a long session notices.
+ */
+export function withDeadline<T>(work: Promise<T>, ms: number, label: string): Promise<T> {
+  if (!(ms > 0) || !Number.isFinite(ms)) return work;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const bell = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new DeadlineError(label, ms)), ms);
+  });
+  return Promise.race([work, bell]).finally(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  }) as Promise<T>;
+}
+
+/**
+ * A budget shared across a boot, so N slow assets cannot SERIALISE into a wait
+ * no per-attempt deadline would ever catch.
+ *
+ * A per-attempt deadline alone is not enough and the arithmetic is the reason:
+ * twenty props at a 15 s rung deadline is five minutes of black screen, with
+ * every individual attempt inside its limit. `remaining()` is what makes the
+ * ceiling the BOOT's rather than each asset's.
+ *
+ * Never returns a negative, and `expired()` is the honest question to ask
+ * before starting more optional work.
+ */
+export function createBootBudget(totalMs: number, now: () => number = () => Date.now()) {
+  const startedAt = now();
+  return {
+    remaining(): number {
+      return Math.max(0, totalMs - (now() - startedAt));
+    },
+    expired(): boolean {
+      return now() - startedAt >= totalMs;
+    },
+    /** The deadline to give the next attempt: its own cap, clipped to what is
+     *  left of the boot. */
+    slice(attemptMs: number): number {
+      return Math.min(attemptMs, Math.max(0, totalMs - (now() - startedAt)));
+    },
+  };
+}
+
+/**
+ * REAL cancellation, for a caller that can parse bytes itself:
+ *
+ *   const buf = await fetchArrayBufferWithDeadline(url, 15000);
+ *   const gltf = await loader.parseAsync(buf, "");
+ *
+ * Safe for OUR generated rungs specifically, because they embed their textures
+ * — a GLB with external resources would lose its base URL this way, which is
+ * why the loaders do NOT use this by default.
+ */
+export async function fetchArrayBufferWithDeadline(
+  url: string,
+  ms: number,
+  label = url,
+): Promise<ArrayBuffer> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    if (!res.ok) throw new Error(`[genex-quality] ${label} → HTTP ${res.status}`);
+    return await res.arrayBuffer();
+  } catch (err) {
+    // An abort is a deadline, and the caller must be able to tell the two apart.
+    if (err instanceof Error && err.name === "AbortError") throw new DeadlineError(label, ms);
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Per-attempt defaults. A rung is small by construction; the original is the
+ *  archival asset and is allowed to be slower, because reaching it at all means
+ *  every rung already failed. */
+export const RUNG_DEADLINE_MS = 15_000;
+export const ORIGINAL_DEADLINE_MS = 30_000;