@trillboards/edge-sdk 0.2.104 → 0.2.107

package/deploy/detector/bench/verify_litert_twin_parity.py

@@ -143,22 +143,44 @@ def main() -> int:
     out_details = interp.get_output_details()
     shape = tuple(int(v) for v in in_detail["shape"])
 
-    # Both runtimes take NCHW here — the LiteRT export of an ultralytics detect
-    # model is NOT NHWC. Transposing "because LiteRT is channels-last" silently
-    # feeds a rotated image and every residual then looks like export noise.
-    if len(shape) != 4 or shape[1] != 3:
-        raise ParityError(f"expected an NCHW [1,3,H,W] input, got {shape}")
-    imgsz = shape[2]
+    # READ THE INPUT LAYOUT OFF THE GRAPH, the same rule this file already applies
+    # to outputs. It used to assert NCHW and refuse anything else, on the reasoning
+    # that "the LiteRT export of an ultralytics detect model is NOT NHWC". That is
+    # true of the toolchain the 21 committed twins were exported with and it is NOT
+    # a property of LiteRT: `onnx2tf` transposes to channels-last by design, and an
+    # export made with ultralytics 8.3.145 declares [1,640,640,3]. The assertion
+    # fired on a real, correct twin (gh_fall_tonlong, 2026-08-26).
+    #
+    # The warning it carried is still right and is why this branches on the DECLARED
+    # shape rather than on a flag: transposing "because LiteRT is channels-last"
+    # feeds a rotated image to a model that wanted NCHW, and every residual then
+    # looks like export noise. Both runtimes must receive the SAME IMAGE, each in
+    # the layout its own graph declares — never the same buffer.
+    if len(shape) != 4:
+        raise ParityError(f"expected a 4-D [1,3,H,W] or [1,H,W,3] input, got {shape}")
+    if shape[1] == 3 and shape[3] != 3:
+        litert_layout, imgsz = "nchw", shape[2]
+    elif shape[3] == 3 and shape[1] != 3:
+        litert_layout, imgsz = "nhwc", shape[1]
+    elif shape[1] == 3 and shape[3] == 3:
+        # [1,3,H,3] is ambiguous and no real detector input is 3 px wide.
+        raise ParityError(f"input {shape} is ambiguous between NCHW and NHWC")
+    else:
+        raise ParityError(f"no channel axis of size 3 in {shape}")
 
     if args.image:
         from PIL import Image
 
         pixels = np.asarray(Image.open(args.image).convert("RGB").resize((imgsz, imgsz)))
-        x = (pixels.astype(np.float32) / 255.0).transpose(2, 0, 1)[None]
+        nchw = (pixels.astype(np.float32) / 255.0).transpose(2, 0, 1)[None]
     else:
-        x = np.random.default_rng(args.seed).random(shape).astype(np.float32)
+        nchw = np.random.default_rng(args.seed).random((1, 3, imgsz, imgsz)).astype(np.float32)
+
+    # ONNX always gets NCHW; LiteRT gets whatever it declared, from the same pixels.
+    x = nchw
+    x_litert = nchw if litert_layout == "nchw" else nchw.transpose(0, 2, 3, 1).copy()
 
-    interp.set_tensor(in_detail["index"], x)
+    interp.set_tensor(in_detail["index"], x_litert)
     interp.invoke()
     litert_out = interp.get_tensor(out_details[0]["index"])
 
@@ -173,11 +195,13 @@ def main() -> int:
     result["reason"] = why
     result["onnx"] = Path(args.onnx).name
     result["litert"] = Path(args.litert).name
+    result["litert_input_layout"] = litert_layout
 
     if args.json:
         print(json.dumps(result, indent=2))
     else:
-        print(f"{'PASS' if ok else 'FAIL'}  {result['onnx']}  layout={layout}  {why}")
+        print(f"{'PASS' if ok else 'FAIL'}  {result['onnx']}  layout={layout}  "
+              f"litert_in={litert_layout}  {why}")
         print(f"  box  x{result['box_scale_applied']:g}: {result['box_residual_px']:.4g} px"
               f"   (unscaled {result['box_residual_unscaled']:.4g})")
         print(f"  cls           : {result['cls_residual']:.4g}")

