@trillboards/edge-sdk 0.2.49 → 0.2.53

package/README.md

@@ -106,6 +106,63 @@ The SDK auto-detects device capabilities and adjusts inference accordingly:
 - `directml` — Windows GPU acceleration
 - `cuda` — NVIDIA GPU
 
+## Acoustic Sensing (opt-in)
+
+The connector can hear as well as see. A microphone catches what a camera has
+nothing to show for — a freezer door left open behind a shelf, glass breaking off
+frame, an alarm in the next room — so an acoustic **onset** is allowed to carry a
+frame that the motion cascade would otherwise have dropped as `no_motion`.
+
+**It is OFF by default, and that default is a consent position rather than a
+rollout setting.** Many US states are all-party-consent for audio; the cameras
+this connector attaches to belong to the customer and were very likely installed,
+signed and papered for video. Turning this on has to be somebody's explicit
+decision.
+
+```ts
+new CloudSensingManager({
+  loops,
+  motionGate: { enabled: true },      // the acoustic gate rides the visual cascade
+  audioSensing: {
+    enabled: true,                    // <- explicit; default false
+    maxAudioSessionsPerSource: 1,     // long-lived audio sessions per recorder
+  },
+});
+```
+
+Every failure on this path is non-fatal by construction — a recorder that refuses
+admission, a stream with no audio track, a missing ffmpeg — all leave the camera
+loops untouched. Audio is supplementary and can never stop a feed from producing
+frames.
+
+### Why the gate is DSP and not the on-device model
+
+Gemma 4 was measured against this exact runtime before the path was built. It
+**transcribes speech excellently and does not name acoustic events**: on real
+recordings it scored 2/8 on an open prompt and 3/8 forced-choice, where every hit
+was an animate vocalization (dog, baby, applause) and every mechanical / impact /
+tonal event — breaking glass, a door slam, a smoke alarm — missed, defaulting to
+the label `speech` on audio containing no speech.
+
+So the two halves are split by what each is actually good at:
+
+| Job | Implementation |
+|---|---|
+| "Did something happen?" | `AudioOnsetDetector` — rolling background estimate + threshold |
+| "What was said?" | `LiteRtVlmProvider.transcribeAudio` (Gemma, via litert-lm `input_audio`) |
+
+The full measured battery is in the `AudioOnsetDetector` header, and the operator
+view is in [docs/runbooks/audio-sensing-substrate.md](../../../docs/runbooks/audio-sensing-substrate.md) §0.
+
+### New exports
+
+| Export | Purpose |
+|---|---|
+| `AudioOnsetDetector`, `rmsDbfs`, `SILENCE_DBFS` | Acoustic onset detection (dBFS — **not** a 0..4 tier) |
+| `attachAudioOnset` | Joins an audio transport to a feed's `MotionGate`; returns `null` when a feed has no audio |
+| `encodeWav16`, `takeMostRecentSeconds` | Float32 PCM → 16-bit mono WAV for the model's `input_audio` |
+| `MotionGateReason: 'audio_onset'` | New cascade verdict — a heard event carried this frame |
+
 ## Sub-Packages
 
 This is the umbrella package. For fine-grained control, install sub-packages individually:
