@rindle/optimistic 0.1.6 → 0.3.1

package/src/backend.ts

@@ -42,6 +42,7 @@ import { CLIENT_MUTATIONS_SCHEMA, LMID_QUERY_NAME, localTableNames, normalizedTa
 import type {
   Ast,
   Backend,
+  BackendDevObserver,
   ChangeEvent,
   ColsMap,
   Mutation,
@@ -65,6 +66,18 @@ import { AggOverlay, type ChildOp, collectAggDefs } from "./agg-overlay.ts";
  *  against the schema at runtime, so a typo throws immediately with the valid names. */
 export type KeyedRow = Record<string, WireValue>;
 
+/** What `MutationTx.query` accepts: a query handle whose `.ast()` lowers to the wire
+ *  {@link Ast} — exactly what the typed query builder (`store.query.<table>…` or
+ *  `newQueryBuilder(schema).<table>…`) produces (203-MUTATOR-READS-DESIGN.md §9.1). Typed
+ *  structurally so the `MutationTx` surface need not carry the builder's heavy generics. */
+export type QueryArg = { ast(): Ast };
+
+/** A row returned by {@link MutationTx.query}: column name → cell, plus each materialized
+ *  relationship name → its nested row(s) — an array (a plural relationship), or a single row /
+ *  `null` (a `.one()` relationship). Recursive (nested rows share the shape). Presented
+ *  identically to a `view.data` row of the same query (203-MUTATOR-READS-DESIGN.md §5.2). */
+export type QueryResultRow = { [key: string]: WireValue | QueryResultRow | QueryResultRow[] };
+
 /** The write handle a client mutator runs against (the client `MutationTx`, §4.2):
  *  reads see the current base + this transaction's own staged writes (§4.1).
  *
@@ -84,6 +97,14 @@ export interface MutationTx {
   upsert(table: string, row: KeyedRow): void;
   /** Delete the row identified by the pk columns. A missing row is a NO-OP. */
   delete(table: string, pk: KeyedRow): void;
+  /** Run a one-shot read query (`where`/`orderBy`/`limit`/join) over the state this
+   *  mutator is mutating — it sees this transaction's own writes-so-far, the same
+   *  read-your-writes contract as `get`/`row` (§4.1; 203-MUTATOR-READS-DESIGN.md §5.2).
+   *  Synchronous; returns the matching rows in the query's order, each with its materialized
+   *  relationship children nested by name (presented identically to a `view.data` row). Pass
+   *  a query from the typed builder, e.g. `tx.query(q.issue.where("owner", "=", me))`.
+   *  Refused inside a FOLDED mutator (a reading mutator is non-absorbing, §9.1). */
+  query(query: QueryArg): QueryResultRow[];
   // --- positional (the wire shape) ---
   get(table: string, pk: WireValue[]): WireValue[] | undefined;
   add(table: string, row: WireValue[]): void;
@@ -287,6 +308,12 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
    *  pending delta `displayed = server_base ⊕ local_pending_delta` is applied from. */
   private readonly overlay = new AggOverlay();
   private handler: (qid: QueryId, ev: ChangeEvent) => void = () => {};
+  /** The Store's commit-boundary handler ({@link Backend.onCommitBoundary}), forwarded from the
+   *  local engine's `dispatch` brackets so the Store folds every affected view before notifying any
+   *  subscriber (cross-view-atomic notification). All this backend's data deltas originate from the
+   *  local engine, so its commit brackets are this backend's commit brackets. */
+  private boundaryHandler: (phase: "begin" | "end") => void = () => {};
+  private readonly devObservers = new Set<BackendDevObserver>();
 
   private pendingMutations: PendingMutation[] = [];
   private nextMid = 1;
@@ -328,6 +355,9 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
   ) {
     this.local = new WasmBackend(schema);
     this.local.onEvent((qid, ev) => this.handler(qid, ev));
+    // Forward the local engine's commit brackets up to the Store (cross-view-atomic notification):
+    // every data delta this backend emits comes from `this.local`, so its commit boundaries are ours.
+    this.local.onCommitBoundary((phase) => this.boundaryHandler(phase));
     this.colCounts = colCountsFromSchema(schema);
     this.colIndex = colIndexFromSchema(schema);
     this.sync = new NormalizedSync(pkColsFromSchema(schema), this.colCounts);
@@ -479,12 +509,18 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
     // Store counter — re-materialize gets a fresh id, never this one again), so drop it on teardown.
   }
 
-  retainRemoteQuery(qid: QueryId, remote: RemoteQuery, localQueryId?: QueryId): void {
+  retainRemoteQuery(qid: QueryId, remote: RemoteQuery, localQueryId?: QueryId, ast?: Ast): void {
+    if (ast) this.ensureSyntheticTables(qid, ast);
     this.retainRemote(qid, remote, localQueryId);
   }
 
   releaseRemoteQuery(qid: QueryId): void {
     const remoteQid = this.releaseRemote(qid);
+    this.releaseSyntheticTables(qid);
+    if (!this.queryTables.has(qid)) {
+      this.resultTypes.delete(qid);
+      this.hydrated.delete(qid);
+    }
     if (remoteQid === undefined) return;
     this.buffer = this.buffer.filter((f) => f.qid !== remoteQid);
     const gc = this.sync.dropQuery(remoteQid);
@@ -512,39 +548,65 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
     this.handler = handler;
   }
 
+  onCommitBoundary(handler: (phase: "begin" | "end") => void): void {
+    this.boundaryHandler = handler;
+  }
+
   // --- the named-mutator entry (§9) ----------------------------------------------
 
+  /** Bracket a multi-step optimistic apply as ONE notification commit (cross-view-atomic
+   *  notification — {@link Backend.onCommitBoundary}). `invoke`/`invokeFolded` apply the prediction
+   *  and then reconcile the `__agg` head in TWO `this.local` commits, but they are two halves of one
+   *  logical mutation: a relationship-`count` view and the data view it counts must update together.
+   *  The Store's `commitDepth` is a counter, so each inner commit's own `begin`/`end` nests under this
+   *  outer pair and the Store flushes every affected view (data AND count) once, together, at the
+   *  outer `end` — a subscriber re-reading a sibling view then sees post-commit data, never a torn
+   *  half. Balanced on throw (the prediction mutator may reject) via the `finally`, so a thrown
+   *  prediction never wedges the Store in deferred mode. */
+  private inOneCommit<T>(apply: () => T): T {
+    this.boundaryHandler("begin");
+    try {
+      return apply();
+    } finally {
+      this.boundaryHandler("end");
+    }
+  }
+
   /** Run the named client mutator optimistically: the prediction applies to the live
    *  engine now (affected views update synchronously), `(mid, name, args)` joins the
    *  pending stack, and the envelope ships upstream. Returns the assigned `mid`. */
   invoke(name: string, args: unknown): number {
     const mutator = this.registry[name];
     if (!mutator) throw new Error(`unknown client mutator: ${name}`);
-    // Apply the prediction FIRST. If the mutator throws (client-side validation, a bad read),
-    // the staged write is discarded (the wasm txn is a clean no-op until commit) and the throw
-    // propagates with NO mid consumed — a burnt mid is a permanent server-side gap that
-    // silently refuses every later mutation from this client (#10).
-    const touched = new Set<string>();
-    const ops: ChildOp[] = [];
-    this.local.writeWith((tx) => {
-      mutator(trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops)), args as never);
+    // One commit boundary spans the prediction AND the `__agg`-head reconcile below, so their views
+    // (data + count) flush together rather than tearing across two engine commits.
+    return this.inOneCommit(() => {
+      // Apply the prediction FIRST. If the mutator throws (client-side validation, a bad read),
+      // the staged write is discarded (the wasm txn is a clean no-op until commit) and the throw
+      // propagates with NO mid consumed — a burnt mid is a permanent server-side gap that
+      // silently refuses every later mutation from this client (#10).
+      const touched = new Set<string>();
+      const ops: ChildOp[] = [];
+      this.local.writeWith((tx) => {
+        mutator(trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops)), args as never);
+      });
+      // Flush-on-enqueue (§4.2): a fold whose tables overlap this write must take its mid NOW, BEFORE
+      // this write does, so wire order == local-apply order for any pair that can observe each other
+      // (a read-dependent write reading a folded cell sees the same value optimistically and on the
+      // wire — no snap). Drained folds ship with smaller mids; this write's mid is dealt after.
+      this.drainOverlapping(touched);
+      const mid = this.nextMid++;
+      this.pendingMutations.push({ mid, name, args, touched });
+      // The prediction stuck — fold its child ops into the optimistic agg delta and push it onto
+      // the `__agg` head rows (§4). No reset here (this is the §1.3 trivial case, no rewind): the
+      // delta accumulates on top of the prior pending set, and `reconcileAggHead` recomputes each
+      // touched group's head as the absolute `server_base ⊕ delta`.
+      for (const op of ops) this.overlay.observe(op);
+      this.reconcileAggHead();
+      this.refreshPending(); // §7.2: this write now touches its queries' pending axis (NOT ResultType).
+      void this.source.pushMutation({ clientID: this.clientID, mid, name, args });
+      return mid;
     });
-    // Flush-on-enqueue (§4.2): a fold whose tables overlap this write must take its mid NOW, BEFORE
-    // this write does, so wire order == local-apply order for any pair that can observe each other
-    // (a read-dependent write reading a folded cell sees the same value optimistically and on the
-    // wire — no snap). Drained folds ship with smaller mids; this write's mid is dealt after.
-    this.drainOverlapping(touched);
-    const mid = this.nextMid++;
-    this.pendingMutations.push({ mid, name, args, touched });
-    // The prediction stuck — fold its child ops into the optimistic agg delta and push it onto
-    // the `__agg` head rows (§4). No reset here (this is the §1.3 trivial case, no rewind): the
-    // delta accumulates on top of the prior pending set, and `reconcileAggHead` recomputes each
-    // touched group's head as the absolute `server_base ⊕ delta`.
-    for (const op of ops) this.overlay.observe(op);
-    this.reconcileAggHead();
-    this.refreshPending(); // §7.2: this write now touches its queries' pending axis (NOT ResultType).
-    void this.source.pushMutation({ clientID: this.clientID, mid, name, args });
-    return mid;
   }
 
   /** Run a FOLDED invoke (FOLDED-MUTATIONS-DESIGN §8): apply the prediction to the live engine now
@@ -555,64 +617,68 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
     const mutator = this.registry[name];
     if (!mutator) throw new Error(`unknown client mutator: ${name}`);
     const foldKey = `${name}\0${stableJson(opts.key)}`;
-    // Apply the prediction with the read trap armed (§5): a folded mutator that reads state to
-    // compute its write is non-absorbing and refused. A throw discards the staged write (clean
-    // no-op) and consumes no mid — exactly `invoke`'s guarantee.
-    const touched = new Set<string>();
-    const ops: ChildOp[] = [];
-    try {
-      this.local.writeWith((tx) => {
-        mutator(trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops), true), args as never);
-      });
-    } catch (e) {
-      if (e instanceof FoldReadError) {
-        throw new Error(
-          `cannot fold "${name}": it reads state via tx.get/tx.row, so it is not absorbing — folded mutators must be last-writer-wins (FOLDED-MUTATIONS-DESIGN §5)`,
-        );
+    // One commit boundary spans the prediction AND the `__agg`-head reconcile (see {@link inOneCommit}),
+    // so a folded mutation's list view and count view flush together, never torn across two commits.
+    return this.inOneCommit(() => {
+      // Apply the prediction with the read trap armed (§5): a folded mutator that reads state to
+      // compute its write is non-absorbing and refused. A throw discards the staged write (clean
+      // no-op) and consumes no mid — exactly `invoke`'s guarantee.
+      const touched = new Set<string>();
+      const ops: ChildOp[] = [];
+      try {
+        this.local.writeWith((tx) => {
+          mutator(trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops), true), args as never);
+        });
+      } catch (e) {
+        if (e instanceof FoldReadError) {
+          throw new Error(
+            `cannot fold "${name}": it reads state via tx.get/tx.row, so it is not absorbing — folded mutators must be last-writer-wins (FOLDED-MUTATIONS-DESIGN §5)`,
+          );
+        }
+        throw e;
       }
-      throw e;
-    }
-    for (const op of ops) this.overlay.observe(op);
-    this.reconcileAggHead();
-
-    const now = this.clock.now();
-    let f = this.folds.get(foldKey);
-    if (f) {
-      // Overwrite the single entry in place — the pending stack does NOT grow (§1 #2). The head
-      // already carries this new prediction (absorbing, last-wins on the cell); the entry holds
-      // only the LATEST args, which is what a rebase re-derives from and what the flush ships.
-      f.entry.args = args;
-      f.entry.touched = touched;
-      f.args = args;
-      this.clock.clearTimeout(f.timer);
-    } else {
-      const entry: PendingMutation = { mid: null, name, args, touched };
-      this.pendingMutations.push(entry);
-      let resolveMid!: (mid: number) => void;
-      const midPromise = new Promise<number>((res) => (resolveMid = res));
-      f = {
-        entry,
-        args,
-        timer: undefined,
-        firstAt: now,
-        debounceMs: opts.debounceMs ?? DEFAULT_FOLD_DEBOUNCE_MS,
-        maxWaitMs: opts.maxWaitMs,
-        deferAcrossWrites: opts.deferAcrossWrites ?? false,
-        midPromise,
-        resolveMid,
-      };
-      this.folds.set(foldKey, f);
-    }
-    // (Re)arm the trailing debounce — unless the maxWaitMs cap is already due (a never-idle drag
-    // still persists periodically, §3/#4), in which case flush now instead of re-arming.
-    if (f.maxWaitMs !== undefined && now - f.firstAt >= f.maxWaitMs) {
-      this.flushFold(foldKey);
-    } else {
-      f.timer = this.clock.setTimeout(() => this.flushFold(foldKey), f.debounceMs);
-    }
-    this.refreshPending();
-    const handle: FoldHandle = { flush: () => this.flushFold(foldKey), mid: f.midPromise };
-    return handle;
+      for (const op of ops) this.overlay.observe(op);
+      this.reconcileAggHead();
+
+      const now = this.clock.now();
+      let f = this.folds.get(foldKey);
+      if (f) {
+        // Overwrite the single entry in place — the pending stack does NOT grow (§1 #2). The head
+        // already carries this new prediction (absorbing, last-wins on the cell); the entry holds
+        // only the LATEST args, which is what a rebase re-derives from and what the flush ships.
+        f.entry.args = args;
+        f.entry.touched = touched;
+        f.args = args;
+        this.clock.clearTimeout(f.timer);
+      } else {
+        const entry: PendingMutation = { mid: null, name, args, touched };
+        this.pendingMutations.push(entry);
+        let resolveMid!: (mid: number) => void;
+        const midPromise = new Promise<number>((res) => (resolveMid = res));
+        f = {
+          entry,
+          args,
+          timer: undefined,
+          firstAt: now,
+          debounceMs: opts.debounceMs ?? DEFAULT_FOLD_DEBOUNCE_MS,
+          maxWaitMs: opts.maxWaitMs,
+          deferAcrossWrites: opts.deferAcrossWrites ?? false,
+          midPromise,
+          resolveMid,
+        };
+        this.folds.set(foldKey, f);
+      }
+      // (Re)arm the trailing debounce — unless the maxWaitMs cap is already due (a never-idle drag
+      // still persists periodically, §3/#4), in which case flush now instead of re-arming.
+      if (f.maxWaitMs !== undefined && now - f.firstAt >= f.maxWaitMs) {
+        this.flushFold(foldKey);
+      } else {
+        f.timer = this.clock.setTimeout(() => this.flushFold(foldKey), f.debounceMs);
+      }
+      this.refreshPending();
+      const handle: FoldHandle = { flush: () => this.flushFold(foldKey), mid: f.midPromise };
+      return handle;
+    });
   }
 
   /** Flush-on-enqueue (§4.2): for each outstanding fold whose touched tables overlap `tables`,
@@ -695,6 +761,13 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
     this.resultTypeHandler = handler;
   }
 
+  __attachDevtoolsServerDeltas(observer: BackendDevObserver): () => void {
+    this.devObservers.add(observer);
+    return () => {
+      this.devObservers.delete(observer);
+    };
+  }
+
   // --- the pending AXIS (§7.2): orthogonal to ResultType -------------------------------
 
   /** Whether any pending mutation (folded or not) touches this query's tables — "is a prediction
@@ -771,6 +844,7 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
   // --- the downstream stream (§8.5: buffer, then release coherently) ---------------
 
   private onNormalized(qid: QueryId, ev: NormalizedEvent): void {
+    if (qid !== LMID_QID) this.emitServerDelta(qid, ev);
     if (ev.type === "hello") {
       // A hello is a (re)subscribe = a NEW epoch. The column map below is mutated eagerly, but
       // data frames are cv-buffered and drained later (onProgress). So any frame still buffered
@@ -807,6 +881,21 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
     if (this.buffer.length > this.bufferCap) this.overflow();
   }
 
+  private emitServerDelta(sourceQid: QueryId, ev: NormalizedEvent): void {
+    if (!this.devObservers.size) return;
+    for (const qid of this.localQidsForSource(sourceQid)) {
+      for (const o of this.devObservers) o.onServerDelta?.(qid, { format: "normalized", event: ev });
+    }
+  }
+
+  private localQidsForSource(sourceQid: QueryId): QueryId[] {
+    const key = this.sourceToRemote.get(sourceQid);
+    const sub = key ? this.remoteSubs.get(key) : undefined;
+    if (!sub) return [sourceQid];
+    const localQids = [...sub.localQids.keys()];
+    return localQids.length ? localQids : [sourceQid];
+  }
+
   private onProgress(frame: ProgressFrame): void {
     // (1) Take every buffered frame at cv ≤ cvMin, in (cv, arrival) order, and fold it:
     // lmid system-query frames advance `confirmedLmid`; data frames fold through the
@@ -978,7 +1067,6 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
   /** Recompute a query's server-channel state from hydration alone (§7): a pending mutation no
    *  longer affects it. Used when a remote sub attaches to or hydrates a local view. */
   private recomputeResultType(qid: QueryId): void {
-    if (!this.queryTables.has(qid)) return;
     this.setResultType(qid, this.hydrated.has(qid) ? "complete" : "unknown");
   }
 