package/deploy/detector/ram-budget.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * The detector's RAM ceiling, DERIVED FROM THIS BOX — run by the installer, for
+ * the supervisor to write down.
+ *
+ * ── Why this file exists ────────────────────────────────────────────────────
+ *
+ * `registry.py::_admit` refuses to make any non-pinned model resident unless a
+ * ceiling was injected, and says so out loud:
+ *
+ *     cannot admit ['gh_forklift_combine'] — no RAM ceiling was injected, so this
+ *     service has no basis for a portfolio decision and will not invent one.
+ *
+ * That refusal is correct. What was missing is the other half of it:
+ * `TRILLBOARDS_DETECTOR_RAM_BUDGET_MB` appeared in the detector's source, its
+ * README, its tests and its CHANGELOG, and in ZERO of the six supervisor
+ * definitions — three plists, three units, three Windows scripts. So on every
+ * fielded box the ceiling was absent, and every delivered specialist stayed
+ * permanently `idle` while `/detect` answered 503. Measured on a live GCE
+ * connector on 2026-08-26.
+ *
+ * ── Why the number is derived and not a constant ────────────────────────────
+ *
+ * `docs/runbooks/sensing-model-library.md` §2 is the arithmetic: the binding
+ * field box is a Ryzen 5 7640HS with a measured 9.8 GB carrying 6 of the 9
+ * spec-reporting screens, and Gemma's working set alone is 3.31 GB. **The SUM
+ * has to fit, not each member** — a selector that approves each model
+ * independently approves a set that OOM-kills the box, and the failure then
+ * looks like a camera problem. A hardcoded 4096 is wrong on that box and wrong
+ * again on the 31.4 GB Core Ultra 9 285H beside it in the same table.
+ *
+ * ── Why HERE and not in the service ─────────────────────────────────────────
+ *
+ * `registry.py`'s header settles it: a ceiling chosen by the detector would be a
+ * SECOND allocation authority that cannot see the first. So the service still
+ * has no default and still refuses; this runs at INSTALL time, in the
+ * installer, and the supervisor records the answer in its own definition where
+ * an operator can read it and override it.
+ *
+ * It also could not honestly live in the Python package: every quantity it
+ * subtracts is a CONNECTOR cost — Gemma's working set, the connector process,
+ * one ffmpeg per feed — and the detector knows none of them. It sits in
+ * `deploy/detector/` because that is the one directory all three installers
+ * already resolve a path to (`find_detector_source` / `Resolve-DetectorSource`),
+ * so no packaging step had to change on any platform. It is NOT part of the
+ * Python distribution: `pyproject.toml` declares
+ * `packages = ["trillboards_detector"]`, so the wheel never sees this file.
+ *
+ * ── Node, and only Node built-ins ───────────────────────────────────────────
+ *
+ * ONE implementation for three supervisors. A bash twin and a PowerShell twin
+ * would be two more places for the arithmetic to drift, and `os.totalmem()` is
+ * the same probe on all three. Node is present wherever this runs: `install.sh`
+ * requires >= 18 before anything else, the macOS pkg bundles `$ROOT/bin/node`
+ * and the Windows payload bundles `bin\node.exe`.
+ *
+ * ── Contract ────────────────────────────────────────────────────────────────
+ *
+ *   stdout   the ceiling, as a bare integer number of MiB. Nothing else, so a
+ *            caller can `$(node ram-budget.js)` it.
+ *   stderr   with --explain, the whole subtraction, so an operator reading a
+ *            setup log can see WHY the number is what it is.
+ *   exit 0   derived. exit 1: could not read this box's memory — the caller
+ *            then injects NOTHING, which leaves the service in its existing,
+ *            honest refusing state rather than acting on a guess.
+ *
+ * `--assume-total-mb` / `--assume-platform` exist for the fixture matrix in
+ * `src/__tests__/detectorRamBudget.test.ts` and for reproducing a field box's
+ * number on a laptop. An INSTALLER must never pass them: a number an installer
+ * supplied is not a number derived from the box.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CONTRACT_PATH = path.join(__dirname, 'ram-budget.json');
+const BYTES_PER_MIB = 1024 * 1024;
+
+/** Read the committed inputs. Keys prefixed `_` are prose and are ignored. */
+function loadContract(contractPath) {
+  const raw = fs.readFileSync(contractPath || CONTRACT_PATH, 'utf8');
+  const parsed = JSON.parse(raw);
+  for (const key of ['pinnedModelMb', 'localVlmWorkingSetMb', 'connectorProcessMb', 'captureMb']) {
+    if (!Number.isFinite(parsed[key]) || parsed[key] <= 0) {
+      throw new Error(`ram-budget.json: ${key} must be a positive number, got ${parsed[key]}`);
+    }
+  }
+  if (!parsed.operatingSystemMb || !Number.isFinite(parsed.operatingSystemMb.default)) {
+    throw new Error('ram-budget.json: operatingSystemMb.default must be a positive number');
+  }
+  return parsed;
+}
+
+/**
+ * The ceiling, in MiB, and the subtraction that produced it.
+ *
+ * FLOORED AT THE PINNED MODEL, never below. `ModelRegistry.__init__` RAISES on a
+ * budget it cannot hold the pinned model in — "the service would be permanently
+ * unavailable rather than merely constrained" — and every supervisor restarts a
+ * non-zero exit, so a ceiling of 200 MiB on a tiny box would be a crash-loop
+ * rather than a constraint. At the floor the service still starts, still holds
+ * the model it was told to hold, and refuses each specialist with a CAPACITY
+ * reason naming what did not fit, which is the truthful thing to say about a box
+ * that has no room.
+ */
+function deriveRamBudgetMb(opts) {
+  const contract = opts.contract;
+  const totalMb = opts.totalMb;
+  const platform = opts.platform;
+
+  const osMb = Number.isFinite(contract.operatingSystemMb[platform])
+    ? contract.operatingSystemMb[platform]
+    : contract.operatingSystemMb.default;
+
+  const reserved = osMb
+    + contract.connectorProcessMb
+    + contract.localVlmWorkingSetMb
+    + contract.captureMb;
+
+  const available = totalMb - reserved;
+  const floored = available < contract.pinnedModelMb;
+  const budgetMb = floored ? contract.pinnedModelMb : Math.floor(available);
+
+  return {
+    budgetMb,
+    totalMb,
+    platform,
+    osMb,
+    osKeyed: Number.isFinite(contract.operatingSystemMb[platform]),
+    connectorProcessMb: contract.connectorProcessMb,
+    localVlmWorkingSetMb: contract.localVlmWorkingSetMb,
+    captureMb: contract.captureMb,
+    pinnedModelMb: contract.pinnedModelMb,
+    reserved,
+    available,
+    floored,
+  };
+}
+
+/** `os.totalmem()` in whole MiB, or null when it reported nothing usable. */
+function readTotalMemoryMb(totalmem) {
+  let bytes;
+  try {
+    bytes = (totalmem || os.totalmem)();
+  } catch {
+    return null;
+  }
+  if (!Number.isFinite(bytes) || bytes <= 0) return null;
+  return Math.floor(bytes / BYTES_PER_MIB);
+}
+
+function explain(d) {
+  const floorNote = d.floored
+    ? `\n  FLOORED at the pinned model (${d.pinnedModelMb} MiB): this box has `
+      + `${d.available} MiB left after the reservations, which cannot hold a second model. `
+      + 'The detector still starts and still holds its pinned model; every specialist is '
+      + 'refused with a capacity reason.'
+    : '';
+  const osNote = d.osKeyed ? d.platform : `${d.platform} -> default (unrecognised platform)`;
+  return `detector RAM ceiling ${d.budgetMb} MiB`
+    + `\n  ${d.totalMb} MiB total on this box`
+    + `\n  - ${d.osMb} MiB operating system (${osNote})`
+    + `\n  - ${d.connectorProcessMb} MiB connector process`
+    + `\n  - ${d.localVlmWorkingSetMb} MiB on-device VLM working set`
+    + `\n  - ${d.captureMb} MiB capture (one persistent ffmpeg per feed, at the 16-session ceiling)`
+    + `\n  = ${d.available} MiB for every resident detector session TOGETHER`
+    + floorNote;
+}
+
+function parseArgs(argv) {
+  const opts = { explain: false, totalMb: null, platform: null };
+  for (const arg of argv) {
+    if (arg === '--explain') opts.explain = true;
+    else if (arg.startsWith('--assume-total-mb=')) opts.totalMb = Number(arg.split('=')[1]);
+    else if (arg.startsWith('--assume-platform=')) opts.platform = arg.split('=')[1];
+    else throw new Error(`unknown argument ${arg}`);
+  }
+  return opts;
+}
+
+function main(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    return 1;
+  }
+
+  const totalMb = opts.totalMb !== null ? Math.floor(opts.totalMb) : readTotalMemoryMb();
+  if (!Number.isFinite(totalMb) || totalMb <= 0) {
+    // NOTHING IS INJECTED, and that is the designed outcome rather than a
+    // fallback. An absent ceiling is a STATE the service already handles
+    // correctly and loudly; a made-up one is a portfolio decision nobody made.
+    process.stderr.write(
+      'could not read this box\'s total memory, so no RAM ceiling is derived. '
+      + 'The detector will start, hold its pinned model, and refuse to make a second '
+      + 'model resident — naming why.\n',
+    );
+    return 1;
+  }
+
+  let derived;
+  try {
+    derived = deriveRamBudgetMb({
+      contract: loadContract(),
+      totalMb,
+      platform: opts.platform || process.platform,
+    });
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    return 1;
+  }
+
+  if (opts.explain) process.stderr.write(`${explain(derived)}\n`);
+  process.stdout.write(`${derived.budgetMb}\n`);
+  return 0;
+}
+
+module.exports = { loadContract, deriveRamBudgetMb, readTotalMemoryMb, explain, main, CONTRACT_PATH };
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));

