@trillboards/edge-sdk 0.2.140 → 0.2.150

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

@@ -29,6 +29,9 @@ LA_DIR="$USER_HOME/Library/LaunchAgents"
 LOCAL_BIN="$USER_HOME/.local/bin"
 MODEL_ID="gemma-4-E2B-it.litertlm"
 HF_REPO="litert-community/gemma-4-E2B-it-litert-lm"
+MODEL_REVISION="84b6978eff6e4eea02825bc2ee4ea48579f13109"
+APPROVED_MODEL_SHA256="ab7838cdfc8f77e54d8ca45eadceb20452d9f01e4bfade03e5dce27911b27e42"
+MODEL_URL="https://huggingface.co/$HF_REPO/resolve/$MODEL_REVISION/$MODEL_ID"
 SERVE_LABEL="com.trillboards.litertlm"
 SERVE_PORT="9379"
 LITERT_PYTHON="${LITERT_LM_PYTHON:-3.12}"
@@ -245,16 +248,29 @@ install_litertlm_shim() {
 # Deliberately NOT a /v1/models check: that answers 200 without ever building an
 # engine, so it cannot tell a working GPU encoder from one that fails on first
 # use.
-verify_litertlm_vision() {
-  _body="$LITERT_DIR/.vision-probe.json"
-  printf '{"model":"%s,gpu","messages":[{"role":"user","content":[{"type":"text","text":"Reply with the single word: ok"},{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,%s"}}]}],"max_completion_tokens":8,"temperature":0}' \
-    "$MODEL_ID" "$LITERTLM_PROBE_JPEG_B64" > "$_body" 2>/dev/null || return 1
-  _code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 180 \
+verify_litertlm_probe() {
+  local requested="$1" body response code tool_dir py verifier candidate valid=1
+  body="$LITERT_DIR/.identity-probe.json"
+  response="$LITERT_DIR/.identity-response.json"
+  printf '{"model":"%s","messages":[{"role":"user","content":[{"type":"text","text":"Reply with the single word: ok"},{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,%s"}}]}],"max_completion_tokens":8,"temperature":0}' \
+    "$requested" "$LITERTLM_PROBE_JPEG_B64" > "$body" 2>/dev/null || return 1
+  code=$(curl -s -o "$response" -w '%{http_code}' --max-time 180 \
     -X POST "http://127.0.0.1:$SERVE_PORT/v1/chat/completions" \
-    -H 'Content-Type: application/json' --data-binary @"$_body" 2>/dev/null)
-  rm -f "$_body" 2>/dev/null || true
-  [ "$_code" = "200" ]
+    -H 'Content-Type: application/json' -H "X-Trillboards-Model-Sha256: $APPROVED_MODEL_SHA256" \
+    --data-binary @"$body" 2>/dev/null)
+  if [ "$code" = "200" ]; then
+    tool_dir="$("${UV:-$LOCAL_BIN/uv}" tool dir 2>/dev/null | tr -d '\r')"
+    py="$tool_dir/litert-lm/bin/python"
+    for candidate in "$SCRIPT_DIR/verify_model_proof.py" "$SCRIPT_DIR/../litertlm/verify_model_proof.py" "$SCRIPT_DIR/../../litertlm/verify_model_proof.py"; do
+      [ -f "$candidate" ] && { verifier="$candidate"; break; }
+    done
+    [ -n "${verifier:-}" ] && [ -x "$py" ] \
+      && "$py" "$verifier" "$response" "$requested" "$APPROVED_MODEL_SHA256" && valid=0
+  fi
+  rm -f "$body" "$response" 2>/dev/null || true
+  return "$valid"
 }
+verify_litertlm_vision() { verify_litertlm_probe "$MODEL_ID,gpu"; }
 
 # The same probe, but asking for NO delegate suffix rather than `,gpu`.
 #
@@ -265,16 +281,7 @@ verify_litertlm_vision() {
 # carries no suffix at all, so a 200 means the box built an engine and ran a real
 # image through it under the config now on disk, which is exactly the claim each
 # rung needs.
-verify_litertlm_plain_inference() {
-  _body="$LITERT_DIR/.plain-probe.json"
-  printf '{"model":"%s","messages":[{"role":"user","content":[{"type":"text","text":"Reply with the single word: ok"},{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,%s"}}]}],"max_completion_tokens":8,"temperature":0}' \
-    "$MODEL_ID" "$LITERTLM_PROBE_JPEG_B64" > "$_body" 2>/dev/null || return 1
-  _code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 180 \
-    -X POST "http://127.0.0.1:$SERVE_PORT/v1/chat/completions" \
-    -H 'Content-Type: application/json' --data-binary @"$_body" 2>/dev/null)
-  rm -f "$_body" 2>/dev/null || true
-  [ "$_code" = "200" ]
-}
+verify_litertlm_plain_inference() { verify_litertlm_probe "$MODEL_ID"; }
 
 local_ai_healthy() {
   curl -fsS --max-time 3 "http://127.0.0.1:$SERVE_PORT/v1/models" 2>/dev/null \
@@ -334,11 +341,33 @@ verify_bundled_model() {
   [ -f "$BUNDLED_MODEL_SHA" ] || fail "bundled model checksum is missing"
   EXPECTED_SHA="$(awk 'NR == 1 { print $1 }' "$BUNDLED_MODEL_SHA" 2>/dev/null || echo '')"
   ACTUAL_SHA="$(shasum -a 256 "$BUNDLED_MODEL" 2>/dev/null | awk '{print $1}')"
-  if [ -z "$EXPECTED_SHA" ] || [ "$ACTUAL_SHA" != "$EXPECTED_SHA" ]; then
+  if [ "$EXPECTED_SHA" != "$APPROVED_MODEL_SHA256" ] || [ "$ACTUAL_SHA" != "$APPROVED_MODEL_SHA256" ]; then
     fail "bundled model checksum mismatch"
   fi
   log "verified bundled model SHA-256"
 }
+installed_model_verified() {
+  [ -f "$STORE_DIR/model.litertlm" ] || return 1
+  [ "$(shasum -a 256 "$STORE_DIR/model.litertlm" 2>/dev/null | awk '{print $1}')" = "$APPROVED_MODEL_SHA256" ]
+}
+import_verified_model() {
+  local source="$1" old_sha rollback
+  [ "$(shasum -a 256 "$source" 2>/dev/null | awk '{print $1}')" = "$APPROVED_MODEL_SHA256" ] || return 1
+  if [ -f "$STORE_DIR/model.litertlm" ] && ! installed_model_verified; then
+    old_sha="$(shasum -a 256 "$STORE_DIR/model.litertlm" | awk '{print $1}')"
+    rollback="$STORE_DIR/rollback/$old_sha.litertlm"
+    mkdir -p "$STORE_DIR/rollback" || return 1
+    [ -f "$rollback" ] || cp "$STORE_DIR/model.litertlm" "$rollback" || return 1
+    [ "$(shasum -a 256 "$rollback" | awk '{print $1}')" = "$old_sha" ] || return 1
+    if launch_agent_loaded; then
+      launchctl bootout "gui/$(id -u)/$SERVE_LABEL" >>"$LOG" 2>&1 || return 1
+      wait_for_launch_agent_removal || return 1
+    fi
+    log "previous model preserved at $rollback"
+  fi
+  "$LITERTLM" import "$source" "$MODEL_ID" >>"$LOG" 2>&1 || return 1
+  installed_model_verified
+}
 
 # One provisioning process per user. Re-opening the pairing helper is a normal
 # recovery path, so duplicate launches must collapse without duplicate downloads.
@@ -351,7 +380,7 @@ if ! mkdir "$LOCK_DIR" 2>/dev/null; then
     log "LiteRT-LM provisioning is already running (pid $LOCK_PID)"
     if [ "$REQUIRE_BUNDLED_MODEL" = "1" ]; then
       for _attempt in $(seq 1 120); do
-        local_ai_healthy && exit 0
+        local_ai_healthy && installed_model_verified && (verify_litertlm_vision || verify_litertlm_plain_inference) && exit 0
         sleep 2
       done
       fail "the existing local AI installation did not become healthy"
@@ -468,12 +497,12 @@ fi
 
 install_litertlm_shim || true
 
-# 3. Model - import the verified bundled file. Idempotent: skip entirely if
-#    litert-lm already has the model. Engineering runs may use HF only with the
+# 3. Model - skip only if the installed BYTES match the approved artifact.
+#    Engineering runs may use the immutable HF revision only with the
 #    explicit TRILLBOARDS_ALLOW_MODEL_DOWNLOAD=1 opt-in.
 HAVE_MODEL=0
-if "$LITERTLM" list 2>/dev/null | grep -q "$MODEL_ID"; then
-  log "model $MODEL_ID already present — skipping import"
+if installed_model_verified; then
+  log "approved model $MODEL_ID already present — skipping import"
   HAVE_MODEL=1
   if [ -f "$BUNDLED_MODEL" ]; then
     verify_bundled_model
@@ -483,7 +512,7 @@ if "$LITERTLM" list 2>/dev/null | grep -q "$MODEL_ID"; then
 elif [ -f "$BUNDLED_MODEL" ]; then
   verify_bundled_model
   log "importing $MODEL_ID from BUNDLED file $BUNDLED_MODEL (no download) …"
-  if "$LITERTLM" import "$BUNDLED_MODEL" "$MODEL_ID" >>"$LOG" 2>&1; then
+  if import_verified_model "$BUNDLED_MODEL"; then
     log "model imported from bundle"
     HAVE_MODEL=1
     # Reclaim the staged ~2.4 GB — the litert-lm store now holds the model.
@@ -497,12 +526,19 @@ fi
 if [ "$HAVE_MODEL" -eq 0 ]; then
   [ "$REQUIRE_BUNDLED_MODEL" = "1" ] && fail "required bundled model is missing"
   [ "$ALLOW_MODEL_DOWNLOAD" = "1" ] || fail "local AI model is missing and network fallback is disabled"
-  log "importing $MODEL_ID from $HF_REPO (~2.4 GB, public repo) …"
-  "$LITERTLM" import --from-huggingface-repo "$HF_REPO" "$MODEL_ID" >>"$LOG" 2>&1 \
-    && { log "model imported from HF"; HAVE_MODEL=1; } \
-    || log "WARN: model import failed (serve will retry on next run)"
+  mkdir -p "$STORE_DIR" || fail "model store is unavailable"
+  DOWNLOAD="$(mktemp "$STORE_DIR/approved-model.XXXXXX")" || fail "could not create a model download file"
+  log "downloading approved $MODEL_ID from immutable revision $MODEL_REVISION"
+  if curl -fL --retry 3 --output "$DOWNLOAD" "$MODEL_URL" >>"$LOG" 2>&1 && import_verified_model "$DOWNLOAD"; then
+    HAVE_MODEL=1
+    rm -f "$DOWNLOAD"
+    log "model imported from verified immutable revision"
+  else
+    rm -f "$DOWNLOAD"
+    fail "approved model download/import failed"
+  fi
 fi
-[ "$HAVE_MODEL" -eq 1 ] || { [ "$REQUIRE_BUNDLED_MODEL" = "1" ] && fail "local AI model is unavailable"; }
+[ "$HAVE_MODEL" -eq 1 ] || fail "local AI model is unavailable"
 
 # Record the installed version next to the store model so the connector's
 # edge-core ModelManager seeds it (readBundledModelVersion) and does not

package/deploy/macos/test-setup-litertlm-reinstall.sh

@@ -10,9 +10,29 @@ export HOME="$TEST_ROOT/home"
 export TRILLBOARDS_TEST_STATE_DIR="$TEST_ROOT/state"
 export LITERT_LM_DIR="$TEST_ROOT/store"
 export TRILLBOARDS_REQUIRE_BUNDLED_MODEL=1
+export TRILLBOARDS_TEST_REAL_PYTHON="${TRILLBOARDS_TEST_REAL_PYTHON:-$(command -v python3)}"
 FAKE_BIN="$HOME/.local/bin"
 SHARE_DIR="$HOME/Library/Trillboards/edge/share"
 mkdir -p "$FAKE_BIN" "$SHARE_DIR" "$TRILLBOARDS_TEST_STATE_DIR"
+mkdir -p "$TRILLBOARDS_TEST_STATE_DIR/tools/litert-lm/bin" "$LITERT_LM_DIR/models/gemma-4-E2B-it.litertlm"
+printf 'fixture evaluated model\n' >"$LITERT_LM_DIR/models/gemma-4-E2B-it.litertlm/model.litertlm"
+
+# These are tiny installer fixtures, not model-inference/accuracy tests. Hashes
+# are simulated from file CONTENT, so the same name with old bytes is rejected.
+cat >"$FAKE_BIN/shasum" <<'EOF'
+#!/bin/bash
+file="${@: -1}"
+if [ -f "$file" ] && [ "$(cat "$file")" = 'fixture evaluated model' ]; then
+  printf 'ab7838cdfc8f77e54d8ca45eadceb20452d9f01e4bfade03e5dce27911b27e42  %s\n' "$file"
+else
+  if [ -x /usr/bin/shasum ]; then /usr/bin/shasum "$@"; else /usr/bin/sha256sum "$file"; fi
+fi
+EOF
+cat >"$TRILLBOARDS_TEST_STATE_DIR/tools/litert-lm/bin/python" <<'EOF'
+#!/bin/bash
+[ "${1:-}" != '-c' ] || exit 0
+exec "$TRILLBOARDS_TEST_REAL_PYTHON" "$@"
+EOF
 
 cat >"$FAKE_BIN/uname" <<'EOF'
 #!/bin/bash
@@ -25,14 +45,20 @@ EOF
 
 cat >"$FAKE_BIN/uv" <<'EOF'
 #!/bin/bash
+[ "${1:-} ${2:-}" != 'tool dir' ] || printf '%s\n' "$TRILLBOARDS_TEST_STATE_DIR/tools"
 exit 0
 EOF
 
 cat >"$FAKE_BIN/litert-lm" <<'EOF'
 #!/bin/bash
-if [ "${1:-}" = "list" ]; then
-  printf 'gemma-4-E2B-it.litertlm\n'
-fi
+case "${1:-}" in
+  list) printf 'gemma-4-E2B-it.litertlm\n' ;;
+  --version) printf 'litert-lm 0.16.0\n' ;;
+  import)
+    cp "$2" "$LITERT_LM_DIR/models/$3/model.litertlm"
+    printf 'import\n' >>"$TRILLBOARDS_TEST_STATE_DIR/imports"
+    ;;
+esac
 exit 0
 EOF
 
