A visit is #1042, not 4cc216ca-dad3-4958-bb96-5f5a82022cf8

Every other thing in this product a person refers to already had a
readable reference: a shop is chennai, a camera cam1, a customer V-42, a
person their email. An audit of every list response found exactly one
gap, and it was the row people look at most - the arrivals feed showed a
visit as 36 hex characters.

012 argued no route takes a visit id so none was needed. That is true of
routing and false of everything else: it is what the feed shows, what a
support conversation quotes, and what somebody reading an API response
judges the product by.

Migration 014 mirrors the visitor scheme exactly - per client, so it
discloses no platform-wide volume, and beside the uuid rather than
instead of it. A stored counter is affordable on the busiest table
because visits from one tenant are already serialised by the consumer's
SetOrderMatters(true), so it adds no contention that was not already
there. A derived reference was the alternative and does not work:
several people through one door share occurred_at to the microsecond,
which is the collision 004 exists to handle.

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

server/internal/api/refs.go

@@ -47,6 +47,20 @@ func VisitorRef(number int64) string {
 	return VisitorRefPrefix + strconv.FormatInt(number, 10)
 }
 
+// VisitRefPrefix marks a visit reference. "#" rather than a letter because a
+// visit is a numbered event, not a named thing, and it reads correctly in a
+// sentence: "visit #1042 at chennai".
+const VisitRefPrefix = "#"
+
+// VisitRef is what a person quotes for one visit. Empty for a visit recorded
+// before 014, which had no number - absent rather than wrong.
+func VisitRef(number int64) string {
+	if number <= 0 {
+		return ""
+	}
+	return VisitRefPrefix + strconv.FormatInt(number, 10)
+}
+
 // ParseVisitorRef accepts "V-42", "v-42" and bare "42".
 //
 // Bare digits are accepted because a shop assistant reading a number off a

server/internal/api/refs_test.go

@@ -140,3 +140,18 @@ func TestAnArrivalCarriesTheShopReferenceItCanBeFilteredBy(t *testing.T) {
 		t.Fatalf("the platform-wide visit counter leaked into the feed: %s", body)
 	}
 }
+
+// A visit reference is what a person quotes; the uuid is what a machine
+// de-duplicates on. Both travel, neither replaces the other.
+func TestVisitRefIsReadableAndAbsentWhenUnnumbered(t *testing.T) {
+	if got := VisitRef(1042); got != "#1042" {
+		t.Errorf("VisitRef(1042) = %q, want #1042", got)
+	}
+	// Visits recorded before 014 have no number. Absent, never "#0" - a
+	// reference that looks real and is not is worse than none.
+	for _, n := range []int64{0, -1} {
+		if got := VisitRef(n); got != "" {
+			t.Errorf("VisitRef(%d) = %q, want empty", n, got)
+		}
+	}
+}

server/internal/api/types.go

@@ -268,6 +268,11 @@ type AgentPrincipal struct {
 // audit log to do it.
 type Arrival struct {
 	VisitID string `json:"visit_id"`
+	// VisitRef is what a person quotes - "#1042" - per client, beside the uuid
+	// rather than instead of it. Every other thing in the product a person
+	// refers to has one: a shop is `chennai`, a camera `cam1`, a customer
+	// `V-42`. A visit had only 36 hex characters.
+	VisitRef string `json:"visit_ref,omitempty"`
 	// Seq is this visit's position in the feed - assigned by the server when it
 	// learned of the visit, not by the camera. It drives the cursor and the
 	// ordering, and it is `json:"-"` on purpose.