@rindle/client 0.4.3 → 0.5.0

package/src/query.ts

@@ -83,6 +83,10 @@ interface QueryBase<C extends AnyCols, Rels, One extends boolean, Sel extends st
   readonly name?: string;
   /** Present when this local query came from `defineQuery`; sent with `name` upstream. */
   readonly args?: unknown;
+  /** Present when this local query came from a realtime-labeled `defineQuery`
+   *  (RINDLE-REALTIME-QUERY-ENABLEMENT §2.1). Declaration metadata only — it never joins the
+   *  wire identity and never changes the AST. */
+  readonly realtime?: RealtimeQueryLabel;
   /** Condition form — consumes `or()`/`and()`/`exists()`/field conditions (AND-ed across calls).
    *  Filters over the FULL column set (`RowOf<C>`), independent of what's `select`ed/masked. */
   where(cond: Cond<RowOf<C>>): Query<C, Rels, One, Sel, LocalRels>;
@@ -314,15 +318,20 @@ export type QueryLocalData<Q extends AnyQuery> =
 const STAMP_NAMED_QUERY: unique symbol = Symbol("rindle.stampNamedQuery");
 
 interface QueryInternals {
-  [STAMP_NAMED_QUERY](name: string, args: unknown): unknown;
+  [STAMP_NAMED_QUERY](name: string, args: unknown, realtime?: RealtimeQueryLabel): unknown;
 }
 
