@ultimat3/realtime 22.14.0 → 23.0.0

package/CLAUDE.md

@@ -85,8 +85,9 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A denial is a decision; everything else is a failure.** `visibleWithPolicy` matches
   `QueryDeniedError` and rethrows the rest; `subscriber-gate.ts` and `reauthorize` ask
   `isPolicyDenial(error)`. A failed snapshot raises out of `subscribe`; a failed delivery desyncs that
-  one subscriber; a failed `reauthorize` keeps the subscription. Failures count as `gateFailures` via
-  `onGateFailed`, never `onRowDenied`.
+  one subscriber; a failed `reauthorize` keeps the subscription, unless its org moved — then it is
+  refused under its sid (`refuseSubscription`), as is a failed re-seat. Failures count as
+  `gateFailures` via `onGateFailed`, never `onRowDenied`.
 - **One serial lane per query id (`WindowLock`) is the only thing that orders a fanout.** `deliver`
   enters every lane before awaiting any; no fanout takes a second lane; a lane that fails desyncs its
   own subscribers; lanes chain on a settled shadow of each task.
@@ -107,8 +108,14 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A change the window already holds is refused** (`change.lsn <= entry.lsn`, counted as
   `staleChanges`). **A gap is detected**: the replicator stamps `producer` + `seq`; a skipped
   sequence marks every window stale and every subscriber desynced; `refillWindowInLane` replaces it.