@@ -54,15 +80,21 @@ EOF
 cat >"$FAKE_BIN/curl" <<'EOF'
 #!/bin/bash
 body=""
+response=""
 prev=""
 for arg in "$@"; do
   case "$prev" in
     --data-binary) body="${arg#@}" ;;
+    -o) response="$arg" ;;
   esac
   prev="$arg"
 done
 for arg in "$@"; do
   if [ "$arg" = "-w" ]; then
+    model="$(sed -n 's/.*"model":"\([^"]*\)".*/\1/p' "$body")"
+    case "$model" in *,gpu|*,cpu) ;; *) model="$model,cpu" ;; esac
+    sha="${TRILLBOARDS_TEST_PROOF_SHA:-ab7838cdfc8f77e54d8ca45eadceb20452d9f01e4bfade03e5dce27911b27e42}"
+    printf '{"runtimeModel":{"version":1,"format":"litert-lm","sha256":"%s","runtimeModelId":"%s"}}' "$sha" "$model" >"$response"
     if [ "${TRILLBOARDS_TEST_FAIL_WHEN_SPECULATIVE:-0}" = "1" ] \
        && grep -Fq '"speculative_decoding":true' "$LITERT_LM_DIR/config.json" 2>/dev/null; then
       printf '500'
@@ -127,7 +159,8 @@ exit 0
 EOF
 
 chmod +x "$FAKE_BIN/uname" "$FAKE_BIN/uv" "$FAKE_BIN/litert-lm" \