-function stampNamedQuery<Q extends AnyQuery>(query: Q, name: string, args: unknown): Q {
+function stampNamedQuery<Q extends AnyQuery>(
+  query: Q,
+  name: string,
+  args: unknown,
+  realtime?: RealtimeQueryLabel,
+): Q {
   const stamp = (query as unknown as QueryInternals)[STAMP_NAMED_QUERY];
   if (typeof stamp !== "function") {
     throw new Error("defineQuery's build must return a Query built by newQueryBuilder/queries");
   }
-  return stamp(name, args) as Q;
+  return stamp(name, args, realtime) as Q;
 }
 
 /** Turn raw, UNTRUSTED wire args into the canonical, typed args a query is built from. Its return
@@ -351,6 +360,56 @@ export type QueryBuilder<Args, Q extends AnyQuery, Ctx extends readonly unknown[
   ...ctx: Ctx
 ) => Q;
 
+/**
+ * The realtime LABEL a named query may declare (RINDLE-REALTIME-QUERY-ENABLEMENT-DESIGN.md §2.1):
+ * which api-server room PROFILE the query wants to be served from, and how the query's args map
+ * to that profile's key args. This is the DECLARATION only — the serve decision (covering proof,
+ * lease routing) is the server's, and the final room key is minted server-side by the profile's
+ * own `key` under authoritative ctx, so a label can never place a query in a room the server
+ * didn't derive itself. Both tiers import the SAME `defineQuery` value, so they always agree
+ * *which profile* a query belongs to.
+ */
+export interface RealtimeQueryLabel<Args = any> {
+  /** The room profile name — must match a `realtime.rooms` key on the api-server (validated
+   *  loudly at `createRindleApiServer` construction). May not contain `/` (the wire room-key
+   *  delimiter). */
+  readonly room: string;
+  /** Map the query's VALIDATED args to the profile's key args (what the server feeds the
+   *  profile's `key(args)`). Identity when omitted. Must be pure — both tiers may run it. */
+  readonly args?: (queryArgs: Args) => unknown;
+}
+
+/** Options for {@link defineQuery}. */
+export interface DefineQueryOptions<Args = any> {
+  /** Declare this query realtime-eligible — see {@link RealtimeQueryLabel}. */
+  realtime?: RealtimeQueryLabel<Args>;
+}
+
+/** Loud, definition-time validation of a realtime label — a malformed label is a config bug the
+ *  author should hit at module load, not a query that silently never room-serves. */
+function validateRealtimeLabel(
+  name: string,
+  label: RealtimeQueryLabel<any> | undefined,
+): RealtimeQueryLabel<any> | undefined {
+  if (label === undefined) return undefined;
+  if (typeof label.room !== "string" || label.room.length === 0) {
+    throw new Error(`defineQuery("${name}"): realtime.room must be a non-empty room-profile name.`);
+  }
+  if (label.room.includes("/")) {
+    throw new Error(
+      `defineQuery("${name}"): realtime.room "${label.room}" may not contain "/" — it delimits the ` +
+        `wire room key ("<profile>/<key>").`,
+    );
+  }
+  if (label.args !== undefined && typeof label.args !== "function") {
+    throw new Error(
+      `defineQuery("${name}"): realtime.args must be a function mapping the query's args to the ` +
+        `profile's key args (or omitted for identity).`,
+    );
+  }
+  return label;
+}
+
 /**
  * A single, co-located NAMED query (see {@link defineQuery}). It is:
  *   - **callable on the client** — `q(args, ctx?)` validates + builds + stamps the result with its
@@ -368,6 +427,10 @@ export interface NamedQuery<Args, Ctx extends readonly unknown[], Q extends AnyQ
   /** The wire identity. The daemon leases by this name; client and server MUST agree on it — which
    *  they do, because both sides import the SAME `defineQuery` value. */
   readonly queryName: string;
+  /** The §2.1 realtime label, when this query was defined with one ({@link DefineQueryOptions}).
+   *  Absent on unlabeled queries. Carried onto the stamped built Query too, and preserved through
+   *  `registerQueries` on the server. */
+  readonly realtime?: RealtimeQueryLabel<Args>;
   /** Server-side: validate raw wire args, then build the authoritative `Query` from the server's
    *  authoritative ctx (forwarded by `registerQueries`). */
   resolve(rawArgs: unknown, ...ctx: Ctx): Q;
@@ -406,29 +469,43 @@ export interface NamedQuery<Args, Ctx extends readonly unknown[], Q extends AnyQ
  * // client: myIssuesQuery({ limit: 20 }, { user: currentUser() })
  * ```
  */
-export function defineQuery<Q extends AnyQuery>(name: string, build: () => Q): NamedQuery<void, [], Q>;
+export function defineQuery<Q extends AnyQuery>(
+  name: string,
+  build: () => Q,
+  options?: DefineQueryOptions<void>,
+): NamedQuery<void, [], Q>;
 export function defineQuery<Args, Ctx extends readonly unknown[], Q extends AnyQuery>(
   name: string,
   build: (args: Args, ...ctx: Ctx) => Q,
+  options?: DefineQueryOptions<Args>,
 ): NamedQuery<Args, Ctx, Q>;
 export function defineQuery<Args, Ctx extends readonly unknown[], Q extends AnyQuery>(
   name: string,
   validate: QueryValidator<Args>,
   build: (args: Args, ...ctx: Ctx) => Q,
+  options?: DefineQueryOptions<Args>,
 ): NamedQuery<Args, Ctx, Q>;
 export function defineQuery(
   name: string,
   validateOrBuild: (...a: any[]) => any,
-  maybeBuild?: (...a: any[]) => any,
+  maybeBuildOrOptions?: ((...a: any[]) => any) | DefineQueryOptions<any>,
+  maybeOptions?: DefineQueryOptions<any>,
 ): NamedQuery<any, any, AnyQuery> {
-  const hasValidator = maybeBuild !== undefined;
+  const hasValidator = typeof maybeBuildOrOptions === "function";
   const validate = (hasValidator ? validateOrBuild : (raw: unknown) => raw) as (raw: unknown) => unknown;
-  const build = (hasValidator ? maybeBuild : validateOrBuild) as (args: unknown, ...ctx: unknown[]) => AnyQuery;
+  const build = (hasValidator ? maybeBuildOrOptions : validateOrBuild) as (args: unknown, ...ctx: unknown[]) => AnyQuery;
+  const options = hasValidator ? maybeOptions : (maybeBuildOrOptions as DefineQueryOptions<any> | undefined);
+  // §2.1 realtime label — pure declaration metadata, validated loudly at definition time.
+  const realtime = validateRealtimeLabel(name, options?.realtime);
   const resolve = (rawArgs: unknown, ...ctx: unknown[]): AnyQuery => build(validate(rawArgs), ...ctx);
   // The wire identity is (name, args) ONLY — ctx is never stamped, so it never crosses the wire.
+  // The realtime label rides the stamp as metadata beside the identity, never inside it.
   const call = (args: unknown, ...ctx: unknown[]): AnyQuery =>
-    stampNamedQuery(build(validate(args), ...ctx), name, args ?? null);
-  return Object.assign(call, { queryName: name, resolve }) as NamedQuery<any, any, AnyQuery>;
+    stampNamedQuery(build(validate(args), ...ctx), name, args ?? null, realtime);
+  return Object.assign(
+    call,
+    realtime === undefined ? { queryName: name, resolve } : { queryName: name, resolve, realtime },
+  ) as NamedQuery<any, any, AnyQuery>;
 }
 
 // ----------------------------- fragments (FRAGMENT-COMPOSITION-DESIGN.md, Phase 0) -----------------------------
@@ -708,6 +785,8 @@ interface State {
 interface NamedQueryState {
   name: string;
   args: unknown;
+  /** The §2.1 realtime label (metadata only — never part of the wire identity). */
+  realtime?: RealtimeQueryLabel;
 }
 
 function emptyState(table: string): State {
@@ -965,6 +1044,7 @@ function makeQuery(
   const base: Record<string, unknown> = {
     name: named?.name,
     args: named?.args,
+    realtime: named?.realtime,
     where: (cond: Condition) => next({ wheres: [...s.wheres, cond] }),
     orderBy: (col: string, dir: Dir) => next({ orderBy: [...s.orderBy, [col, dir]] }),
     select: (...cols: string[]) => next({ select: [...(s.select ?? []), ...cols] }),
@@ -1075,7 +1155,8 @@ function makeQuery(
     get(target, prop) {
       if (prop === "where") return whereProxy;
       if (prop === STAMP_NAMED_QUERY)
-        return (name: string, args: unknown) => makeQuery(meta, s, onMat, { name, args }, guardAst);
+        return (name: string, args: unknown, realtime?: RealtimeQueryLabel) =>
+          makeQuery(meta, s, onMat, { name, args, realtime }, guardAst);
       if (typeof prop === "string" && prop.length > 5 && prop.startsWith("where")) {
         const field = prop[5].toLowerCase() + prop.slice(6);
         return (arg: unknown) => applyField(field, arg);

package/src/schema.ts

@@ -63,16 +63,25 @@ export interface TableMeta<N extends string = string, C extends AnyCols = AnyCol
   /** A **local-only** table (`201-LOCAL-ONLY-TABLES-DESIGN.md`): client-authoritative,
    *  never synced/tracked/rebased. The single marker the whole design keys off (§4) — it is
    *  immutable for the table's lifetime (N2) and never crosses the wire (C2). Absent ⇒ an
-   *  ordinary synced table. */
-  readonly local?: boolean;
+   *  ordinary synced table.
+   *
+   *  `true` ⇒ eligible for the local-persistence plane (durable + cross-tab when the client
+   *  enables `persistLocal`, `207-LOCAL-TABLE-PERSISTENCE-DESIGN.md`). `"session"` ⇒ local but
+   *  EPHEMERAL: outside the plane entirely — never persisted, never replicated across tabs,
+   *  per-client-instance state that empties on reload (201's original behavior) even when
+   *  `persistLocal` is on. Every OTHER locality rule (untracked source, M1/M2 guards, E3/Q1
+   *  wire exclusion) treats both variants identically. */
+  readonly local?: boolean | "session";
 }
 
 /** Options for {@link table}. */
 export interface TableOptions {
   /** Declare a {@link TableMeta.local local-only} table (selection state, draft text, view
    *  prefs, scratch rows): client-authoritative, never synced or rebased. See
-   *  `201-LOCAL-ONLY-TABLES-DESIGN.md`. */
-  local?: boolean;
+   *  `201-LOCAL-ONLY-TABLES-DESIGN.md`. Pass `"session"` for a local table that must stay
+   *  EPHEMERAL and per-tab even when the client enables `persistLocal` — e.g. selection state
+   *  that should not follow the user across tabs or reloads (207 §5.4). */
+  local?: boolean | "session";
 }
 
 export type TableDef<N extends string, C extends AnyCols, PK extends string = string> = {
@@ -235,7 +244,7 @@ export function extendSchema<S extends ColsMap, P extends Record<string, string>
   const tables: Record<string, TableMeta> = { ...base.tables };
   for (const t of opts.tables) {
     const m = t[SCHEMA];
-    if (m.local !== true) {
+    if (!m.local) {
       throw new Error(
         `extendSchema: table "${m.name}" is not local-only — synced tables must be generated from the daemon schema.`,
       );
@@ -364,7 +373,9 @@ function assertRefinementMatches(m: TableMeta, baseMeta: TableMeta): void {
     cols.every((c) => baseMeta.columns[c] !== undefined && m.columns[c].type === baseMeta.columns[c].type) &&
     m.primaryKey.length === baseMeta.primaryKey.length &&
     m.primaryKey.every((k, i) => baseMeta.primaryKey[i] === k) &&
-    (m.local === true) === (baseMeta.local === true);
+    // Locality must match EXACTLY, including the persisted-vs-session variant (a refinement
+    // flipping `true` ↔ `"session"` would silently change the table's durability).
+    (m.local ?? false) === (baseMeta.local ?? false);
   if (!matches) {
     throw new Error(
       `refineSchema: table "${m.name}" does not match the schema's table of that name — pass the ` +
@@ -375,16 +386,46 @@ function assertRefinementMatches(m: TableMeta, baseMeta: TableMeta): void {
 }
 
 /** Whether `table` is a {@link TableMeta.local local-only} table in `schema` (an unknown table
- *  reads as non-local). The single locality predicate the backends key off. */
+ *  reads as non-local). The single locality predicate the backends key off. BOTH variants —
+ *  `true` and `"session"` — are local here; the persisted/ephemeral split matters only to the
+ *  persistence plane ({@link persistedLocalTableNames}). */
 export function isLocalTable<S extends ColsMap>(schema: Schema<S>, table: string): boolean {
-  return schema.tables[table]?.local === true;
+  return Boolean(schema.tables[table]?.local);
 }
 
