A customer number people can say out loud

Every id in the schema is a uuid and stays one. What was wrong was
putting one in front of a person: RecordVisit named every new customer
'Visitor ' || left(id::text, 8), so the arrivals feed, the shop PC and
the mobile app all read "Visitor 3446ec35" - the string a shop assistant
reads to a colleague and types into a search box. label is a stored
column staff can overwrite and SearchVisitors matches on, so formatting
around it in a front end would have left the data wrong on three
surfaces.

Migration 012 adds a per-client visitors.number, taken from a counter on
clients with UPDATE ... RETURNING inside the visit transaction. Per
client rather than global: a global sequence would tell any customer who
signs up how many people the whole platform has ever seen, from their
own first visitor number. The backfill numbers existing rows by
first_seen_at and relabels only the eight-hex pattern the old statement
produced, so a human-typed name is never overwritten.

Three of the four things anyone addresses by URL already had a human
name and the API simply refused it - a site has a slug, a camera has the
id the engine knows it by. refs.go accepts either form anywhere an id is
taken; a uuid resolves with no lookup, so every URL a client already
stored keeps working.

- An ambiguous camera name resolves to nothing, never to a guess: two
  shops may each have an "Office1" and acting on the first row would
  edit the wrong shop's camera.
- 404 on a path, 400 on a query filter. /api/visits answered fine and it
  was the filter that was wrong.
- site and site_id are both accepted everywhere now. They differed per
  endpoint, and an unknown query parameter is silently ignored, so
  getting it the wrong way round returned the whole estate.
- The search matches V-13, which is what the product now shows.

Two bugs found by running it rather than testing it:

- 'Visitor ' || $2::text beside number = $2 makes Postgres deduce two
  types for one parameter and refuse the insert. It compiled and passed
  every in-memory test; the first real database rejected it, along with
  the existing face tests that share the path.
- The fallback avatar said "V1" for Visitor 13, Visitor 10 and Visitor
  15 alike, and read as the V-1 reference for a fourth person. It shows
  the number now. The prop is customerRef, not ref - React reserves
  that name and it would never have arrived.

Verified on the live database and through the running API: 13 hex labels
became Visitor 1-13 in first-seen order, two typed names left alone, and
the same customer reachable by uuid, V-13 and 13.

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

server/internal/store/api_arrivals.go

@@ -15,6 +15,7 @@ const arrivalColumns = `
 	vi.id::text, vi.seq, vi.occurred_at, vi.site_id::text, si.name, vi.camera_id,
 	vi.is_new_visitor, vi.similarity, vi.quality, vi.attributes, vi.image_key,
 	COALESCE(vi.visitor_id::text, ''),
+	COALESCE(vs.number, 0),
 	COALESCE(vs.label, ''),
 	COALESCE(p.full_name, '')`
 
