@ultimat3/realtime 1.2.0 → 2.0.0

package/src/live-query.ts

@@ -9,67 +9,28 @@
 import { type Actor, type Clock, systemClock, uuid } from '@ultimat3/core';
 import type { ChangeEvent } from './changefeed';
 import {
-  advance,
   type LiveCursor,
   makeCursor,
   type ReconnectBudget,
   type ResumeSource,
   resumeFrom,
 } from './cursor';
-import { ProtocolVersionError, SubscriptionLimitError } from './errors';
-import { canonicalJson, fnv1a, type JsonValue, type Row, type RowPatch } from './json';
+import { isPolicyDenial, LiveQueryUnknownError, SubscriptionLimitError } from './errors';
+import type { JsonValue } from './json';
 import {
-  applyToWindow,
-  bridgeChange,
-  type IncrementalMatcher,
-  type SubscriptionShape,
-} from './matcher-bridge';
+  type LiveQueryDefinition,
+  type LiveSubscription,
+  qidOf,
+  type 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';
+import { type Subscriber, SubscriberGate, type SubscriberGateOptions } from './subscriber-gate';
+import { SubscriptionBook, subscriptionKey } from './subscription-book';
 import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
 
-/** `qid` = hash(query name, input). Fanout subjects and change windows are keyed by it. */
-export function qidOf(name: string, input: JsonValue): string {
-  return `${name}:${fnv1a(canonicalJson(input))}`;
-}
-
-export interface SnapshotResult<R extends Row = Row> {
-  readonly rows: readonly R[];
-  readonly lsn: string;
-}
-
-export interface LiveQueryDefinition<R extends Row = Row> {
-  readonly name: string;
-  /** Dependency set for the pre-filter. `x verify` rejects a `live: true` query without one. */
-  readonly entities: readonly string[];
-  /** Read set. Lets the pre-filter skip updates that touch no column this query reads. */
-  readonly columns?: readonly string[];
-  /** Bounded read (`orderBy` + `limit`, enforced by `x verify`), unfiltered by policy. */
-  snapshot(args: { input: JsonValue }): Promise<SnapshotResult<R>>;
-  /** Subscribe-time gate. Throws to deny — the same `policy` used by HTTP, jobs, and MCP. */
-  authorize?(args: { actor: Actor | null; input: JsonValue }): void | Promise<void>;
-  /** Row-level gate, evaluated per subscriber. The only row filter in the pipeline. */
-  visible(args: { actor: Actor | null; row: R; input: JsonValue }): boolean | Promise<boolean>;
-  /** Built once per `qid`, since a qid pins both the query and its input. */
-  matcher(input: JsonValue): IncrementalMatcher;
-  /**
-   * Resolve whatever this input needs before an entry is built. `matcher` is synchronous by
-   * design — a change event must not await anything — so a definition that has to compile a
-   * source or a shape does it here, after `authorize` allowed this subscriber and before the
-   * shared window exists.
-   */
-  prepare?(input: JsonValue): Promise<void>;
-}
-
-export interface LiveSubscription {
-  readonly sid: string;
-  readonly qid: string;
-  readonly socket: SyncSocket;
-  readonly input: JsonValue;
-  readonly definition: LiveQueryDefinition;
-  cursor: LiveCursor;
-}
-
-export interface LiveQueryRegistryOptions {
+export interface LiveQueryRegistryOptions extends SubscriberGateOptions {
   readonly source: ResumeSource;
   readonly budget?: ReconnectBudget;
   readonly clock?: Clock;
@@ -77,61 +38,78 @@ export interface LiveQueryRegistryOptions {
   readonly maxPerTenant?: number;
   readonly tenantOf?: (actor: Actor | null) => string | null;
   /**
-   * `live.rows_denied`. A row an actor's policy refuses is dropped, never sent and never turned
-   * into an error — telling a client "there is a row you may not see" is itself the leak. Dropped
-   * silently it is also invisible, so the drop is a metric instead.
+   * Distinct `(query, input)` pairs this node will hold at once. A `qid` derives from
+   * client-chosen input, so without a ceiling one socket mints entries — a matcher, a row window,
+   * a `WindowLock` and a fanout target each — until the process dies.
    */
-  readonly onRowDenied?: (event: RowDenied) => void;
-}
-
-/** One row withheld from one subscriber. Carries no row payload: the ids are the whole point. */
-export interface RowDenied {
-  readonly qid: string;
-  readonly sid: string;
-  readonly actorId: string | null;
-  readonly rowId: string;
+  readonly maxEntries?: number;
 }
 
 /**
- * Who a decision is being made for. Every policy call in this file takes one, which is the shape
- * of the rule: there is no path through the gate that reads a query id and no actor.
+ * Live `(query, input)` pairs one node holds. Reached, the next NEW pair is refused with
+ * `X_SUBSCRIPTION_LIMIT`; subscribing to a pair that already exists keeps working, because the
+ * cost this bounds is the entry, not the subscriber.
  */
-interface Subscriber {
-  readonly sid: string;
-  readonly actor: Actor | null;
-}
-
-interface QueryEntry {
-  readonly qid: string;
-  readonly definition: LiveQueryDefinition;
-  readonly input: JsonValue;
-  readonly shape: SubscriptionShape;
-  readonly matcher: IncrementalMatcher;
-  readonly subscribers: Map<string, LiveSubscription>;
-  /**
-   * The shared, *pre-policy* result window. One per query id, bounded by the query's `limit`, and
-   * the reason the matcher can run once for N subscribers: the read is shared, the authz is not.
-   */
-  rows: readonly Row[];
-  lsn: string;
-}
+export const DEFAULT_MAX_ENTRIES = 10_000;
 
 export class LiveQueryRegistry {
   readonly #definitions = new Map<string, LiveQueryDefinition>();
   readonly #entries = new Map<string, QueryEntry>();
-  readonly #bySid = new Map<string, LiveSubscription>();
+  /** Keyed by `(socket, sid)`, never by `sid` alone — `subscription-book.ts` owns why. */
+  readonly #book: SubscriptionBook;
   readonly #options: LiveQueryRegistryOptions;
   readonly #clock: Clock;
-  #rowsDenied = 0;
+  readonly #gate: SubscriberGate;
+  readonly #maxEntries: number;
+  /** What one lane needs, and nothing this class holds beyond it. */
+  readonly #fanout: FanoutDeps;
+  #staleChanges = 0;
 
   constructor(options: LiveQueryRegistryOptions) {
     this.#options = options;
     this.#clock = options.clock ?? systemClock;
+    this.#gate = new SubscriberGate(options);
+    this.#maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    // The book owns the caps because it is the only thing that can answer them in O(1).
+    this.#book = new SubscriptionBook(options);
+    this.#fanout = { gate: this.#gate, source: options.source, clock: this.#clock };
   }
 
   /** `live.rows_denied` for this node: rows a subscriber's policy refused since boot. */
   get rowsDenied(): number {
-    return this.#rowsDenied;
+    return this.#gate.rowsDenied;
+  }
+
+  /** `live.gate_failed` for this node: gates that raised instead of deciding. Never a denial. */
+  get gateFailures(): number {
+    return this.#gate.gateFailures;
+  }
+
+  /** `live.changes_stale`: changes at or below a window's own lsn, refused rather than folded. */
+  get staleChanges(): number {
+    return this.#staleChanges;
+  }
+
+  /**
+   * Every window on this node is presumed to have missed a change, so nothing may be patched or
+   * served out of one until it has been re-read, and every subscriber is re-snapshotted.
+   *
+   * The `sync` node calls this when the change stream skips a sequence: over core NATS a fanout is
+   * at-most-once, and a node that missed eleven changes during a reconnect otherwise holds a window
+   * whose lsn never moved, subscribers whose cursors never moved, and therefore nothing that would
+   * ever ask for a re-snapshot. The repair lands on the next change to each query — which is the
+   * event that proves the query is moving at all.
+   */
+  invalidate(): number {
+    let marked = 0;
+    for (const entry of this.#entries.values()) {
+      entry.stale = true;
+      for (const subscription of entry.subscribers.values()) {
+        subscription.socket.markDesynced(subscription.sid);
+        marked += 1;
+      }
+    }
+    return marked;
   }
 
   register(definition: LiveQueryDefinition): this {
@@ -147,8 +125,9 @@ export class LiveQueryRegistry {
     return this.#entries.get(qid)?.subscribers.size ?? 0;
   }
 
-  subscription(sid: string): LiveSubscription | undefined {
-    return this.#bySid.get(sid);
+  /** One socket's subscription. A sid alone does not identify one — see `subscription-book.ts`. */
+  subscription(socketId: string, sid: string): LiveSubscription | undefined {
+    return this.#book.get(socketId, sid);
   }
 
   /**
@@ -163,14 +142,35 @@ export class LiveQueryRegistry {
     cursor?: LiveCursor | null;
   }): Promise<{ subscription: LiveSubscription; frame: Frame }> {
     const definition = this.#definitions.get(args.name);
-    if (!definition) {
-      throw new ProtocolVersionError({
-        got: args.name,
-        expected: PROTOCOL_VERSION,
-        detail: `no live query registered as "${args.name}" — client and server manifests differ`,
-      });
+    // A name this node never registered, and not a protocol skew: the frame parsed, the version
+    // matched, and one string in it names nothing. Reporting it as `X_PROTOCOL_VERSION` handed the
+    // client "x build && redeploy the client" for a typo no rebuild changes.
+    if (!definition) throw new LiveQueryUnknownError({ name: args.name });
+    const sid = args.sid ?? uuid();
+    // Everything this subscribe can be refused for, decided in one synchronous step BEFORE the
+    // first await — the caps and the sid both. Read at the top and acted on three awaits later,
+    // they were bypassed by the ordinary case: one WebSocket write carrying N subscribe frames,
+    // dispatched concurrently, N of them reading a count nothing had grown yet.
+    const slot = this.#book.reserve(args.socket, sid);
+    try {
+      return await this.#subscribeReserved(definition, sid, args);
+    } finally {
+      // After the attach on every path, so the slot is only ever given back to a count that has
+      // already grown — or, on a failure, to one that never will.
+      slot.release();
     }
-    this.#assertLimits(args.socket);
+  }
+
+  async #subscribeReserved(
+    definition: LiveQueryDefinition,
+    sid: string,
+    args: {
+      socket: SyncSocket;
+      name: string;
+      input: JsonValue;
+      cursor?: LiveCursor | null;
+    },
+  ): Promise<{ subscription: LiveSubscription; frame: Frame }> {
     await definition.authorize?.({ actor: args.socket.actor, input: args.input });
     // After this subscriber's own decision, never before it: resolving a shape for a caller who
     // may not subscribe is work an unauthorized client gets to schedule.
@@ -178,89 +178,111 @@ export class LiveQueryRegistry {
 
     const qid = qidOf(args.name, args.input);
     const entry = this.#entryFor(qid, definition, args.input);
-    const sid = args.sid ?? uuid();
     const now = this.#clock.now().getTime();
 
     if (args.cursor) {
-      const resumed = await resumeFrom(args.cursor, {
+      const cursor = args.cursor;
+      const resumed = await resumeFrom(cursor, {
         source: this.#options.source,
         ...(this.#options.budget ? { budget: this.#options.budget } : {}),
         clock: this.#clock,
         snapshot: async () => await this.#read(entry, { sid, actor: args.socket.actor }),
       });
       if (resumed.kind === 'delta') {
-        const patches = await this.#filterPatches(
+        // The gate decides about whole rows out of the shared window, and an entry nothing has read
+        // yet has none — every patch would meet an empty window and be withheld. Filling is
+        // conditional on purpose: a restart storm resumes onto entries that already hold a live
+        // window, and re-reading per resuming subscriber is the cost a delta resume exists to skip.
+        if (entry.lsn === '') await fillWindow(entry);
+        // The live entry on purpose: a resume runs outside the lane, so the window under it may
+        // have moved on — always forwards, and a row whose grant was revoked in the meantime is
+        // one this pass must refuse rather than replay from the state it had at the cursor's lsn.
+        const patches = await this.#gate.filterPatches(
           entry,
           { sid, actor: args.socket.actor },
           resumed.patches,
-          args.cursor,
+          new Set(cursor.ids),
         );
-        const subscription = this.#attach(entry, args.socket, sid, resumed.cursor);
+        const subscription = this.#attachUnlessGone(entry, args.socket, sid, resumed.cursor);
         return {
           subscription,
           frame: { type: 'patch', v: PROTOCOL_VERSION, sid, patches, lsn: resumed.cursor.lsn },
         };
       }
-      const subscription = this.#attach(entry, args.socket, sid, resumed.cursor);
+      const subscription = this.#attachUnlessGone(entry, args.socket, sid, resumed.cursor);
       return {
         subscription,
-        frame: {
-          type: 'snapshot',
-          v: PROTOCOL_VERSION,
-          sid,
-          rows: resumed.rows,
-          cursor: resumed.cursor,
-        },
+        frame: snapshotFrame(entry, sid, resumed.rows, resumed.cursor),
       };
     }
 
     const fresh = await this.#read(entry, { sid, actor: args.socket.actor });
     const cursor = makeCursor(qid, fresh.lsn, fresh.rows, now);
-    const subscription = this.#attach(entry, args.socket, sid, cursor);
-    return {
-      subscription,
-      frame: { type: 'snapshot', v: PROTOCOL_VERSION, sid, rows: fresh.rows, cursor },
-    };
+    const subscription = this.#attachUnlessGone(entry, args.socket, sid, cursor);
+    return { subscription, frame: snapshotFrame(entry, sid, fresh.rows, cursor) };
   }
 
-  unsubscribe(sid: string): void {
-    const subscription = this.#bySid.get(sid);
+  /** Scoped to the socket that asked: a client may only drop its own subscription. */
+  unsubscribe(socketId: string, sid: string): void {
+    const subscription = this.#book.get(socketId, sid);
     if (!subscription) return;
-    this.#bySid.delete(sid);
+    this.#book.delete(socketId, sid);
     subscription.socket.queries.delete(sid);
     subscription.socket.clearDesynced(sid);
     const entry = this.#entries.get(subscription.qid);
     if (!entry) return;
-    entry.subscribers.delete(sid);
+    entry.subscribers.delete(subscriptionKey(socketId, sid));
     // An entry with no subscribers stops costing a matcher and a change window.
-    if (entry.subscribers.size === 0) this.#entries.delete(subscription.qid);
+    if (entry.subscribers.size !== 0) return;
+    this.#entries.delete(subscription.qid);
+    // And the retained patches go with it. `forget` had no caller: the entry was dropped here and
+    // the `ResumeSource` was never told, so its ring for that qid sat at full capacity until the
+    // LRU happened to evict it — a client-chosen input's memory outliving the last subscriber.
+    this.#options.source.forget?.(subscription.qid);
   }
 
   unsubscribeSocket(socketId: string): void {
-    for (const subscription of [...this.#bySid.values()]) {
-      if (subscription.socket.id === socketId) this.unsubscribe(subscription.sid);
+    for (const subscription of this.#book.ofSocket(socketId)) {
+      this.unsubscribe(socketId, subscription.sid);
     }
   }
 
   /**
    * Actor changed mid-connection (login, logout, role change): re-run subscribe-time authz and drop
    * what is no longer allowed. Survivors are marked desynced so the next flush re-snapshots them
-   * under the new actor's row policy.
+   * under the new actor's row policy. Returns the sids that were dropped — a denial and nothing
+   * else, so a caller may tell the client "you may no longer see this" and be right.
    */
   async reauthorize(socket: SyncSocket): Promise<readonly string[]> {
     const dropped: string[] = [];
-    for (const subscription of [...this.#bySid.values()]) {
-      if (subscription.socket.id !== socket.id) continue;
+    // The actor changed, so what tenant this socket's subscriptions count against may have too.
+    // Told here rather than derived per lookup: the per-tenant cap is an index now, and an index
+    // nobody updates is a count that drifts from the book for the rest of the process.
+    this.#book.retenant(socket);
+    for (const subscription of this.#book.ofSocket(socket.id)) {
       try {
         await subscription.definition.authorize?.({
           actor: socket.actor,
           input: subscription.input,
         });
-        socket.markDesynced(subscription.sid);
-      } catch {
-        this.unsubscribe(subscription.sid);
-        dropped.push(subscription.sid);
+      } catch (error) {
+        if (isPolicyDenial(error)) {
+          this.unsubscribe(socket.id, subscription.sid);
+          dropped.push(subscription.sid);
+          continue;
+        }
+        // Not a decision — the gate never reached one. Destroying the subscription would report a
+        // database timeout as a revoked grant, and a client does not resubscribe to a denial. It
+        // survives, desynced: nothing is delivered from the window built under the old actor, and
+        // the row gate still decides every row under the new one, from the same policy `authorize`
+        // consults. The failure is counted and reported rather than silently absorbed.
+        this.#gate.failedAuthorize(
+          subscription.qid,
+          { sid: subscription.sid, actor: socket.actor },
+          error,
+        );
       }
+      socket.markDesynced(subscription.sid);
     }
     return dropped;
   }
@@ -268,53 +290,58 @@ export class LiveQueryRegistry {
   /**
    * Fan one change out. Matched once per query id, authorized once per subscriber. Returns the
    * number of frames sent — the metric the reconnect benchmark watches.
+   *
+   * Each entry's turn is taken in that entry's lane. Nothing upstream orders this: `sync` fires
+   * `void registry.deliver(change)` straight off the bus subscription, so two changes arriving back
+   * to back would otherwise interleave inside one query id — lsn 2 delivered before lsn 1, the
+   * subscriber's cursor rewound to 1, and every gate deciding against whichever window won.
+   *
+   * Every lane is *entered* before any of them is awaited, and nothing inside a fanout takes a
+   * second lane, so holding all of them at once cannot be a cycle. That is what makes the ordering
+   * claim true: two deliveries queue onto each query id in call order, serialized per query id and
+   * never per node — awaiting one entry before entering the next made one slow policy pass the
+   * whole node's pace, and let a lane that threw skip every entry behind it with nobody desynced.
    */
   async deliver(change: ChangeEvent): Promise<number> {
-    let sent = 0;
-    for (const entry of this.#entries.values()) {
-      const result = bridgeChange(entry.shape, entry.matcher, change, entry.rows);
-      if (!result) continue;
-      entry.lsn = change.lsn;
-      entry.rows = applyToWindow(entry.rows, result.patches);
-      // The retained window holds the pre-policy patch; resume re-filters it per subscriber.
-      for (const patch of result.patches) this.#options.source.append(entry.qid, patch);
-
-      for (const subscription of entry.subscribers.values()) {
-        if (result.refill) {
-          // The window lost its tail: guessing is how a sync engine silently diverges.
-          subscription.socket.markDesynced(subscription.sid);
-          continue;
-        }
-        const who: Subscriber = { sid: subscription.sid, actor: subscription.socket.actor };
-        const allowed: RowPatch[] = [];
-        for (const patch of result.patches) {
-          const gated = await this.#gate(
-            entry,
-            who,
-            patch,
-            subscription.cursor.ids.includes(patch.id),
-          );
-          if (gated) allowed.push(gated);
-        }
-        if (allowed.length === 0) continue;
-        const frame: Frame = {
-          type: 'patch',
-          v: PROTOCOL_VERSION,
-          sid: subscription.sid,
-          patches: allowed,
-          lsn: change.lsn,
-        };
-        if (subscription.socket.send(frame)) {
-          subscription.cursor = advance(subscription.cursor, allowed, change.lsn, change.at);
-          sent += 1;
-        } else {
+    const lanes = [...this.#entries.values()].map(async (entry) => {
+      try {
+        const result = await entry.lock.run(() => fanoutChange(this.#fanout, entry, change));
+        this.#staleChanges += result.stale;
+        return result.sent;
+      } catch (error) {
+        // The window advanced under a fanout that did not finish, so every subscriber of this one
+        // query id now holds a cursor below the change and no later flush would correct them:
+        // desynced here, re-snapshotted on the next one. Silent divergence is the whole reason
+        // `markDesynced` exists, and skipping this is how a failure became one.
+        for (const subscription of entry.subscribers.values()) {
           subscription.socket.markDesynced(subscription.sid);
         }
+        throw error;
       }
+    });
+    // `allSettled`, so one lane's rejection neither cancels the others nor goes unhandled. The
+    // first failure still reaches the caller — `sync` logs it — but it costs one query id.
+    let sent = 0;
+    let failure: { readonly error: unknown } | null = null;
+    for (const lane of await Promise.allSettled(lanes)) {
+      if (lane.status === 'fulfilled') sent += lane.value;
+      else failure ??= { error: lane.reason };
     }
+    if (failure !== null) throw failure.error;
     return sent;
   }
 
+  #attachUnlessGone(
+    entry: QueryEntry,
+    socket: SyncSocket,
+    sid: string,
+    cursor: LiveCursor,
+  ): LiveSubscription {
+    const subscription = this.#attach(entry, socket, sid, cursor);
+    if (socket.closed) this.unsubscribe(socket.id, sid);
+    return subscription;
+  }
+
   #attach(
     entry: QueryEntry,
     socket: SyncSocket,
@@ -329,8 +356,10 @@ export class LiveQueryRegistry {
       definition: entry.definition,
       cursor,
     };
-    entry.subscribers.set(sid, subscription);
-    this.#bySid.set(sid, subscription);
+    // The entry's own map takes the SAME composite key: a sid alone would collide across sockets
+    // here exactly as it did in the book, and `unsubscribe` deletes from both by one identity.
+    entry.subscribers.set(subscriptionKey(socket.id, sid), subscription);
+    this.#book.add(subscription);
     socket.queries.set(sid, entry.qid);
     socket.clearDesynced(sid);
     return subscription;
@@ -339,111 +368,29 @@ export class LiveQueryRegistry {
   #entryFor(qid: string, definition: LiveQueryDefinition, input: JsonValue): QueryEntry {
     const existing = this.#entries.get(qid);
     if (existing) return existing;
-    const matcher = definition.matcher(input);
-    const created: QueryEntry = {
-      qid,
-      definition,
-      input,
-      shape: {
-        qid,
-        // The matcher knows the dependency set this *input* produced; `definition.entities` is
-        // the static declaration and can only be a superset of it. Preferring the matcher is what
-        // lets a definition built from a real query carry no static list at all.
-        entities: matcher.entities.length > 0 ? matcher.entities : definition.entities,
-        orgId: orgIdOf(input),
-        ...(definition.columns ? { columns: definition.columns } : {}),
-      },
-      matcher,
-      subscribers: new Map(),
-      rows: [],
-      lsn: '',
-    };
+    // The node-wide ceiling, refused where the entry would be born. `qid` derives from
+    // client-chosen input, so one socket varying it mints a matcher, a row window and a
+    // `WindowLock` per value, and every change then fans out over all of them.
+    if (this.#entries.size >= this.#maxEntries) {
+      throw new SubscriptionLimitError({
+        scope: 'node',
+        id: definition.name,
+        limit: this.#maxEntries,
+        knob: 'maxEntries',
+      });
+    }
+    const created = createEntry(qid, definition, input, definition.matcher(input));
     this.#entries.set(qid, created);
     return created;
   }
 
-  /** One read, then one policy pass per subscriber. Never one read per subscriber. */
-  async #read(entry: QueryEntry, who: Subscriber): Promise<SnapshotResult> {
-    const result = await entry.definition.snapshot({ input: entry.input });
-    entry.rows = result.rows;
-    entry.lsn = result.lsn;
-    const rows: Row[] = [];
-    for (const row of result.rows) {
-      if (await entry.definition.visible({ actor: who.actor, row, input: entry.input })) {
-        rows.push(row);
-      } else {
-        this.#denied(entry, who, row.id);
-      }
-    }
-    return { rows, lsn: result.lsn };
-  }
-
-  async #filterPatches(
-    entry: QueryEntry,
-    who: Subscriber,
-    patches: readonly RowPatch[],
-    cursor: LiveCursor,
-  ): Promise<RowPatch[]> {
-    const held = new Set(cursor.ids);
-    const out: RowPatch[] = [];
-    for (const patch of patches) {
-      const allowed = await this.#gate(entry, who, patch, held.has(patch.id));
-      if (allowed) out.push(allowed);
-    }
-    return out;
-  }
-
   /**
-   * Row-level authz. A row that becomes invisible is converted to a `delete` when the subscriber
-   * holds it — otherwise a revoked grant would leave a stale row on screen forever.
+   * One read, then one policy pass per subscriber. Never one read per subscriber — and never a
+   * partial pass: a gate that fails raises out of `subscribe`, because a snapshot missing the rows
+   * nobody could decide about is a short result set this subscriber would render as the whole one.
    */
-  async #gate(
-    entry: QueryEntry,
-    who: Subscriber,
-    patch: RowPatch,
-    holds: boolean,
-  ): Promise<RowPatch | null> {
-    if (patch.op === 'delete' || patch.row === null) return patch;
-    // The policy always sees the whole row from the shared window — a patch carries changed
-    // columns only, and authorizing a partial row is how a row policy silently starts failing.
-    const full = entry.rows.find((row) => row.id === patch.id);
-    const row: Row = { ...(full ?? {}), ...patch.row, id: patch.id };
-    if (await entry.definition.visible({ actor: who.actor, row, input: entry.input })) return patch;
-    this.#denied(entry, who, patch.id);
-    return holds ? { op: 'delete', id: patch.id, row: null, lsn: patch.lsn } : null;
-  }
-
-  /** `live.rows_denied`. Counted here and nowhere else, so every drop is one increment. */
-  #denied(entry: QueryEntry, who: Subscriber, rowId: string): void {
-    this.#rowsDenied += 1;
-    this.#options.onRowDenied?.({
-      qid: entry.qid,
-      sid: who.sid,
-      actorId: who.actor === null ? null : who.actor.id,
-      rowId,
-    });
-  }
-
-  #assertLimits(socket: SyncSocket): void {
-    const perSocket = this.#options.maxPerSocket ?? 128;
-    if (socket.queries.size >= perSocket) {
-      throw new SubscriptionLimitError({ scope: 'socket', id: socket.id, limit: perSocket });
-    }
-    const perTenant = this.#options.maxPerTenant;
-    const tenant = this.#options.tenantOf?.(socket.actor) ?? null;
-    if (perTenant === undefined || tenant === null) return;
-    let count = 0;
-    for (const subscription of this.#bySid.values()) {
-      if ((this.#options.tenantOf?.(subscription.socket.actor) ?? null) === tenant) count += 1;
-    }
-    if (count >= perTenant) {
-      throw new SubscriptionLimitError({ scope: 'tenant', id: tenant, limit: perTenant });
-    }
+  async #read(entry: QueryEntry, who: Subscriber): Promise<SnapshotResult> {
+    const window = await fillWindow(entry);
+    return { rows: await this.#gate.filterRows(entry, who, window.rows), lsn: window.lsn };
   }
 }
-
-function orgIdOf(input: JsonValue): string | null {
-  if (typeof input !== 'object' || input === null || Array.isArray(input)) return null;
-  const value = input['orgId'];
-  return typeof value === 'string' ? value : null;
-}