@ultimat3/realtime 11.3.0 → 12.0.0

package/CLAUDE.md

@@ -604,8 +604,10 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `liveQueryDefinition` keys the shared window by the qid — so keeping both correct was never the
   option; the first time either moved, every resume decision and every window lookup were keyed
   differently. `realtime -> query` is the one declared sideways edge and this package already
-  imports it. **`fnv1a` stays here**, and only it: its job is the cursor's result-set digest, where
-  a collision costs a missed re-sort and never one client served out of another's window.
+  imports it. **`fnv1a` is gone too, `As of 2026-08-24`**: it stayed for one job — the cursor's
+  result-set digest — and `LiveCursor.digest` was deleted for having no reader, so this package now
+  owns no hash at all. A 32-bit hash nothing calls is one the next caller reaches for as a sharing
+  key, which is the single thing `json.test.ts` used to pin it against.
   `live-contract.test.ts` is the pin — it reads `registry.subscriberCount(queryHash(name, input))`
   through a real subscribe, so a local derivation fails it. Cost of the move: none observable on the
   server. Every qid a node computes comes from a DECODED frame, and `JSON.parse` produces no
@@ -821,7 +823,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 | `policy-gate.ts` | the only authz seam |
 | `subscriber-gate.ts` | the per-subscriber pass of a definition's row policy, and its two counters — `rowsDenied` and `gateFailures`. Evaluates no policy of its own |
 | `live-contract.ts` | what a live query IS: `LiveQueryDefinition`, `SnapshotResult`, `LiveSubscription`. Four modules need the shape and none of them needs the registry that runs it. The **id** is not here and not anywhere in this package — it is `@ultimat3/query`'s `queryHash` |
-| `json.ts` | the wire's value types and `fnv1a` (drift), the one hash still owned here. The canonical form and the sharing-key hash are `@ultimat3/core`'s (`canonicalJson`, `fingerprint`) — `json.test.ts` pins that `fnv1a` is never mistakable for one |
+| `json.ts` | the wire's value types. **No hash**: the canonical form and the sharing-key hash are `@ultimat3/core`'s (`canonicalJson`, `fingerprint`), and the 32-bit `fnv1a` that stayed for `LiveCursor.digest` went with it (2026-08-24) |
 | `live-definition.ts` | the only bridge from a declared `query({ live: true })` to a registrable definition — and `policy-gate.ts`'s only caller |
 | `matcher-bridge.ts` | the only `@ultimat3/query` matcher seam — and where a patch row is narrowed to the columns the query returned |
 
@@ -847,6 +849,16 @@ field always held. Bumping for either refuses every in-flight client on a rollin
 nothing — the version guards incompatibility, not novelty. Removing a field something *does* read
 is the opposite case and bumps.
 