@@ -1220,8 +1308,20 @@ function trackingTx(
     throw new FoldReadError();
   };
 
+  // One-shot query (203 §5.2): lower the builder to an AST, refuse any local-only table it
+  // reads (M1 — same guard as `rawGet`), and run it over the engine's read-cache fork. The
+  // wasm engine returns the rows already keyed by column name with their materialized
+  // relationship children nested by name (`marshal::caught_node_to_js`), in the query's order —
+  // identical in shape to `view.data` — so this is a pass-through.
+  const runQuery = (q: QueryArg): QueryResultRow[] => {
+    const ast = q.ast();
+    for (const t of collectTables(ast)) assertNotLocal(t, "read");
+    return tx.query(ast) as QueryResultRow[];
+  };
+
   return {
     get: trapReads ? trapped : rawGet,
+    query: trapReads ? trapped : runQuery,
     add,
     remove,
     edit,

package/src/client-id.ts

@@ -39,6 +39,22 @@ export function resetTabInstanceForTests(): void {
   tabInstance = 0;
 }
 
+/** Clear the persisted client identity so the next page load starts a fresh mid/lmid stream.
+ *  Intended for dev recovery after out-of-band server state loss, not for normal operation. */
+export function resetStableClientID(): void {
+  try {
+    globalThis.localStorage?.removeItem(CLIENT_ID_KEY);
+  } catch {
+    // Storage can throw in private modes or test shims; best-effort reset.
+  }
+  try {
+    globalThis.sessionStorage?.removeItem(TAB_ID_KEY);
+  } catch {
+    // Storage can throw in private modes or test shims; best-effort reset.
+  }
+  tabInstance = 0;
+}
+
 /** 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

@@ -20,7 +20,7 @@ import { initWasm } from "@rindle/wasm";
 
 import type { OptimisticBackend } from "./backend.ts";
 import type { ClientRegistry, MutationTx } from "./backend.ts";
-import { stableClientID } from "./client-id.ts";
+import { resetStableClientID, stableClientID } from "./client-id.ts";
 import { createOptimisticStore, type MutateFn } from "./index.ts";
 import type { Store } from "@rindle/client";
 
@@ -58,6 +58,13 @@ export interface RindleClientOptions<S extends ColsMap, R extends ClientRegistry
   /** A policy rejection's reason (the prediction's snap-back rides the lmid release). */
   onRejected?: (envelope: MutationEnvelope, reason: string) => void;
   queue?: { maxBatch?: number; retryDelayMs?: (attempt: number) => number };
+  /** Development-only recovery knobs. Keep off in production: a mutation gap means state loss
+   *  or two writers sharing a clientID, and should be investigated. */
+  dev?: {
+    /** On a mutation-gap response, clear the persisted clientID and hard reload the page. This
+     *  recovers from dev DB wipes while making the reset visible to the developer. */
+    resetOnMutationGap?: boolean;
+  };
 }
 
 export interface RindleClient<S extends ColsMap, R extends ClientRegistry> {
@@ -90,8 +97,9 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
       headers: { "content-type": "application/json", ...extra },
       body: JSON.stringify(payload),
     });