-/** The set of local-only table names in `schema` (`201-LOCAL-ONLY-TABLES-DESIGN.md` §4). */
+/** The set of local-only table names in `schema` (`201-LOCAL-ONLY-TABLES-DESIGN.md` §4) — BOTH
+ *  variants (`true` and `"session"`); every locality rule except persistence keys off this set. */
 export function localTableNames<S extends ColsMap>(schema: Schema<S>): Set<string> {
   return new Set(Object.keys(schema.tables).filter((n) => schema.tables[n].local));
 }
 
+/** The subset of {@link localTableNames} eligible for the persistence plane — `local: true` only.
+ *  A `local: "session"` table stays outside it: never persisted, never replicated across tabs
+ *  (`207-LOCAL-TABLE-PERSISTENCE-DESIGN.md` §5.4). */
+export function persistedLocalTableNames<S extends ColsMap>(schema: Schema<S>): Set<string> {
+  return new Set(Object.keys(schema.tables).filter((n) => schema.tables[n].local === true));
+}
+
+/** A stable fingerprint of the schema's PERSISTED local tables only — the persistence gate's
+ *  `schemaHash` (`207-LOCAL-TABLE-PERSISTENCE-DESIGN.md` §3.3 / P7). Per `local: true` table:
+ *  `(name, ordered column names + types + optionality, pk columns)`. Column order is kept (rows are
+ *  positional); tables are sorted by name so registration order can't skew it; synced-table AND
+ *  `local: "session"` changes never move it (reshaping an ephemeral table must not wipe durable
+ *  data). The value is the canonical descriptor itself, not a digest — local-table sets are tiny,
+ *  and exactness (no collision can ever skip a P7 clear) beats compactness here. */
+export function localSchemaHash<S extends ColsMap>(schema: Schema<S>): string {
+  // Derived from persistedLocalTableNames — the hash's contract is "fingerprints exactly the
+  // tables the plane persists", so the two must share one predicate, not two copies of it.
+  const tables = [...persistedLocalTableNames(schema)]
+    .sort()
+    .map((n) => {
+      const meta = schema.tables[n];
+      const cols = Object.keys(meta.columns).map((c) => [c, meta.columns[c].type, meta.columns[c].optional === true]);
+      return [n, cols, meta.primaryKey];
+    });
+  return `v1:${JSON.stringify(tables)}`;
+}
+
 // ----------------------------- relationships (FRAGMENT-COMPOSITION-DESIGN §4.2, named edges) -----
 //
 // A relationship is the correlation (`parent.col → child.col`) declared ONCE as a value, so `sub`,