package/deploy/detector/ram-budget.json

@@ -0,0 +1,76 @@
+{
+  "_comment": [
+    "Inputs to the detector's RAM ceiling. ONE file, read by the one derivation",
+    "(ram-budget.js) that all three installers run, so a number can never mean two",
+    "things on two platforms.",
+    "",
+    "Every entry carries its own basis, and the basis says whether it is a",
+    "MEASUREMENT or a POLICY. That distinction is the whole point of writing them",
+    "down separately: a measurement is re-derived when the thing is re-measured, a",
+    "policy is argued about. Collapsing them into one 'reserve' number is how a",
+    "guess acquires the authority of a measurement."
+  ],
+
+  "pinnedModelMb": 632,
+  "_pinnedModelMb": [
+    "MEASURED. RF-DETR Medium's peak RSS — docs/runbooks/cctv-detector-tier.md §6,",
+    "and the same figure `labels.py` commits as RFDETR_MEDIUM.approx_ram_bytes.",
+    "It is the FLOOR of the derived ceiling, not a reservation: ModelRegistry",
+    "REFUSES to construct with a budget below the pinned model's footprint",
+    "(`the service would be permanently unavailable rather than merely",
+    "constrained`), so a ceiling under this would crash-loop the service on a",
+    "small box instead of merely denying it specialists. tests/test_ram_budget.py",
+    "pins this to labels.py so the two cannot drift."
+  ],
+
+  "localVlmWorkingSetMb": 3390,
+  "_localVlmWorkingSetMb": [
+    "MEASURED. Gemma's working set on the SHIPPED GPU-vision path —",
+    "docs/runbooks/cctv-local-inference-hardware-floor.md §3, re-measured",
+    "2026-08-19 at 3.31 GB (2.7 GB on the retired stock config; the GPU vision",
+    "encoder costs ~0.6 GB). The 4.3 GB .litertlm bundle is memory-MAPPED and is",
+    "deliberately not reserved here — what binds is the working set.",
+    "3.31 read as GiB, which is the larger of the two readings of that unit and",
+    "therefore the safe one: over-reserving costs a specialist slot, under-",
+    "reserving OOM-kills a box and looks like a camera fault."
+  ],
+
+  "connectorProcessMb": 2048,
+  "_connectorProcessMb": [
+    "DECLARED, not measured — and it is our own declaration, which is why it is",
+    "usable: trillboards-edge.service sets MemoryMax=2G, so on Linux this is not",
+    "an estimate of the connector, it is the cgroup ceiling the kernel enforces on",
+    "it. macOS and Windows run the same program with no such cap, so the same",
+    "number carries as the best statement we have about it."
+  ],
+
+  "captureMb": 384,
+  "_captureMb": [
+    "MEASURED. RTSPStreamCameraProvider holds one long-lived ffmpeg per feed into",
+    "a bounded ring; docs/runbooks/sensing-catch-rate.md §2b measured that at",
+    "+366 MB RSS at 16 feeds. 16 is the learned per-recorder session ceiling, so",
+    "this reserves the whole capture lane at its widest rather than per feed —",
+    "the feed count is not known at install time, and a per-feed reservation",
+    "would have to be revised every time an operator adds a camera."
+  ],
+
+  "operatingSystemMb": {
+    "linux": 1024,
+    "darwin": 3072,
+    "win32": 2048,
+    "default": 3072
+  },
+  "_operatingSystemMb": [
+    "POLICY, NOT MEASUREMENT, and it must not be read as one. There is no fleet",
+    "measurement of idle OS footprint anywhere in this tree; these are floors",
+    "chosen to be comfortably above what each platform idles at, because the",
+    "consequence of under-reserving here is the OOM killer choosing which of our",
+    "processes dies. `default` takes the largest value, so an unrecognised",
+    "platform fails conservative rather than optimistic.",
+    "linux 1024: the connector's Linux SKU is a headless mini-PC; a Debian/Ubuntu",
+    "  server idles well under 512 MB, and this is roughly twice that.",
+    "win32 2048: Windows 11 idles at roughly 2-3 GB of working set.",
+    "darwin 3072: macOS holds a large (compressed) working set even idle; on the",
+    "  16 GB Mac mini M4 that is the recommended SKU this is ~19% of the box."
+  ]
+}

