@trillboards/edge-sdk 0.2.131 → 0.2.132

package/deploy/detector/pyproject.toml

@@ -1,6 +1,16 @@
 [project]
 name = "trillboards-detector"
-version = "0.2.0"
+# GENERATED — `stamp_version.py --write` owns this line; `--check` fails CI when
+# it is stale. The `+src.<hex>` local segment is a fingerprint of the bytes this
+# package ships, and it lives HERE rather than in a hatch dynamic-version hook
+# because uv reads the version out of this file to decide whether its cached
+# wheel still describes the directory. A dynamic version would be read only by
+# BUILDING, which is the step a cache hit skips, so it could never invalidate
+# its own cache. Measured on uv 0.9.2 (2026-09-04): with the version held
+# constant, a `labels.py`-only change survives `uv tool install` AND
+# `uv tool install --force`; move the version and a bare `uv tool install`
+# reinstalls. See `stamp_version.py`.
+version = "0.2.0+src.2c3db7881945"
 description = "On-device object-detector service for the Trillboards BYO-CCTV connector (loopback HTTP, ONNX Runtime)."
 requires-python = ">=3.10"
 

package/deploy/detector/stamp_version.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""Stamp `trillboards-detector`'s version from the bytes it ships.
+
+WHY THIS EXISTS — A VERSION THAT DOES NOT MOVE IS A LIE THE INSTALLER BELIEVES
+=============================================================================
+
+`pyproject.toml` said `version = "0.2.0"` for the whole life of this package.
+Measured on 2026-09-04 across the seven commits that touched
+`trillboards_detector/labels.py`, the model vocabulary went from **16,129 bytes
+to 37,321** — one model id to eight — and the version string never moved once.
+
+That is not cosmetic, because uv decides whether to rebuild a LOCAL directory
+from its cached wheel, and the cache is not keyed on the package sources.
+Measured on uv 0.9.2, changing ONLY `trillboards_detector/labels.py` while
+`pyproject.toml` stays untouched:
+
+    uv tool install <dir>                            -> "Audited 1 package"  STALE
+    uv tool install --force <dir>                    -> venv rebuilt,        STALE
+    uv tool install --force --refresh-package <name> -> fresh
+    (version string moved in pyproject.toml)         -> fresh, with no flags
+
+**So `--force` is not enough, and all three shipped installers used exactly
+`--force`.** A box therefore keeps an obsolete CLASS VOCABULARY for ever: a
+granted specialist downloads, sits on disk, and `POST /detect` answers
+400 "requested classes not in this box's vocabulary" while `/health` says
+`ready` — the failure written up in
+`.claude/lessons/2026-09-02-a-granted-model-is-not-a-served-model.md`, where the
+run measured the VLM under a specialist's label.
+
+WHY DERIVED AND NOT HAND-BUMPED
+===============================
+
+A hand-bumped version is the same trap one release later: the seven commits
+above each had an author who could have bumped it and none did, because nothing
+asked them to and nothing checked. So the version's local segment is a
+FINGERPRINT OF THE SHIPPED BYTES. Editing any shipped file moves it; forgetting
+is not an available move, because CI recomputes it (`--check`).
+
+The base version stays hand-editable in `_version.py` — it is the human release
+line, and a release IS a judgement. What is mechanical is only the claim "these
+are different bytes", which is not a judgement at all.
+
+WHAT IS IN THE FINGERPRINT, AND WHY EACH PART
+=============================================
+
+* every `*.py` under `trillboards_detector/`, EXCEPT `_version.py` — the code
+  that is actually installed. `_version.py` is excluded because including the
+  stamp in its own input has no fixed point.
+* `pyproject.toml` with the `version = "..."` line normalised out, for the same
+  reason, and INCLUDED at all because the pinned dependency set
+  (`onnxruntime==1.29.0`) is part of what this tool IS: a box on a different ORT
+  is a box with different kernels, which is the whole reason those pins carry
+  the docblock they carry.
+
+Line endings are normalised to `\n` before hashing. A Windows checkout with
+`core.autocrlf=true` would otherwise fingerprint differently from the Linux one
+that built it, and the stamp would flap per platform rather than per change.
+
+USAGE
+    python3 stamp_version.py --check    # exit 1 on drift (CI)
+    python3 stamp_version.py --write    # re-stamp after editing the package
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+PACKAGE_DIR = HERE / "trillboards_detector"
+PYPROJECT = HERE / "pyproject.toml"
+VERSION_FILE = PACKAGE_DIR / "_version.py"
+
+#: How many hex characters of the digest ride in the local version segment. 12
+#: is git's abbreviated-sha length for the same reason: long enough that a
+#: collision is not a thing that happens to a repository, short enough to read
+#: off a `uv tool list` line.
+FINGERPRINT_CHARS = 12
+
+#: `version = "..."`, exactly as `[project]` spells it.
+VERSION_LINE_RE = re.compile(r'^version\s*=\s*".*"\s*$', re.MULTILINE)
+
+VERSION_FILE_TEMPLATE = '''\
+"""GENERATED FILE — do not hand-edit.
+
+`VERSION`'s local segment is a fingerprint of the bytes this package ships, so
+that an installer can never mistake new code for code it already has. See
+`stamp_version.py` for the measurement that made this necessary.
+
+Re-stamp after editing anything under `trillboards_detector/`:
+
+    python3 trillboards-edge-sdk/packages/edge-sdk/deploy/detector/stamp_version.py --write
+
+`BASE_VERSION` is the hand-editable release line and is the ONLY field here a
+human sets.
+"""
+
+BASE_VERSION = "{base}"
+SOURCE_FINGERPRINT = "{fingerprint}"
+VERSION = "{version}"
+'''
+
+
+def _normalise(raw: bytes) -> bytes:
+    """CRLF/CR -> LF, so the stamp is a property of the change and not the checkout."""
+    return raw.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+
+
+def _fingerprint_inputs() -> "list[tuple[str, bytes]]":
+    """(label, bytes) pairs, in a stable order, for everything the stamp covers."""
+    inputs: "list[tuple[str, bytes]]" = []
+    for path in sorted(PACKAGE_DIR.rglob("*.py"), key=lambda p: p.relative_to(HERE).as_posix()):
+        if path == VERSION_FILE:
+            continue
+        inputs.append((path.relative_to(HERE).as_posix(), _normalise(path.read_bytes())))
+    pyproject = _normalise(PYPROJECT.read_bytes()).decode("utf-8")
+    # The version line is normalised out: it is the OUTPUT of this function and
+    # cannot also be an input to it.
+    pyproject = VERSION_LINE_RE.sub('version = "<STAMPED>"', pyproject)
+    inputs.append(("pyproject.toml", pyproject.encode("utf-8")))
+    return inputs
+
+
+def compute_fingerprint() -> str:
+    digest = hashlib.sha256()
+    for label, blob in _fingerprint_inputs():
+        # Length-delimited so that concatenation is unambiguous: without it,
+        # moving bytes from the end of one file to the start of the next leaves
+        # the digest unchanged.
+        digest.update(f"{label}\0{len(blob)}\0".encode("utf-8"))
+        digest.update(blob)
+    return digest.hexdigest()[:FINGERPRINT_CHARS]
+
+
+def read_base_version() -> str:
+    text = VERSION_FILE.read_text(encoding="utf-8")
+    match = re.search(r'^BASE_VERSION\s*=\s*"([^"]+)"\s*$', text, re.MULTILINE)
+    if not match:
+        raise SystemExit(f"{VERSION_FILE} has no BASE_VERSION assignment")
+    return match.group(1)
+
+
+def expected_version() -> "tuple[str, str, str]":
+    """(base, fingerprint, full version) that the tree SHOULD carry right now."""
+    base = read_base_version()
+    fingerprint = compute_fingerprint()
+    return base, fingerprint, f"{base}+src.{fingerprint}"
+
+
+def read_stamped_version() -> str:
+    text = VERSION_FILE.read_text(encoding="utf-8")
+    match = re.search(r'^VERSION\s*=\s*"([^"]+)"\s*$', text, re.MULTILINE)
+    if not match:
+        raise SystemExit(f"{VERSION_FILE} has no VERSION assignment")
+    return match.group(1)
+
+
+def read_pyproject_version() -> str:
+    text = PYPROJECT.read_text(encoding="utf-8")
+    match = re.search(r'^version\s*=\s*"([^"]+)"\s*$', text, re.MULTILINE)
+    if not match:
+        raise SystemExit(f"{PYPROJECT} has no [project] version assignment")
+    return match.group(1)
+
+
+def write_stamp() -> "tuple[str, bool]":
+    base, fingerprint, version = expected_version()
+    changed = False
+
+    if not VERSION_FILE.exists() or read_stamped_version() != version:
+        VERSION_FILE.write_text(
+            VERSION_FILE_TEMPLATE.format(base=base, fingerprint=fingerprint, version=version),
+            encoding="utf-8",
+        )
+        changed = True
+
+    # pyproject.toml carries the SAME literal, and that is load-bearing rather
+    # than a duplicate: uv reads the version out of THIS file to decide whether
+    # its cached wheel still describes the directory. A dynamic version sourced
+    # from `_version.py` would be read only by BUILDING, which is the step a
+    # cache hit skips — so it could never invalidate its own cache.
+    pyproject_text = PYPROJECT.read_text(encoding="utf-8")
+    stamped = VERSION_LINE_RE.sub(f'version = "{version}"', pyproject_text, count=1)
+    if stamped != pyproject_text:
+        PYPROJECT.write_text(stamped, encoding="utf-8")
+        changed = True
+
+    return version, changed
+
+
+def check_stamp() -> int:
+    _, _, want = expected_version()
+    problems = []
+    have_version_file = read_stamped_version()
+    have_pyproject = read_pyproject_version()
+    if have_version_file != want:
+        problems.append(f"  {VERSION_FILE.name}: VERSION is {have_version_file!r}, expected {want!r}")
+    if have_pyproject != want:
+        problems.append(f"  pyproject.toml: version is {have_pyproject!r}, expected {want!r}")
+    if not problems:
+        print(f"detector-version-stamp OK — {want}")
+        return 0
+    print("detector-version-stamp DRIFT — the shipped bytes changed but the version did not.", file=sys.stderr)
+    for line in problems:
+        print(line, file=sys.stderr)
+    print(
+        "\nA version that does not move lets `uv tool install` keep an OBSOLETE class\n"
+        "vocabulary on a fielded box while /health reports `ready` and /detect answers\n"
+        "400 for the granted specialist's classes. Re-stamp:\n"
+        "  python3 trillboards-edge-sdk/packages/edge-sdk/deploy/detector/stamp_version.py --write",
+        file=sys.stderr,
+    )
+    return 1
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    parser = argparse.ArgumentParser(prog="stamp_version.py", description=__doc__)
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--check", action="store_true", help="exit 1 if the stamp is stale")
+    mode.add_argument("--write", action="store_true", help="re-stamp _version.py and pyproject.toml")
+    mode.add_argument("--print", action="store_true", help="print the version the tree should carry")
+    args = parser.parse_args(argv)
+
+    if args.check:
+        return check_stamp()
+    if args.print:
+        print(expected_version()[2])
+        return 0
+    version, changed = write_stamp()
+    print(f"{'stamped' if changed else 'already stamped'} {version}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/deploy/detector/tests/test_server.py

@@ -217,6 +217,23 @@ class TestHealth(ServerCase):
         status, _ = self.request(f"{url}/health", method="POST", body={})
         self.assertEqual(status, 405)
 
+    def test_health_names_the_build_that_is_answering(self):
+        """WHICH BUILD, on the wire, on both the healthy and the unhealthy reply.
+
+        Two boxes running different vocabularies are byte-identical on every
+        other field here — `state: ready`, the pinned model, the model path — so
+        before this there was nothing an operator or a rig script could read to
+        tell a current box from one whose install silently no-opped. The 503
+        reply carries it too: a box that is stale AND has no artefact yet is
+        exactly when knowing the build matters most.
+        """
+        from trillboards_detector._version import VERSION
+
+        _, ready = self.request(f"{self.serve(FakeLoader())}/health")
+        self.assertEqual(ready["version"], VERSION)
+        _, down = self.request(f"{self.serve(FakeLoader(state='unavailable'))}/health")
+        self.assertEqual(down["version"], VERSION)
+
 
 class TestHealthReportsResidency(ServerCase):
     """`/health` must say WHICH models are resident, and still load nothing.

package/deploy/detector/tests/test_version_stamp.py

@@ -0,0 +1,282 @@
+"""The tool's version must move when the bytes it ships move.
+
+WHY THIS IS A TEST AND NOT A CONVENTION
+=======================================
+
+`pyproject.toml` said `version = "0.2.0"` from the day this package was created.
+Across the seven commits that touched `trillboards_detector/labels.py` the model
+vocabulary went 16,129 -> 37,321 bytes, one model id to eight, and the version
+never moved once. Every one of those commits had an author who could have bumped
+it; nothing asked, so nobody did.
+
+That is not bookkeeping. Measured on uv 0.9.2, with the version held constant, a
+change to a module under `trillboards_detector/` survives BOTH
+`uv tool install` and `uv tool install --force` — uv's local-directory build
+cache is not keyed on the package sources — and both print
+"Installed 1 executable". A box therefore keeps an obsolete class VOCABULARY,
+a granted specialist answers 400, and `/health` says `ready` throughout
+(`.claude/lessons/2026-09-02-a-granted-model-is-not-a-served-model.md`).
+
+So the version's local segment is DERIVED from the shipped bytes, and this file
+is what makes forgetting impossible.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+DETECTOR_DIR = Path(__file__).resolve().parents[1]
+STAMPER = DETECTOR_DIR / "stamp_version.py"
+PYPROJECT = DETECTOR_DIR / "pyproject.toml"
+PACKAGE_DIR = DETECTOR_DIR / "trillboards_detector"
+
+sys.path.insert(0, str(DETECTOR_DIR))
+
+
+def _load_stamper(root: Path):
+    """Import `stamp_version` bound to `root` rather than to the real tree.
+
+    Loaded as a FRESH module object per root so the mutation test below cannot
+    be answered by a cached module still pointing at the committed sources —
+    which is the same class of staleness this whole file exists to catch, and it
+    would make the non-vacuity check vacuous.
+    """
+    spec = importlib.util.spec_from_file_location(f"stamp_version_{abs(hash(str(root)))}", root / "stamp_version.py")
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+class TestVersionStamp(unittest.TestCase):
+    def test_the_committed_stamp_matches_the_committed_bytes(self) -> None:
+        """The check CI runs. Fails loudly with the one command that fixes it."""
+        result = subprocess.run(
+            [sys.executable, str(STAMPER), "--check"],
+            capture_output=True,
+            text=True,
+        )
+        self.assertEqual(
+            result.returncode,
+            0,
+            "the detector's version stamp is stale:\n"
+            f"{result.stdout}{result.stderr}",
+        )
+
+    def test_pyproject_and_the_module_carry_the_same_version(self) -> None:
+        """Two writers, and they must never disagree.
+
+        `pyproject.toml` carries the literal because uv reads the version FROM
+        THIS FILE to decide whether its cached wheel still describes the
+        directory — a hatch dynamic version would be read only by BUILDING,
+        which is the step a cache hit skips, so it could never invalidate its own
+        cache. `_version.py` carries it because the running service has to be
+        able to say what it is without importing package metadata. Both are
+        written by one generator; this asserts the generator is the only writer.
+        """
+        stamper = _load_stamper(DETECTOR_DIR)
+        self.assertEqual(stamper.read_pyproject_version(), stamper.read_stamped_version())
+
+    def test_the_package_exports_the_stamped_version(self) -> None:
+        import trillboards_detector
+        from trillboards_detector import _version
+
+        self.assertEqual(trillboards_detector.__version__, _version.VERSION)
+        self.assertEqual(_version.VERSION, f"{_version.BASE_VERSION}+src.{_version.SOURCE_FINGERPRINT}")
+
+    def test_the_version_carries_a_source_fingerprint(self) -> None:
+        """`0.2.0` and `0.2.0` were two different builds. `+src.<hex>` cannot be."""
+        from trillboards_detector import _version
+
+        self.assertRegex(_version.VERSION, r"^\d+\.\d+\.\d+\+src\.[0-9a-f]{12}$")
+
+    def test_editing_a_shipped_module_moves_the_fingerprint(self) -> None:
+        """NON-VACUITY. A check that cannot go red is not a check.
+
+        Copies the package to a temp tree, appends one line to the file whose
+        growth started all this, and asserts the derived version changes. This is
+        the property the whole design rests on, asserted rather than assumed.
+        """
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp) / "detector"
+            shutil.copytree(
+                DETECTOR_DIR,
+                root,
+                ignore=shutil.ignore_patterns("__pycache__", "bench", "tests", "*.pyc"),
+            )
+            before = _load_stamper(root).expected_version()[2]
+
+            labels = root / "trillboards_detector" / "labels.py"
+            labels.write_text(labels.read_text() + "\n# one more model id\n", encoding="utf-8")
+            after = _load_stamper(root).expected_version()[2]
+
+            self.assertNotEqual(before, after, "a shipped-module edit left the version unchanged")
+
+    def test_the_fingerprint_ignores_line_endings(self) -> None:
+        """A Windows checkout must not stamp differently from the Linux one.
+
+        `core.autocrlf=true` rewrites every checked-out `.py`. Without
+        normalisation the stamp would flap per PLATFORM rather than per change,
+        and a CI check on one OS would fail a tree that is correct on the other.
+        """
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp) / "detector"
+            shutil.copytree(
+                DETECTOR_DIR,
+                root,
+                ignore=shutil.ignore_patterns("__pycache__", "bench", "tests", "*.pyc"),
+            )
+            before = _load_stamper(root).expected_version()[2]
+            for path in list((root / "trillboards_detector").rglob("*.py")) + [root / "pyproject.toml"]:
+                path.write_bytes(path.read_bytes().replace(b"\n", b"\r\n"))
+            after = _load_stamper(root).expected_version()[2]
+            self.assertEqual(before, after, "CRLF alone moved the fingerprint")
+
+    def test_the_stamper_is_idempotent(self) -> None:
+        """`--write` on a stamped tree changes nothing, so it is safe in a loop."""
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp) / "detector"
+            shutil.copytree(
+                DETECTOR_DIR,
+                root,
+                ignore=shutil.ignore_patterns("__pycache__", "bench", "tests", "*.pyc"),
+            )
+            stamper = _load_stamper(root)
+            first_version, first_changed = stamper.write_stamp()
+            second_version, second_changed = stamper.write_stamp()
+            self.assertFalse(first_changed, "the committed tree was not already stamped")
+            self.assertFalse(second_changed)
+            self.assertEqual(first_version, second_version)
+
+    def test_the_version_line_is_excluded_from_its_own_input(self) -> None:
+        """Otherwise the stamp has no fixed point and `--write` never converges."""
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp) / "detector"
+            shutil.copytree(
+                DETECTOR_DIR,
+                root,
+                ignore=shutil.ignore_patterns("__pycache__", "bench", "tests", "*.pyc"),
+            )
+            stamper = _load_stamper(root)
+            before = stamper.compute_fingerprint()
+            pyproject = root / "pyproject.toml"
+            pyproject.write_text(
+                re.sub(
+                    r'^version\s*=\s*".*"\s*$',
+                    'version = "9.9.9+src.deadbeefcafe"',
+                    pyproject.read_text(encoding="utf-8"),
+                    count=1,
+                    flags=re.MULTILINE,
+                ),
+                encoding="utf-8",
+            )
+            self.assertEqual(before, stamper.compute_fingerprint())
+
+    def test_a_dependency_pin_change_moves_the_fingerprint(self) -> None:
+        """The pinned runtime is part of what this tool IS.
+
+        `docs/runbooks/cctv-detector-tier.md` §2 picks this detector on a
+        measured ~63 ms and says ORT's kernel fusion, thread heuristics and SIMD
+        dispatch move between minor releases — so a box on a different
+        onnxruntime is a box the measurement does not describe, and an installer
+        must not mistake it for one it already has.
+        """
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp) / "detector"
+            shutil.copytree(
+                DETECTOR_DIR,
+                root,
+                ignore=shutil.ignore_patterns("__pycache__", "bench", "tests", "*.pyc"),
+            )
+            before = _load_stamper(root).expected_version()[2]
+            pyproject = root / "pyproject.toml"
+            pyproject.write_text(
+                pyproject.read_text(encoding="utf-8").replace(
+                    '"onnxruntime==1.29.0"', '"onnxruntime==1.30.0"'
+                ),
+                encoding="utf-8",
+            )
+            self.assertNotEqual(before, _load_stamper(root).expected_version()[2])
+
+
+class TestInstallersCannotAcceptAStaleInstall(unittest.TestCase):
+    """`--force` is not enough, and all three installers used exactly `--force`.
+
+    Measured on uv 0.9.2 (2026-09-04), local-directory source, `labels.py`-only
+    change with `pyproject.toml` untouched:
+
+        uv tool install <dir>                              STALE ("Audited 1 package")
+        uv tool install --force <dir>                      STALE (cached wheel)
+        uv tool install --force --refresh-package <name>   fresh
+
+    So the flag is load-bearing, and so is asking the installed binary what it
+    is afterwards. Asserted on the shipped text of all three provisioners
+    because there is no runner on which all three can be executed.
+    """
+
+    INSTALLERS = (
+        DETECTOR_DIR.parent / "macos" / "scripts" / "setup-detector.sh",
+        DETECTOR_DIR.parent / "systemd" / "setup-detector.sh",
+        DETECTOR_DIR.parent / "windows" / "setup-detector.ps1",
+    )
+
+    @staticmethod
+    def _install_invocations(text: str) -> "list[str]":
+        """Lines that actually RUN the install, not lines that mention it.
+
+        Keyed on `--managed-python`, which every real invocation carries and no
+        prose line does. A looser rule (any line containing "tool install")
+        matches a log message and a PowerShell block comment, and a rule that
+        matched nothing would pass vacuously — hence the count assertion at the
+        call site.
+        """
+        return [line for line in text.splitlines() if "tool install" in line and "--managed-python" in line]
+
+    def test_every_installer_busts_the_package_cache(self) -> None:
+        for path in self.INSTALLERS:
+            with self.subTest(installer=path.name + f" ({path.parent.name})"):
+                text = path.read_text(encoding="utf-8")
+                install_lines = self._install_invocations(text)
+                # TWO: the ordinary install, and the uninstall-and-retry repair
+                # rung. A file that grew a third would be installing somewhere
+                # this test never looked.
+                self.assertEqual(
+                    len(install_lines),
+                    2,
+                    f"{path} runs {len(install_lines)} `uv tool install` invocations, expected 2",
+                )
+                for line in install_lines:
+                    self.assertIn(
+                        "--refresh-package trillboards-detector",
+                        line,
+                        f"{path} installs without busting uv's cached wheel: {line.strip()}",
+                    )
+
+    def test_every_installer_verifies_what_it_installed(self) -> None:
+        for path in self.INSTALLERS:
+            with self.subTest(installer=path.name + f" ({path.parent.name})"):
+                text = path.read_text(encoding="utf-8")
+                self.assertIn("--version", text, f"{path} never asks the binary what it is")
+                self.assertIn(
+                    "is STALE after a full reinstall",
+                    text,
+                    f"{path} has no loud outcome for an install that did not take",
+                )
+
+    def test_no_installer_uses_the_blunt_refresh(self) -> None:
+        """`--refresh` re-downloads the pinned ~250 MB onnxruntime wheel every run."""
+        for path in self.INSTALLERS:
+            with self.subTest(installer=path.name + f" ({path.parent.name})"):
+                for line in self._install_invocations(path.read_text(encoding="utf-8")):
+                    self.assertNotRegex(line, r"--refresh(?!-package)\b")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/deploy/detector/trillboards_detector/__init__.py