package/src/store.ts

@@ -12,7 +12,7 @@ import { stableKey } from "./key.ts";
 import { queries, type Query, type QueryRoot } from "./query.ts";
 import type { ColsMap, InsertOf, RowOf, Schema } from "./schema.ts";
 import type { Backend, ChangeEvent, ColType, FlatChange, Mutation, QueryId, RemoteQuery, ResultType, WireSchema, WireValue } from "./types.ts";
-import { type ArrayView, FlatArrayView, type SingularArrayView, SingularView, type ViewTypes } from "./view.ts";
+import { type ArrayView, type ChangePhase, FlatArrayView, type SingularArrayView, SingularView, type ViewChangeListener, type ViewTypes } from "./view.ts";
 
 /** One query's SSR snapshot, keyed by its `viewKey` ({@link stableKey} of the AST): the
  *  pre-projected first-paint `rows` plus the `cvMin` watermark they reflect (SSR-DESIGN.md §6.2).
@@ -101,7 +101,9 @@ export class Store<S extends ColsMap> {
   private readonly syncLeases = new Map<QueryId, SyncLeaseState>();
   // SSR seeds (SSR-DESIGN.md §6), keyed by `viewKey`: a view materialized for one of these is
   // seeded for first paint; a seed is consumed (dropped) the moment its query's first live
-  // `hello` lands, so later mounts don't flash stale SSR data.
+  // SNAPSHOT lands — NOT its `hello` — so the seed bridges the `hello`→snapshot gap (the live
+  // data arrives on the snapshot, a round-trip after the hello) and later mounts of a now-live
+  // query don't re-seed stale SSR data.
   private readonly seeds = new Map<string, DehydratedQuery>();
   // Public per-query change subscribers ({@link subscribeChanges}). `undefined` until the first
   // subscription, so an app that never narrates (nor attaches devtools) pays one undefined-check per
@@ -116,6 +118,12 @@ export class Store<S extends ColsMap> {
   // Public per-query {@link ResultType} subscribers ({@link subscribeResultType}). `undefined` until
   // the first subscription. Devtools and any status-driven layer ride this instead of a private tap.
   private resultTypeListeners?: Set<(qid: QueryId, rt: ResultType) => void>;
+  // Whether the backend drives a per-query resultType lifecycle (`onResultType`). When it does, a
+  // REMOTE query is marked PENDING (`unknown`) at register (`registerMaterialized`) so its synchronous
+  // pre-sync snapshot — the optimistic/wasm backend fetches local, not-yet-synced state INSIDE
+  // `registerQuery` — can't be mistaken for the authoritative answer and retire the SSR seed. When it
+  // doesn't, every view stays `complete` and the first snapshot IS authoritative (unchanged behavior).
+  private readonly hasResultTypeLifecycle: boolean;
   // Cross-view-atomic notification (the `Backend.onCommitBoundary` contract): while the backend is
   // delivering one commit's coherent multi-query batch, fold every affected view but DEFER each
   // view's subscriber notification, collecting the changed views here; at the commit's `end` flush
@@ -135,6 +143,7 @@ export class Store<S extends ColsMap> {
   constructor(schema: Schema<S>, backend: Backend) {
     this.schema = schema;
     this.backend = backend;
+    this.hasResultTypeLifecycle = typeof backend.onResultType === "function";
     this.backend.onEvent((qid, ev) => this.onEvent(qid, ev));
     // The in-process engine brackets each commit's multi-query delivery so every affected view
     // folds before any subscriber is notified (see `commitDepth`/`pendingFlush`). A backend with no
@@ -166,10 +175,59 @@ export class Store<S extends ColsMap> {
   }
 
   /** Materialize any fluent query object. Named queries subscribe remotely by `(name,args)`;
-   *  ad-hoc builder queries are local-only for local-first backends. */
-  materialize<Q extends Query<any, any, any>>(query: Q): ReturnType<Q["materialize"]> {
+   *  ad-hoc builder queries are local-only for local-first backends.
+   *
+   *  `opts.onChanges` binds a narrator to this view's DIFF stream ({@link ArrayView.onChanges}) — the
+   *  per-view seam that replaces filtering the store-global {@link subscribeChanges} by `qid`. It is
+   *  wired BEFORE the backend registers the query, so a synchronous backend's first `snapshot` (fired
+   *  inside `registerQuery`, before this returns) is delivered too. */
+  materialize<Q extends Query<any, any, any>>(
+    query: Q,
+    opts?: { onChanges?: ViewChangeListener },
+  ): ReturnType<Q["materialize"]> {
     const remote = typeof query.name === "string" ? { name: query.name, args: query.args } : undefined;
-    return this.registerMaterialized(query.ast(), remote).view as ReturnType<Q["materialize"]>;
+    return this.registerMaterialized(query.ast(), remote, opts?.onChanges).view as ReturnType<Q["materialize"]>;
+  }
+
+  /** One-shot AUTHORITATIVE read: materialize `query`, wait until its result is server-authoritative
+   *  ({@link ResultType} `"complete"`), read the data once, then destroy the view — resolving with the
+   *  plain result rather than a live subscription. Rejects if the query enters the `"error"` state. Use
+   *  it for exports, imports, undo snapshots — anywhere that wants the current answer as a value.
+   *
+   *  A synchronous local-first backend (wasm/replica) has already delivered the first snapshot inside
+   *  {@link materialize}, so the view is `"complete"` on entry and this settles on the next microtask
+   *  without ever attaching a listener; a remote backend settles when the first live snapshot lands.
+   *  The query is NEVER left subscribed — the view is destroyed before the promise settles either way.
+   *  (A remote query that never completes leaves the promise pending, exactly as a `resultType` poll
+   *  would; race a timeout at the call site if you need one.) */
+  readOnce<Q extends Query<any, any, any>>(query: Q): Promise<ReturnType<Q["materialize"]>["data"]> {
+    type Data = ReturnType<Q["materialize"]>["data"];
+    const view = this.materialize(query);
+    return new Promise<Data>((resolve, reject) => {
+      let settled = false;
+      let detach: (() => void) | undefined;
+      const settle = (): boolean => {
+        const rt = view.resultType;
+        if (rt !== "complete" && rt !== "error") return false;
+        settled = true;
+        detach?.();
+        if (rt === "error") {
+          view.destroy();
+          reject(new Error("store.readOnce: query entered the error result state"));
+        } else {
+          const data = view.data as Data;
+          view.destroy();
+          resolve(data);
+        }
+        return true;
+      };
+      // A synchronous backend is already `complete` here — settle now, never attaching a listener.
+      // (`subscribeResultType` never replays on attach, so the pre-check is what covers this case.)
+      if (settle()) return;
+      detach = this.subscribeResultType((qid) => {
+        if (!settled && qid === view.qid) settle();
+      });
+    });
   }
 
   /** True when the backend can retain a remote named query independently from the local
@@ -362,6 +420,7 @@ export class Store<S extends ColsMap> {
   private registerMaterialized(
     ast: Ast,
     remote?: RemoteQuery,
+    onChanges?: ViewChangeListener,
   ): { qid: QueryId; view: ArrayView<unknown> | SingularArrayView<unknown> } {
     const qid: QueryId = this.nextId++;
     this.asts.set(qid, ast);
@@ -384,6 +443,22 @@ export class Store<S extends ColsMap> {
       }
       baseDestroy();
     };
+    // Bind the narrator BEFORE `registerQuery` fires (a synchronous backend dispatches this query's
+    // first `hello`+`snapshot` inside it) so the initial snapshot reaches the change listener too.
+    if (onChanges) view.onChanges(onChanges);
+    // SSR first paint (SSR-DESIGN.md §6): seed the view — and, for a lifecycle-backed REMOTE query,
+    // mark it PENDING (`unknown`) — BEFORE `registerQuery`, because a synchronous optimistic/wasm
+    // backend fires this query's first `hello`+`snapshot` from LOCAL, not-yet-synced state INSIDE that
+    // call. Doing both here first means (a) that pre-sync snapshot finds the seed already applied (so
+    // `data` shows it, not an empty tree) and (b) the view already reads `unknown`, so `retireSeedIfLive`
+    // KEEPS the seed through it — on the optimistic backend the real hydration point is the later
+    // `catchUp` batch (which flips the query to `complete` FIRST, then folds the authoritative rows).
+    // A LOCAL query is authoritative at register (its local snapshot IS the answer), so it keeps the
+    // default `complete`; a lifecycle-LESS backend has no `onResultType`, so every view stays `complete`
+    // and its first snapshot retires the seed exactly as before.
+    const seed = this.seeds.get(stableKey(ast));
+    if (seed) view.seed(seed.rows);
+    if (remote !== undefined && this.hasResultTypeLifecycle) view.setResultType("unknown");
     // If the backend rejects the registration (E3: a remote query naming a local-only table), roll
     // back the per-qid state we just created — otherwise the view + ast entry leak (the caller never
     // gets a handle to `destroy()` them, since the throw aborts before we return).
@@ -394,11 +469,6 @@ export class Store<S extends ColsMap> {
       this.asts.delete(qid);
       throw e;
     }
-    // SSR first paint (SSR-DESIGN.md §6): if this AST was preloaded/hydrated, seed the view now.
-    // A synchronous backend (wasm) already reset the view above, so its live data wins and the
-    // seed is inert; an async backend (ws) leaves it PENDING, so the seed shows until `hello`.
-    const seed = this.seeds.get(stableKey(ast));
-    if (seed) view.seed(seed.rows);
     // A top-level `.one()` (engine-capped to limit 1) unwraps at the result boundary.
     return { qid, view: ast.one ? new SingularView(view) : view };
   }
@@ -419,18 +489,27 @@ export class Store<S extends ColsMap> {
   private onEvent(qid: QueryId, ev: ChangeEvent): void {
     if (ev.type === "hello") {
       const ast = this.asts.get(qid);
-      // First live hello for this view ⇒ retire its SSR seed: the maintained tree now owns the
-      // result, so no future mount of the same query should flash the stale first-paint rows.
-      if (ast) this.seeds.delete(stableKey(ast));
       const types = ast ? this.viewTypes(ev.schema, ast) : undefined;
       // Reset the (pre-created or existing) view IN PLACE — first hello OR a re-hydrate (new
-      // epoch) — so the materialized reference the caller holds survives a re-subscribe.
+      // epoch) — so the materialized reference the caller holds survives a re-subscribe. The SSR
+      // seed is KEPT across the reset and retired on the first `snapshot` below (the live data
+      // lands then, not on the hello), so a seeded query bridges the gap instead of flashing empty.
       const view = this.views.get(qid) ?? this.views.set(qid, new FlatArrayView(undefined, undefined, qid)).get(qid)!;
       view.reset(ev.schema, types);
     } else if (ev.type === "snapshot") {
-      this.applyAndTrack(qid, ev.adds);
+      // A snapshot is a hydration point — retire the SSR seed and fold, gated on the query being
+      // AUTHORITATIVE. {@link foldHydration} handles the empty-fold case (a re-hydrate to nothing).
+      this.foldHydration(qid, ev.adds, "snapshot");
+    } else if (ev.catchUp) {
+      // A `catchUp` batch is a query's initial hydration delivered as a delta — on the optimistic /
+      // normalized backend THIS (not the earlier pre-sync snapshot) is the real hydration point,
+      // arriving right after the query flips to `complete`. Retire the seed + fold, phased as a
+      // `snapshot` so a narrator's "what CHANGED" default ignores the initial rows.
+      this.foldHydration(qid, ev.events, "snapshot");
     } else {
-      this.applyAndTrack(qid, ev.events);
+      // A plain (non-catchUp) batch is a post-hydration delta — the seed is long gone by then, and
+      // this is the incremental hot path, so it does no seed work at all.
+      this.applyAndTrack(qid, ev.events, "batch");
     }
     // Fan the same post-fold frame out to subscribers (narration, devtools, …). Inside a commit
     // bracket the frames are BUFFERED and delivered together at the boundary (after every view has
@@ -448,14 +527,63 @@ export class Store<S extends ColsMap> {
     }
   }
 
+  /** Retire a view's SSR seed — from the view (so `data` switches from the seed to the maintained
+   *  tree) AND from the seeds map (so no later mount re-seeds a now-live query) — but ONLY once the
+   *  query is AUTHORITATIVE (`resultType === "complete"`). Called BEFORE the fold it accompanies, so
+   *  that fold's notify already reflects the live tree with no empty gap. Idempotent.
+   *
+   *  The gate is the fix for the synchronous optimistic/wasm backend: it fires a query's FIRST snapshot
+   *  from LOCAL, not-yet-synced state while the query is still `unknown` (`registerMaterialized` marks a
+   *  lifecycle-backed remote view `unknown` up front for exactly this), then delivers the authoritative
+   *  rows one event later as a `catchUp` batch — having already flipped the query to `complete`. So the
+   *  seed survives the pre-sync snapshot (`unknown` ⇒ skip) and retires on the catch-up (`complete` ⇒
+   *  retire). A lifecycle-LESS backend (pure wasm, the SSR one-shot, tests) is `complete` from creation,
+   *  so its first snapshot retires the seed exactly as before this gate existed. */
+  private retireSeedIfLive(qid: QueryId): boolean {
+    const view = this.views.get(qid);
+    if (!view || view.resultType !== "complete") return false;
+    const retired = view.retireSeed(); // idempotent — false once the seed is already retired
+    // Drop the map entry (so no later mount re-seeds a now-live query) only when we actually retired,
+    // and only pay the `stableKey` hash while a seed is outstanding (the map is empty on a no-SSR app).
+    if (retired && this.seeds.size > 0) {
+      const ast = this.asts.get(qid);
+      if (ast) this.seeds.delete(stableKey(ast));
+    }
+    return retired;
+  }
+
+  /** Retire the SSR seed (if authoritative) and fold the accompanying hydration delta — BEFORE the
+   *  fold so its notify already reflects the live tree with no empty gap. The subtlety: a hydration
+   *  can fold NOTHING — a 0-row authoritative result, or one whose rows are already present in `top`
+   *  (a query whose result is fully covered by an already-hydrated sibling: the shared rows dedup to
+   *  zero net base mutations). Then {@link FlatArrayView.applyChanges} notifies nothing, so the
+   *  seed→tree switch would never reach subscribers and the view freezes on the stale seed. Guard
+   *  against that: if the seed retired but the fold was a no-op, force the handoff notify (inline, or
+   *  via the commit-boundary flush). Flash-safe — the forced notify only fires when there was nothing
+   *  to fold, so `data` is already the correct live tree by then. */
+  private foldHydration(qid: QueryId, events: FlatChange[], phase: ChangePhase): void {
+    const retired = this.retireSeedIfLive(qid);
+    const view = this.views.get(qid);
+    if (!view) return;
+    const deferring = this.commitDepth > 0;
+    const changed = view.applyChanges(events, this.removedSubtreeWanted > 0, deferring, phase);
+    if (deferring) {
+      // Flush at the boundary if the fold changed the tree OR a retire is owed a notify (flush()
+      // always notifies, even with no buffered segments).
+      if (changed || retired) this.pendingFlush.add(view);
+    } else if (retired && !changed) {
+      view.notify(); // the fold notified nothing but the seed retired — land the handoff
+    }
+  }
+
   /** Fold a batch into its view, then notify now or — inside a commit bracket — defer the view's
    *  notification to the commit boundary, so all sibling views fold first (cross-view-atomic
    *  notification; see `commitDepth`). */