-    if (!res.ok) throw new Error(`rindle api ${path} failed: ${res.status} ${await res.text()}`);
-    return res.json();
+    const text = await res.text();
+    if (!res.ok) throw new RindleApiHttpError(path, res.status, text);
+    return text ? JSON.parse(text) : undefined;
   };
 
   // Reads-leg connection: a fixed transport (tests/in-process) or a replaceable connection built
@@ -116,8 +124,15 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
       retryDelayMs: opts.queue?.retryDelayMs,
       onRejected: opts.onRejected,
       send: async (envelopes) => {
-        const outcomes = (await post(routes.mutate, { envelopes })) as Array<{ accepted: boolean; reason?: string }>;
-        return outcomes.map((o): PushOutcome => ({ accepted: o.accepted, reason: o.reason }));
+        try {
+          const outcomes = (await post(routes.mutate, { envelopes })) as Array<{ accepted: boolean; reason?: string }>;
+          return outcomes.map((o): PushOutcome => ({ accepted: o.accepted, reason: o.reason }));
+        } catch (err) {
+          if (opts.dev?.resetOnMutationGap && reloadAfterMutationGap(err)) {
+            return new Promise<never>(() => {});
+          }
+          throw err;
+        }
       },
     }),
   });
@@ -154,3 +169,41 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
 
 export type { ClientRegistry, MutationTx };
 export type { MutateFn } from "./index.ts";