+**"Nothing read it" is decided by the DECODER, not by the callers — and that half is what moved
+`PROTOCOL_VERSION` to 2 (2026-08-24, BREAKING).** `hello.resume` was free because `decode` read it
+through `list()`, which answers `[]` for an absent field; `cursor.digest` and `cursor.count` were
+read through `str()` and `num()`, which **throw**. So deleting two fields no *caller* consumed
+still made the frame unreadable to a peer one deploy behind — in **both** directions, since a
+cursor rides the client's `subscribe` and the node's `snapshot`. Without the bump the skew shows up
+as a per-frame `field "digest" must be a string`, which is the same refusal with none of the
+instruction. Before claiming a removal is free, read the field's line in `decode`: a `list()` is
+free, a `str()`/`num()` is a bump.
+
 **A patch carries the result set's columns, never the table's** — `narrowRow` in
 `matcher-bridge.ts`, `As of 2026-08-20`. A `ChangeEvent` carries the whole TABLE row (that is what
 logical replication emits, and what `@ultimat3/entity`'s `setRowObserver` emits), while a live

package/README.md

@@ -269,9 +269,11 @@ that outlasts the deploy. The design confronts it with exactly two paths and no
 | **delta** | the cursor's gap is inside the retained window and inside the budget | one buffer read, zero DB work |
 | **snapshot** | out of window, past `maxLagMs`, or past `reconnectBudget` | one bounded indexed query |
 
-A `LiveCursor` is `lsn` + result-set `digest` + last-seen `ids` + `count`. The digest is
-order-sensitive and server-side (see `cursor.ts#digestOf` for why a client cannot reproduce one); the ids let a delta be re-filtered per subscriber, because
-the retained window stores **pre-policy** patches. `resumeFrom()` picks the path,
+A `LiveCursor` is `qid` + `lsn` + last-seen `ids` + `at`, and nothing else. The ids let a delta be
+re-filtered per subscriber, because the retained window stores **pre-policy** patches. It carried a
+result-set `digest` and a `count` until 2026-08-24; both were written by every snapshot and read by
+nobody, and the digest cost a canonical serialize plus a hash over every row of every snapshot —
+paid once per live query per reconnecting socket. `resumeFrom()` picks the path,
 `shouldResnapshot()` explains it, and the budget is a cost model in patch-equivalents
 (`snapshotCost: 250` = "replaying 250 patches costs a snapshot") so the expensive path is *chosen*,
 never stumbled into.
@@ -361,10 +363,11 @@ wire twice by a reconnect that raced an ack.
   the rebase log rather than retried: a denial is a decision about that intent, and replaying it
   would put the write the server refused back on the screen. Idempotent for a key the log does not
   hold, because a denial can arrive twice and tier 2 records nothing to undo.
-- **A delta resume leaves the digest unverified** (`DIGEST_UNVERIFIED`). Only a snapshot re-establishes
-  it. The digest is the SERVER's own — nothing on the client reproduces it, and `verifyDigest()`,
-  which claimed otherwise and had no caller, is deleted (2026-08-23). What detects drift on the
-  client is the server's `desynced` mark and the re-snapshot it triggers.
+- **Nothing on the client detects drift, and nothing ever did.** `verifyDigest()` claimed to and had
+  no caller (deleted 2026-08-23); the `digest` it read went with it (2026-08-24), along with the
+  `count` beside it. What detects drift is the server's `desynced` mark and the re-snapshot it
+  triggers. Removing the two fields moved `PROTOCOL_VERSION` to **2** — `cursor()` decodes through
+  readers that throw on an absent field, unlike the `list()` that made `hello.resume`'s removal free.
 - **Backpressure drops patch frames.** That is safe *only* because a re-snapshot is cheap: the drop
   is recorded on the socket (`desynced`) and the next delivery re-snapshots rather than diverging.
 - **A dropped CHANNEL frame is not safe, and is not repaired.** A topic has no cursor, no mark and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "11.3.0",
+  "version": "12.0.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -36,8 +36,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "11.3.0",
-    "@ultimat3/query": "11.3.0",
+    "@ultimat3/core": "12.0.0",
+    "@ultimat3/query": "12.0.0",
     "nats": "2.29.3"
   }
 }

package/src/cursor.ts

@@ -3,26 +3,28 @@
 // and the budget exists to make the expensive answer (a snapshot) the *chosen* one, not the
 // accidental one. See README "Reconnect is the hard part".
 
-import { type Clock, canonicalJson, systemClock } from '@ultimat3/core';
+import { type Clock, systemClock } from '@ultimat3/core';
 import { CursorStaleError } from './errors';
-import { fnv1a, type Row, type RowPatch } from './json';
+import type { Row, RowPatch } from './json';
 
 /** Ids are bounded so a cursor stays small enough to ship on every `subscribe` frame. */
 export const CURSOR_ID_LIMIT = 512;
 