package/deploy/detector/tests/test_ram_budget.py

@@ -0,0 +1,124 @@
+"""The supervisor's ceiling and this service's floor are ONE number.
+
+`ram-budget.json` is read by the installer, not by this package — the ceiling is
+INJECTED and this service owns no RAM policy (`registry.py`'s header). But the
+supervisor's derivation floors its answer at the pinned model's footprint, and
+that floor is only correct if it is EXACTLY the boundary `ModelRegistry` refuses
+below. One MiB either way and the two artifacts disagree in one of two ways:
+
+  * floor too LOW  -> `ModelRegistry.__init__` raises on a small box, the process
+    exits non-zero, and all three supervisors restart it. A crash-loop instead of
+    a constraint, on exactly the boxes least able to report it.
+  * floor too HIGH -> the derivation quietly hands small boxes more than they
+    have, which is the OOM this whole portfolio design exists to prevent.
+
+So the JSON is pinned to `labels.py` here, in the package that owns the number,
+rather than restated in the JS that reads it.
+
+Stdlib only, like every other suite in this directory.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from trillboards_detector.labels import RFDETR_MEDIUM, ModelVocabulary
+from trillboards_detector.registry import ModelEntry, ModelRegistry
+
+MB = 1024 * 1024
+CONTRACT_PATH = Path(__file__).resolve().parent.parent / "ram-budget.json"
+
+
+def _contract() -> dict:
+    return json.loads(CONTRACT_PATH.read_text())
+
+
+class TestTheFloorIsThePinnedModel(unittest.TestCase):
+    def test_the_contract_ships_next_to_the_package(self):
+        # All three installers resolve the detector SOURCE directory and read the
+        # derivation out of it, so the file has to be here and not somewhere a
+        # packaging step would have to be taught about.
+        self.assertTrue(CONTRACT_PATH.is_file(), f"{CONTRACT_PATH} is missing")
+
+    def test_pinned_model_mb_is_exactly_the_pinned_vocabulary_footprint(self):
+        self.assertEqual(
+            _contract()["pinnedModelMb"] * MB,
+            RFDETR_MEDIUM.approx_ram_bytes,
+            "ram-budget.json's floor and RFDETR_MEDIUM.approx_ram_bytes are the same "
+            "quantity; a supervisor flooring below it crash-loops this service",
+        )
+
+    def test_every_reservation_is_a_positive_number_of_mib(self):
+        contract = _contract()
+        for key in (
+            "pinnedModelMb",
+            "localVlmWorkingSetMb",
+            "connectorProcessMb",
+            "captureMb",
+        ):
+            self.assertIsInstance(contract[key], int, key)
+            self.assertGreater(contract[key], 0, key)
+        os_mb = contract["operatingSystemMb"]
+        self.assertIn("default", os_mb)
+        for platform, value in os_mb.items():
+            self.assertIsInstance(value, int, platform)
+            self.assertGreater(value, 0, platform)
+        # An unrecognised platform must be treated at least as expensively as
+        # every recognised one — failing conservative is the only safe direction
+        # when the consequence is the OOM killer picking a victim.
+        self.assertEqual(
+            os_mb["default"],
+            max(v for k, v in os_mb.items() if k != "default"),
+        )
+
+
+class TestTheFloorIsCONSTRUCTIBLE(unittest.TestCase):
+    """The boundary, exercised against the real registry rather than asserted.
+
+    `ModelRegistry.__init__` refuses a ceiling below the pinned model's footprint
+    — "the service would be permanently unavailable rather than merely
+    constrained". These two cases are the MiB either side of the floor the
+    supervisor derives.
+    """
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self._tmp.name)
+        self.addCleanup(self._tmp.cleanup)
+        self.pinned = ModelVocabulary(
+            model_name=RFDETR_MEDIUM.model_name,
+            slot_names=dict(RFDETR_MEDIUM.slot_names),
+            logit_slots=RFDETR_MEDIUM.logit_slots,
+            approx_ram_bytes=RFDETR_MEDIUM.approx_ram_bytes,
+            onnx_variant=RFDETR_MEDIUM.onnx_variant,
+        )
+
+    def _registry(self, budget_bytes: int) -> ModelRegistry:
+        entry = ModelEntry(
+            self.pinned,
+            self.root / "models" / self.pinned.model_name / "model.onnx",
+            pinned=True,
+        )
+        return ModelRegistry(
+            entries=[entry],
+            session_factory=lambda _e: object(),
+            probe=lambda _s: None,
+            ram_budget_bytes=budget_bytes,
+            log=lambda _m: None,
+        )
+
+    def test_the_derived_floor_constructs(self):
+        floor_mb = _contract()["pinnedModelMb"]
+        self.assertIsNotNone(self._registry(floor_mb * MB))
+
+    def test_one_mib_below_the_floor_refuses(self):
+        floor_mb = _contract()["pinnedModelMb"]
+        with self.assertRaises(ValueError):
+            self._registry((floor_mb - 1) * MB)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/deploy/detector/trillboards_detector/labels.py

@@ -523,7 +523,28 @@ PPE_KILLUMINATI_19CLS_V8S = ModelVocabulary(
 #: this artifact as the fixture that exercises `_verify_class_axis_width`, where
 #: `4 + 7 = 11` matches its real `[1, 11, 8400]` head and `4 + 6 = 10` would
 #: reject it.
-BUILTIN_VOCABULARIES: "tuple[ModelVocabulary, ...]" = (RFDETR_MEDIUM, GH_FORKLIFT_COMBINE, PPE_VYRA_14CLS_V8M, PPE_CONSTRUCTION_17CLS_V8N, PPE_KILLUMINATI_19CLS_V8S,)
+#: Person Down Detector — published 2026-08-27 by
+#: scripts/sensing/publish-sensing-model.js. The class list is the artifact's own
+#: (graph metadata key 'names'); the footprint is MEASURED, 817.3594 MiB after a
+#: probe inference via rusage-maxrss, not an estimate from the file size.
+#: Coordinate space MEASURED, not assumed: max|box channel| = 1.5467 over 94 real frames; / imgsz 640 = 0.0024. pixels at >= 0.2, normalized at <= 0.02, refused in between.
+FALL_1CLS_11X_CLASS_NAMES: "MappingProxyType[int, str]" = MappingProxyType({
+    0: "fall detected",
+})
+
+FALL_1CLS_11X = ModelVocabulary(
+    model_name="fall_1cls_11x",
+    slot_names=FALL_1CLS_11X_CLASS_NAMES,
+    logit_slots=1,
+    approx_ram_bytes=857063451,
+    onnx_variant=VariantContract(
+        output_layout="anchor_4_plus_nc",
+        box_units="normalized",
+        box_scale_to_pixels=640.0,
+    ),
+)
+
+BUILTIN_VOCABULARIES: "tuple[ModelVocabulary, ...]" = (RFDETR_MEDIUM, GH_FORKLIFT_COMBINE, PPE_VYRA_14CLS_V8M, PPE_CONSTRUCTION_17CLS_V8N, PPE_KILLUMINATI_19CLS_V8S, FALL_1CLS_11X,)
 
 
 class ClassIndex:
@@ -617,6 +638,7 @@ class ClassIndex:
 
 
 __all__ = [
+    "FALL_1CLS_11X",
     "PPE_KILLUMINATI_19CLS_V8S",
     "PPE_CONSTRUCTION_17CLS_V8N",
     "PPE_VYRA_14CLS_V8M",

package/deploy/macos/com.trillboards.detector.plist

@@ -12,9 +12,19 @@
   here. Port 9380; litert-lm owns 9379 and is not touched.
 
   This is a TEMPLATE: setup-detector.sh substitutes __DETECTOR__ (absolute path
-  to the uv-installed `trillboards-detector` binary) / __PORT__ / __LOG_DIR__ and
-  writes the result to ~/Library/LaunchAgents/com.trillboards.detector.plist,
-  then loads it via `launchctl bootstrap gui/$UID`.
+  to the uv-installed `trillboards-detector` binary) / __PORT__ / __LOG_DIR__ /
+  __RAM_BUDGET_ARGS__ and writes the result to
+  ~/Library/LaunchAgents/com.trillboards.detector.plist, then loads it via
+  `launchctl bootstrap gui/$UID`.
+
+  __RAM_BUDGET_ARGS__ becomes either the two <string> elements of
+  `--ram-budget-mb <N>` or NOTHING AT ALL, and the emptiness is meaningful: the
+  detector distinguishes "the supervisor told me a ceiling" from "nobody has
+  told me one", and refuses to invent one in the second state
+  (`registry.py::_admit`). A placeholder value here would be this file quietly
+  becoming a second allocation authority. The number is derived from THIS
+  machine by deploy/detector/ram-budget.js — see its header for why a constant
+  is wrong on both of the two field boxes we have measured.
 
   KeepAlive=true + ThrottleInterval=30 exactly as com.trillboards.litertlm.plist.
   ThrottleInterval is load-bearing here for a specific reason: the model is OTA'd,
@@ -35,6 +45,7 @@
     <string>127.0.0.1</string>
     <string>--port</string>
     <string>__PORT__</string>
+    __RAM_BUDGET_ARGS__
   </array>
 
   <key>RunAtLoad</key>

package/deploy/macos/scripts/setup-detector.sh

@@ -135,6 +135,39 @@ if [ ! -x "$DETECTOR" ]; then
 fi
 log "trillboards-detector installed at $DETECTOR"
 
+# 2b. THE RAM CEILING, derived from THIS Mac.
+#
+# Without it the service holds its pinned model and refuses to make any second
+# model resident — `registry.py::_admit` says so in the 503 — so every delivered
+# specialist stays permanently `idle`. The refusal is correct; the injection was
+# missing from all six supervisor definitions until 2026-08-26.
+#
+# A COMMAND-LINE ARGUMENT here, not an environment variable, because this
+# supervisor definition is GENERATED by this script — same for the Windows
+# Scheduled Task. Only Linux, whose unit is a static file, uses the env var.
+# One derivation (deploy/detector/ram-budget.js), three transports.
+#
+# EMPTY WHEN IT CANNOT BE DERIVED, never a placeholder: "nobody has told me a
+# ceiling" is a state the detector handles correctly and loudly, and a number
+# invented here would be a second allocation authority.
+RAM_BUDGET_ARGS=""
+NODE_BIN="$SCRIPT_DIR/../bin/node"
+[ -x "$NODE_BIN" ] || NODE_BIN="$(command -v node || true)"
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  log "WARN: no node runtime found, so no RAM ceiling is derived; the detector will refuse a second resident model"
+elif [ ! -f "$SOURCE/ram-budget.js" ]; then
+  log "WARN: $SOURCE/ram-budget.js is missing, so no RAM ceiling is derived"
+else
+  _budget="$("$NODE_BIN" "$SOURCE/ram-budget.js" --explain 2>>"$LOG")" || _budget=""
+  case "$_budget" in
+    ''|*[!0-9]*) log "WARN: could not derive a RAM ceiling for this Mac (see $LOG); the detector will refuse a second resident model" ;;
+    *)
+      RAM_BUDGET_ARGS="<string>--ram-budget-mb</string><string>$_budget</string>"
+      log "RAM ceiling $_budget MiB (derived from this Mac; see the log above for the subtraction)"
+      ;;
+  esac
+fi
+
 # 3. Render + bootstrap the LaunchAgent.
 TEMPLATE="$SHARE_DIR/$SERVE_LABEL.plist"
 TARGET="$LA_DIR/$SERVE_LABEL.plist"
@@ -146,6 +179,7 @@ fi
 sed -e "s#__DETECTOR__#$DETECTOR#g" \
     -e "s#__PORT__#$SERVE_PORT#g" \
     -e "s#__LOG_DIR__#$LOG_DIR#g" \
+    -e "s#__RAM_BUDGET_ARGS__#$RAM_BUDGET_ARGS#g" \
     "$TEMPLATE" > "$TARGET" 2>/dev/null || { log "WARN: could not render the detector plist"; exit 0; }
 
 SERVICE_DOMAIN="gui/$(id -u)"

package/deploy/systemd/install.sh

@@ -157,7 +157,20 @@ sudo -u trillboards HOME=/opt/trillboards bash \
 # starting left a fresh Linux box with no detector until its next reboot, with
 # the installer reporting success. `--now` starts it here, where we have root,
 # and after the provisioner so the binary the unit points at already exists.
-sudo systemctl enable --now trillboards-detector \
+#
+# `enable` THEN `restart`, NOT `enable --now`, AND THE DIFFERENCE ONLY SHOWS ON AN
+# UPGRADE. `--now` starts a unit that is INACTIVE and does nothing at all to one
+# that is already running — so on a box where the detector is already up, the
+# provisioner above would write a new `TRILLBOARDS_DETECTOR_RAM_BUDGET_MB` into
+# /etc/trillboards/env and the running process would keep the environment it was
+# exec'd with, until the next reboot. A ceiling the service never re-read is a
+# decision nobody acted on: exactly what the litert-lm block above this one
+# records about `write_litertlm_config` without a restart.
+#
+# `restart` is correct in BOTH states — it starts an inactive unit and replaces a
+# running one — so the fresh-install behaviour `--now` was added for is kept.
+sudo systemctl enable trillboards-detector 2>/dev/null || true
+sudo systemctl restart trillboards-detector \
   || echo "  *** The detector unit did not start. Sensing is unaffected. Check:
   *** sudo systemctl status trillboards-detector"