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

server/migrations/004_visit_sequence.sql

@@ -0,0 +1,33 @@
+BEGIN;
+
+-- A monotonic, server-assigned position for every visit, so a live feed can be
+-- paged without losing anyone.
+--
+-- The arrivals feed originally ordered by (occurred_at, id). That is wrong in a
+-- way that only appears under the exact condition the feed exists for: several
+-- people walking through one door together share an occurred_at to the
+-- microsecond, so the tiebreaker was a RANDOM uuid. A visit committed after the
+-- reader had moved its cursor, but carrying a lower uuid, sorted behind the
+-- cursor and was never delivered - a silent footfall undercount, exactly the
+-- class of bug this system is otherwise careful about. Measured live: four
+-- simultaneous visits, two delivered.
+--
+-- occurred_at cannot fix it either. It is the CAMERA's clock, and a site that
+-- was offline for a day floods in with yesterday's timestamps; a reader whose
+-- cursor is already past them would skip the entire backlog.
+--
+-- So the feed is ordered by when the SERVER learned of a visit, not by when it
+-- happened. Each row still carries occurred_at for display; seq is only ever a
+-- position. That is what makes a reconnecting site's backlog get delivered
+-- rather than hidden behind a timestamp the reader has passed.
+ALTER TABLE visits ADD COLUMN IF NOT EXISTS seq bigserial;
+
+-- The feed always filters by tenant and orders by seq, so this is the index it
+-- runs on. Without it every poll is a scan of the whole table.
+CREATE INDEX IF NOT EXISTS visits_client_seq_idx ON visits (client_id, seq);
+CREATE INDEX IF NOT EXISTS visits_site_seq_idx   ON visits (site_id, seq);
+
+-- Not UNIQUE by accident: bigserial already guarantees it, and the constraint
+-- would make a future partitioning change harder for no gain.
+
+COMMIT;