-- **A qid is `@ultimat3/query`'s `queryHash(name, input)`**; this package owns no hash
-  (`live-contract.test.ts`). The canonical form is core's and injective (`-0` is wire-reachable).
+- **A bulk write stales only the windows reading its entity** (`invalidate(entity)`, from
+  `onBulk`). **A stale window's re-read re-snapshots EVERY subscriber**, before the lsn guard and
+  on a non-matching change too (`live-replicator-bulk.test.ts`, `live-fanout.test.ts`).
+- **A WINDOW is per TENANT**: its id is `windowId(queryHash(name, input), tenant)` (`live-tenant.ts`;
+  tenant = the subscriber's `actor.orgId`). This package owns no hash. The read runs `readFor`
+  (`live-definition.ts`): the node's ctx, a service actor carrying ONLY that org — never the
+  subscriber. A cursor naming another window is a cold start; `reauthorize` re-seats a
+  subscription whose actor changed org (`live-tenancy.test.ts`; `docs/history/realtime.md`).
 - **A `sid` is CLIENT data: a subscription is keyed by `(socket, sid)`**
   (`subscription-book.ts` is the only spelling). Reusing a sid the same socket holds is
   `X_SUBSCRIPTION_ID_TAKEN`.
@@ -168,8 +175,6 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `DrainedSocket[]` with `notified` and logs `sync.drain_frames_dropped`.
 - **Inbound frames run in a lane, never the socket**: `subscribe` is `sub:<sid>` or `topic:<name>`,
   everything else unlaned (`frame-lanes.ts`); a lane exists only while work is queued.
-- **Bun's native pub/sub is deleted**; `SocketRegistry.deliver` is the one fanout path.
-  `WsLike.subscribe`/`unsubscribe` stay declared for structural implementers.
 - **A dropped `records` frame is counted AND repaired**: per-node `seq`/`epoch` per channel; a refused
   frame marks the socket gapped, and the websocket `drain` handler sends `replay-gap`
   (`channel_replay_gaps_total` beside `channel_frames_dropped_total`). The client re-runs the
@@ -265,20 +270,16 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   throws in the timer is reported through `onError` (default `console.error`) and arms the next.
 - **`connect()` closes the socket it replaces**; `onOpen`, `onMessage` and `onClose` all carry the
   identity guard.
+- **A refusal `ack` is revived as a branded `UltimateError`** (`refusalError`, `client-frames.ts`).
 - **A reconnect replays registrations AND topics** — one `hello`, one `subscribe` per registration
   (with its cursor) and per topic.
-- **`hello` carries NO cursors** (`HelloFrame.resume` is deleted): a cursor's qid names a window but
-  not the input a decision needs.
 - **The client beats** (`heartbeatMs`, default `DEFAULT_HEARTBEAT_MS` 15 s, `0` disables): a `hello`
   plus one subscribe per topic (the presence heartbeat). Two silent windows close with `4000`. The
   node's `socket.skewed` compares the build the `hello` claims against its own. The server beat is
   derived: `PresenceRegistry.heartbeatMs = max(1000, floor(ttlMs / 3))`.
-- **There is ONE `backoffDelay`, `@ultimat3/core`'s, counted from 1.** `policyDelay(policy, attempt,
-  rng)` (internal, not on the barrel) maps a `BackoffPolicy` onto it; a 0-based counter adds 1 at the
-  call site (`client.ts`, `socket-engine.ts`, `replicator.ts`'s 0-based `retryDelayMs`).
-  `client-reconnect.test.ts`, `socket-engine-reconnect.test.ts`, `nats-transport.test.ts` pin the
-  first wait at the base. `drainPlan()` and `AcceptBudget` keep their own arithmetic.
-  `bun run flight-copies` refuses a second curve.
+- **There is ONE `backoffDelay`, `@ultimat3/core`'s, counted from 1** — `policyDelay()` maps a
+  `BackoffPolicy` onto it; `bun run flight-copies` refuses a second curve. Long form:
+  `docs/history/realtime.md`, "Moved 2026-10-01".
 
 ## Rules for code here
 
@@ -287,17 +288,9 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `Denied`, `ThirdPartySdkError`): it simulates a value this package did not construct. The rule
   governs what this package **throws**, never what a test hands it.
 
-## Browser bytes, per hook (`As of 2026-09-22`)
+## The page boot
 
-`bun build --target=browser --minify`, one entry importing one hook from the barrel. Re-measure
-before quoting.
-
-| Hook | Current |
-|---|---|
-| `useRecord` | 13,226 |
-| `useMutation` | 21,725 (after the outbox left islands) |
-| `useQuery` | 47,696 |
-| `useChannel` | 45,585 |
+Browser bytes per hook, as last measured: `docs/history/realtime.md`. Re-measure before quoting.
 
 - **The disk boot is ONE page script (`boot.ts`, `./boot`)**, served at `/_x/page-boot/<hash>.js`
   on a document with the scope tag and a realtime island; it wipes every other principal's stored
@@ -309,7 +302,7 @@ before quoting.
 
 `index.ts` / `server.ts` are the two barrels. Server side: `sync-node.ts` (+ `sync-auth`,
 `sync-frames`, `sync-upgrade`, `sync-listen`, `drain-evictions`), `channel.ts`, `presence.ts`,
-`socket.ts`, `live-query.ts` (+ `live-definition`, `query-window`, `live-fanout`, `window-lock`,
+`socket.ts`, `live-query.ts` (+ `live-definition`, `live-refusal`, `live-tenant`, `live-resume`, `query-window`, `live-fanout`, `window-lock`,
 `subscriber-gate`, `policy-gate` — the only authz seam — and `matcher-bridge`), `replicator.ts` /
 `live-replicator.ts`, the Postgres client (`pg-*.ts`, `pgoutput.ts`), the bus (`nats-*.ts`,
 `transport-env.ts`, `fanout.ts`). Client side: `client*.ts`, `socket-engine.ts` / `socket-host.ts` /

package/README.md

@@ -232,6 +232,32 @@ One authz system, never two: `policy` is evaluated **once per subscriber**, neve
 Two actors on one live query get two different result sets, and a row that leaves an actor's policy
 is delivered to them as a `delete` — never as silence.
 
+**The shared read is a TENANT's, never the node's.** One `(query, input)` is one window per org:
+its id is `windowId(queryHash(name, input), tenant)`, the tenant being the subscriber's
+`actor.orgId`, and its source is read in a context that carries that org and nothing else of any
+subscriber's. So a repo that leaves the tenant to the acting actor — what `x g query --live`
+generates — reads on a sync node exactly as it reads over HTTP, and no org predicate is written
+by hand.
+
+| On a sync node | Answer |
+|---|---|
+| two subscribers of one org, one `(query, input)` | one window, one read, one policy pass each |
+| two subscribers in two orgs, one `(query, input)` | two windows, two reads, two retained patch rings — a row of one is never in the other's, policy or not |
+| the source names no org (`db.posts.orderBy(…)`) | scoped to the window's tenant by `@ultimat3/entity`'s guard |
+| the source names ANOTHER org | `X_TENANCY_ACTOR_MISMATCH`, as over HTTP — it was answered, until 2026-10 |
+| a subscriber with no org reads a tenant-scoped table | `X_TENANCY_ACTOR_ORG_REQUIRED`, as over HTTP |
+| a reconnect presents a cursor minted in another org's window | a cold start: one snapshot, never a replay of that window's patches |
+| the actor changes org mid-connection | `reauthorize` re-seats the subscription on its new tenant's window and sends that snapshot |
+
+The read's actor is `serviceActor({ id: 'live-window', orgId })` — the shape a job run gets. Never
+a subscriber's: a window has many, and one subscriber's identity on a shared read is that
+subscriber's entitlements becoming the window's.
+
+**A refusal reaches the page as itself.** A subscription the node refuses is an `ack` carrying
+`{ code, cause, fix }`; the client revives it as a branded `UltimateError` (`meta.origin:
+'remote'`), so `useQuery`'s `failed` state and an `<ErrorState>` render that code and that fix.
+Handed over as the bare wire object it failed `isUltimateError` and rendered as `X_INTERNAL`.
+
 ## What one socket may cost
 
 Every ceiling on this node, and the option that moves it. Each one is a default, not a policy: an
@@ -401,6 +427,10 @@ wire twice by a reconnect that raced an ack.
   re-reads and re-snapshots. Both fields are optional on the bus, so a publisher that does not
   sequence simply detects nothing. Durable replay (JetStream) is a separate decision — retention,
   storage and replay window — and is deliberately not this mechanism.
+- **A bulk write re-reads only the windows over its entity.** `updateWhere`/`deleteWhere` name a
+  filter, not rows, so the in-process replicator calls `registry.invalidate(entity)`: windows whose
+  shape reads that entity go stale and their subscribers desynced. The next change re-reads the
+  window and re-snapshots every subscriber, whether or not that change matches the query.
 - **`desynced` has a reader.** A subscriber recorded as diverged — a dropped patch, a gate that
   failed, a window that lost its tail — is served a fresh snapshot out of the shared window on the
   next delivery, and only then is the mark cleared. A snapshot the socket refuses leaves it
@@ -443,9 +473,9 @@ wire twice by a reconnect that raced an ack.
   `subscribe` is one lane per sid, or per topic name; `hello` and
   the server-authored kinds are unlaned. A lane exists only while work is queued on it, because a
   lane keyed by a client-chosen sid that outlived its work is an unbounded map one socket can grow.
-- **`qid` is `@ultimat3/query`'s `queryHash(name, input)`** — `<name>:<first 16 hex of
-  SHA-256(canonicalJson(input))>`, 64 bits `As of 2026-08` where it was a 32-bit FNV-1a. It is a
-  *sharing* key: a hit is answered with the existing entry and the seated window, both holding the
+- **A window's `qid` is `@ultimat3/query`'s `queryHash(name, input)`, qualified by the tenant it
+  is read for** (`windowId`) — `<name>:<first 16 hex of SHA-256(canonicalJson(input))>`, 64 bits
+  `As of 2026-08` where it was a 32-bit FNV-1a. It is a *sharing* key: a hit is answered with the existing entry and the seated window, both holding the
   first subscriber's input and rows, and input is client-chosen, so a collision is one client served
   out of another's window. This package derives none of its own — `qidOf` was a second spelling of
   `queryHash` while `@ultimat3/query`'s `planResume` compares a cursor's `queryHash` against the

package/package.json

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

package/src/client-frames.ts

@@ -3,11 +3,12 @@
 // every piece of the client a frame may touch, so the blast radius of a new frame kind is a
 // reviewable list rather than "whatever the router could reach through `this`".
 
+import { UltimateError } from '@ultimat3/core/page';
 import type { ChannelBook } from './client-channels';
 import { CLOSE } from './close-codes';
 import { advance } from './cursor';
 import type { Registration, RowWindows } from './live-rows';
-import type { Frame } from './sync-protocol';
+import type { Frame, WireError } from './sync-protocol';
 
 /** Declared with the window it projects; re-exported here because the router is what writes it. */
 export type { LiveState, Registration } from './live-rows';
@@ -42,6 +43,28 @@ export interface ClientFrameTarget {
   report(error: unknown): void;
 }
 
+/** An absolute HTTP(S) link, or nothing: a node's `docs` is data and may be `javascript:`. */
+const HTTP_URL = /^https?:\/\/[^\s]+$/;
+
+/**
+ * A refusal off the wire, as the error the node raised: the same code, cause and fix, BRANDED —
+ * the shape `@ultimat3/core`'s `problemError` gives an HTTP failure, marked `origin: 'remote'` the
+ * same way. Handed over as the bare `WireError` it failed `isUltimateError`, so every reader that
+ * asks that question — `<ErrorState>`, a boundary, a reporter — fell through to "an unknown value
+ * was thrown": `X_INTERNAL`, the real error JSON-stringified into its cause, and a fix telling the
+ * reader to throw the `UltimateError` it already was.
+ */
+export function refusalError(wire: WireError): UltimateError {
+  const docs = wire.docs !== undefined && HTTP_URL.test(wire.docs) ? wire.docs : undefined;
+  return new UltimateError({
+    code: wire.code,
+    cause: wire.cause,
+    fix: wire.fix,
+    meta: { origin: 'remote' },
+    ...(docs === undefined ? {} : { docs }),
+  });
+}
+
 export function applyFrame(frame: Frame, target: ClientFrameTarget): void {
   switch (frame.type) {
     case 'snapshot': {
@@ -78,13 +101,14 @@ export function applyFrame(frame: Frame, target: ClientFrameTarget): void {
       // The socket carries no writes, so an `ack` is only ever a refusal: of a subscription (its
       // `ref` is the sid) or of a frame the node could not read at all (its `ref` is the socket).
       if (frame.error === null) return;
+      const refusal = refusalError(frame.error);
       const registration = target.registration(frame.ref);
       if (registration === undefined) {
-        if (!target.channels.refused(frame.ref, frame.error)) target.report(frame.error);
+        if (!target.channels.refused(frame.ref, refusal)) target.report(refusal);
         return;
       }
       registration.state = 'failed';
-      registration.error = frame.error;
+      registration.error = refusal;
       registration.notify();
       return;
     }

package/src/live-contract.ts

@@ -26,8 +26,12 @@ export interface LiveQueryDefinition<R extends Row = Row> {
   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>>;
+  /**
+   * Bounded read (`orderBy` + `limit`, enforced by `x verify`), unfiltered by policy — and read
+   * FOR `tenant`: the org of the subscribers this window serves, `null` for subscribers that carry
+   * none. A window is keyed by it (`live-tenant.ts`), so one read is never two orgs' rows.
+   */
+  snapshot(args: { input: JsonValue; tenant: string | null }): 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. */

package/src/live-definition.ts

@@ -9,7 +9,7 @@
 // every time. Collapsing the second onto the first is privilege escalation with a cache hit rate.
 
 import type { Ctx } from '@ultimat3/core';
-import { finiteOption } from '@ultimat3/core';
+import { finiteOption, runWithContext, serviceActor, withChildContext } from '@ultimat3/core';
 import { type AnyQuery, queryHash, queryName } from '@ultimat3/query';
 import { LiveRowUnidentifiedError } from './errors';
 import { isRow, type JsonValue, type Row } from './json';
@@ -22,7 +22,8 @@ export interface LiveDefinitionOptions {
   /**
    * The node's own context — never a subscriber's. It supplies services, clock and locale to the
    * shared read; it supplies no authority, because that read is built with the query's policy
-   * switched off and every row leaving it is gated per subscriber.
+   * switched off and every row leaving it is gated per subscriber. The read itself runs in a CHILD
+   * of it that carries the window's tenant and nothing else of any subscriber's (`readFor`).
    */
   readonly ctx: Ctx;
   /**
@@ -82,6 +83,25 @@ const UNRESOLVED: IncrementalMatcher = {
   match: () => ({ patches: [], refill: true }),
 };
 
+/** Who a shared read runs as: the node, in one org. Never a subscriber — a window has many. */
+const LIVE_READER_ID = 'live-window';
+
+/**
+ * Run one shared read FOR a tenant: inside the node's context, as a service actor that carries the
+ * window's org and no subscriber's identity, roles or grants. `@ultimat3/entity`'s tenant guard
+ * derives from the ambient context, so this is what makes a repo that leaves the tenant to the
+ * acting actor read on a sync node exactly as it reads over HTTP — and what refuses a read that
+ * names another org (`X_TENANCY_ACTOR_MISMATCH`), which with NO context was simply answered.
+ *
+ * `tenant === null` runs under the node's own actor, which has no org: a tenant-scoped read is
+ * then `X_TENANCY_ACTOR_ORG_REQUIRED`, the verdict the same anonymous read gets over HTTP.
+ */
+function readFor<T>(ctx: Ctx, tenant: string | null, read: () => Promise<T>): Promise<T> {
+  if (tenant === null) return runWithContext(ctx, read);
+  const actor = serviceActor({ id: LIVE_READER_ID, orgId: tenant });
+  return runWithContext(ctx, () => withChildContext({ actor }, read));
+}
+
 /**
  * Registrable definition for one declared query. `register` takes it by name, so what comes back
  * is input-independent: the per-input half is resolved by `prepare`, which the registry awaits
@@ -140,13 +160,13 @@ export function liveQueryDefinition(
     prepare: async (input) => {
       await resolve(input);
     },
-    snapshot: async ({ input }): Promise<SnapshotResult> => {
+    snapshot: async ({ input, tenant }): Promise<SnapshotResult> => {
       const window = await resolve(input);
       // The position is taken BEFORE the rows: the rows are then at least that new, so the claim
       // is true. Taken after, a commit landing mid-read was claimed and missing — and every change
       // up to it is dropped downstream as already folded.
       const lsn = options.lsn?.() ?? '';
-      return { rows: await window.read(), lsn };
+      return { rows: await readFor(options.ctx, tenant, () => window.read()), lsn };
     },
     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

package/src/live-fanout.ts

@@ -47,14 +47,29 @@ export async function fanoutChange(
     return { sent: 0, stale: 0 };
   }
   if (change.op === 'truncate') return await truncated(deps, entry, change);
-  if (entry.stale) await refillWindowInLane(entry);
+  const reread = entry.stale;
+  if (reread) {
+    await refillWindowInLane(entry);
+    // Every subscriber was fed from the rows this read just replaced, so each is owed a snapshot —
+    // not only the ones `invalidate()` marked: a read that failed or timed out stales the window
+    // and marks nobody.
+    for (const subscription of entry.subscribers.values()) {
+      subscription.socket.markDesynced(subscription.sid);
+    }
+    // The read claims to hold this change already (`lsn` is the node's newest when it began), so
+    // there is nothing to patch. Returning before the loop below was the defect: the guard after
+    // this refused the change as stale and every desynced subscriber went without the change AND
+    // without its snapshot — a run console frozen on its first event after one `updateWhere`.
+    if (change.lsn <= entry.lsn) return { sent: await resnapshotAll(deps, entry), stale: 0 };
+  }
   // The consume-side twin of the replicator's own duplicate guard, which had none. `entry.lsn =
   // change.lsn` was unconditional, so a change the window already holds — a redelivery, or one
   // that arrived behind the snapshot that already included it — rewound every subscriber's cursor
   // to it and asked them to fold state they had already folded over newer rows.
   if (entry.lsn !== '' && change.lsn <= entry.lsn) return { sent: 0, stale: 1 };
   const bridged = bridgeChange(entry.shape, entry.matcher, change, entry.rows);
