@rindle/optimistic 0.5.0 → 0.6.3

package/src/client-id.ts

@@ -1,3 +1,5 @@
+import type { TicketPersistence } from "@rindle/remote";
+
 // The connection's stable clientID — kept in its own (wasm-free) module so it can be unit-tested
 // without pulling the engine in. A per-ORIGIN base (localStorage) shared by every tab and kept
 // across reloads, a per-TAB suffix (sessionStorage) that survives a reload within a tab but is
@@ -10,6 +12,12 @@
 const CLIENT_ID_KEY = "rindle-client-id";
 /** The per-TAB suffix (sessionStorage): survives a reload within a tab but is distinct per tab. */
 const TAB_ID_KEY = "rindle-tab-id";
+/** The per-TAB follower-affinity ticket (sessionStorage): kept across a reload WITHIN a tab (so a
+ *  reload lands back on the same follower — monotone reads survive it, FOLLOWER-AFFINITY-DESIGN.md
+ *  §8), but DISTINCT per tab so two tabs can pin two regions (design §13; a shared localStorage
+ *  ticket would force both onto one follower). The ticket is opaque and short-lived — the follower
+ *  re-mints one on every connect — so losing it (no sessionStorage) merely re-anycasts. */
+const AFFINITY_TICKET_KEY = "rindle-affinity-ticket";
 
 /** Read-or-mint a value in a web Storage area, tolerating its absence (SSR, privacy mode). Returns
  *  `undefined` when the area is unavailable so the caller can pick a fallback. */
@@ -55,6 +63,42 @@ export function resetStableClientID(): void {
   tabInstance = 0;
 }
 