-  "$FAKE_BIN/curl" "$FAKE_BIN/sleep" "$FAKE_BIN/launchctl"
+  "$FAKE_BIN/curl" "$FAKE_BIN/sleep" "$FAKE_BIN/launchctl" "$FAKE_BIN/shasum" \
+  "$TRILLBOARDS_TEST_STATE_DIR/tools/litert-lm/bin/python"
 
 cat >"$SHARE_DIR/com.trillboards.litertlm.plist" <<'EOF'
 <plist><string>__LITERTLM__</string><string>__PORT__</string><string>__LOG_DIR__</string></plist>
@@ -247,5 +280,25 @@ fi
 
 unset TRILLBOARDS_TEST_FAIL_WHEN_SPECULATIVE
 
+# An existing model under the SAME id must be replaced when its bytes differ,
+# with a checked rollback copy. The fixture importer performs a real file copy.
+printf 'fixture old model\n' >"$LITERT_LM_DIR/models/gemma-4-E2B-it.litertlm/model.litertlm"
+old_sha="$("$FAKE_BIN/shasum" -a 256 "$LITERT_LM_DIR/models/gemma-4-E2B-it.litertlm/model.litertlm" | awk '{print $1}')"
+mkdir -p "$SHARE_DIR/models"
+printf 'fixture evaluated model\n' >"$SHARE_DIR/models/gemma-4-E2B-it.litertlm"
+printf 'ab7838cdfc8f77e54d8ca45eadceb20452d9f01e4bfade03e5dce27911b27e42\n' >"$SHARE_DIR/models/gemma-4-E2B-it.litertlm.sha256"
+if ! OUTPUT4="$(/bin/bash "$SETUP" 2>&1)"; then printf '%s\n' "$OUTPUT4" >&2; exit 1; fi
+[ "$(cat "$LITERT_LM_DIR/models/gemma-4-E2B-it.litertlm/model.litertlm")" = 'fixture evaluated model' ]
+[ "$("$FAKE_BIN/shasum" -a 256 "$LITERT_LM_DIR/models/gemma-4-E2B-it.litertlm/rollback/$old_sha.litertlm" | awk '{print $1}')" = "$old_sha" ]
+[ "$(wc -l <"$TRILLBOARDS_TEST_STATE_DIR/imports" | tr -d ' ')" = '1' ]
+# A correct store and a 200 inference must still fail when the loaded engine's
+# identity differs. This catches a stale in-memory model after an upgrade.
+export TRILLBOARDS_TEST_PROOF_SHA="181938105e0eefd105961417e8da75903eacda102c4fce9ce90f50b97139a63c"
+if OUTPUT5="$(/bin/bash "$SETUP" 2>&1)"; then
+  printf 'FAIL: setup accepted a stale runtime model proof\n' >&2
+  exit 1
+fi
+unset TRILLBOARDS_TEST_PROOF_SHA
+
 printf 'macOS LiteRT-LM reinstall race + engine-settings cascade regressions passed\n'
 