-  if (!bridged) return { sent: 0, stale: 0 };
+  // Matching nothing ends the fanout, but never before a re-read's marks are answered.
+  if (!bridged) return { sent: reread ? await resnapshotAll(deps, entry) : 0, stale: 0 };
   // Keyed ONCE, here, before the retained window stores them: a resume replays the same key.
   const result = { ...bridged, patches: keyPatches(entry, change, bridged.patches) };
   entry.lsn = change.lsn;
@@ -138,12 +153,20 @@ async function truncated(
   if (!entry.shape.entities.includes(change.entity)) return { sent: 0, stale: 0 };
   await refillWindowInLane(entry);
   if (change.lsn > entry.lsn) entry.lsn = change.lsn;
-  let sent = 0;
   for (const subscription of entry.subscribers.values()) {
     subscription.socket.markDesynced(subscription.sid);
+  }
+  return { sent: await resnapshotAll(deps, entry), stale: 0 };
+}
+
+/** Each marked subscriber, re-snapshotted out of the window just read. Frames that left. */
+async function resnapshotAll(deps: FanoutDeps, entry: QueryEntry): Promise<number> {
+  let sent = 0;
+  for (const subscription of entry.subscribers.values()) {
+    if (!subscription.socket.desynced.has(subscription.sid)) continue;
     if (await resnapshot(deps, entry, subscription)) sent += 1;
   }
-  return { sent, stale: 0 };
+  return sent;
 }
 
 /**

package/src/live-query.ts

@@ -1,31 +1,27 @@
 // Tier 2: live queries. Registration, per-subscriber authz, snapshot, patch stream.
 //
 // The rule this file exists to enforce: **policy is evaluated once per subscriber, never once per
-// query**. The DB read is shared across subscribers of the same query id; the authz decision is
-// not. Two actors on one live query see two different result sets, and a row that fails an actor's
+// query**. The DB read is shared across subscribers of the same query id IN ONE TENANT
+// (`live-tenant.ts`); the authz decision is not shared at all. Two actors on one live query see two different result sets, and a row that fails an actor's
 // policy is never sent to that actor — it arrives as a `delete` if they hold it, and is dropped
 // otherwise.
 
 import { type Actor, type Clock, finiteOption, systemClock, uuid } from '@ultimat3/core';
 import { queryHash } from '@ultimat3/query';
 import type { ChangeEvent } from './changefeed';
-import {
-  advance,
-  type LiveCursor,
-  makeCursor,
-  type ReconnectBudget,
-  type ResumeSource,
-  resumeFrom,
-} from './cursor';
+import { type LiveCursor, makeCursor, type ReconnectBudget, type ResumeSource } from './cursor';
 import { isPolicyDenial, LiveQueryUnknownError, SubscriptionLimitError } from './errors';
 import type { JsonValue } from './json';
 import type { LiveQueryDefinition, LiveSubscription, SnapshotResult } from './live-contract';
 import { type FanoutDeps, fanoutChange, snapshotFrame } from './live-fanout';
+import { refuseSubscription } from './live-refusal';
+import { resumeOnto } from './live-resume';
+import { liveTenantOf, windowId } from './live-tenant';
 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';
+import type { Frame } from './sync-protocol';
 import type { Scheduler } from './thundering-herd';
 
 export interface LiveQueryRegistryOptions extends SubscriberGateOptions {
@@ -111,10 +107,15 @@ export class LiveQueryRegistry {
    * 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.
+   *
+   * `entity` narrows it to the windows that read that entity: a filtered write
+   * (`updateWhere`/`deleteWhere`) names its entity but no row, and staling every window on the node
+   * for it re-read every live query in the process on each bulk write to any table.
    */