+/** A sessionStorage-backed {@link TicketPersistence} for the affinity ticket — per-tab, survives a
+ *  reload (see {@link AFFINITY_TICKET_KEY}). Every access tolerates web storage being absent (SSR,
+ *  private mode): the store then behaves as pure in-memory, re-anycasting on each fresh load. */
+export function sessionTicketPersistence(): TicketPersistence {
+  const area = () => {
+    try {
+      return (globalThis as unknown as Record<string, Storage | undefined>).sessionStorage;
+    } catch {
+      return undefined;
+    }
+  };
+  return {
+    load: () => {
+      try {
+        return area()?.getItem(AFFINITY_TICKET_KEY) ?? undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    save: (ticket) => {
+      try {
+        area()?.setItem(AFFINITY_TICKET_KEY, ticket);
+      } catch {
+        // Best-effort persistence; a full/blocked store just means we re-anycast on the next load.
+      }
+    },
+    clear: () => {
+      try {
+        area()?.removeItem(AFFINITY_TICKET_KEY);
+      } catch {
+        // Best-effort.
+      }
+    },
+  };
+}
+
 /** The connection's stable clientID. A per-origin base (localStorage) keeps one logical identity
  *  across reloads; a per-tab suffix (sessionStorage) gives each tab its OWN mid/lmid stream; a
  *  per-load instance suffix keeps two clients constructed in ONE tab from sharing that stream. Falls

package/src/client.ts

@@ -24,15 +24,16 @@ import type {
 import {
   RemoteOptimisticSource,
   WsTransport,
+  createAffinityTicketStore,
   createQueuedMutationSender,
+  offerSubprotocols,
 } from "@rindle/remote";
-import type { PushOutcome, RemoteOptimisticConnection, Transport } from "@rindle/remote";
+import type { AffinityTicketStore, PushOutcome, RemoteOptimisticConnection, Transport } from "@rindle/remote";
 import { initWasm } from "@rindle/wasm";
-import type { WritableDescriptor } from "@rindle/wasm";
 
 import type { OptimisticBackend } from "./backend.ts";
 import type { ClientRegistry, MutationTx } from "./backend.ts";
-import { resetStableClientID, stableClientID } from "./client-id.ts";
+import { resetStableClientID, sessionTicketPersistence, stableClientID } from "./client-id.ts";
 import {
   LIFECYCLE_QUERY_NAME,
   ROOM_CLIENT_MUTATIONS_TABLE,
@@ -157,7 +158,13 @@ export type RealtimeAnomalyKind =
   | "source-key-changed"
   /** The lease POST failed or the room attach threw. The initial-materialize case fails OPEN to
    *  the daemon path (indistinguishable from an unlabeled query's recovery). */
-  | "lease-failed";
+  | "lease-failed"
+  /** 302 §6.1: a view swapping onto a room still references tables the room does NOT own — those
+   *  refs keep reading the plain DAEMON tables (the client-side join across kinds), and the
+   *  room's relayed copies are dropped by design (§6), so the joined rows render only if a
+   *  daemon subscription covers them. Unverifiable client-side — surfaced once per view so a
+   *  silently-empty join is a named condition, not a mystery. */
+  | "context-coverage";
 
 /** A loud realtime lease anomaly (always ALSO `console.error`'d). */
 export interface RealtimeAnomaly {
@@ -170,6 +177,15 @@ export interface RealtimeAnomaly {
 /** Rindle Realtime client knobs (Slice G-v). All optional — an app with no labeled queries never
  *  touches any of this. */
 export interface RealtimeClientOptions {
+  /** The DECLARED room mutators (302 §5: declared, not derived). A mutator named here routes to
+   *  the attached room — it stages onto the room's own tables and ships on the room socket —
+   *  whenever exactly ONE room is attached; solo (no room) it takes the ordinary daemon path,
+   *  and with several rooms attached it routes daemon too (explicit multi-room binding is a
+   *  later slice). Every mutator NOT named here is a daemon mutator. A misdeclaration fails
+   *  SOFT (302 §5.1): the write lands on the other authority's tables, so the view just stops
+   *  feeling instant until the echo relays it — never a divergence. An explicit top-level
+   *  `domainPolicy` overrides this entirely. */
+  mutators?: readonly string[];
   /** Build the ROOM ws transport for a lease's `realtime.wsEndpoint`. Default
    *  `(endpoint) => new WsTransport(endpoint)`. Injectable for tests / custom ws impls. */
   transport?: (endpoint: string) => Transport;
@@ -189,11 +205,10 @@ export interface RealtimeInspect {
     string,
     {
       wsEndpoint: string;
-      /** Promoted table → the lease's `joinKeyCols` ("room mutators never change join keys", the
-       *  §3 write proof's rule #3) — read back from the BACKEND's routing table (H-iii:
-       *  `backend.roomTablesFor`, the one source of truth; the client keeps no shadow copy), and
-       *  deliberately never crossing the wasm `WritableDescriptor` ABI. Shape unchanged since G-v. */
-      promoted: Record<string, string[]>;
+      /** The room's OWNED tables (302 §2): wire table → its namespaced engine table — read back
+       *  from the BACKEND's registry (`backend.roomTablesFor`, the one source of truth; the
+       *  client keeps no shadow copy). */
+      promoted: Record<string, string>;
       /** Live room-retained queries on this room, by remote key. */
       queries: Record<string, { name: string; sourceQid: QueryId; exp: number; refCount: number }>;
     }
@@ -209,6 +224,11 @@ const RENEW_RETRY_MS = 5_000;
 /** A one-shot token handoff not consumed within this window is stale — the resolver falls through
  *  to a fresh lease POST instead of presenting a token the server may already refuse. */
 const HANDOFF_MAX_AGE_MS = 15_000;
+/** How long a fresh (ticketless) connect waits for its affinity mint frame before leasing
+ *  TICKETLESS + warning (FOLLOWER-AFFINITY-DESIGN.md §4.1). Generous — the frame normally arrives in
+ *  well under one RTT; this bound only trips on an affinity-off daemon (misconfig / rolling upgrade),
+ *  so it degrades loudly instead of hanging. */
+const AFFINITY_TICKET_TIMEOUT_MS = 4_000;
 /** Client-minted remote-retain qids live in their own high band so they can never collide with the
  *  Store's own 1, 2, 3, … view qids or the reserved per-channel lmid qid 0. Exact in f64 (the wire
  *  number type), far below 2^53. */
@@ -236,8 +256,14 @@ export interface RindleClientOptions<S extends ColsMap, R extends ClientRegistry
    *    different follower migrates the connection there.
    *  - `{ wsUrl }` omitted — pure-lazy: the first lease's `wsEndpoint` opens the connection (a
    *    routed SPA with no SSR bootstrap).
-   *  - `{ transport }` — a pre-built transport (tests / in-process); fixed, no migration. */
-  daemon: { wsUrl?: string } | { transport: Transport };
+   *  - `{ transport }` — a pre-built transport (tests / in-process); fixed, no migration.
+   *
+   *  Set `affinity: true` (with `wsUrl` pointing at the fleet host, `app-<id>.rindle.cloud`) to run
+   *  FOLLOWER-AFFINITY mode (design §2): the ws offers a placement ticket as a subprotocol, the
+   *  client persists the follower's minted ticket (per-tab) and forwards it on the lease POST so both
+   *  legs pin the same nearby follower — sticky, regional, monotone reads. Off (default) is today's
+   *  single-daemon behavior, byte-identical. Ignored for a pre-built `{ transport }`. */
+  daemon: { wsUrl?: string; affinity?: boolean } | { transport: Transport };
   /** Stable client identity. Default: a per-origin base (localStorage) plus per-tab and per-instance
    *  suffixes, so each tab — and each client instance within a tab — gets its own mid sequence yet a
    *  reload keeps it; falls back to a fresh random id when web storage is unavailable. Pass a value
@@ -316,11 +342,51 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
     return text ? JSON.parse(text) : undefined;
   };
 
+  // FOLLOWER-AFFINITY mode (design §2): opt-in, and only for a fleet `wsUrl` connection (a pre-built
+  // transport has no fleet edge to route through). The store is shared by the ws transport (offers
+  // the ticket as a subprotocol), the source (records the follower's minted ticket / clears it on a
+  // dead follower), and the lease POST below (forwards it). Persisted per-TAB (sessionStorage) so two
+  // tabs can pin two regions (design §13) yet a reload lands back on the same follower.
+  const affinityOn = !("transport" in opts.daemon) && opts.daemon.affinity === true;
+  const affinityStore: AffinityTicketStore | undefined = affinityOn
+    ? createAffinityTicketStore(sessionTicketPersistence())
+    : undefined;
+
   // The ONE app-lease POST both legs share. Sends the stable `clientId` so the api-server/router
   // can use it as the anonymous routing key (READ-ROUTER-DESIGN.md §2.2); the reply's top-level
   // fields are the daemon lease, and a room-served labeled query ADDITIONALLY carries `realtime`.
-  const postLease = (remote: RemoteQuery): Promise<QueryLeaseWire> =>
-    post(routes.query, { name: remote.name, args: remote.args, clientId: clientID }) as Promise<QueryLeaseWire>;
+  // In affinity mode it ALSO forwards the placement `affinity` ticket — awaited first so a fresh
+  // (ticketless) connect leases only AFTER its mint frame arrives, co-locating both legs (§4.1). On
+  // reconnect, the WebSocket may offer the persisted ticket on its handshake, but the lease waits
+  // for that connection's fresh mint frame. The wait is BOUNDED: if no mint frame arrives (the daemon is
+  // affinity-off — a misconfig, or mid rolling-upgrade), we lease
+  // TICKETLESS and warn rather than hang. That first timeout LATCHES ticketless mode in the store:
+  // later leases return immediately (and do not accumulate abandoned waiters) until an affinity
+  // frame actually arrives. A persisted ticket remains useful for the ws handshake but is never
+  // forwarded on a lease until the CURRENT connection refreshes it, preventing a restored stale
+  // ticket from independently re-pinning the HTTP and ws legs.
+  let affinityFallbackWarned = false;
+  const postLease = async (remote: RemoteQuery): Promise<QueryLeaseWire> => {
+    let affinity: string | undefined;
+    if (affinityStore) {
+      const ticket = await affinityStore.leaseTicket(AFFINITY_TICKET_TIMEOUT_MS);
+      affinity = ticket.ticket;
+      if (affinity !== undefined) affinityFallbackWarned = false;
+      if (ticket.timedOut && !affinityFallbackWarned) {
+        affinityFallbackWarned = true;
+        console.warn(
+          `[rindle] no affinity ticket after ${AFFINITY_TICKET_TIMEOUT_MS}ms — leasing ticketless ` +
+            "(is the daemon affinity-enabled / RINDLE_AFFINITY_KEY set?)",
+        );
+      }
+    }
+    return post(routes.query, {
+      name: remote.name,
+      args: remote.args,
+      clientId: clientID,
+      ...(affinity !== undefined ? { affinity } : {}),
+    }) as Promise<QueryLeaseWire>;
+  };
 
   // One-shot fresh-token handoffs, by remote key: G-v's resolve-then-register (and the proactive
   // renewal) has ALREADY leased when the subscribe fires, so the resolver consumes the handed
@@ -359,12 +425,22 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
 
   // Reads-leg connection: a fixed transport (tests/in-process) or a replaceable connection built
   // from `wsUrl` (eager when present, lazy when omitted). A routed lease's `wsEndpoint` migrates it.
+  // In affinity mode each transport offers the current ticket as a subprotocol (evaluated per
+  // connect, so a reconnect presents the freshest — or freshly cleared — ticket).
   const connection: RemoteOptimisticConnection =
     "transport" in opts.daemon
       ? { transport: opts.daemon.transport }
-      : { factory: (endpoint) => new WsTransport(endpoint), endpoint: opts.daemon.wsUrl };
+      : {
+          factory: (endpoint) =>
+            new WsTransport(
+              endpoint,
+              affinityStore ? { subprotocols: () => offerSubprotocols(affinityStore) } : {},
+            ),
+          endpoint: opts.daemon.wsUrl,
+        };
 
   const source = new RemoteOptimisticSource(connection, clientID, {
+    ...(affinityStore ? { affinity: affinityStore } : {}),
     resolveSubscribe: async ({ remote }) => {
       // A fail-open labeled register already leased — present exactly that token (see
       // `tokenHandoffs`); otherwise lease now. Read back the follower's `wsEndpoint` for placement.
@@ -401,7 +477,14 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
   const { store, backend, mutate } = createOptimisticStore(opts.schema, source, opts.mutators, {
     clientID,
     user: opts.user,
-    ...(opts.domainPolicy ? { domainPolicy: opts.domainPolicy } : {}),
+    // The DECLARED router (302 §5): an explicit `domainPolicy` wins; otherwise the app's declared
+    // realtime mutators route to the one attached room (`rooms` is read lazily at invoke time —
+    // it is declared below, after this construction).
+    ...(opts.domainPolicy
+      ? { domainPolicy: opts.domainPolicy }
+      : opts.realtime?.mutators !== undefined
+        ? { domainPolicy: declaredMutatorPolicy(new Set(opts.realtime.mutators), () => rooms) }
+        : {}),
     // Room-plane rejection parity (H-v): a room's `mutationOutcome {kind:"rejected"}` frame
     // surfaces through the SAME callback the HTTP mutate path uses below — one app-level
     // rejection surface, whichever authority said no.
@@ -434,9 +517,9 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
   };
 
   /** One connected room: its gate key + its `RemoteOptimisticSource`. The promoted-table
-   *  bookkeeping that used to live here (G-v's `promoted` map) is DELEGATED to the backend's
-   *  routing table since H-iii (`backend.roomTablesFor(sourceKey)` — one source of truth for the
-   *  §3 router, the idempotence check, and `__realtimeInspect`). */
+   *  bookkeeping lives in the backend's 302 roomTables record (`backend.roomTablesFor(sourceKey)`
+   *  — the wire→namespaced-twin rename map; one source of truth for the gate's rename/DROP, the
+   *  idempotence check, and `__realtimeInspect`). */
   interface RoomConnection {
     sourceKey: string;
     wsEndpoint: string;
@@ -541,26 +624,21 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
     claims.clear();
   };
 
-  /** Promote every lease table spec this client can hold, exactly once per (sourceKey, table) —
-   *  re-leases (renewal / reconnect) must never re-promote (the engine refuses a duplicate room);
-   *  the idempotence check reads the BACKEND's routing record (the one source of truth since
-   *  H-iii). A footprint table absent from the client schema has nothing to promote (the client
-   *  never materializes rows for it) and is skipped. The lease spec's routing half —
-   *  `joinKeyCols`, the row-local writable `where`, and `footprintWhere` (H-iii) — threads through
-   *  as the backend's per-(sourceKey, table) `RoomTableRouting` record, the §3 router's input;
-   *  none of it crosses the wasm `WritableDescriptor` ABI. */
+  /** Register the room's OWNED tables (302 §2 — one source per table): every lease table spec
+   *  whose `writable` kind is not `"none"` names a table the room owns; the backend registers a
+   *  namespaced engine twin the room channel feeds and the room-homed views swap onto. Context
+   *  tables (`kind: "none"`) are deliberately NOT registered — the daemon is their sole
+   *  authority, and the gate DROPS the room's relayed copies (302 §6). Idempotent per
+   *  (sourceKey, table) — the backend's record is the one source of truth; a footprint table
+   *  absent from the client schema has nothing to hold rows for and is skipped backend-side. */
   const promoteRoomTables = (room: RoomConnection, specs: RealtimeLeaseTableSpec[]): void => {
-    for (const spec of specs) {
-      if (backend.roomTablesFor(room.sourceKey).has(spec.table)) continue;
-      if (!(spec.table in opts.schema.tables)) continue;
-      backend.promoteRoomTable(spec.table, room.sourceKey, toWritableDescriptor(spec), {
-        joinKeyCols: spec.writable.kind === "predicate" ? spec.writable.joinKeyCols : [],
-        ...(spec.writable.kind === "predicate" && spec.writable.where !== undefined
-          ? { where: spec.writable.where }
-          : {}),
-        ...(spec.footprintWhere !== undefined ? { footprintWhere: spec.footprintWhere } : {}),
-      });
-    }
+    const owned = specs.filter((s) => s.writable.kind !== "none").map((s) => s.table);
+    // ALWAYS register — even an all-context lease's `owned = []`: the installed (empty) map is
+    // what makes the room gate DROP every relayed delta (302 §6). Skipping the call would leave
+    // `gate.tableMap` undefined — the DAEMON identity path — and fold the room's relayed copies
+    // of daemon-authoritative rows verbatim into the plain tables, two syncs fighting over one
+    // baseline (stale overwrites + dueling GC removes).
+    backend.registerRoomTables(room.sourceKey, owned);
   };
 
   /** (Re)arm a room query's proactive renewal from its current `exp`. Timers are unref'd (Node)
@@ -940,6 +1018,18 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
     );
   });
 
+  // The 302 §6.1 context-coverage surface: a room-homed view's non-owned refs stay daemon-served
+  // after the swap (the gate drops the room's relayed copies by design) — whether a daemon
+  // subscription covers those rows is unknowable here, so name the condition loudly once per
+  // view instead of letting the join render silently empty.
+  backend.onRoomContextJoin(({ sourceKey, name, args, tables }) => {
+    anomaly(
+      "context-coverage",
+      { name, args },
+      `after swapping onto room ${JSON.stringify(sourceKey)}, table(s) ${tables.join(", ")} stay daemon-served (the room does not own them) — ensure a daemon subscription covers the joined rows, or the join renders empty for the room session (302 §6.1)`,
+    );
+  });
+
   // The split-register ticket: set (synchronously) by the wrapped `materialize` just before it
   // delegates, consumed by the shadowed `backend.registerQuery` below — which registers the LOCAL
   // half only (the Store's SSR-seed + `unknown` pre-marking has already run) and defers the remote
@@ -1214,11 +1304,8 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
           sourceKey,
           {
             wsEndpoint: room.wsEndpoint,
-            // Read back from the backend's routing table (H-iii) — shape-compatible with G-v's
-            // client-held map (table → joinKeyCols).
-            promoted: Object.fromEntries(
-              [...backend.roomTablesFor(sourceKey)].map(([t, spec]) => [t, [...spec.joinKeyCols]]),
-            ),
+            // Read back from the backend's room-table registry (302 §2): wire → engine table.
+            promoted: Object.fromEntries(backend.roomTablesFor(sourceKey)),
             queries: Object.fromEntries(
               [...roomQueries]
                 .filter(([, s]) => s.sourceKey === sourceKey)
@@ -1243,16 +1330,20 @@ interface MaterializedViewLike {
   destroy(): void;
 }
 
-/** Map a lease `RoomTableSpec.writable` onto the wasm engine's {@link WritableDescriptor}. An
- *  absent `where` on the predicate arm means NO row-local constraint — every row the room holds
- *  for the table is in the writable scope (the spec contract) — i.e. the engine's `all` arm. The
- *  spec's `joinKeyCols`/`footprintWhere` deliberately do NOT cross this boundary — they live in
- *  the backend's per-(sourceKey, table) routing record (H-iii, `backend.roomTablesFor`). */
-function toWritableDescriptor(spec: RealtimeLeaseTableSpec): WritableDescriptor {
-  if (spec.writable.kind === "none") return { kind: "none" };
-  return spec.writable.where === undefined
-    ? { kind: "all" }
-    : { kind: "predicate", where: spec.writable.where };
+/** The default DECLARED router (302 §5) when the app names `realtime.mutators` and passes no
+ *  explicit `domainPolicy`: a declared mutator routes to the ONE attached room; solo or
+ *  multi-room it abstains (⇒ daemon). `getRooms` is read lazily per invoke so the policy tracks
+ *  attach/downgrade live. */
+function declaredMutatorPolicy(
+  declared: ReadonlySet<string>,
+  getRooms: () => ReadonlyMap<string, unknown>,
+): (name: string, args: unknown) => string | undefined {
+  return (name) => {
+    if (!declared.has(name)) return undefined;
+    const rooms = getRooms();
+    if (rooms.size !== 1) return undefined; // solo or ambiguous — the daemon path (302 §5)
+    return rooms.keys().next().value as string;
+  };
 }
 
 /** Flip a just-materialized labeled view back to `unknown` for the lease-resolve window. The

package/src/index.ts

@@ -41,10 +41,7 @@ export type {
   ReadOutcome,
   ReadRecord,
   ResultType,
-  RoomTableRouting,
-  RoomTableRoutingSpec,
-  RoutingFailureReason,
-  RoutingInspect,
+  RoomContextJoinEvent,
   ScopeSessionsEvent,
   SystemStreamSpec,
   SystemStreamTable,
@@ -62,7 +59,11 @@ export {
   roomDomainKey,
   SCOPE_SESSIONS_TABLE,
 } from "./system-streams.ts";
-export type { MutationEnvelope, OptimisticSource, ProgressFrame } from "@rindle/client";
+export type {
+  MutationEnvelope,
+  OptimisticSource,
+  ProgressFrame,
+} from "@rindle/client";
 // The shared (generator) mutator seam — a registry may hold plain client mutators OR these isomorphic
 // generators (the SAME body the API server runs); re-exported here so an app registers from one import.
 export { isoTx } from "@rindle/client";