@ultimat3/realtime 2.0.0 → 4.0.0

package/src/index.ts

@@ -90,6 +90,7 @@ export {
   RealtimeError,
   type RealtimeErrorCode,
   RebaseConflictError,
+  ReplicaIdentityError,
   ReplicationFailedError,
   ReplicationProtocolError,
   ReplicatorSlotHeldError,
@@ -136,7 +137,6 @@ export {
 } from './identity-map';
 // ---- shared value domain ---------------------------------------------------------------------
 export {
-  canonicalJson,
   changedColumns,
   fnv1a,
   isJsonObject,
@@ -147,11 +147,10 @@ export {
   type RowOp,
   type RowPatch,
 } from './json';
-export {
-  type LiveQueryDefinition,
-  type LiveSubscription,
-  qidOf,
-  type SnapshotResult,
+export type {
+  LiveQueryDefinition,
+  LiveSubscription,
+  SnapshotResult,
 } from './live-contract';
 export { type LiveDefinitionOptions, liveQueryDefinition } from './live-definition';
 export {
@@ -263,6 +262,7 @@ export {
   createEntry,
   fillWindow,
   orgIdOf,
+  type PendingRead,
   type QueryEntry,
   refillWindowInLane,
 } from './query-window';
@@ -299,8 +299,10 @@ export {
   actorIdOf,
   CLOSE,
   DEFAULT_FRAME_BURST,
+  DEFAULT_IDLE_TIMEOUT_MS,
   DEFAULT_MAX_BUFFERED_BYTES,
   DEFAULT_MAX_FRAMES_PER_SECOND,
+  idleSweepPeriodMs,
   SocketRegistry,
   type SocketRegistryOptions,
   SyncSocket,
@@ -374,6 +376,7 @@ export {
   type AcceptBudgetOptions,
   type BackoffPolicy,
   backoffDelay,
+  type DrainedSocket,
   type DrainPlanEntry,
   type DrainPlanOptions,
   defaultBackoff,

package/src/json.ts

@@ -1,5 +1,11 @@
-// The JSON value domain shared by the wire, the matcher, and the local store.
-// Kept dependency-free so every other module in this package can import it without a cycle.
+// The JSON value domain shared by the wire, the matcher, and the local store, plus `fnv1a` — the
+// one hash this package still owns.
+//
+// `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.
 
 export type JsonValue =
   | string
@@ -49,52 +55,6 @@ export function changedColumns(before: JsonObject | null, after: JsonObject): Js
   return out;
 }
 
-/**
- * Key-sorted JSON so a query id derived from input is stable across property order — and
- * INJECTIVE, because that id decides who shares a window.
- *
- * `qidOf` is `stableDigest(canonicalJson(input))` and a qid HIT hands the joiner the existing
- * entry: the first subscriber's compiled source, its matcher and its seated rows. Two inputs that
- * canonicalise to one string are therefore two clients served out of one window. `JSON.stringify`
- * is not injective over numbers — `NaN` and `±Infinity` are both `"null"`, which also collides
- * with JSON `null` itself, and `-0` is `"0"` — so the number branch is spelled out here.
- *
- * `-0` is the one of those a client can put on the wire (`JSON.parse('{"a":-0}')` answers `-0`);
- * the non-finite three have no JSON spelling and arrive only from a caller building `input` in JS,
- * such as `useLive(feed, () => ({ limit: Number.parseInt(raw) }))` on an unparseable `raw`.
- * The tokens are bare, never quoted: this output is only ever hashed, and the `string` branch
- * always quotes, so an unquoted word cannot collide with the text that spells it.
- *
- * The twin of `@ultimat3/query`'s and `@ultimat3/action`'s rules in their own `stable.ts`. All
- * three are tier 3, so no two of them can import each other; the shared home is `@ultimat3/core`
- * if one is ever made.
- */
-export function canonicalJson(value: JsonValue): string {
-  if (typeof value === 'number') return canonicalNumber(value);
-  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
-  const keys = Object.keys(value).sort();
-  const parts = keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key] ?? null)}`);
-  return `{${parts.join(',')}}`;
-}
-
-/** Ordinary numbers are `String(n)`, byte-identical to what this emitted before. */
-function canonicalNumber(value: number): string {
-  if (Number.isNaN(value)) return 'NaN';
-  if (!Number.isFinite(value)) return value > 0 ? 'Infinity' : '-Infinity';
-  return Object.is(value, -0) ? '-0' : String(value);
-}
-
-/**
- * SHA-256, first 16 hex characters. For the hashes that are also SHARING keys — a `qid` decides
- * which subscribers are served from one window, and it is derived from input a client chooses, so
- * the 32 bits `fnv1a` answers are a collision anyone can find offline in seconds. Same primitive
- * and same width `@ultimat3/entity`'s `planScope` already chose for a cursor's scope.
- */
-export function stableDigest(text: string): string {
-  return new Bun.CryptoHasher('sha256').update(text).digest('hex').slice(0, 16);
-}
-
 /** 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;

package/src/live-contract.ts

@@ -1,27 +1,20 @@
-// What a live query IS: the id one is keyed by, the contract a definition satisfies, and the
-// subscription one socket holds. Split from `live-query.ts` because four modules need the shape
-// and none of them needs the registry that runs it — and because one file runs one job.
+// What a live query IS: the contract a definition satisfies and the subscription one socket holds.
+// Split from `live-query.ts` because four modules need the shape and none of them needs the
+// registry that runs it — and because one file runs one job.
+//
+// The id is NOT here, and no longer anywhere in this package: a `qid` is `@ultimat3/query`'s
+// `queryHash(name, input)`, imported across the declared `realtime -> query` edge. `qidOf` was the
+// same two lines over this package's own copy of the canonical form, and the two had already
+// diverged on an `undefined`-valued key — while `planResume` compares a cursor's `queryHash` and
+// `liveQueryDefinition` keys the shared window by the qid, so a divergence is every resume
+// decision and every window lookup keyed differently.
 
 import type { Actor } from '@ultimat3/core';
 import type { LiveCursor } from './cursor';
-import { canonicalJson, type JsonValue, type Row, stableDigest } from './json';
+import type { JsonValue, Row } from './json';
 import type { IncrementalMatcher } from './matcher-bridge';
 import type { SyncSocket } from './socket';
 
-/**
- * `qid` = hash(query name, input). Fanout subjects and change windows are keyed by it.
- *
- * The hash is a **sharing** key, which is why it is `stableDigest` and not `fnv1a`: `#entryFor`
- * answers a hit with the EXISTING entry and `liveQueryDefinition` answers with the seated
- * `SharedWindow`, both carrying the first subscriber's input, compiled source and rows. Input is
- * client-chosen, so a second input colliding with the first passes `authorize` against its own
- * arguments and is then served out of somebody else's window — and 32 bits is a collision found
- * offline in seconds.
- */
-export function qidOf(name: string, input: JsonValue): string {
-  return `${name}:${stableDigest(canonicalJson(input))}`;
-}
-
 export interface SnapshotResult<R extends Row = Row> {
   readonly rows: readonly R[];
   readonly lsn: string;

package/src/live-definition.ts

@@ -9,10 +9,10 @@
 // every time. Collapsing the second onto the first is privilege escalation with a cache hit rate.
 
 import type { Ctx } from '@ultimat3/core';
-import { type AnyQuery, queryName } from '@ultimat3/query';
+import { type AnyQuery, queryHash, queryName } from '@ultimat3/query';
 import { LiveRowUnidentifiedError } from './errors';
 import { isRow, type JsonValue, type Row } from './json';
-import { type LiveQueryDefinition, qidOf, type SnapshotResult } from './live-contract';
+import type { LiveQueryDefinition, SnapshotResult } from './live-contract';
 import { type IncrementalMatcher, matcherFor } from './matcher-bridge';
 import { authorizeWithPolicy, visibleWithPolicy } from './policy-gate';
 
@@ -73,7 +73,7 @@ export function liveQueryDefinition(
   const windows = new Map<string, SharedWindow>();
 
   const resolve = async (input: JsonValue): Promise<SharedWindow> => {
-    const qid = qidOf(name, input);
+    const qid = queryHash(name, input);
     const seated = windows.get(qid);
     if (seated !== undefined) return seated;
     const live = await target.live(input, {
@@ -113,10 +113,10 @@ export function liveQueryDefinition(
       const window = await resolve(input);
       return { rows: await window.read(), lsn: options.lsn?.() ?? '' };
     },
-    matcher: (input) => windows.get(qidOf(name, input))?.matcher ?? UNRESOLVED,
+    matcher: (input) => windows.get(queryHash(name, input))?.matcher ?? UNRESOLVED,
     // Read off the same resolved window as the matcher, so the scope the client keys rows under and
     // the entity the matcher patches them from can never be two different names.
-    rowEntity: (input) => windows.get(qidOf(name, input))?.rowEntity ?? null,
+    rowEntity: (input) => windows.get(queryHash(name, input))?.rowEntity ?? null,
     // The two per-subscriber gates, both through the package's one authz seam. Neither result is
     // memoised anywhere: `authorize` runs on every subscribe, `visible` on every row of every
     // delivery, and there is no key here an actor could share with another actor.

package/src/live-query.ts

@@ -7,6 +7,7 @@
 // otherwise.
 
 import { type Actor, type Clock, systemClock, uuid } from '@ultimat3/core';
+import { queryHash } from '@ultimat3/query';
 import type { ChangeEvent } from './changefeed';
 import {
   type LiveCursor,
@@ -17,12 +18,7 @@ import {
 } from './cursor';
 import { isPolicyDenial, LiveQueryUnknownError, SubscriptionLimitError } from './errors';
 import type { JsonValue } from './json';
-import {
-  type LiveQueryDefinition,
-  type LiveSubscription,
-  qidOf,
-  type SnapshotResult,
-} from './live-contract';
+import type { LiveQueryDefinition, LiveSubscription, SnapshotResult } from './live-contract';
 import { type FanoutDeps, fanoutChange, snapshotFrame } from './live-fanout';
 import { createEntry, fillWindow, type QueryEntry } from './query-window';
 import type { SyncSocket } from './socket';
@@ -176,7 +172,7 @@ export class LiveQueryRegistry {
     // may not subscribe is work an unauthorized client gets to schedule.
     await definition.prepare?.(args.input);
 
-    const qid = qidOf(args.name, args.input);
+    const qid = queryHash(args.name, args.input);
     const entry = this.#entryFor(qid, definition, args.input);
     const now = this.#clock.now().getTime();
 

package/src/pg-preflight.ts

@@ -0,0 +1,117 @@
+// Single responsibility: the four questions asked of a database BEFORE `START_REPLICATION`, and
+// the identifier charset every one of them interpolates through. Three refuse the boot with the
+// exact statement that fixes them; the fourth warns, because refusing it would stop every app on
+// the default replica identity from starting.
+
+import { logger } from '@ultimat3/core';
+import { ReplicaIdentityError, ReplicationFailedError } from './errors';
+import type { PgConnection } from './pg-connection';
+
+/** Identifiers reach a simple query unparameterised, so the charset is the injection boundary. */
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+
+/**
+ * The one gate between a caller-supplied name and a simple query. Exported because
+ * `PgReplicationStream` checks its slot, publication and entity names in its CONSTRUCTOR — a
+ * mistyped `REPLICATION_SLOT` is a boot-time fact, and finding it at the first WAL read means a
+ * replicator that reported itself started and then never delivered a change.
+ */
+export const assertIdentifier = (kind: string, value: string): string => {
+  if (IDENTIFIER.test(value)) return value;
+  throw new ReplicationFailedError({
+    stage: 'preflight',
+    detail: `${kind} "${value}" is not a lower-case postgres identifier`,
+    fix: `rename the ${kind} to match [a-z_][a-z0-9_]* — it is interpolated into a replication command`,
+  });
+};
+
+/**
+ * The four things that are always misconfigured. Three produce an unreadable server message if
+ * left to the server, so each gets its own `fix:` line; the fourth is `warnPartialIdentity` and
+ * only warns. `slot` and `publication` are interpolated into simple queries, so the `IDENTIFIER`
+ * charset is the injection boundary; re-asserted here rather than trusted, so the guarantee
+ * travels with the function instead of living only in `start()`.
+ */
+export async function preflight(
+  connection: PgConnection,
+  slot: string,
+  publication: string,
+  entities: ReadonlySet<string>,
+): Promise<void> {
+  assertIdentifier('slot', slot);
+  assertIdentifier('publication', publication);
+  const [walLevel] = await connection.query('SHOW wal_level');
+  if (walLevel?.[0] !== 'logical') {
+    throw new ReplicationFailedError({
+      stage: 'preflight',
+      detail: `wal_level is "${walLevel?.[0] ?? 'unknown'}", so the server writes no logical WAL`,
+      fix: "ALTER SYSTEM SET wal_level = 'logical'; -- then restart postgres",
+    });
+  }
+  const publications = await connection.query(
+    `SELECT 1 FROM pg_publication WHERE pubname = '${publication}'`,
+  );
+  if (publications.length === 0) {
+    throw new ReplicationFailedError({
+      stage: 'preflight',
+      detail: `no publication named "${publication}" exists`,
+      fix: `CREATE PUBLICATION ${publication} FOR ALL TABLES;`,
+    });
+  }
+  await warnPartialIdentity(connection, entities);
+  const [existing] = await connection.query(
+    `SELECT plugin FROM pg_replication_slots WHERE slot_name = '${slot}'`,
+  );
+  if (existing === undefined) {
+    // Plain SQL rather than CREATE_REPLICATION_SLOT: the replication command exports a snapshot
+    // that pins xmin for the session, and its option syntax changed in postgres 15.
+    await connection.query(`SELECT pg_create_logical_replication_slot('${slot}', 'pgoutput')`);
+    return;
+  }
+  if (existing[0] !== 'pgoutput') {
+    throw new ReplicationFailedError({
+      stage: 'preflight',
+      detail: `slot "${slot}" decodes with "${existing[0] ?? 'unknown'}", not pgoutput`,
+      fix: `SELECT pg_drop_replication_slot('${slot}'); -- then start the replicator again`,
+    });
+  }
+}
+
+/**
+ * The fourth preflight question, and the one that does NOT refuse. A live query decides whether a
+ * row left its result set from `change.before`, and under any replica identity but FULL that tuple
+ * is the key columns alone — which `toRow` accepts, since it only requires a text `id`.
+ *
+ * It runs BEFORE `pg_create_logical_replication_slot`: a slot decodes with the identity the
+ * catalog held when the rows were written, so asking after the slot exists answers about a stream
+ * nobody is reading yet. It WARNS rather than throws because every app on the default identity
+ * would otherwise stop booting, and a replicator that will not start is worse than the partial
+ * rows it is complaining about — `ReplicationStreamStats.partialBefore` is the running half.
+ *
+ * Entity names are the ones the constructor already put through `assertIdentifier`, which is what
+ * makes both the interpolation and the `fix:` safe; a name postgres answers with that is not in
+ * that set is dropped rather than rendered.
+ */
+async function warnPartialIdentity(
+  connection: PgConnection,
+  entities: ReadonlySet<string>,
+): Promise<void> {
+  if (entities.size === 0) return;
+  const names = [...entities].map((name) => `'${name}'`).join(', ');
+  const rows = await connection.query(
+    `SELECT relname FROM pg_class WHERE relkind = 'r' AND relreplident <> 'f' ` +
+      `AND relname IN (${names})`,
+  );
+  const tables = [
+    ...new Set(
+      rows
+        .map((row) => row[0])
+        .filter((name): name is string => typeof name === 'string' && entities.has(name)),
+    ),
+  ].sort();
+  if (tables.length === 0) return;
+  const warning = new ReplicaIdentityError({ tables });
+  // FIELDS, never interpolation, and the message is the CODE alone — the same rule
+  // `@ultimat3/http`'s error-map stage follows, so a log index can be alerted on by code.
+  logger.warn(warning.code, { cause: warning.cause, fix: warning.fix, tables });
+}

package/src/pg-replication.ts

@@ -1,21 +1,19 @@
 // Single responsibility: turn a Postgres logical-replication slot into ordered `ChangeEvent`s —
-// preflight the three things that are always misconfigured, START_REPLICATION, decode pgoutput,
-// and keep the slot confirmed. The connection, the framing and the pgoutput decode live next door;
-// what is decided here is *ordering*, because the lsn is the only authority the pipeline has.
+// START_REPLICATION, decode pgoutput, and keep the slot confirmed. The preflight, the connection,
+// the framing and the pgoutput decode live next door; what is decided here is *ordering*, because
+// the lsn is the only authority the pipeline has.
 
 import { type Clock, logger, systemClock } from '@ultimat3/core';
 import type { ChangeEvent, ChangeOp, PgLogicalReplicationOptions } from './changefeed';
-import { ReplicationFailedError, ReplicationProtocolError } from './errors';
+import { ReplicationProtocolError } from './errors';
 import { isRow, type JsonObject, type Row } from './json';
 import { ByteReader, ByteWriter, epochMsToPgTimestamp, printLsn } from './pg-bytes';
 import { PgConnection } from './pg-connection';
 import { entityRow } from './pg-entity-row';
+import { assertIdentifier, preflight } from './pg-preflight';
 import { bunPgStream, parsePgUrl } from './pg-socket';
 import { PgOutputDecoder, type PgOutputMessage, type PgRelation } from './pgoutput';
 
-/** Identifiers reach a simple query unparameterised, so the charset is the injection boundary. */
-const IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
-
 const DEFAULT_STATUS_INTERVAL_MS = 10_000;
 
 /** `r` — the standby status update, the only frontend message a walsender listens for. */
@@ -27,6 +25,14 @@ export interface ReplicationStreamStats {
   readonly skipped: number;
   /** Rows replayed from before the resume position, dropped so `onChange` sees each one once. */
   readonly replayed: number;
+  /**
+   * Changes delivered from a relation whose replica identity is not FULL — so the `before` row is
+   * the key columns alone (or absent), and the live matcher's "did this row leave the result set"
+   * is decided on a partial row. `X_LIVE_REPLICA_IDENTITY` warns about the CONFIGURATION once at
+   * preflight; this counts the decisions it actually cost, which is the half a running node can
+   * be alerted on. Inserts never count: there is no `before` to be partial.
+   */
+  readonly partialBefore: number;
   /**
    * Why the pump stopped, or `null` while it is live. The read loop cannot throw into a caller —
    * nothing awaits it — so this is the one place `/readyz` and a test can see that it died at all.
@@ -58,15 +64,6 @@ export const changeLsn = (commitLsn: bigint, sequence: number): string =>
 /** The commit position inside a change lsn — where a resume asks the server to restart. */
 export const commitPositionOf = (lsn: string): bigint => BigInt(`0x${lsn.slice(0, 16) || '0'}`);
 
-const assertIdentifier = (kind: string, value: string): string => {
-  if (IDENTIFIER.test(value)) return value;
-  throw new ReplicationFailedError({
-    stage: 'preflight',
-    detail: `${kind} "${value}" is not a lower-case postgres identifier`,
-    fix: `rename the ${kind} to match [a-z_][a-z0-9_]* — it is interpolated into a replication command`,
-  });
-};
-
 export interface ReplicationStreamHandlers {
   readonly from?: string | undefined;
   onChange(event: ChangeEvent): void | Promise<void>;
@@ -94,6 +91,7 @@ export class PgReplicationStream {
   #delivered = 0;
   #skipped = 0;
   #replayed = 0;
+  #partialBefore = 0;
   #failure: string | null = null;
 
   constructor(options: PgLogicalReplicationOptions) {
@@ -116,6 +114,7 @@ export class PgReplicationStream {
       delivered: this.#delivered,
       skipped: this.#skipped,
       replayed: this.#replayed,
+      partialBefore: this.#partialBefore,
       failure: this.#failure,
     };
   }
@@ -147,7 +146,7 @@ export class PgReplicationStream {
     });
     this.#connection = connection;
     try {
-      await preflight(connection, slot, publication);
+      await preflight(connection, slot, publication, this.#entities);
       const from = handlers.from;
       this.#confirmed = from === undefined ? 0n : commitPositionOf(from);
       await connection.startCopyBoth(
@@ -339,6 +338,10 @@ export class PgReplicationStream {
       this.#replayed += 1;
       return;
     }
+    // Read off the Relation message rather than off the tuple: a DEFAULT-identity table whose
+    // non-key columns happen to be NULL sends the same bytes a FULL one does, so counting missing
+    // keys would undercount exactly the rows a policy is most likely to misjudge.
+    if (op !== 'insert' && relation.replicaIdentity !== 'f') this.#partialBefore += 1;
     const before = toRow(relation, oldTuple);
     const after = toRow(relation, newTuple);
     const event: ChangeEvent = {
@@ -380,55 +383,6 @@ export class PgReplicationStream {
   }
 }
 
-/**
- * The three misconfigurations that produce an unreadable server message if left to the server.
- * `slot` and `publication` are interpolated into simple queries, so the `IDENTIFIER` charset is the
- * injection boundary; re-asserted here rather than trusted, so the guarantee travels with the
- * function instead of living only in `start()`.
- */
-async function preflight(
-  connection: PgConnection,
-  slot: string,
-  publication: string,
-): Promise<void> {
-  assertIdentifier('slot', slot);
-  assertIdentifier('publication', publication);
-  const [walLevel] = await connection.query('SHOW wal_level');
-  if (walLevel?.[0] !== 'logical') {
-    throw new ReplicationFailedError({
-      stage: 'preflight',
-      detail: `wal_level is "${walLevel?.[0] ?? 'unknown'}", so the server writes no logical WAL`,
-      fix: "ALTER SYSTEM SET wal_level = 'logical'; -- then restart postgres",
-    });
-  }
-  const publications = await connection.query(
-    `SELECT 1 FROM pg_publication WHERE pubname = '${publication}'`,
-  );
-  if (publications.length === 0) {
-    throw new ReplicationFailedError({
-      stage: 'preflight',
-      detail: `no publication named "${publication}" exists`,
-      fix: `CREATE PUBLICATION ${publication} FOR ALL TABLES;`,
-    });
-  }
-  const [existing] = await connection.query(
-    `SELECT plugin FROM pg_replication_slots WHERE slot_name = '${slot}'`,
-  );
-  if (existing === undefined) {
-    // Plain SQL rather than CREATE_REPLICATION_SLOT: the replication command exports a snapshot
-    // that pins xmin for the session, and its option syntax changed in postgres 15.
-    await connection.query(`SELECT pg_create_logical_replication_slot('${slot}', 'pgoutput')`);
-    return;
-  }
-  if (existing[0] !== 'pgoutput') {
-    throw new ReplicationFailedError({
-      stage: 'preflight',
-      detail: `slot "${slot}" decodes with "${existing[0] ?? 'unknown'}", not pgoutput`,
-      fix: `SELECT pg_drop_replication_slot('${slot}'); -- then start the replicator again`,
-    });
-  }
-}
-
 /** A physical tuple becomes the row the matcher's predicates are written against, or nothing. */
 function toRow(relation: PgRelation, physical: JsonObject | null): Row | null {
   if (physical === null) return null;

package/src/query-window.ts

@@ -32,7 +32,24 @@ export interface QueryEntry {
   /** Serial lane over `rows`/`lsn`. Every fanout and every window assignment takes its turn here. */
   readonly lock: WindowLock;
   /** The read in flight, shared by every subscriber that arrives during it. `null` between reads. */
-  reading: Promise<SnapshotResult> | null;
+  reading: PendingRead | null;
+  /**
+   * Reads issued against this entry, ever. It is the ORDER of two reads, which nothing else here
+   * can answer: a definition with no lsn provider returns `''` from every snapshot.
+   */
+  generation: number;
+  /** The generation of the newest read whose rows are in `rows`. `0` before the first one lands. */
+  applied: number;
+}
+
+/**
+ * One read and which read it is. They are one fact — a joiner needs the promise AND the generation
+ * it will have to compare against when it lands — and two fields on the entry is two writes a later
+ * edit can separate.
+ */
+export interface PendingRead {
+  readonly generation: number;
+  readonly result: Promise<SnapshotResult>;
 }
 
 export function createEntry(
@@ -64,6 +81,8 @@ export function createEntry(
     stale: false,
     lock: new WindowLock(),
     reading: null,
+    generation: 0,
+    applied: 0,
   };
 }
 
@@ -82,18 +101,21 @@ export async function fillWindow(
   // Read before `startRead` clears it: a second caller arriving during the read joins it and is
   // not the one that forced it, which is what keeps one forced read from becoming N.
   const forced = entry.stale;
-  const result = await (forced || entry.reading === null ? startRead(entry) : entry.reading);
+  const pending = forced || entry.reading === null ? startRead(entry) : entry.reading;
+  const result = await pending.result;
   return await entry.lock.run(async () => {
-    if (forced) {
-      // A forced read replaces the window whatever its lsn says: it was issued *because* what is
-      // under it is wrong, and a definition with no lsn provider answers `''` — which the
-      // never-backwards rule below would read as older than what we hold and discard, leaving
-      // every subscriber served from the window the gap already invalidated.
-      entry.rows = result.rows;
-      if (result.lsn > entry.lsn) entry.lsn = result.lsn;
-    } else if (result.lsn >= entry.lsn) {
-      entry.rows = result.rows;
-      entry.lsn = result.lsn;
+    // Two rules, and neither can stand in for the other. Against another READ it is identity —
+    // the same check `startRead` makes on `entry.reading` one function down, and the one
+    // `packages/cache/src/single-flight.ts` makes for the same reason — because an lsn cannot
+    // order two reads at all: a definition with no lsn provider answers `''` for both, and
+    // `'' >= ''` let the older one overwrite the gap repair the newer one had just landed, with
+    // `stale` already cleared by its issue and therefore nothing left to re-read. Against a
+    // CHANGE it is still the lsn, because a fanout moved `entry.lsn` forwards while this read was
+    // in flight and rewinding to what the read saw hands that subscriber rows the fanout has
+    // moved past — except for a forced read, which was issued *because* what is under it is
+    // wrong.
+    if (isNewestRead(entry, pending) && (forced || result.lsn >= entry.lsn)) {
+      applyRead(entry, pending, result);
     }
     return { rows: entry.rows, lsn: entry.lsn };
   });
@@ -105,22 +127,36 @@ export async function fillWindow(
  * that repairs a stale window mid-fanout is spelled here rather than deadlocking on the other.
  */
 export async function refillWindowInLane(entry: QueryEntry): Promise<void> {
-  const result = await startRead(entry);
+  const pending = startRead(entry);
+  const result = await pending.result;
+  // Same identity rule as `fillWindow`: a read issued before this one may still be in flight, and
+  // whichever was issued LAST is the one the window keeps.
+  if (isNewestRead(entry, pending)) applyRead(entry, pending, result);
+}
+
+/** Is this the newest read to have landed? An older one's rows are behind the window, not on it. */
+function isNewestRead(entry: QueryEntry, pending: PendingRead): boolean {
+  return pending.generation > entry.applied;
+}
+
+function applyRead(entry: QueryEntry, pending: PendingRead, result: SnapshotResult): void {
+  entry.applied = pending.generation;
   entry.rows = result.rows;
   if (result.lsn > entry.lsn) entry.lsn = result.lsn;
 }
 
 /** Publishes the in-flight read, and clears it as it settles — the share is per read, not a cache. */
-function startRead(entry: QueryEntry): Promise<SnapshotResult> {
+function startRead(entry: QueryEntry): PendingRead {
   // Cleared here rather than when the read lands: the read about to be issued is the one that
   // answers the staleness, so a second caller must join it instead of forcing another.
   entry.stale = false;
-  const reading = readSnapshot(entry);
+  entry.generation += 1;
+  const reading: PendingRead = { generation: entry.generation, result: readSnapshot(entry) };
   entry.reading = reading;
   const done = (): void => {
     if (entry.reading === reading) entry.reading = null;
   };
-  void reading.then(done, done);
+  void reading.result.then(done, done);
   return reading;
 }
 

package/src/rebase.ts

@@ -9,7 +9,7 @@
 import { RebaseConflictError } from './errors';
 import type { Row } from './json';
 import type { LocalStore, LocalTx, TableMap } from './local-store';
-import { type ConflictStrategyName, type Frame, PROTOCOL_VERSION } from './sync-protocol';
+import { type ConflictStrategyName, PROTOCOL_VERSION, type RebaseFrame } from './sync-protocol';
 
 export interface MergeArgs {
   /** Local row as the user last saw it, before any rollback. */
@@ -246,7 +246,12 @@ function numberAt(row: Row | null | undefined, field: string): number | null {
   return typeof value === 'number' ? value : null;
 }
 
-export function rebaseFrame(ack: ServerAck, strategy: ConflictStrategy): Frame {
+/**
+ * `RebaseFrame`, not `Frame`: this builds exactly one member of the union and declaring the whole
+ * union threw that away, so every caller had to re-narrow a frame it had just constructed before it
+ * could read `strategy` or `row` back off it.
+ */
+export function rebaseFrame(ack: ServerAck, strategy: ConflictStrategy): RebaseFrame {
   return {
     type: 'rebase',
     v: PROTOCOL_VERSION,