Behavision: face recognition for retail, edge to head office

Five components that ship as one product:

- behavision/  the recognition engine. RTSP ingest, YuNet detection, IoU
               tracking, ArcFace embeddings, a FAISS/SQLite gallery, and a
               FastAPI dashboard. Identity is decided once per TRACK from an
               average of at least three embeddings, never per frame.
- agent/       the Go edge agent: supervises the engine, holds a durable
               spool, and drains it to MQTT. Nothing is acked before the
               broker confirms.
- desktop/     the shop PC application (Wails + React + tray).
- server/      the cloud API, MQTT consumer, reports and assistant.
- web/         platform.loyaly.ai, the head-office app, embedded in the
               server binary.

The gallery stores 512-float embeddings and timestamps - no images unless
`app.store_faces` is switched on. Those embeddings are biometric personal
data under GDPR and India's DPDP: template inversion reconstructs a
recognisable face from an ArcFace vector, so data/behavision.db is treated
as a biometric database and DELETE /api/visitors/{id} is a real erasure.

CLAUDE.md carries the reasoning behind every non-obvious decision here,
including the ones that were measured and the ones that were wrong first.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HViLj9gYNRtSr7YVZmW5sn

agent/pkg/engine/health_test.go

@@ -0,0 +1,44 @@
+package engine
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// The engine's REAL reply, copied from a running instance. The point of this
+// test is the `"frozen": false` inside `paths`: Health.Paths was
+// map[string]string, so decoding failed on that one bool, and because a failed
+// decode fails the whole document a working engine was reported unreachable -
+// red tray, and a heartbeat carrying neither the model nor the cameras, so head
+// office showed "0 of 0 cameras" for a site that was watching one.
+const realHealthBody = `{"status":"ok","recognition_model":"w600k_r50",
+"paths":{"frozen":false,"install_root":"/opt/behavision","state_root":"/var/behavision",
+"config":"/var/behavision/config/default.yaml","data_dir":"/var/behavision/data",
+"models_dir":"/var/behavision/models"},"cameras":{"cam1":true},"uptime_seconds":42.5}`
+
+func TestHealthDecodesWhatTheEngineActuallySends(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(realHealthBody))
+	}))
+	defer srv.Close()
+
+	s := New(Options{HealthURL: srv.URL})
+	h, err := s.Health(context.Background())
+	if err != nil {
+		t.Fatalf("the engine's own reply did not decode: %v", err)
+	}
+	if h.RecognitionModel != "w600k_r50" {
+		t.Errorf("model = %q", h.RecognitionModel)
+	}
+	// The two fields the heartbeat carries. Losing these is what made a
+	// working site look empty at head office.
+	if up, ok := h.Cameras["cam1"]; !ok || !up {
+		t.Errorf("cameras = %v, want cam1 connected", h.Cameras)
+	}
+	if h.Paths.StateRoot != "/var/behavision" || h.Paths.Frozen {
+		t.Errorf("paths = %+v", h.Paths)
+	}
+}