-  private applyAndTrack(qid: QueryId, events: FlatChange[]): void {
+  private applyAndTrack(qid: QueryId, events: FlatChange[], phase: ChangePhase): void {
     const view = this.views.get(qid);
     if (!view) return;
     const deferring = this.commitDepth > 0;
-    if (view.applyChanges(events, this.removedSubtreeWanted > 0, deferring) && deferring) {
+    if (view.applyChanges(events, this.removedSubtreeWanted > 0, deferring, phase) && deferring) {
       this.pendingFlush.add(view);
     }
   }

package/src/types.ts

@@ -75,7 +75,12 @@ export interface FlatChange {
 export type ChangeEvent =
   | { type: "hello"; schema: WireSchema; comparatorVersion: number }
   | { type: "snapshot"; adds: FlatChange[]; last: boolean }
-  | { type: "batch"; events: FlatChange[] };
+  // `catchUp` marks a batch that is really a query's INITIAL hydration delivered as a delta — the
+  // optimistic backend hydrates a fresh query through its reconcile cycle (a `serverBatchEnd`), so
+  // the whole first result set arrives as a `batch`, not a `snapshot`. The Store maps a catch-up
+  // batch to the `snapshot` change-phase so a narrator's "what CHANGED" default ignores the initial
+  // rows instead of narrating every one as a fresh add. A normal incremental batch omits it.
+  | { type: "batch"; events: FlatChange[]; catchUp?: boolean };
 
 export type Mutation =
   | { op: "add"; table: string; row: WireValue[] }
@@ -173,8 +178,13 @@ export interface Backend {
   /** Optional DIRECT-COMMIT path for LOCAL-only tables (`201-LOCAL-ONLY-TABLES-DESIGN.md` §6):
    *  applies the writes straight to the engine, OUTSIDE the optimistic pending stack (a local
    *  table is untracked, so it never rebases). The backend rejects any synced/tracked table (M2).
-   *  Backends with no local-table support (a plain remote sync backend) omit it. */
-  writeLocal?(mutations: Mutation[]): void;
+   *  Backends with no local-table support (a plain remote sync backend) omit it.
+   *
+   *  `onCommitted` (207 §5.1) runs after the engine commit is applied but BEFORE subscriber
+   *  delivery: a subscriber throwing during delivery re-raises out of this call, and a caller
+   *  that must stay coherent with the engine (the persistence tap) cannot tell that throw from
+   *  a pre-commit rejection — the callback can, because it fires exactly when the commit is in. */
+  writeLocal?(mutations: Mutation[], onCommitted?: () => void): void;
   onEvent(handler: (queryId: QueryId, event: ChangeEvent) => void): void;
   /** Optional: the backend pushes per-query {@link ResultType} changes here and the core routes
    *  each to the matching view (so `view.resultType` tracks it). Backends with no lifecycle (the
@@ -226,6 +236,33 @@ export interface MutationEnvelope {
   args: unknown;
 }
 
+/** A room authority's verdict for a NON-applied mutation (RINDLE-REALTIME-QUERY-ENABLEMENT
+ *  §3.3, the deopt handshake; Slice H-iv-b server half / H-v client half). Sent on the author's
+ *  own socket for every mutation the room did NOT apply, always BEFORE the lmid ack that burns
+ *  the `mid` (same-socket ordering only — the ack may reach the client through another path
+ *  first, e.g. a replayed lmid snapshot). Applied mutations send NOTHING: silence + lmid
+ *  coverage ⇒ applied.
+ *
+ *  - `kind: "deopt"` — the room's §3.3 commit gate refused the routed mutation (or its
+ *    environment fell short, e.g. `tx.query`); the mid is burnt in the ROOM ledger with zero
+ *    effects and the client re-enqueues the same logical mutation onto the daemon stream.
+ *    `name`/`args` are echoed so the frame is SELF-CONTAINED: a client that already retired the
+ *    entry (the burnt-mid confirm won the race, or the frame is a replay re-answer) re-invokes
+ *    from the frame alone.
+ *  - `kind: "rejected"` — FINAL (authz/validation): the mid is burnt the same way and the
+ *    prediction snaps back on the ordinary lmid release; no re-route.
+ *
+ *  `reason` may be absent on a re-answered frame whose record was seeded from journal replay
+ *  (the verdict is journaled; the reason is not). */
+export interface MutationOutcomeFrame {
+  mid: number;
+  kind: "deopt" | "rejected";
+  reason?: string;
+  /** Echoed on DEOPT frames only (self-contained re-invoke — see above). */
+  name?: string;
+  args?: unknown;
+}
+
 /** The connection-level progress frame (§8.6): advances the coherent-apply release point
  *  (`cvMin`). A pure release signal — mutation confirmation does NOT ride it: `lmid` is a
  *  row in {@link CLIENT_MUTATIONS_TABLE}, delivered through the client's own per-client
@@ -233,6 +270,13 @@ export interface MutationEnvelope {
  *  `cvMin` as the commit's effects (transactionally coherent by construction). */
 export interface ProgressFrame {
   cvMin: number;
+  /** A ROOM shell's upstream-absorption advert (`301-ECHO-FENCE-DESIGN.md` §1.2, optional —
+   *  old shells omit both): "I have absorbed upstream daemon commits through cv `upstreamCv`
+   *  of daemon boot `upstreamBoot`." The client's §301 direction-B pin fence: a pin stamped
+   *  `(boot, cv)` at its parking daemon release drops once the room advertises coverage under
+   *  the §2.4 boot rule. The daemon's own progress frames never carry these. */
+  upstreamCv?: number;
+  upstreamBoot?: string;
 }
 
 /** The replicated bookkeeping table carrying each client's high-water mutation id
@@ -273,4 +317,34 @@ export interface OptimisticSource {
    *  boot id). The backend resets its `cv` watermark so the server's reset `cv` sequence is
    *  accepted rather than dropped as stale. In-process sources never restart and omit it. */
   onRestart?(handler: () => void): void;
+  /** Optional (§301 §2.4): the transport's observed authority BOOT-ID stream — fired on the
+   *  FIRST observation and on every change (the same signal that drives {@link onRestart}, plus
+   *  the initial one). The backend keeps client-local ordinals over these opaque ids; the
+   *  direction-B pin fence's boot rule compares a room's advertised
+   *  {@link ProgressFrame.upstreamBoot} against them. Sources that cannot observe one omit it —
+   *  direction-B pins then hold to the state-match fallback across restarts (conservative). */
+  onBootId?(handler: (bootId: string) => void): void;
+  /** Optional (Slice H-v): the channel's {@link MutationOutcomeFrame} stream — the room deopt
+   *  handshake's client half. **OUT-OF-BAND BY DESIGN**: the frame carries no `cv` and the source
+   *  MUST dispatch it immediately on arrival, never behind the cv buffer — a deopt has to migrate
+   *  its pending entry BEFORE the buffered lmid release that would otherwise retire it as a
+   *  success (and the §7.3 hold-back trigger, keyed on the entry's confirming domain, would then
+   *  park its staged writes the wrong way). Sources whose authority never deopts (the in-process
+   *  native source, a plain daemon) omit it. */
+  onMutationOutcome?(handler: (frame: MutationOutcomeFrame) => void): void;
+  /** Optional (Slice H-v, the §7.5 rule-3 crash-window closer): fired when the transport
+   *  RE-establishes its session (reconnect → re-`init`), BEFORE any post-reconnect frame is
+   *  processed — the ordering is load-bearing: the re-subscribed lmid stream's fresh snapshot may
+   *  cover a mid whose `mutationOutcome` frame died with the old socket, and once that release
+   *  retires the entry as an apparent success there is nothing left to re-send. The backend
+   *  re-sends this domain's unconfirmed pending envelopes with their ORIGINAL mids, in mid order;
+   *  the source may DEFER their delivery until the session is re-authorized (a room's
+   *  `pushMutation` requires the lease-token subscribe's subject). Idempotent under the domain's
+   *  own ledger — a processed mid dedups silently (silence + lmid coverage ⇒ applied), a
+   *  non-applied mid is re-answered from the authority's recorded-outcome map (resolving even an
+   *  already-retired entry through the handshake's not-found arm). Distinct from
+   *  {@link onRestart} (a NEW server incarnation): a same-incarnation socket drop re-syncs
+   *  without restarting, and envelopes sent into the dead socket are exactly what this recovers.
+   *  In-process sources never drop a session and omit it. */
+  onResync?(handler: () => void): void;
 }