-/** A digest of `''` means "not verified at this lsn" — set on every delta resume. */
-export const DIGEST_UNVERIFIED = '';
-
+/**
+ * What a resume decides from, and nothing else. `digest` and `count` were here until 2026-08-24
+ * and were written by every snapshot, encoded and validated on every `subscribe` frame, and read
+ * by nothing — the same shape `verifyDigest()` was deleted for one release earlier, one field
+ * down. `digest` cost a `canonicalJson` plus a hash over EVERY ROW of every snapshot, paid once
+ * per live query per reconnecting socket in the restart storm this package is measured on; and
+ * `count` would have been wrong had it ever gained a reader, because `advance` seeds its set from
+ * the already-truncated `ids`, so a delete of a row past `CURSOR_ID_LIMIT` never decremented it.
+ */
 export interface LiveCursor {
   readonly qid: string;
   /** Last lsn the subscriber has applied. Lexicographically comparable (see `formatLsn`). */
   readonly lsn: string;
-  /** Result-set digest at the last snapshot, or `DIGEST_UNVERIFIED` after a delta resume. */
-  readonly digest: string;
   /** Last-seen row ids, truncated at `CURSOR_ID_LIMIT`. */
   readonly ids: readonly string[];
-  /** Number of rows in the result set — survives id truncation. */
-  readonly count: number;
   readonly at: number;
 }
 
@@ -53,8 +55,7 @@ export type ResumeReason =
   | 'unknown-query'
   | 'out-of-window'
   | 'lag-exceeded'