@@ -5,4 +5,9 @@ Its own uv tool, its own venv, its own OS-supervised loopback service on
 `docs/runbooks/cctv-detector-tier.md` for what it runs and why that model.
 """
 
-__version__ = "0.2.0"
+from ._version import VERSION as __version__  # noqa: F401  (re-exported)
+
+# THE VERSION IS DERIVED FROM THE BYTES, NOT TYPED. Its local segment is a
+# fingerprint of everything this package ships, because a version that does not
+# move lets `uv tool install` keep an obsolete class VOCABULARY on a fielded box
+# while `/health` still says `ready`. `stamp_version.py` carries the measurement.

package/deploy/detector/trillboards_detector/_version.py

@@ -0,0 +1,17 @@
+"""GENERATED FILE — do not hand-edit.
+
+`VERSION`'s local segment is a fingerprint of the bytes this package ships, so
+that an installer can never mistake new code for code it already has. See
+`stamp_version.py` for the measurement that made this necessary.
+
+Re-stamp after editing anything under `trillboards_detector/`:
+
+    python3 trillboards-edge-sdk/packages/edge-sdk/deploy/detector/stamp_version.py --write
+
+`BASE_VERSION` is the hand-editable release line and is the ONLY field here a
+human sets.
+"""
+
+BASE_VERSION = "0.2.0"
+SOURCE_FINGERPRINT = "2c3db7881945"
+VERSION = "0.2.0+src.2c3db7881945"

package/deploy/detector/trillboards_detector/cli.py

@@ -17,6 +17,7 @@ import sys
 import threading
 from pathlib import Path
 
+from ._version import VERSION
 from .loader import DEFAULT_POLL_INTERVAL_S, DetectorLoader
 from .modelpath import DEFAULT_MODEL_NAME, resolve_model_path, resolve_ram_budget_mb
 from .server import DEFAULT_HOST, DEFAULT_PORT, serve
@@ -60,6 +61,14 @@ def _configure_logging(log_file: "str | None", verbose: bool) -> None:
 
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog="trillboards-detector")
+    # `--version` IS THE INSTALLER'S ONLY WAY TO ASK WHAT IT ACTUALLY INSTALLED,
+    # and it exists because `uv tool install` reports success on work it did not
+    # do. Measured on uv 0.9.2: changing only `labels.py` and re-running the
+    # install — even with `--force` — leaves the OLD wheel in place and prints
+    # "Installed 1 executable". The three setup-detector scripts therefore run
+    # this and compare it against the staged source's version; see
+    # `stamp_version.py` for why the version can be trusted to have moved.
+    p.add_argument("--version", action="version", version=f"trillboards-detector {VERSION}")
     sub = p.add_subparsers(dest="command")
     s = sub.add_parser("serve", help="run the loopback detector service")
     s.add_argument("--host", default=DEFAULT_HOST)
@@ -132,7 +141,8 @@ def main(argv: "list[str] | None" = None) -> int:
         )
 
     LOG.info(
-        "[detector] starting on %s:%s, pinned model %s at %s, ceiling %s",
+        "[detector] %s starting on %s:%s, pinned model %s at %s, ceiling %s",
+        VERSION,
         args.host,
         args.port,
         args.model_name,

package/deploy/detector/trillboards_detector/server.py

@@ -32,6 +32,7 @@ import sys as _sys
 import threading
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 
+from ._version import VERSION
 from .errors import DetectorNotReady, UnknownClasses
 
 #: Loopback only. litert-lm owns 9379; this is a SECOND service, not a route on
@@ -264,6 +265,15 @@ class DetectorHandler(BaseHTTPRequestHandler):
         info = loader.info()
         ready = info.get("state") == "ready"
         info["status"] = "ok" if ready else info.get("state", "unavailable")
+        # WHICH BUILD IS ANSWERING. A box that kept an obsolete build keeps an
+        # obsolete class VOCABULARY with it, and every other field here is
+        # identical on both — `state: ready`, the pinned model, the model path —
+        # so before this there was nothing on the wire that could tell a current
+        # box from a stale one. The 2026-09-02 rig lost a run to exactly that:
+        # a granted specialist downloaded, `/health` said `ready`, and `/detect`
+        # answered 400 for its classes. Reported on the LOADER's payload rather
+        # than only in a log because the reader that needs it is a script.
+        info["version"] = VERSION
         self._json(200 if ready else 503, info)
 
     # ── /detect ──────────────────────────────────────────────────────────────

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

@@ -121,9 +121,32 @@ fi
 # drifted one. Gating it behind a health check is how a repaired-and-healthy box
 # keeps a broken venv while reporting fine (setup-litertlm.sh's shim carries the
 # same note, from the same mistake).
+#
+# THE INSTALL MUST NOT SILENTLY NO-OP, AND `--force` IS NOT ENOUGH.
+#
+# Measured on uv 0.9.2 (2026-09-04) against a local-directory source, changing
+# ONLY a module under `trillboards_detector/` while `pyproject.toml` stays
+# untouched:
+#
+#   uv tool install <dir>                                  "Audited 1 package"   STALE
+#   uv tool install --force <dir>                          venv rebuilt from the
+#                                                          CACHED wheel          STALE
+#   uv tool install --force --refresh-package <name>       fresh
+#
+# uv's build cache for a local directory is NOT keyed on the package sources, so
+# `--force` rebuilds the venv and reinstalls the same stale wheel into it. Both
+# print "Installed 1 executable". That is how a fielded box kept an obsolete
+# class VOCABULARY while every light stayed green: a granted specialist
+# downloaded, sat on disk, and `POST /detect` answered 400 "requested classes
+# not in this box's vocabulary" with `/health` reporting `ready`
+# (`.claude/lessons/2026-09-02-a-granted-model-is-not-a-served-model.md`).
+#
+# `--refresh-package trillboards-detector`, NOT `--refresh`: the latter also
+# re-downloads the pinned ~250 MB onnxruntime wheel on a shop PC every time, for
+# nothing — an exact pin cannot resolve to different bytes.
 SOURCE="$(find_detector_source)" || { log "ERROR: detector package source not found next to this script"; exit 0; }
 log "installing/repairing trillboards-detector from $SOURCE with uv-managed Python $DETECTOR_PYTHON"
-if ! "$UV" tool install --python "$DETECTOR_PYTHON" --managed-python --force "$SOURCE" >>"$LOG" 2>&1; then
+if ! "$UV" tool install --python "$DETECTOR_PYTHON" --managed-python --force --refresh-package trillboards-detector "$SOURCE" >>"$LOG" 2>&1; then
   log "ERROR: trillboards-detector install failed; the cascade stays off (the VLM still runs every frame)"
   exit 0
 fi
@@ -135,6 +158,48 @@ if [ ! -x "$DETECTOR" ]; then
 fi
 log "trillboards-detector installed at $DETECTOR"
 
+# AND THEN ASK WHAT IS ACTUALLY INSTALLED, because every step above reports
+# success on work it did not do. The version's `+src.<hex>` local segment is a
+# fingerprint of the bytes the staged package ships
+# (`deploy/detector/stamp_version.py`), so this comparison is the only thing in
+# the chain that can tell a real install from a convincing no-op. It reads the
+# STAGED pyproject rather than a constant: a constant here would be a fourth
+# place the same version is written down.
+staged_detector_version() {
+  sed -n 's/^version[[:space:]]*=[[:space:]]*"\(.*\)"[[:space:]]*$/\1/p' "$SOURCE/pyproject.toml" 2>/dev/null | head -1
+}
+installed_detector_version() {
+  "$DETECTOR" --version 2>/dev/null | awk '{print $NF}'
+}
+
+WANT_VERSION="$(staged_detector_version)"
+HAVE_VERSION="$(installed_detector_version)"
+if [ -z "$WANT_VERSION" ]; then
+  log "WARN: could not read the staged detector version from $SOURCE/pyproject.toml; the staleness check is skipped"
+elif [ "$HAVE_VERSION" != "$WANT_VERSION" ]; then
+  # ONE REPAIR RUNG, and it is a real uninstall rather than another flag: a
+  # mismatch here means uv served something other than the staged directory, so
+  # asking it again the same way is not a repair.
+  log "WARN: the installed detector reports '$HAVE_VERSION' but the staged package is '$WANT_VERSION' - reinstalling from scratch"
+  "$UV" tool uninstall trillboards-detector >>"$LOG" 2>&1 || true
+  "$UV" tool install --python "$DETECTOR_PYTHON" --managed-python --force --refresh-package trillboards-detector "$SOURCE" >>"$LOG" 2>&1 || true
+  DETECTOR="$LOCAL_BIN/trillboards-detector"
+  [ -x "$DETECTOR" ] || DETECTOR="$(command -v trillboards-detector || echo "$DETECTOR")"
+  HAVE_VERSION="$(installed_detector_version)"
+  if [ "$HAVE_VERSION" = "$WANT_VERSION" ]; then
+    log "trillboards-detector repaired to $HAVE_VERSION"
+  else
+    # NOT FATAL - rule 1 of this provisioner is that it may never block camera
+    # pairing - but never silent either. A box left here serves the OLD class
+    # VOCABULARY, so every granted specialist past it answers 400 and the fields
+    # it owns are simply ABSENT from the observation, which reads as a quiet
+    # store rather than as a broken instrument.
+    log "ERROR: trillboards-detector is STALE after a full reinstall - it reports '$HAVE_VERSION', the staged package is '$WANT_VERSION'. This box answers 400 for any class only the newer vocabulary knows. /health reports the version it is actually running."
+  fi
+else
+  log "trillboards-detector $HAVE_VERSION matches the staged package"
+fi
+
 # 2b. THE RAM CEILING, derived from THIS Mac.
 #
 # Without it the service holds its pinned model and refuses to make any second

package/deploy/systemd/setup-detector.sh

@@ -69,8 +69,31 @@ SOURCE="$(find_detector_source)" || { log "ERROR: detector package source not fo
 # ITS OWN TOOL NAME, so uv gives it its own venv. Never a package added into
 # litert-lm's: `uv tool install --force` rebuilds that venv from scratch on any
 # version drift or health failure and would take the addition with it.
+#
+# THE INSTALL MUST NOT SILENTLY NO-OP, AND `--force` IS NOT ENOUGH.
+#
+# Measured on uv 0.9.2 (2026-09-04) against a local-directory source, changing
+# ONLY a module under `trillboards_detector/` while `pyproject.toml` stays
+# untouched:
+#
+#   uv tool install <dir>                                  "Audited 1 package"   STALE
+#   uv tool install --force <dir>                          venv rebuilt from the
+#                                                          CACHED wheel          STALE
+#   uv tool install --force --refresh-package <name>       fresh
+#
+# uv's build cache for a local directory is NOT keyed on the package sources, so
+# `--force` rebuilds the venv and reinstalls the same stale wheel into it. Both
+# print "Installed 1 executable". That is how a fielded box kept an obsolete
+# class VOCABULARY while every light stayed green: a granted specialist
+# downloaded, sat on disk, and `POST /detect` answered 400 "requested classes
+# not in this box's vocabulary" with `/health` reporting `ready`
+# (`.claude/lessons/2026-09-02-a-granted-model-is-not-a-served-model.md`).
+#
+# `--refresh-package trillboards-detector`, NOT `--refresh`: the latter also
+# re-downloads the pinned ~250 MB onnxruntime wheel on a shop PC every time, for
+# nothing — an exact pin cannot resolve to different bytes.
 log "installing/repairing trillboards-detector from $SOURCE with uv-managed Python $DETECTOR_PYTHON"
-if ! "$UV" tool install --python "$DETECTOR_PYTHON" --managed-python --force "$SOURCE" >>"$LOG" 2>&1; then
+if ! "$UV" tool install --python "$DETECTOR_PYTHON" --managed-python --force --refresh-package trillboards-detector "$SOURCE" >>"$LOG" 2>&1; then
   log "ERROR: trillboards-detector install failed; the cascade stays off"
   exit 0
 fi
@@ -79,6 +102,48 @@ DETECTOR="$LOCAL_BIN/trillboards-detector"
 [ -x "$DETECTOR" ] || { log "ERROR: trillboards-detector binary missing after install"; exit 0; }
 log "trillboards-detector installed at $DETECTOR"
 
+# AND THEN ASK WHAT IS ACTUALLY INSTALLED, because every step above reports
+# success on work it did not do. The version's `+src.<hex>` local segment is a
+# fingerprint of the bytes the staged package ships
+# (`deploy/detector/stamp_version.py`), so this comparison is the only thing in
+# the chain that can tell a real install from a convincing no-op. It reads the
+# STAGED pyproject rather than a constant: a constant here would be a fourth
+# place the same version is written down.
+staged_detector_version() {
+  sed -n 's/^version[[:space:]]*=[[:space:]]*"\(.*\)"[[:space:]]*$/\1/p' "$SOURCE/pyproject.toml" 2>/dev/null | head -1
+}
+installed_detector_version() {
+  "$DETECTOR" --version 2>/dev/null | awk '{print $NF}'
+}
+
+WANT_VERSION="$(staged_detector_version)"
+HAVE_VERSION="$(installed_detector_version)"
+if [ -z "$WANT_VERSION" ]; then
+  log "WARN: could not read the staged detector version from $SOURCE/pyproject.toml; the staleness check is skipped"
+elif [ "$HAVE_VERSION" != "$WANT_VERSION" ]; then
+  # ONE REPAIR RUNG, and it is a real uninstall rather than another flag: a
+  # mismatch here means uv served something other than the staged directory, so
+  # asking it again the same way is not a repair.
+  log "WARN: the installed detector reports '$HAVE_VERSION' but the staged package is '$WANT_VERSION' - reinstalling from scratch"
+  "$UV" tool uninstall trillboards-detector >>"$LOG" 2>&1 || true
+  "$UV" tool install --python "$DETECTOR_PYTHON" --managed-python --force --refresh-package trillboards-detector "$SOURCE" >>"$LOG" 2>&1 || true
+  DETECTOR="$LOCAL_BIN/trillboards-detector"
+  [ -x "$DETECTOR" ] || DETECTOR="$(command -v trillboards-detector || echo "$DETECTOR")"
+  HAVE_VERSION="$(installed_detector_version)"
+  if [ "$HAVE_VERSION" = "$WANT_VERSION" ]; then
+    log "trillboards-detector repaired to $HAVE_VERSION"
+  else
+    # NOT FATAL - rule 1 of this provisioner is that it may never block camera
+    # pairing - but never silent either. A box left here serves the OLD class
+    # VOCABULARY, so every granted specialist past it answers 400 and the fields
+    # it owns are simply ABSENT from the observation, which reads as a quiet
+    # store rather than as a broken instrument.
+    log "ERROR: trillboards-detector is STALE after a full reinstall - it reports '$HAVE_VERSION', the staged package is '$WANT_VERSION'. This box answers 400 for any class only the newer vocabulary knows. /health reports the version it is actually running."
+  fi
+else
+  log "trillboards-detector $HAVE_VERSION matches the staged package"
+fi
+
 # ── THE RAM CEILING ─────────────────────────────────────────────────────────
 #
 # Without this the detector holds its pinned model and REFUSES to make any

package/deploy/windows/setup-detector.ps1

@@ -122,8 +122,29 @@ if (-not $source) {
   Log "ERROR: detector package source not found near $Here"
   exit 0
 }
+# THE INSTALL MUST NOT SILENTLY NO-OP, AND --force IS NOT ENOUGH.
+#
+# Measured on uv 0.9.2 (2026-09-04) against a local-directory source, changing
+# ONLY a module under trillboards_detector\ while pyproject.toml stays untouched:
+#
+#   uv tool install <dir>                              "Audited 1 package"  STALE
+#   uv tool install --force <dir>                      venv rebuilt from the
+#                                                      CACHED wheel         STALE
+#   uv tool install --force --refresh-package <name>   fresh
+#
+# uv's build cache for a local directory is NOT keyed on the package sources, so
+# --force rebuilds the venv and reinstalls the same stale wheel into it. Both
+# print "Installed 1 executable". That is how a fielded box kept an obsolete
+# class VOCABULARY while every light stayed green: a granted specialist
+# downloaded, sat on disk, and POST /detect answered 400 "requested classes not
+# in this box's vocabulary" with /health reporting `ready`
+# (.claude/lessons/2026-09-02-a-granted-model-is-not-a-served-model.md).
+#
+# --refresh-package trillboards-detector, NOT --refresh: the latter also
+# re-downloads the pinned ~250 MB onnxruntime wheel on a shop PC every time, for
+# nothing - an exact pin cannot resolve to different bytes.
 Log "installing/repairing trillboards-detector from $source with uv-managed Python $DetectorPython"
-& $uvCmd.Source tool install --python $DetectorPython --managed-python --force "$source" *>> $LogPath
+& $uvCmd.Source tool install --python $DetectorPython --managed-python --force --refresh-package trillboards-detector "$source" *>> $LogPath
 if ($LASTEXITCODE -ne 0) {
   Log "ERROR: trillboards-detector install failed; the cascade stays off (the VLM still runs every frame)"
   exit 0
@@ -140,6 +161,56 @@ if (-not (Test-Path -LiteralPath $detectorPath)) {
 }
 Log "trillboards-detector installed at $detectorPath"
 
+# AND THEN ASK WHAT IS ACTUALLY INSTALLED, because every step above reports
+# success on work it did not do. The version's +src.<hex> local segment is a
+# fingerprint of the bytes the staged package ships (deploy/detector/stamp_version.py),
+# so this comparison is the only thing in the chain that can tell a real install
+# from a convincing no-op. It reads the STAGED pyproject rather than a constant:
+# a constant here would be a fourth place the same version is written down.
+function Get-StagedDetectorVersion {
+  param([string] $SourceDir)
+  $pyproject = Join-Path $SourceDir 'pyproject.toml'
+  if (-not (Test-Path -LiteralPath $pyproject)) { return $null }
+  foreach ($line in (Get-Content -LiteralPath $pyproject)) {
+    if ($line -match '^\s*version\s*=\s*"([^"]+)"\s*$') { return $Matches[1] }
+  }
+  return $null
+}
+function Get-InstalledDetectorVersion {
+  param([string] $Exe)
+  if (-not (Test-Path -LiteralPath $Exe)) { return $null }
+  # `--version` prints "trillboards-detector <version>"; take the last token.
+  $out = & $Exe --version 2>$null
+  if ($LASTEXITCODE -ne 0 -or -not $out) { return $null }
+  return ([string]$out).Trim().Split(' ')[-1]
+}
+
+$wantVersion = Get-StagedDetectorVersion -SourceDir $source
+$haveVersion = Get-InstalledDetectorVersion -Exe $detectorPath
+if (-not $wantVersion) {
+  Log "WARN: could not read the staged detector version from $source\pyproject.toml; the staleness check is skipped"
+} elseif ($haveVersion -ne $wantVersion) {
+  # ONE REPAIR RUNG, and it is a real uninstall rather than another flag: a
+  # mismatch here means uv served something other than the staged directory, so
+  # asking it again the same way is not a repair.
+  Log "WARN: the installed detector reports '$haveVersion' but the staged package is '$wantVersion' - reinstalling from scratch"
+  & $uvCmd.Source tool uninstall trillboards-detector *>> $LogPath
+  & $uvCmd.Source tool install --python $DetectorPython --managed-python --force --refresh-package trillboards-detector "$source" *>> $LogPath
+  $haveVersion = Get-InstalledDetectorVersion -Exe $detectorPath
+  if ($haveVersion -eq $wantVersion) {
+    Log "trillboards-detector repaired to $haveVersion"
+  } else {
+    # NOT FATAL - rule 1 of this provisioner is that it may never block camera
+    # pairing - but never silent either. A box left here serves the OLD class
+    # VOCABULARY, so every granted specialist past it answers 400 and the fields
+    # it owns are simply ABSENT from the observation, which reads as a quiet
+    # store rather than as a broken instrument.
+    Log "ERROR: trillboards-detector is STALE after a full reinstall - it reports '$haveVersion', the staged package is '$wantVersion'. This box answers 400 for any class only the newer vocabulary knows. /health reports the version it is actually running."
+  }
+} else {
+  Log "trillboards-detector $haveVersion matches the staged package"
+}
+
 # --- 2b. The RAM ceiling, derived from THIS machine --------------------------
 #
 # Without it the service holds its pinned model and refuses to make any second

package/dist/EdgeAgent.js

@@ -44,7 +44,7 @@ const edge_ads_1 = require("@trillboards/edge-ads");
 const CommandRouter_1 = require("./CommandRouter");
 const config_1 = require("./config");
 const dataDir_1 = require("./dataDir");
-const SDK_VERSION = '0.2.131';
+const SDK_VERSION = '0.2.132';
 class EdgeAgent extends events_1.EventEmitter {
     constructor(config, deps) {
         super();

package/dist/diagnose.d.ts

@@ -31,7 +31,7 @@ export interface DiagnosticReport {
         skipped: number;
     };
 }
-declare const SDK_VERSION = "0.2.131";
+declare const SDK_VERSION = "0.2.132";
 declare function checkNodeVersion(): CheckResult;
 declare function checkPlatform(): CheckResult;
 declare function checkMemory(): CheckResult;

package/dist/diagnose.js

@@ -63,7 +63,7 @@ const localNetworkAccess_1 = require("./localNetworkAccess");
 // ---------------------------------------------------------------------------
 // SDK version — mirrors package.json; kept in sync by CI
 // ---------------------------------------------------------------------------
-const SDK_VERSION = '0.2.131';
+const SDK_VERSION = '0.2.132';
 exports._SDK_VERSION = SDK_VERSION;
 // ---------------------------------------------------------------------------
 // ANSI helpers (no external deps)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trillboards/edge-sdk",
-  "version": "0.2.131",
+  "version": "0.2.132",
   "description": "Composable cross-platform Edge AI SDK for audience sensing on DOOH/CTV devices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",