@@ -119,6 +176,7 @@ This is the umbrella package. For fine-grained control, install sub-packages ind
 | [@trillboards/edge-cloud](https://www.npmjs.com/package/@trillboards/edge-cloud) | Gemini Vision scene analysis, contextual targeting |
 | [@trillboards/edge-platform-linux](https://www.npmjs.com/package/@trillboards/edge-platform-linux) | V4L2 camera, PulseAudio, systemd, kiosk mode |
 | [@trillboards/edge-platform-windows](https://www.npmjs.com/package/@trillboards/edge-platform-windows) | DirectShow, RTSP IP cameras, WASAPI audio |
+| [@trillboards/edge-platform-rtsp](https://www.npmjs.com/package/@trillboards/edge-platform-rtsp) | RTSP camera frames, RTSP **audio** sessions, macOS microphone |
 
 ## MCP Server (AI Agent Integration)
 

package/deploy/macos/README.md

@@ -19,6 +19,7 @@ What lands on disk (home-domain, **no sudo / no admin password**):
                            edge-sdk), WITHOUT the heavy local-inference stack
   share/com.trillboards.edge.plist   LaunchAgent template
   share/ensure-litertlm.sh           background local-AI retry supervisor
+  share/apply-update.sh              signed-pkg updater with rollback
   share/models/gemma-4-E2B-it.litertlm   required customer local VLM (removed after import)
 ~/Applications/Trillboards CCTV Setup.app native customer setup window (opened automatically)
 ~/Library/Application Support/Trillboards/trillboards.config.json   (after pair, 0600)
@@ -31,8 +32,9 @@ bootstrapped automatically on first successful pair. The device token is
 delivered **only by pairing** — it is never baked into the `.pkg`.
 
 > The customer build includes Gemma and completes its local health check before
-> pairing. Cloud inference requires explicit configuration. `--skip-model` is
-> available only for engineering checks and must not be published.
+> pairing. Cloud inference requires explicit configuration. The release lane
+> also builds a signed, notarized `--skip-model` package for automatic upgrades;
+> it is accepted only on an already-provisioned machine whose model is healthy.
 
 ---
 
@@ -83,13 +85,26 @@ Options:
 | `--arch arm64\|x64` | host arch | target architecture |
 | `--node-version vX.Y.Z` | `v22.22.0` | pinned Node runtime to bundle |
 | `--bundle-model` | on | include the pinned ~2.4 GB Gemma model required by customer setup |
-| `--skip-model` | off | build a slim engineering artifact that must not be published to customers |
+| `--skip-model` | off | build the slim code-only upgrade package; it is not a valid first installer |
 | `--offline` | off | skip the official Node download; copy the host `node` |
 | `--sign-installer "Developer ID Installer: …"` | unset | `productsign` the pkg |
 
 The build is idempotent (it wipes its staging tree each run) and **smoke-tests
 the staged bundle** (`trillboards-edge version`) before packaging.
 
+### Automatic updates
+
+Every paired connector checks the macOS version manifest at launch and every
+six hours. Once a release has baked for six hours, the connector downloads the
+content-addressed code-only package while sensing remains online. Before it can
+be staged, macOS must validate the exact Aethercorp Developer ID Installer
+identity, the notarization staple, Gatekeeper acceptance, size, and SHA-256.
+The connector waits for a safe sensing point, exits cleanly, installs the
+package, smoke-tests the new version, and relaunches the LaunchAgent. The old
+tree remains as `~/Library/Trillboards/edge.previous` and is restored
+automatically if installation, smoke testing, or relaunch fails. Existing
+pairing and the local model are preserved; the setup window does not reopen.
+
 ### Local end-to-end test
 
 ```bash

package/deploy/macos/apply-update.sh

@@ -0,0 +1,225 @@
+#!/bin/bash
+#
+# Stage and apply the signed, notarized macOS connector update package.
+# The running connector chooses the safe point; this detached helper owns the
+# download, macOS trust checks, LaunchAgent handoff, swap, smoke test, and
+# `.previous` rollback.
+
+set -u
+
+LABEL='com.trillboards.edge'
+EXPECTED_SIGNER='Developer ID Installer: Aethercorp Inc (78JQ7882U9)'
+MODE=''
+INSTALL_DIR=''
+UPDATE_URL=''
+EXPECTED_VERSION=''
+CURRENT_VERSION=''
+EXPECTED_SHA256=''
+EXPECTED_SIZE=''
+WAIT_PID=''
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --stage|--commit) MODE="$1"; shift ;;
+    --install-dir) INSTALL_DIR="${2:-}"; shift 2 ;;
+    --update-url) UPDATE_URL="${2:-}"; shift 2 ;;
+    --expected-version) EXPECTED_VERSION="${2:-}"; shift 2 ;;
+    --current-version) CURRENT_VERSION="${2:-}"; shift 2 ;;
+    --expected-sha256) EXPECTED_SHA256="${2:-}"; shift 2 ;;
+    --expected-size) EXPECTED_SIZE="${2:-}"; shift 2 ;;
+    --wait-pid) WAIT_PID="${2:-}"; shift 2 ;;
+    *) printf '[apply-update] unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+log() {
+  /usr/bin/logger -t com.trillboards.edge "apply-update: $*" 2>/dev/null || true
+  printf '[apply-update] %s\n' "$*"
+}
+
+case "$EXPECTED_VERSION" in
+  [0-9]*.[0-9]*.[0-9]*) ;;
+  *) log 'invalid expected version'; exit 2 ;;
+esac
+
+# The updater is intentionally scoped to the one home-domain path the package
+# installs. This makes every later rm/mv target resolved and bounded.
+EXPECTED_INSTALL_DIR="${HOME}/Library/Trillboards/edge"
+if [ "$INSTALL_DIR" != "$EXPECTED_INSTALL_DIR" ]; then
+  log "refusing unexpected install root: $INSTALL_DIR"
+  exit 2
+fi
+
+PARENT_DIR="$(dirname "$INSTALL_DIR")"
+UPDATE_DIR="$PARENT_DIR/.edge-auto-update"
+ARCHIVE="$UPDATE_DIR/connector-update.pkg"
+MARKER="$UPDATE_DIR/staged.json"
+OUTCOME="$UPDATE_DIR/outcome.json"
+LOCK_DIR="$UPDATE_DIR/lock"
+PREVIOUS="$PARENT_DIR/edge.previous"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+
+mkdir -p "$UPDATE_DIR" || exit 1
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  log 'another update transaction is already running'
+  exit 0
+fi
+trap 'rmdir "$LOCK_DIR" 2>/dev/null || true' EXIT
+
+json_escape() {
+  printf '%s' "$1" | /usr/bin/sed 's/\\/\\\\/g; s/"/\\"/g'
+}
+
+write_outcome() {
+  local result="$1" detail="$2" tmp="$OUTCOME.tmp.$$"
+  printf '{"attemptedAt":"%s","result":"%s","detail":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$result" "$(json_escape "$detail")" > "$tmp" \
+    && mv -f "$tmp" "$OUTCOME"
+}
+
+fail_stage() {
+  log "$1"
+  rm -f "$ARCHIVE.download" "$MARKER.tmp.$$"
+  exit 1
+}
+
+configure_proxy() {
+  if [ -n "${HTTPS_PROXY:-}" ] || [ -n "${https_proxy:-}" ] || [ -n "${ALL_PROXY:-}" ]; then
+    return
+  fi
+  local proxy_conf enabled host port
+  proxy_conf="$(/usr/sbin/scutil --proxy 2>/dev/null || true)"
+  enabled="$(printf '%s\n' "$proxy_conf" | /usr/bin/awk '/HTTPSEnable/ {print $3}')"
+  [ "$enabled" = '1' ] || return
+  host="$(printf '%s\n' "$proxy_conf" | /usr/bin/awk '/HTTPSProxy/ {print $3}')"
+  port="$(printf '%s\n' "$proxy_conf" | /usr/bin/awk '/HTTPSPort/ {print $3}')"
+  [ -n "$host" ] || return
+  HTTPS_PROXY="http://$host${port:+:$port}"
+  export HTTPS_PROXY HTTP_PROXY="$HTTPS_PROXY"
+}
+
+verify_pkg() {
+  local pkg="$1" sha="$2" size="$3" actual_size actual_sha sig_out
+  [ -f "$pkg" ] || return 1
+  case "$size" in *[!0-9]*|'') return 1 ;; esac
+  printf '%s' "$sha" | /usr/bin/grep -Eq '^[0-9a-f]{64}$' || return 1
+
+  actual_size="$(/usr/bin/wc -c < "$pkg" | tr -d ' ')"
+  [ "$actual_size" = "$size" ] || { log "payload size mismatch: expected $size, got $actual_size"; return 1; }
+  actual_sha="$(/usr/bin/shasum -a 256 "$pkg" | /usr/bin/awk '{print $1}')"
+  [ "$actual_sha" = "$sha" ] || { log 'payload SHA-256 mismatch'; return 1; }
+
+  sig_out="$UPDATE_DIR/signature.txt"
+  /usr/sbin/pkgutil --check-signature "$pkg" > "$sig_out" 2>&1 || { log 'package signature is invalid'; return 1; }
+  /usr/bin/grep -Fq "$EXPECTED_SIGNER" "$sig_out" || { log 'package signer is not Aethercorp'; return 1; }
+  /usr/bin/xcrun stapler validate "$pkg" >/dev/null 2>&1 || { log 'package has no valid notarization staple'; return 1; }
+  /usr/sbin/spctl -a -vv --type install "$pkg" >/dev/null 2>&1 || { log 'Gatekeeper rejected the update package'; return 1; }
+  return 0
+}
+
+if [ "$MODE" = '--stage' ]; then
+  case "$UPDATE_URL" in https://*) ;; *) fail_stage 'update URL must use HTTPS' ;; esac
+  configure_proxy
+  log "downloading connector $EXPECTED_VERSION while sensing stays online"
+  /usr/bin/curl --fail --location --silent --show-error --proto '=https' --tlsv1.2 \
+    --connect-timeout 30 --max-time 3600 --output "$ARCHIVE.download" "$UPDATE_URL" \
+    || fail_stage 'update download failed'
+  verify_pkg "$ARCHIVE.download" "$EXPECTED_SHA256" "$EXPECTED_SIZE" \
+    || fail_stage 'update package verification failed'
+  mv -f "$ARCHIVE.download" "$ARCHIVE" || fail_stage 'could not retain verified package'
+  marker_tmp="$MARKER.tmp.$$"
+  printf '{"version":"%s","currentVersion":"%s","sha256":"%s","sizeBytes":%s}\n' \
+    "$EXPECTED_VERSION" "$CURRENT_VERSION" "$EXPECTED_SHA256" "$EXPECTED_SIZE" > "$marker_tmp" \
+    || fail_stage 'could not write staged marker'
+  mv -f "$marker_tmp" "$MARKER" || fail_stage 'could not publish staged marker'
+  log "connector $EXPECTED_VERSION is staged, signed, notarized, and verified"
+  exit 0
+fi
+
+if [ "$MODE" != '--commit' ]; then
+  log 'exactly one of --stage or --commit is required'
+  exit 2
+fi
+
+marker_version="$(/usr/bin/plutil -extract version raw "$MARKER" 2>/dev/null || true)"
+marker_sha="$(/usr/bin/plutil -extract sha256 raw "$MARKER" 2>/dev/null || true)"
+marker_size="$(/usr/bin/plutil -extract sizeBytes raw "$MARKER" 2>/dev/null || true)"
+if [ "$marker_version" != "$EXPECTED_VERSION" ]; then
+  write_outcome 'rejected' 'staged version did not match the requested version'
+  log 'staged version mismatch; refusing update'
+  exit 1
+fi
+verify_pkg "$ARCHIVE" "$marker_sha" "$marker_size" || {
+  write_outcome 'rejected' 'staged package failed commit-time verification'
+  rm -f "$MARKER" "$ARCHIVE"
+  exit 1
+}
+
+# The connector launches us and then exits cleanly. Do not touch its mapped
+# binaries until that PID is gone; a timeout leaves the current install intact.
+if [ -n "$WAIT_PID" ]; then
+  waited=0
+  while kill -0 "$WAIT_PID" 2>/dev/null && [ "$waited" -lt 120 ]; do
+    sleep 1
+    waited=$((waited + 1))
+  done
+  if kill -0 "$WAIT_PID" 2>/dev/null; then
+    write_outcome 'failed' 'connector did not exit before the update deadline'
+    log 'connector did not exit; leaving current install untouched'
+    exit 1
+  fi
+fi
+
+restart_agent() {
+  [ -f "$PLIST" ] || return 1
+  /bin/launchctl bootout "gui/$(id -u)/$LABEL" >/dev/null 2>&1 || true
+  local attempt=1
+  while [ "$attempt" -le 10 ]; do
+    /bin/launchctl bootstrap "gui/$(id -u)" "$PLIST" >/dev/null 2>&1 || true
+    if /bin/launchctl print "gui/$(id -u)/$LABEL" >/dev/null 2>&1; then
+      /bin/launchctl kickstart -k "gui/$(id -u)/$LABEL" >/dev/null 2>&1 || true
+      return 0
+    fi
+    sleep 1
+    attempt=$((attempt + 1))
+  done
+  return 1
+}
+
+rollback() {
+  local detail="$1"
+  /bin/launchctl bootout "gui/$(id -u)/$LABEL" >/dev/null 2>&1 || true
+  rm -rf "$INSTALL_DIR"
+  if [ -d "$PREVIOUS" ]; then
+    mv "$PREVIOUS" "$INSTALL_DIR" || true
+  fi
+  if restart_agent; then
+    write_outcome 'failed' "$detail; previous version restored"
+  else
+    write_outcome 'failed' "$detail; previous files restored but the agent did not restart"
+  fi
+  rm -f "$MARKER" "$ARCHIVE"
+  log "$detail; rolled back"
+  exit 1
+}
+
+log "applying connector $EXPECTED_VERSION"
+/bin/launchctl bootout "gui/$(id -u)/$LABEL" >/dev/null 2>&1 || true
+rm -rf "$PREVIOUS"
+mv "$INSTALL_DIR" "$PREVIOUS" || {
+  write_outcome 'failed' 'could not preserve the current install for rollback'
+  exit 1
+}
+
+/usr/sbin/installer -pkg "$ARCHIVE" -target CurrentUserHomeDirectory >/dev/null 2>&1 \
+  || rollback 'macOS Installer rejected the update'
+
+installed_version="$($INSTALL_DIR/bin/trillboards-edge version 2>/dev/null || true)"
+printf '%s' "$installed_version" | /usr/bin/grep -Fq "edge-sdk v$EXPECTED_VERSION" \
+  || rollback 'updated connector failed its version smoke test'
+
+restart_agent || rollback 'updated connector installed but its LaunchAgent did not restart'
+write_outcome 'success' "updated from $CURRENT_VERSION to $EXPECTED_VERSION"
+rm -f "$MARKER" "$ARCHIVE" "$UPDATE_DIR/signature.txt"
+log "connector $EXPECTED_VERSION installed and relaunched"
+exit 0

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

@@ -31,7 +31,7 @@
 #                      [--sign-app "Developer ID Application: …"]
 #                      [--sign-installer "Developer ID Installer: …"]
 #                      [--bundle-model] (default; include the pinned ~2.4 GB VLM)
-#                      [--skip-model] (engineering-only slim build)
+#                      [--skip-model] (code-only upgrade; not a first installer)
 #                      [--offline]   (skip the official Node + ffmpeg downloads,
 #                                     copy the host `node`/`ffmpeg` instead — for
 #                                     air-gapped CI)
@@ -150,8 +150,8 @@ while [ $# -gt 0 ]; do
   esac
 done
 
-# Offline customer builds must provide the model cache explicitly. Slim builds
-# remain available only for focused engineering checks.
+# Offline first-install builds must provide the model cache explicitly. Slim
+# builds are the release lane's code-only upgrade artifact.
 if [ "$OFFLINE" -eq 1 ] && [ "$BUNDLE_MODEL" -eq 1 ] && [ -z "$GEMMA_MODEL_FILE" ]; then
   echo "--offline with the customer model bundle requires GEMMA_MODEL_FILE" >&2
   exit 2
@@ -398,7 +398,9 @@ cp "$PKG_ROOT/deploy/macos/com.trillboards.edge.plist" "$PAYLOAD/share/com.trill
 cp "$PKG_ROOT/deploy/macos/com.trillboards.litertlm.plist" "$PAYLOAD/share/com.trillboards.litertlm.plist"
 cp "$PKG_ROOT/deploy/macos/scripts/setup-litertlm.sh" "$PAYLOAD/share/setup-litertlm.sh"
 cp "$PKG_ROOT/deploy/macos/scripts/ensure-litertlm.sh" "$PAYLOAD/share/ensure-litertlm.sh"
-chmod +x "$PAYLOAD/share/setup-litertlm.sh" "$PAYLOAD/share/ensure-litertlm.sh"
+cp "$PKG_ROOT/deploy/macos/apply-update.sh" "$PAYLOAD/share/apply-update.sh"
+chmod +x "$PAYLOAD/share/setup-litertlm.sh" "$PAYLOAD/share/ensure-litertlm.sh" \
+  "$PAYLOAD/share/apply-update.sh"
 
 # ─── 7b. Stage the pre-bundled Gemma model (.litertlm) into the payload ───────
 # Stage the redistributable (Apache-2.0) Gemma 4 E2B LiteRT-LM model and verify
@@ -423,7 +425,7 @@ if [ "$BUNDLE_MODEL" -eq 1 ]; then
   printf '%s  %s\n' "$GEMMA_MODEL_SHA256" "$GEMMA_MODEL_ID" > "$PAYLOAD/share/models/$GEMMA_MODEL_ID.sha256"
   log "Staged + SHA-verified bundled Gemma model ($(du -h "$GEMMA_OUT" | cut -f1))"
 else
-  warn "Building an engineering-only slim package without local AI. Do not publish this artifact to customers."
+  warn "Building the code-only upgrade package without bundled local AI; it requires an already-provisioned Mac."
 fi
 
 # ─── 7c. Build the native customer setup application ─────────────────────────
@@ -603,12 +605,12 @@ else
   warn "cert (pass --sign-installer) then notarize (see deploy/macos/README.md)."
 fi
 
-# Keep deliberately slim engineering builds bounded so an unrelated payload
-# regression cannot masquerade as the bundled customer package.
+# Keep code-only upgrade builds bounded so an unrelated payload regression
+# cannot turn an automatic update into another multi-gigabyte first install.
 PKG_BYTES="$(stat -f%z "$PKG_OUT")"
 MAX_SLIM_PKG_BYTES="${MAX_SLIM_PKG_BYTES:-262144000}"
 if [ "$BUNDLE_MODEL" -eq 0 ] && [ "$PKG_BYTES" -gt "$MAX_SLIM_PKG_BYTES" ]; then
-  die "slim engineering installer is $PKG_BYTES bytes; maximum is $MAX_SLIM_PKG_BYTES bytes"
+  die "code-only update package is $PKG_BYTES bytes; maximum is $MAX_SLIM_PKG_BYTES bytes"
 fi
 
 # ─── Done ────────────────────────────────────────────────────────────────────

package/deploy/macos/scripts/postinstall

@@ -8,7 +8,8 @@
 #   - ensure the runtime dirs exist (Application Support config dir + Logs dir)
 #   - make the bundled binaries executable (pkg payloads can lose +x)
 #   - install and health-check the bundled local AI model
-#   - open camera pairing only after local AI is ready
+#   - open camera pairing only after local AI is ready on a first install
+#   - keep an already-paired update headless
 #   - DO NOT start the LaunchAgent: there is no paired config yet, and a
 #     config-less cloud-sense crash-loops. The agent is bootstrapped only after
 #     a successful setup (the installed pairing engine does that).
@@ -42,6 +43,9 @@ fi
 EDGE_ROOT="$USER_HOME/Library/Trillboards/edge"
 APP_SUPPORT="$USER_HOME/Library/Application Support/Trillboards"
 LOG_DIR="$USER_HOME/Library/Logs/Trillboards"
+PAIRED_CONFIG="$APP_SUPPORT/trillboards.config.json"
+IS_UPGRADE=0
+[ -s "$PAIRED_CONFIG" ] && IS_UPGRADE=1
 
 log() { /usr/bin/logger -t com.trillboards.edge "postinstall: $*" 2>/dev/null || true; printf '[trillboards postinstall] %s\n' "$*"; }
 
@@ -118,7 +122,9 @@ APPS_DIR="$USER_HOME/Applications"
 SETUP_APP="$APPS_DIR/Trillboards CCTV Setup.app"
 LEGACY_PAIR_LAUNCHER="$APPS_DIR/Trillboards Pair.command"
 rm -f "$LEGACY_PAIR_LAUNCHER" 2>/dev/null || true
-if [ -d "$SETUP_APP" ] && [ -x "$EDGE_ROOT/bin/trillboards-pair" ]; then
+if [ "$IS_UPGRADE" -eq 1 ]; then
+  log "paired connector upgrade detected; setup remains closed"
+elif [ -d "$SETUP_APP" ] && [ -x "$EDGE_ROOT/bin/trillboards-pair" ]; then
   log "native setup app ready: \"$SETUP_APP\" (opening it)"
   if [ "$(id -u)" = "0" ] && [ -n "$OWNER" ] && [ "$OWNER" != "root" ]; then
     LAUNCH_UID="$(id -u "$OWNER" 2>/dev/null || echo '')"
@@ -149,5 +155,9 @@ else
   log "WARNING: launcher not executable at $EDGE_ROOT/bin/trillboards-edge"
 fi
 
-log "done. Connector and local AI installed; Trillboards CCTV Setup opened automatically."
+if [ "$IS_UPGRADE" -eq 1 ]; then
+  log "done. Connector update installed; existing pairing preserved."
+else
+  log "done. Connector and local AI installed; Trillboards CCTV Setup opened automatically."
+fi
 exit 0

package/dist/AudioOnsetDetector.d.ts

@@ -0,0 +1,211 @@
+/**
+ * AudioOnsetDetector — the connector's acoustic equivalent of
+ * `SceneChangeDetector`: the CHEAP stage that answers "did anything happen?"
+ * so the expensive stage (a VLM inference) is spent only when it might matter.
+ *
+ * ── WHY THIS IS DSP AND NOT A MODEL. The plan for this feature was to let
+ * Gemma 4 name acoustic events directly — it is already on the box, litert-lm
+ * accepts `input_audio`, and both encoders ship in our `.litertlm`, so no
+ * second model would be needed. That was MEASURED before it was built, and it
+ * does not hold. Against `gemma-4-E2B-it.litertlm,gpu`, mono 16 kHz WAV, real
+ * recordings, fresh serve, a speech control passing before and after every
+ * trial, on an Apple M4 Max — and run TWICE, on litert-lm 0.13.1 (the machine
+ * default) and again on an isolated 0.16.0 (the version both provisioners pin,
+ * so the one the fleet actually runs). The two agree clip-for-clip:
+ *
+ *   | clip          | open prompt ("describe every sound")  | forced choice |
+ *   |---------------|---------------------------------------|---------------|
+ *   | glass break   | "I cannot hear any audio"             | `speech`      |
+ *   | glass break 2 | "you haven't provided an audio file"  | `speech`      |
+ *   | door slam     | "a click or a snap"                   | `speech`      |
+ *   | smoke alarm   | "I cannot hear any audio"             | `speech`      |
+ *   | siren         | "possibly a scream or a siren"        | `dog_barking` |
+ *   | dog bark      | "resemble a bird call"                | `dog_barking` |
+ *   | baby cry      | "possibly laughter or screams"        | `baby_crying` |
+ *   | applause      | "a single, loud, sharp sound"         | `applause`    |
+ *
+ * 2/8 open, 3/8 forced — the SAME 3/8 and the same per-clip labels on both
+ * runtimes, siren -> `dog_barking` included, so this is a property of the model
+ * and not of a runtime version. The three forced-choice hits are ALL animate
+ * vocalizations (dog, baby, human hands); every miss is mechanical, impact or
+ * tonal — and those four default to the label `speech` on audio containing no
+ * speech at all, because it is a speech model. The result is stable, not noisy:
+ * the smoke alarm returned a byte-identical refusal 16/16 times on a fresh
+ * serve, and the siren reads as `dog_barking` even as the FIRST request after a
+ * restart, so it is a real misclassification and not cross-request context
+ * bleed. The audio was genuinely INGESTED in every one of those trials — proven
+ * by a mixed control, `glass_then_speech.wav`, whose speech (which is SECOND in
+ * the file) transcribes exactly; a miss is therefore a capability result and
+ * not a silently dropped payload.
+ *
+ * The three events the product actually needs — a freezer door, breaking glass,
+ * a smoke alarm — are 0/3 in BOTH prompt regimes. So the gate is DSP, and Gemma
+ * keeps the half it is genuinely excellent at: it transcribed
+ * "There is a fire in the kitchen, everyone get out now" verbatim, 30/30, in
+ * 0.63–5.83 s. Speech goes to the model; "something happened" does not.
+ *
+ * TWO THINGS THOSE TIMINGS ARE NOT. (1) The DELEGATE is unconfirmed: the `,gpu`
+ * id was POSTed, but no engine trace was read back, and a warm mldrift cache
+ * does not re-emit the `Replacing N … (LITERT_WEBGPU)` line — so a latency range
+ * quoted here may span two delegates. The CAPABILITY result does not depend on
+ * that; the latencies are indicative only. (2) They are not this feature's
+ * running cost. The gate never calls the model at all — see below.
+ *
+ * ── COST, WHICH IS THE POINT OF PUTTING IT HERE. `litert-lm serve` is a SINGLE
+ * conversation and the connector's whole inference budget flows through it. A
+ * model-based gate would have spent that budget continuously, at 25 audio
+ * tokens per second of audio, on a machine already ceilinged in analyses/hour.
+ * This detector spends NONE of it: measured over 1 h of 16 kHz audio pushed in
+ * 100 ms blocks (36,000 blocks, one M4 Max core), it costs 50.5 ms of CPU
+ * total — 1.40 µs per block, 0.0014% of one core — and zero model tokens. The
+ * acoustic channel is therefore free with respect to the serial slot, and only
+ * `transcribeAudio` (opt-in, speech only) ever competes for it.
+ *
+ * ── WHAT IT DOES. Frame the PCM into short hops, take each hop's RMS in dBFS,
+ * hold a rolling estimate of the room's background level, and fire when a hop
+ * stands `thresholdDb` above that background for at least `minDurationMs`.
+ *
+ * ── THE ONE NON-OBVIOUS RULE, AND IT IS BORROWED ON PURPOSE. The background
+ * must NOT absorb the event that is currently firing. `SceneChangeDetector`
+ * carries the visual form of this rule from Frigate (rule 1 in its header: the
+ * background only moves after motion has persisted `BACKGROUND_UPDATE_AFTER_FRAMES`
+ * frames, otherwise a slowly-moving object is absorbed mid-walk and becomes
+ * invisible). The acoustic failure is the same shape and worse, because sound
+ * levels move much faster than pixels: a mean that updates every hop is dragged
+ * up by the very transient it is supposed to be measuring against, so a long
+ * event raises its own floor and the detector goes deaf partway through it.
+ * So the background updates freely while the room is quiet, and while a hop is
+ * above threshold it updates ONLY once that loudness has PERSISTED past
+ * `backgroundAbsorbAfterMs`. A 200 ms door slam never moves the floor; a
+ * genuinely louder room (a compressor kicking on, a lunch rush) is absorbed
+ * after a few seconds and stops re-firing forever.
+ *
+ * ── CALIBRATION, for the same reason `SceneChangeDetector` has it. On the
+ * first hops there is no trustworthy background, and firing off a floor built
+ * from one sample means every connector start costs an inference storm. The
+ * detector reports `calibrating` until it has `calibrationFrames` hops and
+ * refuses to fire until then. Unlike the visual detector it never RE-ENTERS
+ * calibration: there is no acoustic analogue of the dusk IR-cut flip that
+ * changes every pixel at once, and a detector that can be talked back into
+ * calibration by loud audio is a detector an attacker (or a busy store) can
+ * silence.
+ *
+ * ── REFRACTORY. One physical event is many loud hops. `refractoryMs` collapses
+ * a burst into ONE onset so a single dropped tray does not spend the feed's
+ * whole inference budget.
+ *
+ * ── UNITS: THIS CLASS EMITS dBFS AND NOTHING ELSE. dBFS here is a NEGATIVE
+ * number relative to full scale (digital silence floors at `SILENCE_DBFS`).
+ * It is deliberately NOT a 0..4 loudness tier. The Android DOOH fleet wired a
+ * tier-valued device field to a decibel-valued server field, and the decibel
+ * column has read as a constant sentinel on 100% of rows ever since — a value
+ * that scores perfectly on any fill-rate monitor while measuring nothing, and
+ * which pins every venue at "quiet". A tier and a decibel level are two
+ * quantities, not a naming difference; docs/runbooks/audio-sensing-substrate.md
+ * §3 names both fields and why they must never be aliased. Nothing in this file
+ * writes either of them: a caller that wants a tier must map dBFS to one
+ * explicitly and own that mapping.
+ */
+/** dBFS reported for a digitally-silent hop. Finite so the EMA stays finite. */
+export declare const SILENCE_DBFS = -100;
+export interface AudioOnsetDetectorOptions {
+    /** Sample rate of the PCM handed to `push()` (Hz). */
+    sampleRate: number;
+    /** Analysis hop length (ms). Default 20 — short enough to catch an impact. */
+    frameMs?: number;
+    /** dB above background that counts as an onset. Default 12. */
+    thresholdDb?: number;
+    /** Loudness must persist this long to fire (ms). Default 40. */
+    minDurationMs?: number;
+    /** Minimum gap between two reported onsets (ms). Default 3000. */
+    refractoryMs?: number;
+    /** Hops required before the background is trusted. Default 50 (=1 s @20 ms). */
+    calibrationFrames?: number;
+    /** Background EMA blend per quiet hop, 0..1. Default 0.02 (~1 s constant). */
+    backgroundAlpha?: number;
+    /**
+     * Sustained loudness is absorbed into the background after this long (ms).
+     * Default 4000. This is the acoustic form of Frigate's
+     * `BACKGROUND_UPDATE_AFTER_FRAMES` — see the header.
+     */
+    backgroundAbsorbAfterMs?: number;
+    /**
+     * Absolute floor: hops quieter than this never fire, however far above the
+     * background they sit. Without it a silent room's background collapses toward
+     * `SILENCE_DBFS` and pure dither trips the threshold. Default -55 dBFS.
+     */
+    minLevelDbfs?: number;
+    /** Clock injection for tests. */
+    now?: () => number;
+}
+export interface AudioOnsetEvent {
+    /** Wall-clock ms at which the onset was reported. */
+    atMs: number;
+    /** Peak hop level (dBFS) observed during the triggering burst. */
+    peakDbfs: number;
+    /** Background level (dBFS) the peak was measured against. */
+    backgroundDbfs: number;
+    /** `peakDbfs - backgroundDbfs`, i.e. how far above the room it stood. */
+    excessDb: number;
+    /** How long the burst had been above threshold when it fired (ms). */
+    durationMs: number;
+}
+export interface AudioOnsetStats {
+    framesSeen: number;
+    onsets: number;
+    calibrating: boolean;
+    /** Current rolling background estimate (dBFS), or null while uncalibrated. */
+    backgroundDbfs: number | null;
+    /** Most recent hop level (dBFS), or null before any audio. */
+    lastLevelDbfs: number | null;
+    suppressedByRefractory: number;
+}
+/** RMS of a slice, expressed in dBFS (0 = full scale). */
+export declare function rmsDbfs(samples: Float32Array, from: number, to: number): number;
+/**
+ * Stateful, one instance per audio feed. PCM must be pushed to the SAME
+ * instance in capture order — like `SceneChangeDetector`, the background model
+ * is the state.
+ */
+export declare class AudioOnsetDetector {
+    private readonly sampleRate;
+    private readonly frameSamples;
+    private readonly frameMs;
+    private readonly thresholdDb;
+    private readonly minDurationMs;
+    private readonly refractoryMs;
+    private readonly calibrationFrames;
+    private readonly backgroundAlpha;
+    private readonly backgroundAbsorbAfterMs;
+    private readonly minLevelDbfs;
+    private readonly now;
+    /** Samples carried across `push()` boundaries so hops are never torn. */
+    private residue;
+    private background;
+    private framesSeen;
+    private lastLevelDbfs;
+    /** ms of contiguous above-threshold audio accumulated so far. */
+    private aboveMs;
+    private burstPeakDbfs;
+    private burstBackgroundDbfs;
+    /** Set once a burst has fired, so it fires ONCE rather than every hop. */
+    private burstFired;
+    private lastOnsetAtMs;
+    private onsets;
+    private suppressedByRefractory;
+    constructor(options: AudioOnsetDetectorOptions);
+    isCalibrating(): boolean;
+    getStats(): AudioOnsetStats;
+    /**
+     * Feed PCM. Returns every onset detected within THIS push (usually none, and
+     * at most one per `refractoryMs`). Sample count need not align to a hop — the
+     * remainder is carried into the next call so an event straddling a buffer
+     * boundary is not silently split.
+     */
+    push(pcm: Float32Array, nowMs?: number): AudioOnsetEvent[];
+    /** Drop all state — used when a feed reconnects and continuity is broken. */
+    reset(): void;
+    /** One hop. Split out so the state machine is readable in one screen. */
+    private consumeFrame;
+}
+//# sourceMappingURL=AudioOnsetDetector.d.ts.map

package/dist/AudioOnsetDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioOnsetDetector.d.ts","sourceRoot":"","sources":["../src/AudioOnsetDetector.ts"],"names":[],"mappings":"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"}