-  invalidate(): number {
+  invalidate(entity?: string): number {
     let marked = 0;
     for (const entry of this.#entries.values()) {
+      if (entity !== undefined && !entry.shape.entities.includes(entity)) continue;
       entry.stale = true;
       for (const subscription of entry.subscribers.values()) {
         subscription.socket.markDesynced(subscription.sid);
@@ -188,8 +189,11 @@ export class LiveQueryRegistry {
     // may not subscribe is work an unauthorized client gets to schedule.
     await definition.prepare?.(args.input);
 
-    const qid = queryHash(args.name, args.input);
-    const entry = this.#entryFor(qid, definition, args.input);
+    // The window is the subscriber's TENANT's: two orgs on one `(query, input)` are two entries,
+    // two reads and two retained rings, so no shared row ever stands between them and a policy.
+    const tenant = liveTenantOf(args.socket.actor);
+    const qid = windowId(queryHash(args.name, args.input), tenant);
+    const entry = this.#entryFor(qid, definition, args.input, tenant);
     try {
       return await this.#serve(entry, sid, args);
     } catch (error) {
@@ -215,48 +219,27 @@ export class LiveQueryRegistry {
     const qid = entry.qid;
     const now = this.#clock.now().getTime();
 
-    if (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') {
-        // 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,
-          new Set(cursor.ids),
-        );
-        // Advanced over the FILTERED list, never over `resumed.cursor` — which `resumeFrom` built
-        // by advancing across the retained window, and that window is PRE-POLICY. Seated as it
-        // came back, this subscriber's `cursor.ids` gained the id of every row inserted for every
-        // OTHER actor while it was away; `subscriber-gate` then reads `held.has(patch.id)` off it,
-        // takes the "the subscriber holds this row" branch, and delivers a `delete` frame carrying
-        // another tenant's row id and the instant it went. The leak that branch closes, re-opened
-        // one layer up. `live-fanout.ts` advances over `allowed` for exactly this reason.
-        const seated = advance(cursor, patches, resumed.cursor.lsn, now);
-        const subscription = this.#attachUnlessGone(entry, args.socket, sid, seated);
-        return {
-          subscription,
-          frame: { type: 'patch', v: PROTOCOL_VERSION, sid, patches, lsn: seated.lsn },
-        };
-      }
+    // A cursor is CLIENT data, and its `qid` names the window whose retained patches a resume
+    // replays. One that names another window — the same browser, signed in to another org, or a
+    // forged frame — is not a position in this one: it is a cold start, never a replay of a ring
+    // this subscriber's window does not own.
+    if (args.cursor && args.cursor.qid === qid) {
+      const who = { sid, actor: args.socket.actor };
+      const resumed = await resumeOnto(
+        {
+          source: this.#options.source,
+          budget: this.#options.budget,
+          clock: this.#clock,
+          gate: this.#gate,
+          read: () => this.#read(entry, who),
+        },
+        entry,
+        who,
+        args.cursor,
+        now,
+      );
       const subscription = this.#attachUnlessGone(entry, args.socket, sid, resumed.cursor);
-      return {
-        subscription,
-        frame: snapshotFrame(entry, sid, resumed.rows, resumed.cursor),
-      };
+      return { subscription, frame: resumed.frame };
     }
 
     const fresh = await this.#read(entry, { sid, actor: args.socket.actor });
@@ -314,6 +297,11 @@ export class LiveQueryRegistry {
    * what is no longer allowed. Survivors are marked desynced so the next flush re-snapshots them
    * 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.
+   *
+   * A survivor whose actor now belongs to ANOTHER tenant cannot stay where it is: its window is the
+   * old org's. It is re-seated — dropped, subscribed again under the new tenant, and sent that
+   * window's snapshot under the same sid — or, when that cannot complete, refused on the socket
+   * under the sid (`refuseSubscription`), never kept on the old org's window.
    */
   async reauthorize(socket: SyncSocket): Promise<readonly string[]> {
     const dropped: string[] = [];
@@ -322,6 +310,7 @@ export class LiveQueryRegistry {
     // 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)) {
+      let failed: { readonly error: unknown } | undefined;
       try {
         await subscription.definition.authorize?.({
           actor: socket.actor,
@@ -343,12 +332,46 @@ export class LiveQueryRegistry {
           { sid: subscription.sid, actor: socket.actor },
           error,
         );
+        failed = { error };
       }
+      if (await this.#reseat(socket, subscription, failed)) continue;
       socket.markDesynced(subscription.sid);
     }
     return dropped;
   }
 
+  /**
+   * Move one subscription onto its actor's CURRENT tenant's window. `false` when it is already
+   * there. A re-seat that cannot complete leaves the subscription dropped — never attached to the
+   * window of an org its actor has left — and REFUSED on the socket under its sid, the frame a
+   * refused subscribe gets, so the client's window renders `failed` instead of going quiet.
+   *
+   * `failed` is the `authorize` this pass already saw fail: it is not asked again — the store that
+   * just timed out is the one `subscribe` would ask — and it is not counted twice.
+   */
+  async #reseat(
+    socket: SyncSocket,
+    subscription: LiveSubscription,
+    failed: { readonly error: unknown } | undefined,
+  ): Promise<boolean> {
+    const { sid, input, definition } = subscription;
+    const wanted = windowId(queryHash(definition.name, input), liveTenantOf(socket.actor));
+    if (wanted === subscription.qid) return false;
+    this.unsubscribe(socket.id, sid);
+    if (failed !== undefined) {
+      refuseSubscription(socket, sid, failed.error);
+      return true;
+    }
+    try {
+      const { frame } = await this.subscribe({ socket, name: definition.name, input, sid });
+      if (!socket.send(frame)) socket.markDesynced(sid);
+    } catch (error) {
+      this.#gate.failedAuthorize(wanted, { sid, actor: socket.actor }, error);
+      refuseSubscription(socket, sid, error);
+    }
+    return true;
+  }
+
   /**
    * 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.
@@ -437,7 +460,12 @@ export class LiveQueryRegistry {
     return subscription;
   }
 
-  #entryFor(qid: string, definition: LiveQueryDefinition, input: JsonValue): QueryEntry {
+  #entryFor(
+    qid: string,
+    definition: LiveQueryDefinition,
+    input: JsonValue,
+    tenant: string | null,
+  ): QueryEntry {
     const existing = this.#entries.get(qid);
     if (existing) return existing;
     // The node-wide ceiling, refused where the entry would be born. `qid` derives from
@@ -454,6 +482,7 @@ export class LiveQueryRegistry {
     const created = createEntry(qid, definition, input, definition.matcher(input), {
       readDeadlineMs: this.#options.readDeadlineMs,
       schedule: this.#options.schedule,
+      tenant,
     });
     this.#entries.set(qid, created);
     return created;

package/src/live-refusal.ts

@@ -0,0 +1,21 @@
+// A live subscription refused AFTER it was served: the frame a refused `subscribe` gets — an `ack`
+// whose `ref` is the sid — sent by the node itself, so the client's window renders `failed` with
+// the code, cause and fix instead of going quiet. `sync-node.ts` sends the same frame when a
+// subscribe frame throws.
+
+import { logger } from '@ultimat3/core';
+import type { SyncSocket } from './socket';
+import { PROTOCOL_VERSION, toWireError } from './sync-protocol';
+
+export function refuseSubscription(socket: SyncSocket, sid: string, error: unknown): void {
+  const sent = socket.send({
+    type: 'ack',
+    v: PROTOCOL_VERSION,
+    ref: sid,
+    lsn: null,
+    error: toWireError(error),
+  });
+  // Read, never assumed: the subscription is already gone, so a dropped refusal leaves a client
+  // waiting on a window nothing serves — the log is the only trace it would leave.
+  if (!sent) logger.warn('sync.refusal_dropped', { socketId: socket.id, sid });
+}

package/src/live-replicator.ts

@@ -125,14 +125,14 @@ export async function startLiveReplicator(options: LiveReplicatorOptions): Promi
 
     /**
      * A filtered write names rows this seam never saw, so there is no event to shape. Every window
-     * on the node is marked stale instead and re-read on the next change — `invalidate()` is the
-     * node's own answer to "the change stream skipped something", used here for the one write that
-     * genuinely does. Silence would be the alternative, and a subscriber told nothing happened
-     * diverges with nobody ever asking again.
+     * over THAT entity is marked stale instead and re-read, its subscribers re-snapshotted, on the
+     * next change — `invalidate()` is the node's own answer to "the change stream skipped
+     * something", used here for the one write that genuinely does. Silence would be the
+     * alternative, and a subscriber told nothing happened diverges with nobody ever asking again.
      */
-    onBulk(_change: RowBulkChange): void {
+    onBulk(change: RowBulkChange): void {
       if (stopped) return;
-      registry.invalidate();
+      registry.invalidate(change.entity);
     },
   };
 

package/src/live-resume.ts

@@ -0,0 +1,74 @@
+// One subscriber resuming onto its window from a cursor: replay the retained patches when the
+// cursor is inside them, serve one bounded snapshot when it is not. Split from `live-query.ts` at
+// that file's size ceiling — the registry owns the entry table and who is attached to what; this
+// owns what a returning subscriber is SENT. It attaches nothing: the caller seats the cursor.
+
+import type { Clock } from '@ultimat3/core';
+import {
+  advance,
+  type LiveCursor,
+  type ReconnectBudget,
+  type ResumeSource,
+  resumeFrom,
+} from './cursor';
+import type { SnapshotResult } from './live-contract';
+import { snapshotFrame } from './live-fanout';
+import { fillWindow, type QueryEntry } from './query-window';
+import type { Subscriber, SubscriberGate } from './subscriber-gate';
+import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
+
+export interface ResumeOntoDeps {
+  readonly source: ResumeSource;
+  readonly budget?: ReconnectBudget | undefined;
+  readonly clock: Clock;
+  readonly gate: SubscriberGate;
+  /** The window, read once for the entry and filtered for THIS subscriber. */
+  read(): Promise<SnapshotResult>;
+}
+
+/**
+ * The frame a resuming subscriber needs and the cursor it is seated under. The caller has already
+ * established that `cursor` names THIS window: a cursor is client data, and one minted for another
+ * window is a cold start, never a replay of a ring this window does not own.
+ */
+export async function resumeOnto(
+  deps: ResumeOntoDeps,
+  entry: QueryEntry,
+  who: Subscriber,
+  cursor: LiveCursor,
+  now: number,
+): Promise<{ readonly cursor: LiveCursor; readonly frame: Frame }> {
+  const resumed = await resumeFrom(cursor, {
+    source: deps.source,
+    ...(deps.budget ? { budget: deps.budget } : {}),
+    clock: deps.clock,
+    snapshot: () => deps.read(),
+  });
+  if (resumed.kind !== 'delta') {
+    return {
+      cursor: resumed.cursor,
+      frame: snapshotFrame(entry, who.sid, resumed.rows, resumed.cursor),
+    };
+  }
+  // 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 deps.gate.filterPatches(entry, who, resumed.patches, new Set(cursor.ids));
+  // Advanced over the FILTERED list, never over `resumed.cursor` — which `resumeFrom` built
+  // by advancing across the retained window, and that window is PRE-POLICY. Seated as it
+  // came back, this subscriber's `cursor.ids` gained the id of every row inserted for every
+  // OTHER actor while it was away; `subscriber-gate` then reads `held.has(patch.id)` off it,
+  // takes the "the subscriber holds this row" branch, and delivers a `delete` frame carrying
+  // another tenant's row id and the instant it went. The leak that branch closes, re-opened
+  // one layer up. `live-fanout.ts` advances over `allowed` for exactly this reason.
+  const seated = advance(cursor, patches, resumed.cursor.lsn, now);
+  return {
+    cursor: seated,
+    frame: { type: 'patch', v: PROTOCOL_VERSION, sid: who.sid, patches, lsn: seated.lsn },
+  };
+}

package/src/live-tenant.ts

@@ -0,0 +1,25 @@
+// Which tenant a live window belongs to, and the id that keeps two tenants' windows apart.
+//
+// A window is the SHARED, pre-policy read of one `(query, input)`. Shared across every subscriber
+// of one org it is the fan-out the pipeline is built on; shared across two orgs it is one org's
+// rows in a window the other is served from, with a row policy as the only thing in between. So
+// the tenant is part of the window's identity — the same place `@ultimat3/query`'s read cache puts
+// its authority — and the read under it runs in a context that carries that tenant
+// (`live-definition.ts`), which is where `@ultimat3/entity`'s guard takes it from on every surface.
+
+import type { Actor } from '@ultimat3/core';
+
+/** The org a subscriber's windows are read for. `null`: anonymous, or an actor in no org. */
+export function liveTenantOf(actor: Actor | null): string | null {
+  const orgId = actor?.orgId;
+  return typeof orgId === 'string' && orgId !== '' ? orgId : null;
+}
+
+/**
+ * One window's id: the query id, qualified by the tenant it is read for. JSON for the reason
+ * `readAuthority` gives — an org id is app data and may carry any separator, and a value that can
+ * spell a boundary can spell someone else's. An org-less window keeps the bare query id.
+ */
+export function windowId(queryId: string, tenant: string | null): string {
+  return tenant === null ? queryId : JSON.stringify([queryId, tenant]);
+}

package/src/nats-open.ts

@@ -0,0 +1,9 @@
+// The production `NatsConnect`, as a door: the adapter and the `nats` library behind it — 65
+// vendor modules — are imported when a client is OPENED, never when this package is. Every role
+// of every app imports `@ultimat3/realtime/server`; only one configured for the NATS transport
+// ever opens a client.
+
+import type { NatsClient, NatsClientOptions } from './nats-client';
+
+export const openNatsClient = async (options: NatsClientOptions): Promise<NatsClient> =>
+  (await import('./nats-lib-client')).openNatsClient(options);

package/src/nats-transport.ts

@@ -17,7 +17,7 @@ import type { NatsClient, NatsConnect } from './nats-client';
 import { parseNatsUrl } from './nats-client';
 import { ensureKvBucket } from './nats-jetstream';
 import { NatsKvSet } from './nats-kv';
-import { openNatsClient } from './nats-lib-client';
+import { openNatsClient } from './nats-open';
 import { type BackoffPolicy, defaultBackoff, policyDelay, type Rng } from './thundering-herd';
 
 const encoder = new TextEncoder();

package/src/pg-entity-row.ts

@@ -6,8 +6,12 @@
 // pair folded into money by name. So a nullable money column diverged from the repository shape,
 // two plain columns that happened to be called `x_minor`/`x_currency` were folded into a `Money`,
 // and a `.column()` rename arrived under its physical name. One decoder, the entity's, now.
+//
+// A SEALED column is the one place a live row is not the repository's: the log carries the stored
+// string, and nothing here opens it. It is dropped, so a change — on the bus, in the ring, in a
+// patch frame — names no sealed column at all.
 
-import { decodeRow, entityForTable } from '@ultimat3/entity';
+import { decodeRow, entityForTable, sealedFields } from '@ultimat3/entity';
 import { ReplicationProtocolError } from './errors';
 import type { PhysicalRow } from './pg-values';
 import type { PgRelation } from './pgoutput';
@@ -47,5 +51,10 @@ export function entityRow(
     });
   }
   const source = image === 'before' ? replicatedOnly(relation, physical) : physical;
-  return decodeRow(entity, source) as PhysicalRow;
+  const row = decodeRow(entity, source) as PhysicalRow;
+  // Not opened and not forwarded. A client never receives a sealed column on any other path, so
+  // a patch carrying one would be the only frame that does — and a `lookup` column's stored string
+  // is the same for equal plaintexts, which tells every subscriber which rows share a value.
+  for (const field of sealedFields(entity)) delete row[field.property];
+  return row;
 }

package/src/query-window.ts

@@ -30,6 +30,11 @@ export interface QueryEntry {
   readonly qid: string;
   readonly definition: LiveQueryDefinition;
   readonly input: JsonValue;
+  /**
+   * The org this window is read for and patched for — its subscribers' own, `null` for subscribers
+   * that carry none. Part of `qid`, so two orgs on one `(query, input)` are two entries.
+   */
+  readonly tenant: string | null;
   /** Told to the client on every snapshot: the identity scope its rows belong under. */
   readonly rowEntity: string | null;
   /** The record key a row travels under; `null` = its `id` (a plain table). */
@@ -80,12 +85,14 @@ export function createEntry(
   definition: LiveQueryDefinition,
   input: JsonValue,
   matcher: IncrementalMatcher,
-  options?: EntryOptions,
+  options?: EntryOptions & { readonly tenant?: string | null },
 ): QueryEntry {
+  const tenant = options?.tenant ?? null;
   return {
     qid,
     definition,
     input,
+    tenant,
     // Resolved with the matcher, from the same build: `prepare` has already run, so a definition
     // that compiles its shape per input can answer.
     rowEntity: definition.rowEntity?.(input) ?? null,
@@ -96,7 +103,9 @@ export function createEntry(
       // 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),
+      // The window's own tenant first: a change in another org is dropped before any predicate
+      // runs, whether or not the query's `where` happens to name one.
+      orgId: tenant ?? orgIdOf(input),
       ...(definition.columns ? { columns: definition.columns } : {}),
     },
     matcher,
@@ -253,7 +262,7 @@ function startRead(entry: QueryEntry): PendingRead {
  */
 async function readSnapshot(entry: QueryEntry): Promise<SnapshotResult> {
   try {
-    return await entry.definition.snapshot({ input: entry.input });
+    return await entry.definition.snapshot({ input: entry.input, tenant: entry.tenant });
   } catch (error) {
     entry.stale = true;
     throw error;

package/src/server.ts

@@ -111,7 +111,7 @@ export {
   kvWrite,
 } from './nats-jetstream';
 export { decodeToken, encodeToken, NatsKvSet, type NatsKvSetOptions } from './nats-kv';
-export { openNatsClient } from './nats-lib-client';
+export { openNatsClient } from './nats-open';
 export { NatsTransport, type NatsTransportOptions } from './nats-transport';
 export { PgAdvisoryLock, type PgAdvisoryLockOptions } from './pg-advisory-lock';
 // ---- the postgres replication path ------------------------------------------------------------