-  | 'budget-exceeded'
-  | 'digest-unverified';
+  | 'budget-exceeded';
 
 export interface ResumeDecision {
   readonly resnapshot: boolean;
@@ -98,30 +99,11 @@ export function makeCursor(
   return {
     qid,
     lsn,
-    digest: digestOf(rows),
     ids: rows.slice(0, CURSOR_ID_LIMIT).map((r) => r.id),
-    count: rows.length,
     at: now,
   };
 }
 
-/**
- * FNV-1a over `id:row` pairs in result order — order-sensitive, so a re-sort is detected.
- *
- * **Server-side only, and it is not reproducible by a client.** `verifyDigest()` used to sit here
- * and was DELETED (2026-08-23): it was documented as "how a client detects drift", had no caller
- * outside its own test, and could not have had one. Three reasons, any one of them fatal.
- * `canonicalJson` tags a `Date` as `Date(<epoch>)` while the client holds the ISO string
- * `JSON.stringify` sent it. A delta-resumed cursor carries `DIGEST_UNVERIFIED`, so the check
- * answered `false` for every cursor a delta produced — which is the only state drift can be
- * detected in. And `identity-map.ts` MERGES columns across queries on purpose, so a client's row
- * for one id is legitimately a superset of the row any single snapshot sent: an app with two reads
- * over one entity would have reported permanent drift.
- */
-export function digestOf(rows: readonly Row[]): string {
-  return fnv1a(rows.map((row) => `${row.id}:${canonicalJson(row)}`).join(';'));
-}
-
 export function shouldResnapshot(
   cursor: LiveCursor,
   available: readonly RowPatch[] | null,
@@ -172,7 +154,7 @@ export async function resumeFrom<R extends Row = Row>(
   };
 }
 
-/** Advance a cursor across a delta without re-reading rows: ids are patchable, the digest is not. */
+/** Advance a cursor across a delta without re-reading rows: ids are patchable. */
 export function advance(
   cursor: LiveCursor,
   patches: readonly RowPatch[],
@@ -180,21 +162,14 @@ export function advance(
   now: number,
 ): LiveCursor {
   const ids = new Set(cursor.ids);
-  let count = cursor.count;
   for (const patch of patches) {
-    if (patch.op === 'delete') {
-      if (ids.delete(patch.id)) count -= 1;
-    } else if (patch.op === 'insert' && !ids.has(patch.id)) {
-      ids.add(patch.id);
-      count += 1;
-    }
+    if (patch.op === 'delete') ids.delete(patch.id);
+    else if (patch.op === 'insert') ids.add(patch.id);
   }
   return {
     qid: cursor.qid,
     lsn,
-    digest: DIGEST_UNVERIFIED,
     ids: [...ids].slice(0, CURSOR_ID_LIMIT),
-    count,
     at: now,
   };
 }

package/src/index.ts

@@ -22,9 +22,7 @@ export {
 export {
   advance,
   CURSOR_ID_LIMIT,
-  DIGEST_UNVERIFIED,
   defaultReconnectBudget,
-  digestOf,
   type LiveCursor,
   makeCursor,
   type ReconnectBudget,
@@ -91,7 +89,6 @@ export {
 // ---- shared value domain ---------------------------------------------------------------------
 export {
   changedColumns,
-  fnv1a,
   isJsonObject,
   isRow,
   type JsonObject,

package/src/json.ts

@@ -1,11 +1,12 @@
-// The JSON value domain shared by the wire, the matcher, and the local store, plus `fnv1a` — the
-// one hash this package still owns.
+// The JSON value domain shared by the wire, the matcher, and the local store. This package now
+// owns NO hash at all.
 //
 // `canonicalJson` and `stableDigest` USED to live here and are `@ultimat3/core`'s now: they were a
 // third copy of one injective canonical form and one sharing-key hash, beside `@ultimat3/action`'s
-// and `@ultimat3/query`'s, and the copies had already diverged. `fnv1a` stays because its job is
-// genuinely different — it is a cursor's result-set digest, where a collision costs a missed
-// re-sort and never one client served out of another's window.
+// and `@ultimat3/query`'s, and the copies had already diverged. `fnv1a` stayed for one job — a
+// cursor's result-set digest — and went with it (2026-08-24) when `LiveCursor.digest` was deleted
+// for having no reader. A 32-bit hash nothing calls is a hash the next caller reaches for as a
+// sharing key, which is the one thing it must never be.
 
 export type JsonValue =
   | string
@@ -55,16 +56,6 @@ export function changedColumns(before: JsonObject | null, after: JsonObject): Js
   return out;
 }
 
-/** FNV-1a, 32-bit, hex. Not cryptographic — it identifies and detects drift, it does not protect. */
-export function fnv1a(text: string): string {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < text.length; i += 1) {
-    hash ^= text.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  return hash.toString(16).padStart(8, '0');
-}
-
 function sameJson(a: JsonValue | undefined, b: JsonValue | undefined): boolean {
   if (a === b) return true;
   if (a === undefined || b === undefined || a === null || b === null) return false;

package/src/sync-protocol.ts

@@ -14,7 +14,17 @@ import {
   type RowPatch,
 } from './json';
 
-export const PROTOCOL_VERSION = 1;
+/**
+ * **2 since 2026-08-24**, when `cursor.digest` and `cursor.count` were deleted. The version guards
+ * incompatibility, never novelty — an additive optional field (`snapshot.entity`) and a removed
+ * field read through `list()` (`hello.resume`) both stayed at 1, because `decode` is a whitelist
+ * and `list()` answers `[]` for an absent field. `cursor()` is the other kind of reader: it reads
+ * through `str`/`num`, which THROW on an absent field, so a cursor without those two is a frame a
+ * node or a client one deploy behind cannot read — in BOTH directions, since a cursor rides the
+ * client's `subscribe` and the node's `snapshot`. That is exactly what this number refuses, with
+ * one instruction instead of a per-frame "field \"digest\" must be a string".
+ */
+export const PROTOCOL_VERSION = 2;
 
 /**
  * What one frame may contain. Hard ceilings a caller cannot widen — the shape
@@ -410,12 +420,10 @@ function cursor(value: unknown): LiveCursor {
   return {
     qid: str(value, 'qid'),
     lsn: str(value, 'lsn'),
-    digest: str(value, 'digest'),
     ids: list(value, 'ids', FRAME_LIMITS.cursorIds, 'cursor.ids').map((id) => {
       if (typeof id !== 'string') throw fail('cursor.ids must be strings');
       return id;
     }),
-    count: num(value, 'count'),
     at: num(value, 'at'),
   };
 }