package/deploy/systemd/setup-detector.sh

@@ -93,7 +93,7 @@ SOURCE="$(find_detector_source)" || { log "ERROR: detector package source not fo
 # 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 --refresh-package trillboards-detector "$SOURCE" >>"$LOG" 2>&1; then
+if ! "$UV" tool install --python "$DETECTOR_PYTHON" --managed-python --force --refresh-package trillboards-detector "${SOURCE}[cpu]" >>"$LOG" 2>&1; then
   log "ERROR: trillboards-detector install failed; the cascade stays off"
   exit 0
 fi
@@ -126,7 +126,7 @@ elif [ "$HAVE_VERSION" != "$WANT_VERSION" ]; then
   # 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
+  "$UV" tool install --python "$DETECTOR_PYTHON" --managed-python --force --refresh-package trillboards-detector "${SOURCE}[cpu]" >>"$LOG" 2>&1 || true
   DETECTOR="$LOCAL_BIN/trillboards-detector"
   [ -x "$DETECTOR" ] || DETECTOR="$(command -v trillboards-detector || echo "$DETECTOR")"
   HAVE_VERSION="$(installed_detector_version)"

package/deploy/systemd/setup-litertlm.sh

@@ -37,6 +37,9 @@ LOG_DIR="${TRILLBOARDS_LOG_DIR:-/var/log/trillboards}"
 LOCAL_BIN="$USER_HOME/.local/bin"
 MODEL_ID="gemma-4-E2B-it.litertlm"
 HF_REPO="litert-community/gemma-4-E2B-it-litert-lm"
+MODEL_REVISION="84b6978eff6e4eea02825bc2ee4ea48579f13109"
+APPROVED_MODEL_SHA256="ab7838cdfc8f77e54d8ca45eadceb20452d9f01e4bfade03e5dce27911b27e42"
+MODEL_URL="https://huggingface.co/$HF_REPO/resolve/$MODEL_REVISION/$MODEL_ID"
 SERVE_PORT="9379"
 SERVE_UNIT="trillboards-litertlm"
 LITERT_PYTHON="${LITERT_LM_PYTHON:-3.12}"
@@ -253,16 +256,29 @@ install_litertlm_shim() {
 # Deliberately NOT a /v1/models check: that answers 200 without ever building an
 # engine, so it cannot tell a working GPU encoder from one that fails on first
 # use.
-verify_litertlm_vision() {
-  _body="$LITERT_DIR/.vision-probe.json"
-  printf '{"model":"%s,gpu","messages":[{"role":"user","content":[{"type":"text","text":"Reply with the single word: ok"},{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,%s"}}]}],"max_completion_tokens":8,"temperature":0}' \
-    "$MODEL_ID" "$LITERTLM_PROBE_JPEG_B64" > "$_body" 2>/dev/null || return 1
-  _code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 180 \
+verify_litertlm_probe() {
+  local requested="$1" body response code tool_dir py verifier candidate valid=1
+  body="$LITERT_DIR/.identity-probe.json"
+  response="$LITERT_DIR/.identity-response.json"
+  printf '{"model":"%s","messages":[{"role":"user","content":[{"type":"text","text":"Reply with the single word: ok"},{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,%s"}}]}],"max_completion_tokens":8,"temperature":0}' \
+    "$requested" "$LITERTLM_PROBE_JPEG_B64" > "$body" 2>/dev/null || return 1
+  code=$(curl -s -o "$response" -w '%{http_code}' --max-time 180 \
     -X POST "http://127.0.0.1:$SERVE_PORT/v1/chat/completions" \
-    -H 'Content-Type: application/json' --data-binary @"$_body" 2>/dev/null)
-  rm -f "$_body" 2>/dev/null || true
-  [ "$_code" = "200" ]
+    -H 'Content-Type: application/json' -H "X-Trillboards-Model-Sha256: $APPROVED_MODEL_SHA256" \
+    --data-binary @"$body" 2>/dev/null)
+  if [ "$code" = "200" ]; then
+    tool_dir="$("${UV:-$LOCAL_BIN/uv}" tool dir 2>/dev/null | tr -d '\r')"
+    py="$tool_dir/litert-lm/bin/python"
+    for candidate in "$SCRIPT_DIR/verify_model_proof.py" "$SCRIPT_DIR/../litertlm/verify_model_proof.py" "$SCRIPT_DIR/../../litertlm/verify_model_proof.py"; do
+      [ -f "$candidate" ] && { verifier="$candidate"; break; }
+    done
+    [ -n "${verifier:-}" ] && [ -x "$py" ] \
+      && "$py" "$verifier" "$response" "$requested" "$APPROVED_MODEL_SHA256" && valid=0
+  fi
+  rm -f "$body" "$response" 2>/dev/null || true
+  return "$valid"
 }
+verify_litertlm_vision() { verify_litertlm_probe "$MODEL_ID,gpu"; }
 
 # The same probe, but asking for NO delegate suffix rather than `,gpu`.
 #
@@ -273,16 +289,7 @@ verify_litertlm_vision() {
 # carries no suffix at all, so a 200 means the box built an engine and ran a real
 # image through it under the config now on disk, which is exactly the claim each
 # rung needs.
-verify_litertlm_plain_inference() {
-  _body="$LITERT_DIR/.plain-probe.json"
-  printf '{"model":"%s","messages":[{"role":"user","content":[{"type":"text","text":"Reply with the single word: ok"},{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,%s"}}]}],"max_completion_tokens":8,"temperature":0}' \
-    "$MODEL_ID" "$LITERTLM_PROBE_JPEG_B64" > "$_body" 2>/dev/null || return 1
-  _code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 180 \
-    -X POST "http://127.0.0.1:$SERVE_PORT/v1/chat/completions" \
-    -H 'Content-Type: application/json' --data-binary @"$_body" 2>/dev/null)
-  rm -f "$_body" 2>/dev/null || true
-  [ "$_code" = "200" ]
-}
+verify_litertlm_plain_inference() { verify_litertlm_probe "$MODEL_ID"; }
 
 local_ai_healthy() {
   curl -fsS --max-time 3 "http://127.0.0.1:$SERVE_PORT/v1/models" 2>/dev/null \
@@ -362,20 +369,37 @@ fi
 
 install_litertlm_shim || true
 
-# 3. Model. Idempotent: skip entirely if litert-lm already has it.
+# 3. Model: a matching name is not a matching artifact. Upgrade from the immutable
+# revision, preserve the old bytes, and verify the installed copy.
 HAVE_MODEL=0
-if "$LITERTLM" list 2>/dev/null | grep -q "$MODEL_ID"; then
-  log "model $MODEL_ID already present — skipping import"
+INSTALLED_SHA="$(sha256sum "$STORE_DIR/model.litertlm" 2>/dev/null | awk '{print $1}')"
+if [ "$INSTALLED_SHA" = "$APPROVED_MODEL_SHA256" ]; then
+  log "approved model $MODEL_ID already present — skipping import"
   HAVE_MODEL=1
 else
   [ "$ALLOW_MODEL_DOWNLOAD" = "1" ] || fail "local AI model is missing and the network import is disabled"
-  log "importing $MODEL_ID from $HF_REPO (~2.4 GB, public repo) — this takes a while"
-  if "$LITERTLM" import --from-huggingface-repo "$HF_REPO" "$MODEL_ID" >>"$LOG" 2>&1; then
-    log "model imported"
-    HAVE_MODEL=1
-  else
-    fail "model import failed — the connector will WAIT (and beacon) until this succeeds"
+  mkdir -p "$STORE_DIR" || fail "model store is unavailable"
+  DOWNLOAD="$(mktemp "$STORE_DIR/approved-model.XXXXXX")" || fail "could not create a model download file"
+  log "downloading approved $MODEL_ID from immutable revision $MODEL_REVISION"
+  if ! curl -fL --retry 3 --output "$DOWNLOAD" "$MODEL_URL" >>"$LOG" 2>&1 \
+    || [ "$(sha256sum "$DOWNLOAD" | awk '{print $1}')" != "$APPROVED_MODEL_SHA256" ]; then
+    rm -f "$DOWNLOAD"
+    fail "approved model download/checksum failed"
+  fi
+  if [ -n "$INSTALLED_SHA" ]; then
+    ROLLBACK="$STORE_DIR/rollback/$INSTALLED_SHA.litertlm"
+    mkdir -p "$STORE_DIR/rollback" || fail "could not preserve previous model"
+    [ -f "$ROLLBACK" ] || cp "$STORE_DIR/model.litertlm" "$ROLLBACK" || fail "could not preserve previous model"
+    [ "$(sha256sum "$ROLLBACK" | awk '{print $1}')" = "$INSTALLED_SHA" ] || fail "previous model backup verification failed"
   fi
+  if ! "$LITERTLM" import "$DOWNLOAD" "$MODEL_ID" >>"$LOG" 2>&1 \
+    || [ "$(sha256sum "$STORE_DIR/model.litertlm" | awk '{print $1}')" != "$APPROVED_MODEL_SHA256" ]; then
+    rm -f "$DOWNLOAD"
+    fail "approved model import verification failed — the connector will WAIT until this succeeds"
+  fi
+  rm -f "$DOWNLOAD"
+  HAVE_MODEL=1
+  log "model imported from verified immutable revision"
 fi
 
 # Record the installed version next to the store model so the connector's

package/deploy/windows/build-windows.ps1

@@ -16,11 +16,11 @@
       bin\trillboards-pair.cmd   first-run claim-code pairing helper
       lib\edge-sdk\dist\cli.js   the connector CLI
       lib\node_modules\...       runtime subset (edge-core + edge-platform-rtsp +
-                                 edge-sdk + transitive deps), WITHOUT the heavy
-                                 local ONNX/sharp/sqlite inference stack.
+                                 edge-sdk + transitive deps, including Sharp for
+                                 focused image masks), WITHOUT local ONNX/sqlite.
 
-  The connector is loaded WITHOUT the heavy ONNX/sharp/sqlite stack (cli.ts
-  lazy-requires EdgeAgent), so the bundle omits onnxruntime-node/sharp/
+  The connector is loaded WITHOUT the heavy ONNX/sqlite stack (cli.ts
+  lazy-requires EdgeAgent), so the bundle omits onnxruntime-node/
   better-sqlite3 — keeping the inner .exe small. The release workflow signs this
   connector installer, then bundle-windows-installer.ps1 wraps it with the
   pinned Gemma model in one customer-facing executable. The inner installer
@@ -107,6 +107,7 @@ Push-Location $WorkspaceRoot; npm run build; if ($LASTEXITCODE -ne 0) { Die "edg
 Log "Staging edge-sdk dist…"
 New-Item -ItemType Directory -Force -Path "$Payload\lib\edge-sdk" | Out-Null
 Copy-Item -Recurse -Force "$PkgRoot\dist" "$Payload\lib\edge-sdk\dist"
+Copy-Item -Recurse -Force "$PkgRoot\retained" "$Payload\lib\edge-sdk\retained"
 Copy-Item -Force "$PkgRoot\package.json" "$Payload\lib\edge-sdk\package.json"
 
 # ─── 3. Runtime node_modules subset (NO heavy native stack) ────────────────────
@@ -123,9 +124,11 @@ Copy-Item -Force "$PkgRoot\package.json" "$Payload\lib\edge-sdk\package.json"
 # the job was killed at its timeout on EVERY release run, so the .exe never
 # published. /MT parallelises the small-file copy; /R:1 /W:1 bound retries so a
 # single transiently-locked file can't trigger robocopy's default 1e6×30s hang.
-Log "Staging runtime node_modules (excluding ONNX/sharp/sqlite/dev)…"
+Log "Staging runtime node_modules (including focused-image masks; excluding ONNX/sqlite/dev)…"
 New-Item -ItemType Directory -Force -Path "$Payload\lib\node_modules" | Out-Null
-$xd = @("onnxruntime-node","sharp","@img","better-sqlite3","ffmpeg-static",".cache",".bin","typescript","jest","jest-cli","@jest","ts-jest","@types")
+# Focused retained reviews use Sharp to mask pixels, not just prompt geometry.
+# Keep its platform-native dependencies; detectors still use the local HTTP service.
+$xd = @("onnxruntime-node","better-sqlite3","ffmpeg-static",".cache",".bin","typescript","jest","jest-cli","@jest","ts-jest","@types")
 $rcArgs = @("$WorkspaceRoot\node_modules", "$Payload\lib\node_modules", "/E", "/XJ", "/MT:16", "/R:1", "/W:1", "/NFL","/NDL","/NJH","/NJS","/NP")
 foreach ($d in $xd) { $rcArgs += @("/XD", $d) }
 robocopy @rcArgs | Out-Null
@@ -141,6 +144,7 @@ foreach ($p in @("edge-core","edge-sensing","edge-ads","edge-federated","edge-cl
   if (Test-Path $dest) { Remove-Item -Recurse -Force $dest }
   New-Item -ItemType Directory -Force -Path $dest | Out-Null
   if (Test-Path "$src\dist") { Copy-Item -Recurse -Force "$src\dist" "$dest\dist" }
+  if ($p -eq 'edge-sdk') { Copy-Item -Recurse -Force "$src\retained" "$dest\retained" }
   Copy-Item -Force "$src\package.json" "$dest\package.json"
 }
 

package/deploy/windows/bundle-windows-installer.ps1

@@ -15,8 +15,8 @@ param(
   [Parameter(Mandatory = $true)][string]$InnerInstaller,
   [string]$OutputPath = "",
   [string]$ModelPath = "",
-  [string]$ModelUrl = "https://huggingface.co/litert-community/gemma-4-E2B-it-litert-lm/resolve/main/gemma-4-E2B-it.litertlm",
-  [string]$ModelSha256 = "181938105e0eefd105961417e8da75903eacda102c4fce9ce90f50b97139a63c",
+  [string]$ModelUrl = "https://huggingface.co/litert-community/gemma-4-E2B-it-litert-lm/resolve/84b6978eff6e4eea02825bc2ee4ea48579f13109/gemma-4-E2B-it.litertlm",
+  [string]$ModelSha256 = "ab7838cdfc8f77e54d8ca45eadceb20452d9f01e4bfade03e5dce27911b27e42",
   [string]$SevenZipSdkUrl = "https://www.7-zip.org/a/lzma2602.7z",
   [string]$SevenZipSdkSha256 = "2878c85f5f43a4a4e0952b1fd4e5fe097c1c143997a8047c7e1e788892aa9357",
   [string]$IconPath = ""
@@ -87,7 +87,7 @@ if (-not $sfxModule) { Fail "official 7zSD.sfx installer module was not found" }
 # Brand the executable module before appending the config and archive. This
 # keeps the SFX overlay byte-for-byte intact and the final Authenticode signing
 # step covers both the application icon and the customer payload.
-& (Join-Path $Here "set-executable-icon.ps1") -ExecutablePath $sfxModule.FullName -IconPath $IconPath
+& (Join-Path $Here "set-executable-icon.ps1") -ExecutablePath $sfxModule.FullName -IconPath $IconPath -EnsurePerUserExecution
 
 $innerName = "TrillboardsEdgeSetup-core.exe"
 Copy-Item -LiteralPath $InnerInstaller -Destination (Join-Path $Stage $innerName) -Force

package/deploy/windows/e2e/test-local-sense.ps1

@@ -12,11 +12,12 @@
   wiring (DEFAULT, runs on EVERY CI event incl. PRs):
     Builds the connector, then runs the cross-platform Node wiring runner
     (scripts/run-local-sense-wiring-e2e.mjs) which drives the REAL built
-    `cli.js local-sense` against a STUB :9379 VLM (returns a fixed valid Gemma
-    JSON, person_count>=1) + a STUB ingest API, feeding the committed person
-    fixture through the connector's real RTSP/ffmpeg path. Proves the
-    connector → serve → preAnalyzed → assert plumbing WITHOUT the ~2.4 GB model.
-    This is a STUB-VLM proof — NOT a real-model proof.
+    `cli.js local-sense` against STUB local VLM/detector services and an
+    authenticated retained capability/profile/ingest API, feeding the committed
+    fixture through real RTSP/ffmpeg. Checks declared field ownership, pinned
+    requests and original evidence/hash/capture time with the genuine retained
+    protocol parser/acknowledgement, WITHOUT downloading the real models.
+    This is a STUB-MODEL wiring proof — NOT an inference-accuracy proof.
 
   bench (workflow_dispatch only):
     Provisions exactly as 'real' does, then runs scripts/bench-local-vlm.mjs

package/deploy/windows/install-update.ps1

@@ -56,12 +56,10 @@ function Register-Connector([string]$Root) {
   2026-08-19 Windows BOM incident, and it is why this is here rather than left
   to the repair path.
 
-  RE-REGISTER, NOT RE-PROVISION. `setup-detector.ps1` runs `uv tool install
-  --force`, which rebuilds a venv and needs the network; putting that inside an
-  update transaction would give the upgrade a new way to be slow and a new way
-  to fail. Re-registering the task is the whole of what has to change, and
-  register-detector-task.ps1 already stops the running service, replaces the
-  action and starts it again - so this both migrates and restarts it.
+  Re-register when the runtime source stamp matches. When it differs, run the
+  owned provisioner so a healthy old CPU-only service cannot survive a GPU
+  update indefinitely. The provisioner serializes replacement, verifies its
+  installed stamp and chooses one CPU/CUDA dependency set. Pairings stay intact.
 
   BEST EFFORT, ALWAYS. The detector is a cost optimisation: without it every
   frame goes to the VLM exactly as it does today. It must never be able to fail
@@ -77,6 +75,47 @@ function Update-DetectorTask([string]$Root) {
     # register-task.ps1 states for its own repair.
     $exe = ($task.Actions | Select-Object -First 1).Execute
     if (-not $exe) { return }
+    # Older updater array-splatting bound the text '-DetectorPath' positionally
+    # as the executable, shifting the real path into --port. Recover ONLY this
+    # known shape, under the current user's SID and exact local tool path.
+    if ($exe -eq '-DetectorPath') {
+      $taskUser = [string]$task.Principal.UserId
+      $taskSid = if ($taskUser -match '^S-1-') { $taskUser } else {
+        (New-Object System.Security.Principal.NTAccount($taskUser)).Translate([System.Security.Principal.SecurityIdentifier]).Value
+      }
+      $currentSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+      $oldArgs = [string]($task.Actions | Select-Object -First 1).Arguments
+      $ownTool = Join-Path $env:USERPROFILE '.local\bin\trillboards-detector.exe'
+      if ($taskSid -ne $currentSid -or $oldArgs -notmatch '^serve --host 127\.0\.0\.1 --port (.+?) --log-file "-RamBudgetMb" --ram-budget-mb \d+$') {
+        throw 'Cannot verify ownership of the malformed detector task'
+      }
+      $recovered = $Matches[1]
+      if ([IO.Path]::GetFullPath($recovered) -ine [IO.Path]::GetFullPath($ownTool) -or -not (Test-Path -LiteralPath $ownTool)) {
+        throw 'Malformed detector task does not identify this user installation'
+      }
+      $exe = $ownTool
+    }
+
+    $detectorSource = Join-Path $Root 'bin\detector'
+    $project = Join-Path $detectorSource 'pyproject.toml'
+    $setup = Join-Path $Root 'bin\setup-detector.ps1'
+    if ((Test-Path -LiteralPath $project) -and (Test-Path -LiteralPath $setup)) {
+      $versionLine = @(Get-Content -LiteralPath $project | Where-Object { $_ -match '^version\s*=\s*"([^"]+)"\s*$' })
+      if ($versionLine.Count -ne 1 -or $versionLine[0] -notmatch '^version\s*=\s*"([^"]+)"\s*$') {
+        throw 'Cannot resolve the staged detector source version'
+      }
+      $stagedDetectorVersion = $Matches[1]
+      $installedDetectorVersion = ((& $exe --version 2>$null | Out-String).Trim() -split '\s+')[-1]
+      if ($LASTEXITCODE -ne 0 -or $installedDetectorVersion -ne $stagedDetectorVersion) {
+        Write-Host "Updating the managed detector runtime to $stagedDetectorVersion."
+        & $setup -SourcePath $detectorSource
+        $verifiedDetectorVersion = ((& $exe --version 2>$null | Out-String).Trim() -split '\s+')[-1]
+        if ($LASTEXITCODE -ne 0 -or $verifiedDetectorVersion -ne $stagedDetectorVersion) {
+          throw 'Detector runtime update did not verify; pairing preserved, local detector needs repair'
+        }
+        return # the owned provisioner already registered and restarted the task
+      }
+    }
 
     $register = Join-Path $Root "bin\register-detector-task.ps1"
     if (-not (Test-Path -LiteralPath $register)) { return }
@@ -93,12 +132,16 @@ function Update-DetectorTask([string]$Root) {
       if ($LASTEXITCODE -eq 0 -and $derived -match '^\d+$') { $budget = $derived }
     }
 
-    $registerArgs = @('-DetectorPath', $exe)
-    if ($budget) { $registerArgs += @('-RamBudgetMb', $budget) }
+    # A PowerShell SCRIPT takes named parameters from a hashtable. An array of
+    # flag strings is positional; it creates Execute='-DetectorPath' while
+    # reporting registration success. Native powershell.exe argument arrays
+    # elsewhere are a different boundary and must not be changed with this.
+    $registerArgs = @{ DetectorPath = $exe }
+    if ($budget) { $registerArgs.RamBudgetMb = $budget }
     & $register @registerArgs | Out-Null
     Write-Host "Detector task migrated$(if ($budget) { " (RAM ceiling $budget MiB)" })."
   } catch {
-    Write-Warning "Could not migrate the detector task: $($_.Exception.Message). Sensing is unaffected; every frame keeps going to the VLM."
+    Write-Warning "Could not migrate the detector task: $($_.Exception.Message). Detector-backed profiles need the local detector repaired; camera pairing is preserved."
   }
 }