+
+class RindleApiHttpError extends Error {
+  readonly path: string;
+  readonly status: number;
+  readonly body: string;
+
+  constructor(path: string, status: number, body: string) {
+    super(`rindle api ${path} failed: ${status}${body ? ` ${body}` : ""}`);
+    this.name = "RindleApiHttpError";
+    this.path = path;
+    this.status = status;
+    this.body = body;
+  }
+}
+
+const MUTATION_GAP_RE = /\bmutation(?: id)? gap\b/i;
+
+function reloadAfterMutationGap(err: unknown): boolean {
+  const text =
+    err instanceof RindleApiHttpError
+      ? `${err.status} ${err.body} ${err.message}`
+      : String((err as Error)?.message ?? err);
+  if (!MUTATION_GAP_RE.test(text)) return false;
+
+  resetStableClientID();
+  console.error(
+    "[rindle] mutation gap detected; cleared the dev client id and reloading so this tab starts a fresh mutation stream.",
+    err,
+  );
+  const loc = (globalThis as unknown as { location?: { reload?: () => void } }).location;
+  if (typeof loc?.reload !== "function") return false;
+  try {
+    loc.reload();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -34,6 +34,8 @@ export type {
   OptimisticBackendOptions,
   OptimisticInspect,
   PendingInspect,
+  QueryArg,
+  QueryResultRow,
   ResultType,
 } from "./backend.ts";
 export type { MutationEnvelope, OptimisticSource, ProgressFrame } from "@rindle/client";
@@ -41,7 +43,7 @@ export type { MutationEnvelope, OptimisticSource, ProgressFrame } from "@rindle/
 // The one-call client for the daemon/serverless topology (API server + daemon ws).
 export { createRindleClient } from "./client.ts";
 export type { RindleClient, RindleClientOptions } from "./client.ts";
-export { stableClientID } from "./client-id.ts";
+export { resetStableClientID, stableClientID } from "./client-id.ts";
 
 /** A {@link Store} over an {@link OptimisticBackend}, plus the named-mutator entry
  *  (`mutate.createIssue(args)` — the §9 dream shape) and the §6 lifecycle surface. */