@trillboards/edge-sdk 0.2.138 → 0.2.150

package/deploy/macos/TrillboardsSetupApp.m

@@ -40,6 +40,14 @@ static BOOL acquireSetupInstanceLock(void) {
 
 @interface TrillboardsSetupDelegate : NSObject <NSApplicationDelegate, NSWindowDelegate, WKNavigationDelegate, WKUIDelegate>
 @property(nonatomic, strong) NSWindow *window;
+@property(nonatomic, strong) NSDictionary *guidanceCatalog;
+@property(nonatomic, strong) NSView *guidancePanel;
+@property(nonatomic, strong) NSTextField *guidanceTitle;
+@property(nonatomic, strong) NSTextField *guidanceBody;
+@property(nonatomic, strong) NSButton *guidanceToggle;
+@property(nonatomic, strong) NSButton *guidanceRestore;
+@property(nonatomic, strong) NSMutableSet<NSString *> *dismissedGuidance;
+
 @property(nonatomic, strong) NSFileHandle *setupOutput;
 @property(nonatomic, strong) NSMutableData *setupOutputBuffer;
 @property(nonatomic, strong) NSWindow *cameraWindow;
@@ -327,14 +335,14 @@ static BOOL acquireSetupInstanceLock(void) {
 
 - (void)buildWindow {
   self.window = [[NSWindow alloc]
-      initWithContentRect:NSMakeRect(0, 0, 760, 540)
+      initWithContentRect:NSMakeRect(0, 0, 760, 700)
                 styleMask:NSWindowStyleMaskTitled | NSWindowStyleMaskClosable | NSWindowStyleMaskMiniaturizable
                   backing:NSBackingStoreBuffered
                     defer:NO];
   self.window.title = @"Sense Anything Connector";
   self.window.delegate = self;
-  self.window.minSize = NSMakeSize(760, 540);
-  self.window.maxSize = NSMakeSize(760, 540);
+  self.window.minSize = NSMakeSize(760, 700);
+  self.window.maxSize = NSMakeSize(760, 700);
   [self.window center];
 
   NSView *root = self.window.contentView;
@@ -536,10 +544,85 @@ static BOOL acquireSetupInstanceLock(void) {
   [self.chooseAccountPanel addSubview:self.chooseAccountSubmit];
   [root addSubview:self.chooseAccountPanel];
 
+  // Reserve a separate help region; never cover native forms or recovery actions.
+  for (NSView *view in root.subviews) {
+    NSRect frame = view.frame;
+    frame.origin.y += 160;
+    view.frame = frame;
+  }
+  NSView *guideSidebar = [[NSView alloc] initWithFrame:NSMakeRect(0, 0, 190, 160)];
+  guideSidebar.wantsLayer = YES;
+  guideSidebar.layer.backgroundColor = NSColor.controlBackgroundColor.CGColor;
+  [root addSubview:guideSidebar];
+  NSString *guidePath = [NSBundle.mainBundle pathForResource:@"setup-guidance" ofType:@"json"];
+  NSData *guideData = guidePath ? [NSData dataWithContentsOfFile:guidePath] : nil;
+  id catalog = guideData ? [NSJSONSerialization JSONObjectWithData:guideData options:0 error:nil] : nil;
+  self.guidanceCatalog = [catalog isKindOfClass:NSDictionary.class] ? catalog : @{};
+  self.dismissedGuidance = [NSMutableSet set];
+  self.guidanceToggle = [NSButton checkboxWithTitle:@"Guiding tips" target:self action:@selector(toggleGuidance)];
+  self.guidanceToggle.frame = NSMakeRect(24, 118, 150, 24);
+  self.guidanceToggle.state = [NSUserDefaults.standardUserDefaults boolForKey:@"setupGuidingTipsDisabled"] ? NSControlStateValueOff : NSControlStateValueOn;
+  [root addSubview:self.guidanceToggle];
+  self.guidanceRestore = [self panelButton:@"Show this tip" frame:NSMakeRect(20, 80, 150, 28) action:@selector(restoreGuidance)];
+  [root addSubview:self.guidanceRestore];
+  self.guidancePanel = [[NSView alloc] initWithFrame:NSMakeRect(236, 12, 465, 145)];
+  self.guidancePanel.wantsLayer = YES;
+  self.guidancePanel.layer.backgroundColor = [NSColor colorWithCalibratedRed:1 green:0.96 blue:0.91 alpha:1].CGColor;
+  self.guidancePanel.layer.borderColor = [NSColor colorWithCalibratedRed:0.93 green:0.65 blue:0.40 alpha:1].CGColor;
+  self.guidancePanel.layer.borderWidth = 1;
+  self.guidancePanel.layer.cornerRadius = 10;
+  self.guidanceTitle = [self label:@"" size:13 weight:NSFontWeightSemibold frame:NSMakeRect(14, 94, 405, 40)];
+  self.guidanceBody = [self label:@"" size:12 weight:NSFontWeightRegular frame:NSMakeRect(14, 35, 435, 60)];
+  self.guidanceTitle.textColor = [NSColor colorWithCalibratedRed:0.28 green:0.20 blue:0.14 alpha:1];
+  self.guidanceBody.textColor = [NSColor colorWithCalibratedRed:0.38 green:0.29 blue:0.23 alpha:1];
+  [self.guidancePanel addSubview:self.guidanceTitle];
+  [self.guidancePanel addSubview:self.guidanceBody];
+  NSButton *dismiss = [self panelButton:@"×" frame:NSMakeRect(424, 110, 30, 26) action:@selector(dismissGuidance)];
+  dismiss.accessibilityLabel = @"Dismiss this tip";
+  [self.guidancePanel addSubview:dismiss];
+  [self.guidancePanel addSubview:[self panelButton:@"More help" frame:NSMakeRect(8, 5, 110, 26) action:@selector(showGuidanceDetail)]];
+  [root addSubview:self.guidancePanel];
+
   self.onboardingPanels = @[self.accountPanel, self.termsPanel, self.planPanel, self.chooseAccountPanel];
   [self showOnboardingPanel:nil];
 }
 
+- (void)renderGuidance {
+  NSDictionary *guide = self.guidanceCatalog[self.lastStage];
+  BOOL enabled = self.guidanceToggle.state == NSControlStateValueOn;
+  BOOL dismissed = [self.dismissedGuidance containsObject:self.lastStage];
+  self.guidancePanel.hidden = !enabled || dismissed || ![guide isKindOfClass:NSDictionary.class];
+  self.guidanceRestore.hidden = !enabled || !dismissed;
+  self.guidanceTitle.stringValue = [guide[@"title"] isKindOfClass:NSString.class] ? guide[@"title"] : @"";
+  self.guidanceBody.stringValue = [guide[@"body"] isKindOfClass:NSString.class] ? guide[@"body"] : @"";
+}
+
+- (void)toggleGuidance {
+  [NSUserDefaults.standardUserDefaults setBool:self.guidanceToggle.state != NSControlStateValueOn forKey:@"setupGuidingTipsDisabled"];
+  [self.dismissedGuidance removeAllObjects];
+  [self renderGuidance];
+}
+
+- (void)dismissGuidance {
+  [self.dismissedGuidance addObject:self.lastStage];
+  [self renderGuidance];
+}
+
+- (void)restoreGuidance {
+  [self.dismissedGuidance removeObject:self.lastStage];
+  [self renderGuidance];
+}
+
+- (void)showGuidanceDetail {
+  NSDictionary *guide = self.guidanceCatalog[self.lastStage];
+  if (![guide[@"detail"] isKindOfClass:NSString.class]) return;
+  NSAlert *alert = [[NSAlert alloc] init];
+  alert.messageText = self.guidanceTitle.stringValue;
+  alert.informativeText = guide[@"detail"];
+  [alert addButtonWithTitle:@"Got it"];
+  [alert beginSheetModalForWindow:self.window completionHandler:nil];
+}
+
 - (void)showOnboardingPanel:(NSView *)panel {
   for (NSView *candidate in self.onboardingPanels ?: @[]) candidate.hidden = candidate != panel;
   BOOL showStatus = panel == nil;
@@ -663,6 +746,7 @@ static BOOL acquireSetupInstanceLock(void) {
 - (void)showWelcome {
   [self showOnboardingPanel:nil];
   self.lastStage = @"welcome";
+  [self renderGuidance];
   self.headline.stringValue = @"Set up this computer for CCTV";
   self.detail.stringValue = @"Connect your Sense Anything account, find your recorder, and verify every camera before screens are created.";
   self.statusValue.stringValue = @"About 5 minutes";
@@ -678,6 +762,7 @@ static BOOL acquireSetupInstanceLock(void) {
 - (void)showLocalError:(NSString *)title message:(NSString *)message {
   [self showOnboardingPanel:nil];
   self.lastStage = @"error";
+  [self renderGuidance];
   self.headline.stringValue = title;
   self.detail.stringValue = message;
   self.statusValue.stringValue = @"Setup stopped";
@@ -763,6 +848,7 @@ static BOOL acquireSetupInstanceLock(void) {
         }
         self.requiredUpdateURL = downloadURL;
         self.lastStage = @"update_required";
+        [self renderGuidance];
         self.headline.stringValue = @"Update required before setup can continue";
         self.detail.stringValue = @"Install the latest Sense Anything Connector, then reopen it to finish camera setup.";
         self.statusValue.stringValue = [NSString stringWithFormat:@"Version %@", availableText];
@@ -835,6 +921,7 @@ static BOOL acquireSetupInstanceLock(void) {
   if (![files fileExistsAtPath:logPath]) [files createFileAtPath:logPath contents:nil attributes:nil];
 
   self.lastStage = @"starting";
+  [self renderGuidance];
   self.setupStarted = YES;
   self.headline.stringValue = @"Starting camera setup";
   self.detail.stringValue = @"Connecting securely to Sense Anything.";
@@ -868,6 +955,7 @@ static BOOL acquireSetupInstanceLock(void) {
   if (!stage) return;
   NSString *previousStage = self.lastStage;
   self.lastStage = stage;
+  [self renderGuidance];
   if ([state[@"portalUrl"] isKindOfClass:NSString.class]) self.portalURL = state[@"portalUrl"];
   if ([state[@"title"] isKindOfClass:NSString.class]) self.headline.stringValue = state[@"title"];
   if ([state[@"message"] isKindOfClass:NSString.class]) self.detail.stringValue = state[@"message"];
@@ -1168,6 +1256,43 @@ static BOOL acquireSetupInstanceLock(void) {
 
 @end
 
+static int runGuidanceSmokeTest(void) {
+  [NSApplication sharedApplication];
+  TrillboardsSetupDelegate *delegate = [[TrillboardsSetupDelegate alloc] init];
+  [delegate buildWindow];
+  if (delegate.guidanceCatalog.count == 0) return 1;
+  delegate.guidanceToggle.state = NSControlStateValueOn;
+  for (NSString *stage in delegate.guidanceCatalog) {
+    delegate.lastStage = stage;
+    [delegate renderGuidance];
+    if (delegate.guidancePanel.hidden || !delegate.guidanceTitle.stringValue.length) return 2;
+    for (NSTextField *field in @[delegate.guidanceTitle, delegate.guidanceBody]) {
+      NSRect textBounds = [field.attributedStringValue boundingRectWithSize:NSMakeSize(field.frame.size.width - 4, CGFLOAT_MAX)
+          options:NSStringDrawingUsesLineFragmentOrigin | NSStringDrawingUsesFontLeading];
+      if (textBounds.size.height > field.frame.size.height) {
+        fprintf(stderr, "Guidance text clipped at %s\n", stage.UTF8String);
+        return 3;
+      }
+    }
+    [delegate dismissGuidance];
+    if (!delegate.guidancePanel.hidden || delegate.guidanceRestore.hidden) return 4;
+    [delegate restoreGuidance];
+    if (delegate.guidancePanel.hidden) return 5;
+  }
+  delegate.lastStage = @"onboarding_terms";
+  delegate.termsCheck.state = NSControlStateValueOff;
+  delegate.termsSubmit.enabled = NO;
+  delegate.guidanceToggle.state = NSControlStateValueOff;
+  [delegate renderGuidance];
+  if (!delegate.guidancePanel.hidden || delegate.termsSubmit.enabled) return 6;
+  if (NSIntersectsRect(delegate.guidancePanel.frame, delegate.accountPanel.frame) ||
+      NSIntersectsRect(delegate.guidancePanel.frame, delegate.actionButton.frame)) return 7;
+  fprintf(stdout, "Native guidance stages, dismissal, text bounds and consent isolation passed.\n");
+  fflush(stdout);
+  [delegate.window close];
+  return 0;
+}
+
 static int runCancellationSmokeTest(void) {
   NSString *pidPath = [NSTemporaryDirectory()
       stringByAppendingPathComponent:[NSString stringWithFormat:@"trillboards-setup-child-%@.pid", NSUUID.UUID.UUIDString]];
@@ -1288,6 +1413,9 @@ int main(int argc, const char *argv[]) {
     if (argc == 3 && [[NSString stringWithUTF8String:argv[1]] isEqualToString:@"--smoke-test-ui-pipe"]) {
       return runNativePipeSmokeTest([NSString stringWithUTF8String:argv[2]]);
     }
+    if (argc == 2 && [[NSString stringWithUTF8String:argv[1]] isEqualToString:@"--smoke-test-guidance"]) {
+      return runGuidanceSmokeTest();
+    }
     if (argc == 2 && [[NSString stringWithUTF8String:argv[1]] isEqualToString:@"--smoke-test-cancel"]) {
       return runCancellationSmokeTest();
     }

package/deploy/macos/build-macos-pkg.sh

@@ -16,12 +16,11 @@
 #     lib/edge-sdk/dist/cli.js   the connector CLI
 #     lib/node_modules/...       the runtime subset (edge-core +
 #                                edge-platform-rtsp + edge-sdk + their
-#                                transitive deps), WITHOUT the heavy local
-#                                ONNX/sharp inference stack.
+#                                transitive deps), including Sharp for scoped
+#                                evidence masks, without the ONNX stack.
 #
-# Because cloud-sense + pair are loaded WITHOUT the local-inference stack
-# (cli.ts lazy-requires EdgeAgent), the bundle omits onnxruntime-node/sharp/
-# better-sqlite3 — keeping the pkg small.
+# The local CCTV path does not load EdgeAgent's ONNX stack. The bundle omits
+# onnxruntime-node/better-sqlite3, but retains Sharp and its native pixel codec.
 #
 # Install (no sudo, no admin password):
 #   installer -pkg <pkg> -target CurrentUserHomeDirectory
@@ -131,8 +130,8 @@ FFMPEG_SHA256_X64="${FFMPEG_SHA256_X64:-cfe20936c83ecf5d68e424b87e8cc45b24dd6be8
 # at a verified local cache; otherwise the release build fetches the pinned URL.
 # Override GEMMA_MODEL_URL / GEMMA_MODEL_SHA256 only when upstream is re-pinned.
 GEMMA_MODEL_ID="gemma-4-E2B-it.litertlm"
-GEMMA_MODEL_URL="${GEMMA_MODEL_URL:-https://huggingface.co/litert-community/gemma-4-E2B-it-litert-lm/resolve/main/gemma-4-E2B-it.litertlm}"
-GEMMA_MODEL_SHA256="${GEMMA_MODEL_SHA256:-181938105e0eefd105961417e8da75903eacda102c4fce9ce90f50b97139a63c}"
+GEMMA_MODEL_URL="${GEMMA_MODEL_URL:-https://huggingface.co/litert-community/gemma-4-E2B-it-litert-lm/resolve/84b6978eff6e4eea02825bc2ee4ea48579f13109/gemma-4-E2B-it.litertlm}"
+GEMMA_MODEL_SHA256="${GEMMA_MODEL_SHA256:-ab7838cdfc8f77e54d8ca45eadceb20452d9f01e4bfade03e5dce27911b27e42}"
 GEMMA_MODEL_FILE="${GEMMA_MODEL_FILE:-}"
 BUNDLE_MODEL=1
 
@@ -207,6 +206,7 @@ log "Building all edge workspaces (tsc, dependency order)…"
 log "Staging edge-sdk dist…"
 mkdir -p "$PAYLOAD/lib/edge-sdk"
 cp -R "$PKG_ROOT/dist" "$PAYLOAD/lib/edge-sdk/dist"
+cp -R "$PKG_ROOT/retained" "$PAYLOAD/lib/edge-sdk/retained"
 cp "$PKG_ROOT/package.json" "$PAYLOAD/lib/edge-sdk/package.json"
 
 # ─── 3. Lay down the runtime node_modules subset (NO heavy native stack) ──────
@@ -214,12 +214,10 @@ cp "$PKG_ROOT/package.json" "$PAYLOAD/lib/edge-sdk/package.json"
 # closure) and EXCLUDE the heavy/native/dev packages. cloud-sense + pair never
 # require them (EdgeAgent → edge-sensing → onnxruntime-node is lazy now), so
 # their absence is fine and keeps the pkg ~50 MB instead of ~270 MB.
-log "Staging runtime node_modules (excluding ONNX/sharp/sqlite/dev)…"
+log "Staging runtime node_modules (including focused-image masks; excluding ONNX/sqlite/dev)…"
 mkdir -p "$PAYLOAD/lib/node_modules"
 rsync -a \
   --exclude 'onnxruntime-node' \
-  --exclude 'sharp' \
-  --exclude '@img' \
   --exclude 'better-sqlite3' \
   --exclude 'ffmpeg-static' \
   --exclude '.cache' \
@@ -244,6 +242,7 @@ for p in edge-core edge-sensing edge-ads edge-federated edge-cloud \
   rm -rf "$dest"
   mkdir -p "$dest"
   [ -d "$src/dist" ] && cp -R "$src/dist" "$dest/dist"
+  [ "$p" != "edge-sdk" ] || cp -R "$src/retained" "$dest/retained"
   cp "$src/package.json" "$dest/package.json"
 done
 
@@ -424,6 +423,7 @@ cp "$PKG_ROOT/deploy/macos/scripts/setup-litertlm.sh" "$PAYLOAD/share/setup-lite
 # looks first. It is copied into the litert-lm tool venv's site-packages at
 # provisioning time; nothing else reads it, and no upstream file is modified.
 cp "$PKG_ROOT/deploy/litertlm/trillboards_litertlm_shim.py" "$PAYLOAD/share/trillboards_litertlm_shim.py"
+cp "$PKG_ROOT/deploy/litertlm/verify_model_proof.py" "$PAYLOAD/share/verify_model_proof.py"
 cp "$PKG_ROOT/deploy/macos/scripts/ensure-litertlm.sh" "$PAYLOAD/share/ensure-litertlm.sh"
 cp "$PKG_ROOT/deploy/macos/apply-update.sh" "$PAYLOAD/share/apply-update.sh"
 
@@ -490,6 +490,7 @@ SETUP_APP_BIN="$SETUP_APP_MACOS/Sense Anything Connector"
 mkdir -p "$SETUP_APP_MACOS" "$SETUP_APP_RESOURCES"
 cp "$PKG_ROOT/deploy/branding/SenseAnythingConnector.icns" \
   "$SETUP_APP_RESOURCES/SenseAnythingConnector.icns"
+cp "$PKG_ROOT/deploy/setup-guidance.json" "$SETUP_APP_RESOURCES/setup-guidance.json"
 log "Building native Sense Anything Connector.app…"
 if [ "$UNIVERSAL" -eq 1 ]; then
   clang -fobjc-arc -Wall -Wextra -Werror -O2 -mmacosx-version-min=12.0 -arch arm64 -arch x86_64 -framework Cocoa -framework WebKit \
@@ -536,6 +537,8 @@ cat > "$SETUP_APP/Contents/Info.plist" <<PLIST
 </plist>
 PLIST
 plutil -lint "$SETUP_APP/Contents/Info.plist" >/dev/null || die "native setup app Info.plist is invalid"
+"$SETUP_APP_BIN" --smoke-test-guidance \
+  || die "native setup guidance smoke test failed"
 file "$SETUP_APP_BIN" | grep -q 'Mach-O' || die "native setup app executable is not Mach-O"
 log "Native setup app staged: $SETUP_APP"
 

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

@@ -146,7 +146,7 @@ fi
 # 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 --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 (the VLM still runs every frame)"
   exit 0
 fi
@@ -182,7 +182,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/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'