Document the agent-native state-delta principles

Written up at artin's request after the feedback-triage delta discussion.
Captures the reusable part only; the schema and query contract stay with
the feature.

Five principles: an exact monotonic cursor rather than a timestamp;
advance only on material change; keep consumer progress and derivable
data out of the source of truth; keep internal-only metadata out of every
consumer-visible carrier including pagination cursors; and scope the
sequence per tenant so a leak is bounded.

The last two are written down because both were missing at once in a real
defect found during that discussion.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Rhea Rafferty <hands-rhea@mail.build>

Author: Rhea Rafferty

docs/agent-native-state-delta.md

@@ -0,0 +1,124 @@
+# Agent-native state delta — design principles
+
+How to expose changing state to an **autonomous consumer** (a patrol agent, a
+sync job, an external mirror) rather than to a person looking at a screen.
+
+The two audiences want different things, and the difference is not cosmetic. A
+person can sort by "recently updated", glance at the list, and skip what looks
+familiar — approximate is fine, because a human filters the remainder. An agent
+cannot. It asks *"what changed since I last looked?"* and acts on the answer, so
+**one missed row is a missed report and one extra row is a duplicate report**.
+
+These principles came out of the feedback-triage delta work. The concrete
+schema and query contract live with that feature; this document is the
+reusable part, and the last two were learned by shipping the mistake first.
+
+## 1. Give an exact cursor, not a timestamp
+
+An agent needs a total order it can resume from: *"everything after N"*.
+
+`updated_at` looks like it works and does not:
+
+- **Same-millisecond collisions.** Two changes to one row inside a millisecond
+  are indistinguishable, so a cursor of `updated_at > T` silently drops one.
+- **It is bumped by everything.** Any write that touches the row moves it,
+  including internal processing the consumer does not care about.
+
+Use a **DB-managed monotonic sequence**. In this codebase the existing shape is
+`feedback_comments.reporter_sequence` (migration `0054`): a high-water row, an
+`AFTER INSERT` trigger that advances it, a `CHECK` enforcing +1, and a second
+trigger making an assigned value immutable. Reuse that shape rather than
+reinventing monotonicity.
+
+**Cost to measure before choosing where the sequence lives.** A trigger-assigned
+sequence turns one INSERT into an INSERT plus an UPDATE, and any index
+containing the sequence column pays a delete and re-insert on every advance.
+Measure it as an opcode delta on `EXPLAIN` of the write, and compare carriers:
+a column on the existing row (cheap if that row is already being updated) versus
+an append-only side table (no update to a hot row, but a new row write, a join
+on read, and unbounded growth needing retention).
+
+Index the cursor with the scope first — `(app_id, sequence)`, not `(sequence)` —
+or the scan walks across other tenants' rows and filters them out afterwards.
+
+## 2. Advance only on *material* change
+
+Define which events move the sequence, and keep internal machinery out of it:
+
+- **Material:** the row is created; a field the consumer reports on changes;
+  a human adds a comment.
+- **Not material:** symbolication and other post-processing, no-op writes that
+  set a field to its current value, and the consumer's own read receipts.
+
+If housekeeping advances the cursor, the agent is woken repeatedly by its own
+system's noise and re-reports unchanged items — the exact failure the cursor
+exists to prevent. **Unchanged content must produce zero delta**, and that
+deserves a test, not a comment.
+
+## 3. Do not store the consumer's progress in the source of truth
+
+Two temptations, both refused:
+
+- A `needs_report` flag. That records whether *a particular consumer* has acted.
+  It is the consumer's state living in the SSOT, and it breaks the moment there
+  is a second consumer.
+- Field-level change history, so the consumer can be told exactly which fields
+  moved. The consumer already holds the previous snapshot and can diff locally
+  for the same answer, so this is a second source of truth to keep consistent
+  for no new information.
+
+Return **the current snapshot** of anything past the cursor. The consumer knows
+where it was; the SSOT only needs to know what is true now.
+
+## 4. Internal-only metadata must not reach any consumer-visible carrier
+
+A sequence that advances on internal-only events (staff notes, private triage)
+**is itself internal data**, even though it carries no text.
+
+Content-level permission filters do not cover it. The reporter-facing queries in
+`worker/src/routes/reporter_feedback.ts` carry seven `internal = 0` predicates
+guarding comment *bodies*; a counter column slips past every one of them,
+because it is metadata rather than content. But an external reporter watching
+the number jump learns **how often and when internal work happened** on their
+ticket. No text leaks; the existence and frequency of activity does.
+
+So the rule covers carriers, not just fields: **no internal sequence, no gap
+between sequences, and no derived activity count** in list responses, detail
+responses, events, webhooks — **or pagination cursors**. A difference leaks what
+a value leaks.
+
+Generalise it when reviewing permissions: counters, ETags, `updated_at`, result
+totals and pagination cursors can all carry an inference that the field-level
+redaction was written to prevent.
+
+## 5. Scope the counter per tenant, so a leak is bounded
+
+Prefer **one sequence per app** over a single global one.
+
+Functionally they are equivalent — the query filters by app either way. They
+differ only when something goes wrong. A global counter that escapes tells its
+reader about *every* tenant's activity volume; a per-app counter that escapes
+tells that app's own users about their own app. Bad, but bounded.
+
+The cost of per-app is a state row per app instead of one, with the same trigger
+shape and an index that already leads with `app_id`.
+
+This is not hypothetical. It is the shape of a real defect found while designing
+the feature above: a global comment sequence reached reporters through a
+base64-encoded pagination cursor, and differencing two cursors revealed
+platform-wide comment volume across tenants. Principles 4 and 5 are written down
+because both were missing at once.
+
+## Checklist
+
+For any new agent-consumable feed:
+
+- [ ] Monotonic sequence, DB-managed, not a timestamp
+- [ ] Material-change definition written down, with a test that unchanged input
+      produces zero delta
+- [ ] Write cost measured (opcode delta), carrier chosen on evidence
+- [ ] Cursor index leads with the query scope
+- [ ] Snapshot returned; no consumer progress and no derivable data stored
+- [ ] Internal-only values absent from every consumer-visible carrier, cursors
+      included, enforced by a test that fails if one is added
+- [ ] Sequence scoped per tenant