@rindle/client 0.4.4 → 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/store.ts

@@ -118,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
@@ -137,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
@@ -182,6 +189,47 @@ export class Store<S extends ColsMap> {
     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
    *  materialized AST view. React uses this to keep one local view per AST while still sending
    *  every mounted `(name,args)` lease through the backend. */
@@ -398,6 +446,19 @@ export class Store<S extends ColsMap> {
     // 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).
@@ -408,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 };
   }
@@ -441,19 +497,19 @@ export class Store<S extends ColsMap> {
       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") {
-      // The first live snapshot IS the query's hydration point (even an empty one — 0 rows is an
-      // authoritative answer): retire the SSR seed now, from the view (so `data` switches to the
-      // maintained tree) AND from the seeds map (so no later mount re-seeds a now-live query),
-      // BEFORE folding so the fold's notify already reflects the live tree with no empty gap.
-      const ast = this.asts.get(qid);
-      if (ast) this.seeds.delete(stableKey(ast));
-      this.views.get(qid)?.retireSeed();
-      this.applyAndTrack(qid, ev.adds, "snapshot");
+      // 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 {
-      // A `catchUp` batch is a query's initial hydration delivered as a delta (the optimistic
-      // backend hydrates through its reconcile cycle), so phase it as a `snapshot` — a narrator's
-      // "what CHANGED" default then ignores the initial rows instead of narrating each as an add.
-      this.applyAndTrack(qid, ev.events, ev.catchUp ? "snapshot" : "batch");
+      // 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
@@ -471,6 +527,55 @@ 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`). */

package/src/types.ts

@@ -236,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
@@ -243,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
@@ -283,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;
 }

package/src/view.ts

@@ -437,10 +437,15 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
 
   /** Retire the SSR first-paint seed — the Store calls this as it folds the maintained tree's first
    *  live snapshot, so `data` switches from the seed to the live tree with no empty gap between them
-   *  (the seed deliberately survived the earlier `reset`/`hello`). Idempotent; a no-op once retired.
-   *  Does NOT notify — the snapshot fold it accompanies does. */
-  retireSeed(): void {
+   *  (the seed deliberately survived the earlier `reset`/`hello`). Idempotent. Does NOT notify — the
+   *  snapshot fold it accompanies does; BUT when that fold is empty (a 0-row result, or rows already
+   *  in `top`) it notifies nothing, so the Store forces a {@link notify} on the strength of the `true`
+   *  return here — else the view reads the live tree yet never re-renders (a frozen seed). Returns
+   *  whether a live seed was actually cleared (so the Store knows a forced notify is owed). */
+  retireSeed(): boolean {
+    if (this.seeded === null) return false;
     this.seeded = null;
+    return true;
   }
 
   /** Apply a batch (the hydrate snapshot or one transaction's events) in order, then
@@ -737,7 +742,10 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
     return obj;
   }
 
-  private notify(): void {
+  /** Notify data subscribers with the current {@link data}. Normally driven by a fold ({@link
+   *  applyChanges}/{@link flush}); the Store also calls it directly to land a seed retirement whose
+   *  accompanying fold was empty (see {@link retireSeed}). */
+  notify(): void {
     const d = this.data;
     for (const l of this.listeners) l(d);
   }