@@ -111,11 +112,13 @@ func (s *Store) Arrivals(ctx context.Context, q api.ArrivalQuery) ([]api.Arrival
 		var at time.Time
 		var sim, qual *float64
 		var imageKey string
+		var number int64
 		if err := rows.Scan(&a.VisitID, &a.Seq, &at, &a.SiteID, &a.Site, &a.CameraID,
 			&a.IsNew, &sim, &qual, &a.Attributes, &imageKey,
-			&a.VisitorID, &a.Label, &a.Name); err != nil {
+			&a.VisitorID, &number, &a.Label, &a.Name); err != nil {
 			return nil, err
 		}
+		a.VisitorRef = api.VisitorRef(number)
 		a.OccurredAt = at.UTC().Format(time.RFC3339Nano)
 		if sim != nil {
 			a.Similarity = *sim

server/internal/store/api_arrivals_live_test.go

@@ -63,9 +63,9 @@ func seedTenant(t *testing.T, st *Store, name string, n int, withImages bool) (c
 	for i := 0; i < n; i++ {
 		var visitorID string
 		if err := st.pool.QueryRow(ctx, `
-			INSERT INTO visitors (client_id, label, first_seen_at)
-			VALUES ($1::uuid, $2, $3) RETURNING id::text`,
-			clientID, fmt.Sprintf("Visitor %d", i), start).Scan(&visitorID); err != nil {
+			INSERT INTO visitors (client_id, number, label, first_seen_at)
+			VALUES ($1::uuid, $2, $3, $4) RETURNING id::text`,
+			clientID, i+1, fmt.Sprintf("Visitor %d", i+1), start).Scan(&visitorID); err != nil {
 			t.Fatalf("seed visitor: %v", err)
 		}
 		key := ""

server/internal/store/api_people.go

@@ -25,11 +25,27 @@ func likePattern(q string) string {
 	return "%" + r.Replace(q) + "%"
 }
 
+// searchNumber is the customer number behind a query, or 0 for a query that is
+// not one.
+//
+// The reference is what staff now READ on screen - "V-13" - so it is what they
+// paste into the search box, and matching only `label ILIKE '%V-13%'` finds
+// nothing at all, because the stored label says "Visitor 13". A search that
+// comes back empty for the identifier the product just showed you is worse
+// than no search at all.
+func searchNumber(query string) int64 {
+	n, ok := api.ParseVisitorRef(query)
+	if !ok {
+		return 0
+	}
+	return n
+}
+
 func (s *Store) SearchVisitors(ctx context.Context, clientID, query string, limit int) (
 	[]api.Customer, error) {
 
 	rows, err := s.pool.Query(ctx, `
-		SELECT v.id::text, v.label,
+		SELECT v.id::text, v.number, v.label,
 		       COALESCE(p.full_name, ''), COALESCE(p.phone, ''), COALESCE(p.email, ''),
 		       v.visit_count, v.first_seen_at, v.last_seen_at,
 		       (p.id IS NOT NULL),
@@ -39,13 +55,15 @@ func (s *Store) SearchVisitors(ctx context.Context, clientID, query string, limi
 		LEFT JOIN visitor_profiles p
 		       ON p.visitor_id = v.id AND p.client_id = v.client_id
 		WHERE v.client_id = $1 AND v.deleted_at IS NULL
-		  AND ($2 = '' OR v.label ILIKE $3 ESCAPE '\'
+		  AND ($2 = '' OR v.number = $5
+		               OR v.label ILIKE $3 ESCAPE '\'
 		               OR p.full_name ILIKE $3 ESCAPE '\'
 		               OR p.phone     ILIKE $3 ESCAPE '\'
 		               OR p.email     ILIKE $3 ESCAPE '\')
 		ORDER BY v.last_seen_at DESC NULLS LAST, v.first_seen_at DESC
 		LIMIT $4`,
-		clientID, strings.TrimSpace(query), likePattern(strings.TrimSpace(query)), limit)
+		clientID, strings.TrimSpace(query), likePattern(strings.TrimSpace(query)),
+		limit, searchNumber(query))
 	if err != nil {
 		return nil, err
 	}
@@ -56,10 +74,12 @@ func (s *Store) SearchVisitors(ctx context.Context, clientID, query string, limi
 		var c api.Customer
 		var first time.Time
 		var last *time.Time
-		if err := rows.Scan(&c.ID, &c.Label, &c.FullName, &c.Phone, &c.Email,
+		var number int64
+		if err := rows.Scan(&c.ID, &number, &c.Label, &c.FullName, &c.Phone, &c.Email,
 			&c.VisitCount, &first, &last, &c.HasProfile, &c.HasConsent); err != nil {
 			return nil, err
 		}
+		c.Ref = api.VisitorRef(number)
 		c.FirstSeenAt = first.UTC().Format(time.RFC3339)
 		if last != nil {
 			c.LastSeenAt = last.UTC().Format(time.RFC3339)

server/internal/store/api_refs.go

@@ -0,0 +1,81 @@
+package store
+
+import (
+	"context"
+	"errors"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// Resolving a public reference to the uuid it names.
+//
+// Every id in this schema is a uuid and stays one. These three exist because a
+// uuid is not something a person can say, type or recognise, and three of the
+// four things anyone addresses by URL already HAD a human name that the API
+// simply refused to accept: a site has a slug, a camera has the id the engine
+// knows it by (and the one that lands in `visits.camera_id`), and a visitor now
+// has a per-tenant number. See api/refs.go for the formats.
+//
+// All three answer "" with a nil error when nothing matches. A found id is
+// never empty, so the two cases cannot be confused, and a mistyped reference is
+// a 404 rather than an error the handler has to classify.
+
+// SiteIDBySlug resolves a site slug within one tenant.
+func (s *Store) SiteIDBySlug(ctx context.Context, clientID, slug string) (string, error) {
+	var id string
+	err := s.pool.QueryRow(ctx, `
+		SELECT id::text FROM sites
+		 WHERE client_id = $1::uuid AND slug = $2`,
+		clientID, slug).Scan(&id)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", nil
+	}
+	return id, err
+}
+
+// CameraIDByRef resolves the engine's own camera id - "Office1" - to the row
+// uuid, within one tenant.
+//
+// A camera id is unique per SITE, not per tenant, so two shops may each have an
+// "Office1". Ambiguity is resolved as no match rather than by picking one:
+// silently acting on whichever row sorted first would edit or delete the wrong
+// shop's camera. A caller in that position has the uuid, or can scope by site.
+func (s *Store) CameraIDByRef(ctx context.Context, clientID, ref string) (string, error) {
+	rows, err := s.pool.Query(ctx, `
+		SELECT id::text FROM site_cameras
+		 WHERE client_id = $1::uuid AND camera_id = $2 AND deleted_at IS NULL
+		 LIMIT 2`, clientID, ref)
+	if err != nil {
+		return "", err
+	}
+	defer rows.Close()
+
+	var found []string
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err != nil {
+			return "", err
+		}
+		found = append(found, id)
+	}
+	if err := rows.Err(); err != nil {
+		return "", err
+	}
+	if len(found) != 1 {
+		return "", nil
+	}
+	return found[0], nil
+}
+
+// VisitorIDByNumber resolves the number behind "V-42" within one tenant.
+func (s *Store) VisitorIDByNumber(ctx context.Context, clientID string, number int64) (string, error) {
+	var id string
+	err := s.pool.QueryRow(ctx, `
+		SELECT id::text FROM visitors
+		 WHERE client_id = $1::uuid AND number = $2`,
+		clientID, number).Scan(&id)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", nil
+	}
+	return id, err
+}

server/internal/store/api_refs_live_test.go

@@ -0,0 +1,182 @@
+package store
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/loyaly/behavision-server/internal/contract"
+	"github.com/loyaly/behavision-server/internal/ingest"
+)
+
+// The name a shop assistant actually reads.
+//
+// Before 012 this was `'Visitor ' || left(id::text, 8)`, so the arrivals feed
+// said "Visitor 3446ec35" - a string nobody can say out loud, write on a card
+// or type into a search box. The number is what fixes that, and it has to be
+// right at the point it is WRITTEN: `label` is a stored column that staff can
+// overwrite and that SearchVisitors matches on, so formatting around it in the
+// front end would have left the stored data wrong on three surfaces.
+//
+// Only a real database proves this. The counter lives on `clients` and is taken
+// with UPDATE ... RETURNING inside the visit transaction - the same semantics
+// that silently broke the face prune in 011 by returning the value it had just
+// written. Here that is exactly what is wanted, and an in-memory fake would
+// agree with any implementation.
+// distinctFace returns a vector pointing along its own axis, so any two of them
+// are orthogonal - cosine 0, far below any match threshold.
+//
+// `embedding(seed)` fills every dimension with one value, so after L2
+// normalisation 0.31 and 0.62 are the SAME direction and the matcher correctly
+// calls them one person. That is right for the face tests it was written for
+// and useless here, where the whole point is several different people.
+func distinctFace(i int) []float32 {
+	v := make([]float32, contract.EmbeddingDim)
+	v[i%contract.EmbeddingDim] = 1
+	return v
+}
+
+func TestLiveVisitorNumbersStartAtOneForEveryTenant(t *testing.T) {
+	st := liveStore(t)
+	ctx := context.Background()
+
+	// Two tenants, so a number that leaked across them would show up as a gap.
+	for _, tenant := range []string{"num-a-" + stamp(), "num-b-" + stamp()} {
+		site := seedAgentSite(t, st, tenant)
+
+		for i := 0; i < 3; i++ {
+			// A different face each time, so each becomes its own visitor.
+			ok, err := st.RecordVisit(ctx, site, &contract.Visit{
+				EventID:    fmt.Sprintf("%s-%d", tenant, i),
+				OccurredAt: time.Now().UTC().Add(time.Duration(i) * time.Second),
+				CameraID:   "door",
+				IsNew:      true,
+				Quality:    0.8,
+				Embedding:  distinctFace(i),
+			})
+			if err != nil || !ok {
+				t.Fatalf("%s visit %d: ok=%v err=%v", tenant, i, ok, err)
+			}
+		}
+
+		rows, err := st.pool.Query(ctx, `
+			SELECT number, label FROM visitors
+			 WHERE client_id = $1::uuid ORDER BY number`, site.ClientID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		var got []string
+		for rows.Next() {
+			var n int64
+			var label string
+			if err := rows.Scan(&n, &label); err != nil {
+				t.Fatal(err)
+			}
+			got = append(got, fmt.Sprintf("%d=%s", n, label))
+		}
+		rows.Close()
+
+		want := []string{"1=Visitor 1", "2=Visitor 2", "3=Visitor 3"}
+		if len(got) != len(want) {
+			t.Fatalf("%s: got %v, want %v", tenant, got, want)
+		}
+		for i := range want {
+			if got[i] != want[i] {
+				t.Fatalf("%s: got %v, want %v", tenant, got, want)
+			}
+		}
+	}
+}
+
+// A number is a public reference, so it must resolve only within the tenant it
+// belongs to. Both tenants have a V-1; asking as one must never return the
+// other's customer.
+func TestLiveAVisitorNumberResolvesOnlyWithinItsOwnTenant(t *testing.T) {
+	st := liveStore(t)
+	ctx := context.Background()
+
+	mine := seedAgentSite(t, st, "ref-mine-"+stamp())
+	theirs := seedAgentSite(t, st, "ref-theirs-"+stamp())
+
+	for i, s := range []ingest.Site{mine, theirs} {
+		if ok, err := st.RecordVisit(ctx, s, &contract.Visit{
+			EventID:    s.Slug + "-1",
+			OccurredAt: time.Now().UTC(),
+			CameraID:   "door",
+			IsNew:      true,
+			Quality:    0.8,
+			Embedding:  distinctFace(i),
+		}); err != nil || !ok {
+			t.Fatalf("seed visit: ok=%v err=%v", ok, err)
+		}
+	}
+
+	mineID, err := st.VisitorIDByNumber(ctx, mine.ClientID, 1)
+	if err != nil || mineID == "" {
+		t.Fatalf("V-1 in my own tenant: %q %v", mineID, err)
+	}
+	theirsID, err := st.VisitorIDByNumber(ctx, theirs.ClientID, 1)
+	if err != nil || theirsID == "" {
+		t.Fatalf("V-1 in the other tenant: %q %v", theirsID, err)
+	}
+	if mineID == theirsID {
+		t.Fatal("V-1 resolved to the same customer for two different tenants")
+	}
+
+	// And a number nobody has is a miss, not an error - which is what lets the
+	// handler answer 404 without classifying an error first.
+	got, err := st.VisitorIDByNumber(ctx, mine.ClientID, 999999)
+	if err != nil || got != "" {
+		t.Fatalf("unknown number: got %q, err %v - want an empty miss", got, err)
+	}
+}
+
+// A site slug and a camera id are the other two references, and both already
+// existed in the schema; only the API refused to accept them.
+func TestLiveSiteAndCameraResolveByTheirOwnNames(t *testing.T) {
+	st := liveStore(t)
+	ctx := context.Background()
+	site := seedAgentSite(t, st, "names-"+stamp())
+
+	id, err := st.SiteIDBySlug(ctx, site.ClientID, site.Slug)
+	if err != nil || id != site.SiteID {
+		t.Fatalf("slug %q resolved to %q (want %q), err %v",
+			site.Slug, id, site.SiteID, err)
+	}
+	if got, err := st.SiteIDBySlug(ctx, site.ClientID, "no-such-shop"); err != nil || got != "" {
+		t.Fatalf("unknown slug: got %q, err %v", got, err)
+	}
+
+	var camUUID string
+	if err := st.pool.QueryRow(ctx, `
+		INSERT INTO site_cameras (client_id, site_id, camera_id, label, host)
+		VALUES ($1::uuid, $2::uuid, 'Office1', 'Front door', '10.0.0.5')
+		RETURNING id::text`, site.ClientID, site.SiteID).Scan(&camUUID); err != nil {
+		t.Fatal(err)
+	}
+	got, err := st.CameraIDByRef(ctx, site.ClientID, "Office1")
+	if err != nil || got != camUUID {
+		t.Fatalf("camera by name: got %q (want %q), err %v", got, camUUID, err)
+	}
+
+	// Two shops in one tenant may each have an "Office1". Acting on whichever
+	// row sorted first would edit the wrong shop's camera, so ambiguity must
+	// resolve to nothing rather than to a guess.
+	var secondSite string
+	if err := st.pool.QueryRow(ctx, `
+		INSERT INTO sites (client_id, name, slug) VALUES ($1::uuid, 'Second', $2)
+		RETURNING id::text`, site.ClientID, site.Slug+"-2").Scan(&secondSite); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := st.pool.Exec(ctx, `
+		INSERT INTO site_cameras (client_id, site_id, camera_id, label, host)
+		VALUES ($1::uuid, $2::uuid, 'Office1', 'Other door', '10.0.0.6')`,
+		site.ClientID, secondSite); err != nil {
+		t.Fatal(err)
+	}
+	if got, err := st.CameraIDByRef(ctx, site.ClientID, "Office1"); err != nil || got != "" {
+		t.Fatalf("an ambiguous camera name resolved to %q - it must resolve to "+
+			"nothing rather than pick one", got)
+	}
+}

server/internal/store/store.go

@@ -222,18 +222,34 @@ func (s *Store) matchOrCreateVisitor(ctx context.Context, tx pgx.Tx,
 	}
 
 	// New person for this client.
+	//
+	// The number comes off the tenant's own counter rather than being derived
+	// from the uuid, because it is what a human will read, say and search for:
+	// "Visitor 42", not "Visitor 3446ec35". UPDATE ... RETURNING yields the
+	// value AFTER the update, which is what is wanted here, and it row-locks
+	// the client for the length of the insert so two shops cannot take the
+	// same number. That lock is free - this runs only for a face nobody in the
+	// estate has ever seen, not once per visit.
+	var number int64
+	if err := tx.QueryRow(ctx, `
+		UPDATE clients SET visitor_seq = visitor_seq + 1
+		WHERE id = $1 RETURNING visitor_seq`,
+		site.ClientID).Scan(&number); err != nil {
+		return "", fmt.Errorf("next visitor number: %w", err)
+	}
+	// The label is formatted here rather than as `'Visitor ' || $2::text` in
+	// the statement: reusing one parameter as a bigint and as a string operand
+	// makes Postgres deduce two types for it and refuse the whole insert
+	// ("inconsistent types deduced for parameter $2"). It compiled, it passed
+	// every in-memory test, and it failed on the first real database.
 	var newID string
 	if err := tx.QueryRow(ctx, `
-		INSERT INTO visitors (client_id, label, first_seen_at)
-		VALUES ($1, '', $2) RETURNING id::text`,
-		site.ClientID, v.OccurredAt).Scan(&newID); err != nil {
+		INSERT INTO visitors (client_id, number, label, first_seen_at)
+		VALUES ($1, $2, $3, $4) RETURNING id::text`,
+		site.ClientID, number, fmt.Sprintf("Visitor %d", number),
+		v.OccurredAt).Scan(&newID); err != nil {
 		return "", fmt.Errorf("create visitor: %w", err)
 	}
-	if _, err := tx.Exec(ctx, `
-		UPDATE visitors SET label = 'Visitor ' || left(id::text, 8)
-		WHERE id = $1 AND label = ''`, newID); err != nil {
-		return "", err
-	}
 	if _, err := tx.Exec(ctx, `
 		INSERT INTO visitor_embeddings
 		  (visitor_id, client_id, model, embedding, quality, source_site_id)