@doync/client 0.1.0

package/src/engine.ts

@@ -0,0 +1,3322 @@
+import type {
+  BoundQuery,
+  DoyncSchema,
+  MutationDefinition,
+  RowDecoder,
+  SqlValue,
+} from '@doync/core'
+import type {
+  DesiredQuery,
+  InstanceInfo,
+  OnceEndMessage,
+  Patch,
+  PksPatch,
+  SchemaDirectiveMessage,
+  SchemaSkewMessage,
+  ServerMessage,
+} from '@doync/core/internal'
+
+import { isBoundQuery } from '@doync/core/internal'
+import {
+  assertWireRepresentable,
+  canonicalizeArgsBinary,
+  declaredSchemaVersion,
+  decodeArgs,
+  decodeImageValue,
+  encodeArgs,
+  isInternalTable,
+} from '@doync/core/internal'
+
+import type { ClientMutationRegistry, ClientMutationTx } from './mutations'
+import type { LocalDb } from './port'
+import type { SeamStatus, SyncSocket } from './socket'
+
+import { asClientMutation, validateMutationArgs } from './mutations'
+import { RawRead, type LocalStatement } from './raw-read'
+import {
+  applyBundledMigrations,
+  assertNoReservedTables,
+  clearReleaseStamps,
+  createEngineTables,
+  decodePatchImage,
+  deleteReleaseStamp,
+  dropConsumerTables,
+  listReleaseStamps,
+  parsePk,
+  pkWhereClause,
+  quoteIdent,
+  readMeta,
+  readReleaseStamp,
+  replayMigrations,
+  requireTable,
+  resolveReleaseTtlMs,
+  upsertReleaseStamp,
+  writeMeta,
+  type ReleaseStamp,
+} from './replica'
+
+/**
+ * What `mutate()` returns: `client` settles when the optimistic body applies
+ * locally (rejects if the body throws or args fail validation); `server`
+ * settles when the Origin confirms or rejects the mutation. Render off
+ * `client`; await `server` when you need authoritative confirmation.
+ */
+export interface MutationResult {
+  readonly client: Promise<void>
+  readonly server: Promise<void>
+}
+
+// ADR-0022; closeio/doync#135/#139 (durable per-identity logout retention).
+/**
+ * What happens to this identity's local store on logout: `keep` leaves it so
+ * unsynced writes await the next login (default); `forget` erases it
+ * (shared-computer / privacy). Set at construction or via
+ * {@link DoyncClient.setLogoutBehavior}.
+ */
+export type LogoutBehavior = 'keep' | 'forget'
+
+/**
+ * The `__doync_meta` key the durable {@link LogoutBehavior} lives under
+ * (closeio/doync#135) — shared by the direct engine's
+ * {@link ClientEngine.setLogoutBehavior} / `createClient` write and the web DB
+ * worker's per-identity write + boot read, so the ends can never drift.
+ */
+export const __LOGOUT_BEHAVIOR_META_KEY = 'logout_behavior'
+
+/**
+ * The `__doync_meta` key the Client's durable connected-time counter lives
+ * under (ADR-0014 client-half addendum / closeio/doync#223). Blob-typed
+ * store-as-bound: no engine-track migration. Package-internal — release stamps
+ * (#224) and membership GC read it through the engine, not this key.
+ */
+export const __CONNECTED_CLOCK_META_KEY = 'connected_clock'
+
+// ADR-0020/0022 (schema-skew + recovery surface).
+/**
+ * Schema / recovery states the UI can show as a banner:
+ *
+ * - `reload` — client bundle cannot understand the server's shape; reload the app
+ *   after deploying a matching client. Terminal until reload.
+ * - `server-behind` — client is ahead of a mid-deploy Mirror; the client backs
+ *   off and re-handshakes automatically.
+ * - `resync` — local replica/memberships wiped and rebuilding; pending writes and
+ *   clientId survive. Transient; clears when sync resumes.
+ * - `forget` — local store erased (including identity); boots as a fresh client.
+ *   Transient; clears when sync resumes.
+ */
+export type SchemaEventKind = 'reload' | 'server-behind' | 'resync' | 'forget'
+
+/**
+ * One schema-status transition: `kind` plus a human-readable `message` for
+ * diagnostics (not a control signal). `null` on the client means nominal.
+ */
+export interface SchemaEvent {
+  readonly kind: SchemaEventKind
+  /** Human-readable reason (diagnostics; never a control signal). */
+  readonly message: string
+}
+
+/** Options for one `mutate()` call. */
+export interface MutationOptions {
+  /**
+   * Idempotency key: a second `mutate()` with a key already in flight (or
+   * already settled) returns the same `{client, server}` pair and enqueues
+   * nothing, so a retried submit never double-writes.
+   */
+  readonly key?: string
+}
+
+// ADR-0021 addendum; closeio/doync#104 (honest View status lifecycle).
+/**
+ * Whether a view's rows have been server-confirmed:
+ *
+ * - `unknown` — local answer only (fresh subscribe, skip, or reconnect). Rows may
+ *   already be present; this speaks to confirmation, not emptiness.
+ * - `complete` — server has confirmed this subscription's rows up to the current
+ *   sync point. Empty results can still be `complete`.
+ * - `error` — the Mirror could not honor the subscribe; detail on
+ *   {@link ViewStatus.error}.
+ */
+export type QueryStatus = 'unknown' | 'complete' | 'error'
+
+/**
+ * A view's status snapshot. The object reference is stable until the visible
+ * status changes, so it is safe for `useSyncExternalStore`.
+ */
+export interface ViewStatus {
+  readonly status: QueryStatus
+  /** Subscribe-failure detail; present only when `status` is `error`. */
+  readonly error?: Error
+}
+
+// closeio/doync#102/#105/#136 (connection status surface).
+/**
+ * Client ↔ Mirror connection state (backing for `useConnectionStatus`):
+ *
+ * - `connecting` — a (re)connect attempt is in flight
+ * - `connected` — socket open, sync live
+ * - `disconnected` — dropped and backing off
+ * - `error` — transport error
+ * - `needs-auth` — Mirror rejected auth; refresh credentials before sync resumes
+ */
+export type ConnectionStatus =
+  | 'connecting'
+  | 'connected'
+  | 'disconnected'
+  | 'error'
+  | 'needs-auth'
+
+// ADR-0019/0021/0023; closeio/doync#104/#120/#131/#137 (desire layer, Warm pool, status snapshots).
+/**
+ * A live, shared handle on a query's rows — what `subscribe()` and `local()`
+ * return, and what `useQuery` renders from.
+ *
+ * `current()` returns the latest rows; the array reference only changes when
+ * the rows do, so it is safe for `useSyncExternalStore`. `onChange` fires when
+ * the rows or the visible status move; re-read both `current()` and `status()`
+ * in the listener. A view keeps serving its last rows through disconnects and
+ * errors — check `status()` to tell fresh from stale.
+ *
+ * Lifecycle: creating a view is free and owns nothing. Call `retain()` when
+ * your component mounts, `release()` when it unmounts (both idempotent). Views
+ * for the same query share one subscription automatically.
+ */
+export interface View<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+> {
+  current(): readonly Row[]
+  onChange(listener: () => void): () => void
+  /**
+   * Take ownership of this handle (call from a mount effect, never during
+   * render). Idempotent per handle.
+   */
+  retain(): void
+  /**
+   * Drop ownership (call from unmount cleanup). The last release unsubscribes
+   * upstream; this handle keeps serving its last snapshot. Idempotent.
+   */
+  release(): void
+  /** Latest status snapshot. Moves ride the same `onChange` as row changes. */
+  status(): ViewStatus
+  /**
+   * `true` when the query is one-row (`` sql.one`…` `` / Drizzle `findFirst`),
+   * so `useQuery` unwraps to `Row | undefined`. `false` for multi-row;
+   * `undefined` when one-ness is not yet known.
+   */
+  readonly one?: boolean
+}
+
+// ADR-0012/0021/0023 (Once = cache-and-network, no ongoing subscription).
+/**
+ * A one-shot cache-and-network read — what `once()` returns and `useQueryOnce`
+ * renders from. `current()` is the local cache immediately; `server` resolves
+ * with the Mirror's answer (and updates the snapshot). Not reactive to later
+ * local writes. Call `dispose()` when done; a quick remount within a short
+ * grace keeps the same promise and in-flight request (StrictMode-safe).
+ */
+export interface OnceView<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+> {
+  current(): readonly Row[]
+  onChange(listener: () => void): () => void
+  dispose(): void
+  /** Resolves with the server's answer (network half of cache-and-network). */
+  readonly server: Promise<readonly Row[]>
+}
+
+/**
+ * The client call surface: `subscribe` / `once` / `local` / `mutate`, plus
+ * connection and schema status. Platform adapters (`@doync/web`,
+ * `@doync/mobile`) implement this; `@doync/react` hooks adapt over it.
+ *
+ * Query-taking methods accept a {@link BoundQuery} (from a registered query
+ * call) or {@link FalsyQuery} ("no query"). `options.skip` is also supported.
+ */
+export interface DoyncClient {
+  /**
+   * Live subscription for a bound query (`queries.foo(args)`). Falsy or
+   * `options.skip` yields an inert view (empty rows, status `unknown`).
+   */
+  subscribe<Row extends Record<string, unknown> = Record<string, SqlValue>>(
+    query: BoundQuery<Row, boolean> | FalsyQuery,
+    options?: SubscribeOptions,
+  ): View<Row>
+  /**
+   * One-shot cache-and-network read for a bound query. Falsy never starts a
+   * network half.
+   */
+  once<Row extends Record<string, unknown> = Record<string, SqlValue>>(
+    query: BoundQuery<Row, boolean> | FalsyQuery,
+  ): OnceView<Row>
+  /**
+   * Live local-only read of raw SQL against the replica (no server
+   * subscription). Same retain/release lifecycle as {@link subscribe}.
+   */
+  local<Row extends Record<string, unknown> = Record<string, SqlValue>>(
+    sql: string,
+    ...params: SqlValue[]
+  ): View<Row>
+  /**
+   * Apply a registered mutation optimistically and push it to the Origin. Pass
+   * the {@link MutationDefinition} from your mutations tree; args are
+   * type-checked from the definition. Returns {@link MutationResult}.
+   */
+  mutate<Args = unknown>(
+    mutation: MutationDefinition<Args>,
+    args: Args,
+    options?: MutationOptions,
+  ): MutationResult
+  /** Current schema/recovery state, or `null` when nominal. */
+  readonly schemaStatus: SchemaEvent | null
+  /**
+   * Subscribe to schema-status transitions (including a clear back to nominal).
+   * Returns the unsubscribe function.
+   */
+  onSchemaChange(listener: () => void): () => void
+  /**
+   * Wipe the replica and resubscribe while keeping clientId and pending writes.
+   * Safe "my local data looks wrong" refresh. Optional on the interface —
+   * platform clients implement it.
+   */
+  resync?(): void
+  /**
+   * Erase this identity's local data (replica, pendings, identity). Privacy /
+   * logout-forget path. Optional on the interface — platform clients implement
+   * it.
+   */
+  forget?(): void
+  /**
+   * Durably set {@link LogoutBehavior} at runtime (e.g. a "remember me"
+   * checkbox). Survives restart. Optional — platform clients implement it.
+   */
+  setLogoutBehavior?(behavior: LogoutBehavior): void
+  /**
+   * Authenticated identity, or `null` when anonymous. Updated by auth refresh;
+   * never derived from a bearer token by the library.
+   */
+  readonly userId: string | null
+  /**
+   * Warm the replica for a query without creating a local view — rows flow in
+   * for other queries that read the same tables. Falsy yields a no-op handle.
+   * Call `cleanup()` to release (often never, for a session-long preload).
+   */
+  preload(
+    query: BoundQuery | FalsyQuery,
+    options?: PreloadOptions,
+  ): PreloadHandle
+  /** Current {@link ConnectionStatus} to the Mirror. */
+  readonly connectionStatus: ConnectionStatus
+  /** Subscribe to connection-status transitions. Returns the unsubscribe. */
+  onConnectionChange(listener: () => void): () => void
+}
+
+/**
+ * Falsy "no query" on subscribe / once / preload: `false | null | undefined`.
+ * Lets `cond && query(args)` and optional-prop patterns type-check.
+ */
+export type FalsyQuery = false | null | undefined
+
+/** Per-subscribe options. */
+export interface SubscribeOptions {
+  /**
+   * How long after unmount the server keeps this subscription warm, in ms of
+   * connected time. Absent ⇒ server default (clamped to its ceiling).
+   */
+  readonly ttl?: number
+  /**
+   * Skip the subscribe: empty rows, status `unknown`, no network. Use for
+   * conditional queries under React's unconditional-hooks rule.
+   */
+  readonly skip?: boolean
+}
+
+/** Options for {@link DoyncClient.preload}. */
+export interface PreloadOptions {
+  /**
+   * Connected-time grace after cleanup before the server drops the warm
+   * subscription, in ms. Absent ⇒ server default.
+   */
+  readonly ttl?: number
+}
+
+/** Handle returned by {@link DoyncClient.preload}. */
+export interface PreloadHandle {
+  /**
+   * Release the preload. Idempotent; typically unused for a session-long
+   * preload.
+   */
+  cleanup(): void
+}
+
+export interface ClientEngineConfig {
+  /**
+   * The synchronous local-DB port (ADR-0019): node:sqlite in tests, wa-sqlite
+   * on the web.
+   */
+  readonly db: LocalDb
+  /**
+   * The consumer's synced schema — the shape source replayed for the replica
+   * (ADR-0020).
+   */
+  readonly schema: DoyncSchema
+  /**
+   * Named mutation bodies resolved on `push` — deterministic, DB-only
+   * (ADR-0017/0021).
+   */
+  readonly mutations: ClientMutationRegistry
+  /** The Mirror socket seam (ADR-0016). */
+  readonly socket: SyncSocket
+  /**
+   * The asserted projected auth context (ADR-0018 addendum / closeio/doync#167)
+   * queries and mutation bodies read. Consumer-owned; the library ships no
+   * decode. Anonymous `{}`.
+   */
+  readonly ctx?: Record<string, unknown>
+  /**
+   * Transport credential PRESENTED as `connect{jwt}` (ADR-0016/0018) — the
+   * Mirror resolves token-first. Auth must ride the HANDSHAKE, not only the
+   * WebSocket upgrade's Cookie header: the socket lives in the SharedWorker and
+   * can OUTLIVE a login. The engine NEVER derives identity from this token;
+   * {@link userId} and {@link ctx} are the asserted siblings.
+   */
+  readonly token?: string
+  /**
+   * The ASSERTED authenticated identity (closeio/doync#167) — drives
+   * {@link ClientEngine.userId}. `null` / omitted = anonymous. Never derived
+   * from {@link token}.
+   */
+  readonly userId?: string | null
+  /**
+   * The durable clientId (ADR-0019's respawn-double-apply trap): reused from
+   * `__doync_meta` when present, else this value, else generated. Provide it to
+   * pin identity across engine restarts over the same DB.
+   */
+  readonly clientId?: string
+  /**
+   * ClientId generator when none is stored/provided (default:
+   * `crypto.randomUUID`). Test-only pin — production paths always provide
+   * {@link clientId} or accept a random UUID.
+   */
+  readonly generateId?: () => string
+  /**
+   * Consume schema-state transitions (ADR-0020): a stale-client or above-bundle
+   * skew (`reload`), a client-ahead skew (`server-behind`), or a
+   * post-failed-migration wipe (`resync`). The UI layer reloads the app on
+   * `reload` and can surface a retry banner on `server-behind`; the engine
+   * drives the recovery itself (re-handshake / wipe). The current state is also
+   * readable synchronously via {@link ClientEngine.schemaStatus}.
+   */
+  readonly onSchemaEvent?: (event: SchemaEvent) => void
+  /**
+   * Wall-clock source for the connected-time counter (ADR-0014 client half /
+   * closeio/doync#223). Defaults to `Date.now`. Injectable so Seam A tests pin
+   * pong deltas without real timers; package-internal — never a public
+   * surface.
+   */
+  readonly now?: () => number
+}
+
+/**
+ * Durable pending mutation mirrored from `__doync_pending`. `args` = live
+ * canonicalized JS for replay (#230). `wireArgs` = reserved-key form in the
+ * queue and on push (ADR-0031 / #231). Reload decodes wire -> live.
+ */
+interface PendingMutation {
+  readonly mutationId: number
+  readonly name: string
+  readonly args: unknown
+  readonly wireArgs: unknown
+  readonly key: string | undefined
+}
+
+/** Resolvers for one mutation's `{client, server}` pair. */
+interface PendingPromise {
+  readonly pair: MutationResult
+  resolveClient: () => void
+  rejectClient: (error: unknown) => void
+  resolveServer: () => void
+  rejectServer: (error: unknown) => void
+  clientSettled: boolean
+  serverSettled: boolean
+}
+
+const OPTIMISTIC_SAVEPOINT = 'doync_optimistic'
+const BODY_SAVEPOINT = 'doync_body'
+
+/**
+ * Client engine (ADR-0019): synchronous local-DB port + socket seam +
+ * optimistic Layer 1.
+ *
+ * Durable base (consumer tables, `__doync_membership`, `__doync_meta`) stays
+ * committed. One held SAVEPOINT ({@link OPTIMISTIC_SAVEPOINT}) layers pending
+ * bodies in order; same-connection reads see that uncommitted state. Durable
+ * `__doync_pending` is written only while the overlay is closed, so an overlay
+ * crash loses the guess and boot replays from the queue. Every durable write
+ * closes the overlay (`ROLLBACK TO` → `RELEASE`), commits outside it, then
+ * reopens and replays survivors — overlay always equals current pendings on
+ * current base.
+ *
+ * Rebase, never merge: a poke rolls the guess off, applies authoritative
+ * patches (puts before dels; row delete only when last membership drops), drops
+ * rejected-then-acked pendings, persists cookie only on pokeEnd, then replays
+ * survivors. A rejected write vanishes by not replaying.
+ */
+/**
+ * Internal confirmation phase for a desired Subscription (closeio/doync#104),
+ * finer than visible {@link QueryStatus}:
+ *
+ * - `pending` — subscribe/connect sent, no ack yet (visible `unknown`)
+ * - `acked` — `subscribeAck` seen; waiting for a `pokeEnd` that names this
+ *   instance in `confirms` (#114) (visible `unknown`)
+ * - `complete` — that hydration/reactivation pokeEnd confirmed it
+ * - `error` — Mirror framed a subscribe failure for this instance
+ *
+ * `pending`↔`acked` share visible `unknown`, so that step neither swaps status
+ * references nor notifies.
+ */
+type SubPhase = 'pending' | 'acked' | 'complete' | 'error'
+
+/**
+ * Mount declaration shared by `subscribe`, `preload`, and the desire layer:
+ * wire name+args, declared ttl, and the resolved local statement.
+ */
+interface SubscriptionSpec {
+  readonly name: string
+  readonly args: unknown
+  readonly ttl: number | undefined
+  readonly statement: LocalStatement
+}
+
+/**
+ * One desired Subscription (refcounted), keyed by statement identity. Shared by
+ * live subscribes and `preload` (preload = desire with no View). Wire `heldAt`
+ * is NOT stored — re-derived from live membership + release stamps on every
+ * (re)send (ADR-0029) so reconnect attests what the replica holds NOW.
+ */
+interface DesiredEntry {
+  readonly name: string
+  readonly args: unknown
+  /**
+   * Widest ttl any retain declared (#102 ratchet — see `#retainDesire`; release
+   * never lowers it).
+   */
+  ttl: number | undefined
+  /**
+   * Retained holders only (ADR-0023: commit owns): retained Views + preloads.
+   * Handle creation does not count. 0→1 sends `subscribe`; last release sends
+   * `unsubscribe` immediately (#120/Q2 — Warm pool is paint budget, not wire
+   * lifetime).
+   */
+  count: number
+  /**
+   * Shared reactive read for this instance (ADR-0023 share-raw). `null` for
+   * preload-only (no local execution — #104).
+   */
+  read: RawRead | null
+  /** Confirmation phase driving View {@link QueryStatus} (#104). */
+  phase: SubPhase
+  /** Subscribe-failure detail when `phase` is `error` (#104). */
+  error: Error | undefined
+}
+
+/**
+ * Local-read slot (sql+params key): shared RawRead + retain count. Same retain
+ * / warm lifecycle as {@link DesiredEntry}, no wire half.
+ */
+interface LocalReadEntry {
+  count: number
+  read: RawRead | null
+}
+
+/**
+ * View handle from `subscribe()`/`local()` (CONTEXT.md; ADR-0023). Creation is
+ * pure compute; `retain()` is first ownership (0→1 sends wire `subscribe`).
+ * Last `release()` unsubscribes immediately (#120/Q2) and parks the read in the
+ * Warm pool for one tick.
+ *
+ * Stale-but-stable (Q1): after Warm eviction the handle keeps last rows/status
+ * until a re-retain's read notifies fresh ones. `onChange` listeners re-wire
+ * onto the recreated read so the handle never observes the gap.
+ */
+class ViewHandle implements View<Record<string, unknown>> {
+  /** Whether THIS handle currently retains (idempotent; #120). */
+  #held = false
+  #unwire: (() => void) | null = null
+  readonly #listeners = new Set<() => void>()
+  #lastRows: readonly Record<string, unknown>[] = EMPTY_ROWS
+  #lastStatus: ViewStatus = UNKNOWN_STATUS
+  #seeded = false
+  /**
+   * Decode memo (Q4): read identity + generation that produced `#lastRows`
+   * (recreated reads restart generations).
+   */
+  #decodedFrom: { read: RawRead; generation: number } | null = null
+
+  constructor(
+    /**
+     * Retain/release/peek for the shared read; `compute` is pure discardable
+     * seed.
+     */
+    private readonly lifecycle: {
+      retain(): RawRead
+      release(): void
+      peek(): RawRead | null
+      /**
+       * Pure creation-time compute (ADR-0023/Q3): run statement + decode, no
+       * shared state. Caller snapshot-gates mid-replay (torn overlay → empty
+       * seed; commit-time read supplies truth).
+       */
+      compute(): {
+        rows: readonly Record<string, unknown>[]
+        status: ViewStatus
+      }
+    },
+    /**
+     * Per-handle decode (Q4): never keyed by statement — two flavors with
+     * identical SQL share one RawRead and decode here, memoized on generation.
+     */
+    private readonly decode: RowDecoder | undefined,
+    readonly one: boolean | undefined,
+  ) {}
+
+  /** Decode shared raw rows with this handle's flavor, memoized on generation. */
+  #project(read: RawRead): readonly Record<string, unknown>[] {
+    if (
+      this.#decodedFrom?.read !== read ||
+      this.#decodedFrom.generation !== read.generation
+    ) {
+      const raw = read.rawRows()
+      this.#lastRows = this.decode
+        ? this.decode(raw as readonly Record<string, SqlValue>[])
+        : raw
+      this.#decodedFrom = { read, generation: read.generation }
+    }
+    return this.#lastRows
+  }
+
+  /**
+   * Lazy first-paint seed (Q1/Q3): prefer the live shared read (another retain
+   * or Warm pool), else pure `compute` once. Discarded renders that never read
+   * stay zero-cost; retain-then-read shares the live read's execution.
+   */
+  #seed(): void {
+    if (this.#seeded) return
+    this.#seeded = true
+    const read = this.lifecycle.peek()
+    if (read !== null) {
+      this.#project(read)
+      this.#lastStatus = read.status()
+    } else {
+      const seed = this.lifecycle.compute()
+      this.#lastRows = seed.rows
+      this.#lastStatus = seed.status
+    }
+  }
+
+  current(): readonly Record<string, unknown>[] {
+    const read = this.lifecycle.peek()
+    if (read !== null && read.generation > 0) {
+      this.#seeded = true
+      return this.#project(read)
+    }
+    this.#seed()
+    return this.#lastRows
+  }
+
+  status(): ViewStatus {
+    const read = this.lifecycle.peek()
+    if (read !== null) {
+      this.#seeded = true
+      this.#lastStatus = read.status()
+      return this.#lastStatus
+    }
+    this.#seed()
+    return this.#lastStatus
+  }
+
+  onChange(listener: () => void): () => void {
+    this.#listeners.add(listener)
+    return () => this.#listeners.delete(listener)
+  }
+
+  retain(): void {
+    if (this.#held) return
+    this.#held = true
+    this.#seeded = true
+    const read = this.lifecycle.retain()
+    // One forwarder per handle onto the (possibly recreated) shared read.
+    this.#unwire = read.onChange(() => {
+      this.#project(read)
+      this.#lastStatus = read.status()
+      for (const l of this.#listeners) l()
+    })
+    // Re-project when the live read is newer than our snapshot. Generation 0
+    // (gated initial compute) holds nothing fresher than any seed — must not
+    // overwrite; its first real recompute notifies via the wire above (Q1:
+    // never blank, only move forward).
+    if (
+      (read.generation > 0 &&
+        (this.#decodedFrom?.read !== read ||
+          this.#decodedFrom.generation !== read.generation)) ||
+      read.status() !== this.#lastStatus
+    ) {
+      if (read.generation > 0) this.#project(read)
+      this.#lastStatus = read.status()
+      for (const l of this.#listeners) l()
+    }
+  }
+
+  release(): void {
+    if (!this.#held) return
+    this.#held = false
+    this.#unwire?.()
+    this.#unwire = null
+    this.lifecycle.release()
+  }
+}
+
+export class ClientEngine implements DoyncClient {
+  readonly #db: LocalDb
+  readonly #schema: DoyncSchema
+  readonly #mutations: ClientMutationRegistry
+  readonly #socket: SyncSocket
+  /**
+   * Projected auth ctx (ADR-0018) for queries/bodies. Updated by
+   * {@link updateAuth} on same-user refresh (#102).
+   */
+  #ctx: Record<string, unknown>
+  /**
+   * Bearer for every handshake (ADR-0016/0018). Updated by {@link updateAuth} so
+   * refresh rides in-band update AND the next reconnect (#102).
+   */
+  #token: string | undefined
+  /**
+   * Asserted identity (#104 / #167) from construction / {@link updateAuth}.
+   * Never derived from {@link #token}.
+   */
+  #userId: string | null = null
+
+  #clientId!: string
+  /**
+   * ClientId mint (config `generateId` or {@link defaultGenerateID}). Kept so
+   * `forget()` and corrupt-meta heal can mint mid-session, not only at boot.
+   */
+  readonly #generateId: () => string
+  /** Durable next-mutation-id high-water mark (ADR-0019). */
+  #nextMutationId = 1
+  /** Origin-commit cookie; advances only on pokeEnd. */
+  #cookie: number | null = null
+  #connected = false
+  /**
+   * Connected-time ms (ADR-0014 client / #223): pong deltas while connected;
+   * frozen offline. Currency for release stamps and membership GC. Memory
+   * first; piggybacks durable rebases (naive meta write would join the overlay
+   * and roll back — #139). Lost ticks ⇒ clock runs SLOW (safe).
+   */
+  #connectedClock = 0
+  /**
+   * Wall time of previous pong on THIS connection (`null` until first pong).
+   * Re-anchored on open/close so disconnect gaps add nothing.
+   */
+  #lastPongAt: number | null = null
+  /** Wall clock for pong deltas (injectable in tests). */
+  readonly #now: () => number
+  /**
+   * Sticky auth failure (#136, ADR-0018): set on framed `unauthorized` (engine
+   * inference — seam never reports it). Sticky across backoff until a
+   * substantive frame proves a refreshed handshake (same as shared-hub.ts).
+   * Outranks seam report and live `open` in {@link connectionStatus}.
+   */
+  #needsAuth = false
+  /**
+   * Last optional seam transient (#136), or `null` if never reported / cleared
+   * by live open. Surfaces in {@link connectionStatus} only when neither open
+   * nor needs-auth wins.
+   */
+  #seamStatus: SeamStatus | null = null
+  #overlayOpen = false
+  /**
+   * Connection-status subscribers (#105): notified when visible
+   * {@link connectionStatus} flips.
+   */
+  readonly #connectionListeners = new Set<() => void>()
+
+  /** Bundled schema version — handshake skew currency (ADR-0020). */
+  #bundleVersion = 0
+  /**
+   * Replica data schema version in `__doync_meta`. Fresh → `#bundleVersion`;
+   * persists until mid-session `schema` directives advance it.
+   */
+  #appliedVersion = 0
+  /** Current schema-handling state, or `null` when nominal (ADR-0020). */
+  #schemaEvent: SchemaEvent | null = null
+  readonly #onSchemaEvent: ((event: SchemaEvent) => void) | undefined
+  /**
+   * Schema-state subscribers (#89): every transition including silent clear.
+   * Config `onSchemaEvent` fires only on NEW state (clears emit nothing), so a
+   * banner on that alone sticks after recovery — hooks use this +
+   * `schemaStatus`.
+   */
+  readonly #schemaListeners = new Set<() => void>()
+  /**
+   * After `reload` skew: stop handshakes and frame apply until app reload
+   * (ADR-0020).
+   */
+  #halted = false
+
+  /** Durable pending queue, ascending mutation id. */
+  #pending: PendingMutation[] = []
+  /** `{client, server}` resolvers by mutation id. */
+  readonly #promises = new Map<number, PendingPromise>()
+  /** Idempotency key → result pair (ADR-0019 retry-once). */
+  readonly #keyed = new Map<string, MutationResult>()
+  /**
+   * Keys reloaded from durable queue at boot (ADR-0019): pairs are orphaned (no
+   * caller awaits; settlement swallowed). A DB_FAILOVER retry on a respawned
+   * engine must treat client phase as already applied.
+   */
+  readonly #recoveredKeys = new Set<string>()
+  /** Mutids dropped by `pokeReject` — never resolved by a later lmid. */
+  readonly #rejected = new Set<number>()
+  /** Mutids whose body threw in the latest optimistic replay. */
+  readonly #optimisticFailed = new Map<number, unknown>()
+
+  /** SubscribeAck metadata (Read-set + Level→table). */
+  readonly #instanceInfo = new Map<string, InstanceInfo>()
+  /**
+   * Desired set by statement identity. `heldAt` re-derived on send from
+   * membership + stamps (ADR-0029), not stored.
+   */
+  readonly #desired = new Map<string, DesiredEntry>()
+  /**
+   * In-flight Once (ADR-0012) by client id: view + wire `{name, args}` for
+   * reconnect re-issue (Once is not durable).
+   */
+  readonly #onceRequests = new Map<
+    string,
+    { view: OnceViewImpl; name: string; args: unknown }
+  >()
+  /**
+   * Once answer accumulation (ADR-0012): start → parts → end. Feeds OnceView,
+   * never replica/cookie.
+   */
+  readonly #onceBuffers = new Map<string, Record<string, unknown>[]>()
+  #nextOnceSeq = 1
+  /**
+   * Local shared raw reads (ADR-0019: re-run on any local commit, unhinted).
+   * Separate from {@link DesiredEntry} so each reactive read has one owner
+   * (ADR-0023 one-count).
+   */
+  readonly #localReads = new Map<string, LocalReadEntry>()
+  /**
+   * Warm pool (CONTEXT.md; ADR-0023): last-release reads kept one tick outside
+   * `#desired` (desired = handshake truth — #120). Re-retain reclaims rows and
+   * re-sends `subscribe`; wire `unsubscribe` already fired (Q2).
+   */
+  readonly #warmReads = new Map<
+    string,
+    { read: RawRead; timer: ReturnType<typeof setTimeout> }
+  >()
+  /**
+   * Consumer tables written by the current overlay. Overlay rollback removes
+   * those optimistic rows — rebase must re-project them even without a patch or
+   * survivor rewrite (else phantoms of rejected/acked-away guesses).
+   */
+  #overlayTables = new Set<string>()
+
+  /** Patches between pokeStart and pokeEnd; `null` when idle. */
+  #pokeBuffer: Patch[] | null = null
+  /** Framed protocol errors — never silent (ADR-0016). */
+  readonly #errors: string[] = []
+
+  /**
+   * Exclusive chain (ADR-0019 addendum). True while an overlay-touching op runs
+   * and STAYS true across an awaited body so concurrent JS sees busy. Sync ops
+   * set/clear without yield — observers only see true during async replay.
+   * Serialization latch ({@link #chainQueue}) and snapshot gate (defer new view
+   * initial reads). All-sync bodies never queue or gate.
+   */
+  #chainBusy = false
+  /** Ops deferred behind in-flight async replay (FIFO). */
+  readonly #chainQueue: ChainStep[] = []
+  /**
+   * Views whose initial recompute was gated mid-async-replay (torn overlay).
+   * Flushed when the chain idles.
+   */
+  readonly #gatedViews = new Set<RawRead>()
+
+  constructor(config: ClientEngineConfig) {
+    this.#db = config.db
+    this.#schema = config.schema
+    this.#mutations = config.mutations
+    this.#socket = config.socket
+    this.#ctx = config.ctx ?? {}
+    this.#token = config.token
+    // Asserted identity (#167) — never from the token.
+    this.#userId = config.userId ?? null
+    this.#onSchemaEvent = config.onSchemaEvent
+    this.#generateId = config.generateId ?? defaultGenerateID
+    this.#now = config.now ?? Date.now
+    this.#boot(config)
+    this.#socket.setHandlers({
+      message: (message) => this.#onMessage(message),
+      open: () => this.#onOpen(),
+      close: () => {
+        // Freeze connected clock across the gap (ADR-0014 / #223): clear pong
+        // anchor so the first post-open pong contributes nothing.
+        this.#lastPongAt = null
+        this.#setConnected(false)
+      },
+      // Optional seam status (#136): reconnecting adapters feed connecting/error.
+      status: (status) => this.#onSeamStatus(status),
+    })
+  }
+
+  /**
+   * In-memory connected-time ms (ADR-0014 / #223). Package-internal for release
+   * stamps (#224) and membership GC — not on {@link DoyncClient}.
+   */
+  get connectedClock(): number {
+    return this.#connectedClock
+  }
+
+  /**
+   * Durable release stamp for one instance, or `null` (ADR-0014 / #224).
+   * Package-internal for `heldAt` (#225) and GC (#226).
+   */
+  releaseStamp(instance: string): ReleaseStamp | null {
+    return readReleaseStamp(this.#db, instance)
+  }
+
+  /**
+   * Every parked release stamp (#226 hygiene GC). Package-internal; order
+   * unspecified.
+   */
+  releaseStamps(): ReleaseStamp[] {
+    return listReleaseStamps(this.#db)
+  }
+
+  /** Durable clientId (stable across restarts on the same DB). */
+  get clientId(): string {
+    return this.#clientId
+  }
+
+  /**
+   * Asserted `userId` from construction / {@link updateAuth}, or `null` (#104 /
+   * #167). Never derived from a bearer (ADR-0018) — cookie sessions assert
+   * `userId` with no token.
+   */
+  get userId(): string | null {
+    return this.#userId
+  }
+
+  /** Scalar cookie held now (`null` on first sight). */
+  get cookie(): number | null {
+    return this.#cookie
+  }
+
+  /** Framed protocol errors (`error` frames, stray poke parts). */
+  get errors(): readonly string[] {
+    return this.#errors
+  }
+
+  /**
+   * Idempotency keys recovered at boot (ADR-0019). A DB_FAILOVER retry on a
+   * respawned engine gets the recovered pair whose orphaned `client` never
+   * settles for it — treat client phase as already applied.
+   */
+  get recoveredKeys(): ReadonlySet<string> {
+    return this.#recoveredKeys
+  }
+
+  /** Bundled schema version (ADR-0020) — declared on every handshake for skew. */
+  get schemaVersion(): number {
+    return this.#bundleVersion
+  }
+
+  /**
+   * Schema-handling state, or `null` when nominal (ADR-0020). Sync counterpart
+   * to {@link ClientEngineConfig.onSchemaEvent} for reload/retry UI.
+   */
+  get schemaStatus(): SchemaEvent | null {
+    return this.#schemaEvent
+  }
+
+  // --- boot / durable state -------------------------------------------------
+
+  #boot(config: ClientEngineConfig): void {
+    const db = this.#db
+    // Clients apply state, never enforce (ADR-0009/0020).
+    db.exec('PRAGMA foreign_keys = OFF')
+    assertNoReservedTables(this.#schema)
+    // Engine track via `__doync_engine` ledger (ADR-0024). Ledger-above-bundle
+    // rebuilds engine tables and flags consumer wipe-and-resync below.
+    const { rolledBack } = createEngineTables(db)
+    if (rolledBack) {
+      // Consumer half of wipe-and-resync: drop tables + memberships, re-replay
+      // bundle from empty, null cookie. Pending + clientId + ledger survive.
+      dropConsumerTables(db, this.#schema)
+      db.exec('DELETE FROM __doync_membership')
+      writeMeta(db, 'schema_version', '0')
+      applyBundledMigrations(
+        db,
+        this.#schema,
+        0,
+        declaredSchemaVersion(this.#schema),
+      )
+      this.#cookie = null
+      db.exec('DELETE FROM __doync_meta WHERE k = ?', 'cookie')
+    } else {
+      replayMigrations(db, this.#schema)
+    }
+    this.#bundleVersion = declaredSchemaVersion(this.#schema)
+
+    // Corrupt-meta heal (ADR-0022): non-integer durable counters cannot boot
+    // safely (NaN would ride wire as cookie/lmid or reissue mutids — ADR-0019
+    // next-id trap; corrupt mut counter makes pending untrustworthy). Loud
+    // forget-shaped heal to a fresh first-sight base, then mint clientId /
+    // empty queue below. Emit the reset only after that state exists.
+    const corruptKey = corruptMetaKey(db)
+    if (corruptKey !== null) {
+      // Silent would look like data loss — name the corruption and consequence.
+      console.error(
+        `doync: durable meta "${corruptKey}" is corrupt — healing by ` +
+          `FORGETTING the local store (fresh identity, full re-hydration). A ` +
+          `corrupt mutation counter makes the pending queue untrustworthy, so ` +
+          `unsynced writes are discarded rather than risk double-apply.`,
+      )
+      this.#forgetStore(db)
+    }
+
+    this.#appliedVersion = this.#durableInt(db, 'schema_version') ?? 0
+
+    // Reuse durable clientId when present (respawn-double-apply trap). Heal
+    // cleared it ⇒ mint fresh first-sight id.
+    const stored = readMeta(db, 'client_id')
+    this.#clientId = stored ?? config.clientId ?? this.#generateId()
+    if (stored === null) writeMeta(db, 'client_id', this.#clientId)
+
+    // Independent high-water mark (not MAX(pending)+1).
+    this.#nextMutationId = this.#durableInt(db, 'next_mutation_id') ?? 1
+    this.#cookie = this.#durableInt(db, 'cookie')
+    // Connected clock (ADR-0014 / #223): resume last persisted reading. Lost
+    // unpersisted ticks ⇒ slow (safe). Lenient outside forget heal — corrupt
+    // clock must not cost identity/pending (never rides wire); zero matches
+    // crash-loss direction.
+    const storedClock = Number(readMeta(db, __CONNECTED_CLOCK_META_KEY))
+    if (Number.isInteger(storedClock) && storedClock >= 0) {
+      this.#connectedClock = storedClock
+    } else {
+      if (readMeta(db, __CONNECTED_CLOCK_META_KEY) !== null) {
+        console.warn(
+          'doync: durable connected-clock reading is corrupt — resetting to 0 (clock runs slow; GC defers, server full-hydrates)',
+        )
+      }
+      this.#connectedClock = 0
+    }
+    this.#lastPongAt = null
+
+    // Emit corrupt-meta forget only once clientId/cookie are initialized.
+    if (corruptKey !== null) {
+      this.#emitSchemaEvent(
+        'forget',
+        `corrupt durable meta "${corruptKey}" — forgot the local store and ` +
+          `reset to a fresh identity`,
+      )
+    }
+
+    // Reload durable pending; decode reserved-key JSON (ADR-0031 / #231) so
+    // replay sees live ArrayBuffers matching the original optimistic bind.
+    this.#pending = db
+      .exec<{
+        mutation_id: SqlValue
+        name: SqlValue
+        args: SqlValue
+        idem_key: SqlValue
+      }>(
+        `SELECT mutation_id, name, args, idem_key FROM __doync_pending ORDER BY mutation_id ASC`,
+      )
+      .map((row) => {
+        const wireArgs = JSON.parse(String(row.args)) as unknown
+        return {
+          mutationId: Number(row.mutation_id),
+          name: String(row.name),
+          wireArgs,
+          args: decodeArgs(wireArgs, 'mutation args'),
+          key: row.idem_key === null ? undefined : String(row.idem_key),
+        }
+      })
+    for (const p of this.#pending) {
+      // Orphan promises: swallow settlement (no caller awaits reloaded pendings).
+      const promise = this.#ensurePromise(p.mutationId, true)
+      if (p.key !== undefined) {
+        this.#keyed.set(p.key, promise.pair)
+        this.#recoveredKeys.add(p.key)
+      }
+    }
+    // Membership GC at boot (ADR-0014 / #226): aged stamped releases only.
+    // Defer stampless until in-session (`#desired` live) — at boot every
+    // instance looks undesired, so stampless would wipe live memberships that
+    // only survived process death / DB-worker failover. Before overlay opens
+    // (plain autocommit). Clock piggybacks only when the sweep has work.
+    this.#runMembershipGc({ includeStampless: false })
+
+    // Discard bootstrap writes before opening the overlay.
+    db.drainWrittenTables()
+    // Initial overlay is usually sync. Async durable pending cannot be awaited
+    // in the constructor — hold chain busy (gate reads) until it lands.
+    const opened = this.#openOverlay()
+    if (isThenable(opened)) {
+      this.#chainBusy = true
+      opened.then(
+        () => this.#finishChainStep(),
+        () => this.#finishChainStep(),
+      )
+    }
+  }
+
+  /**
+   * Durable integer meta (ADR-0015/0019). `null` when unset (caller default;
+   * cookie may stay null). Present-but-corrupt throws — never silent NaN on the
+   * wire (ADR-0019 next-id trap).
+   *
+   * At boot the throw is unreachable: {@link corruptMetaKey} + ADR-0022 heal
+   * clear the store first. Kept as fail-loud tripwire for values the heal
+   * missed (invariant break).
+   */
+  #durableInt(db: LocalDb, key: string): number | null {
+    const raw = readMeta(db, key)
+    if (raw === null) return null
+    const n = Number(raw)
+    if (!Number.isInteger(n)) {
+      throw new Error(
+        `doync: durable meta "${key}" is corrupt (${JSON.stringify(raw)} → ` +
+          `${n}) — a non-integer must never ride the wire (ADR-0019 next-id ` +
+          `trap); the boot-time corrupt-meta heal should have caught this`,
+      )
+    }
+    return n
+  }
+
+  // --- the exclusive chain (ADR-0019 addendum) ------------------------------
+
+  /**
+   * Run one overlay-touching op on the exclusive chain. Idle ⇒ run now (sync
+   * path stays fully sync). Busy ⇒ queue until prior finishes so mutate /
+   * rebase / poke never interleave and an awaited body only defers its paint.
+   */
+  #exclusive(work: ChainStep): void {
+    if (this.#chainBusy) {
+      this.#chainQueue.push(work)
+      return
+    }
+    this.#chainBusy = true
+    this.#runExclusive(work)
+  }
+
+  #runExclusive(work: ChainStep): void {
+    let running: Awaitable<void>
+    try {
+      running = work()
+    } catch (error) {
+      // Sync throw: free chain and rethrow (same surface as pre-chain code).
+      this.#chainBusy = false
+      this.#drainOrFlush()
+      throw error
+    }
+    if (isThenable(running)) {
+      running.then(
+        () => this.#finishChainStep(),
+        (error: unknown) => {
+          // Async rejection cannot reach the sync caller — frame it (ADR-0016)
+          // and free the chain so the engine is not wedged.
+          this.#errors.push(
+            `doync: exclusive-chain step rejected — ${errorMessage(error)}`,
+          )
+          this.#finishChainStep()
+        },
+      )
+    } else {
+      this.#finishChainStep()
+    }
+  }
+
+  #finishChainStep(): void {
+    this.#chainBusy = false
+    this.#drainOrFlush()
+  }
+
+  /** Next queued op, or flush gated views when idle. */
+  #drainOrFlush(): void {
+    const next = this.#chainQueue.shift()
+    if (next !== undefined) {
+      this.#chainBusy = true
+      this.#runExclusive(next)
+      return
+    }
+    this.#flushGatedViews()
+  }
+
+  /**
+   * Recompute views gated during replay on the settled overlay; notify movers.
+   * No-op on the common all-sync path.
+   */
+  #flushGatedViews(): void {
+    if (this.#gatedViews.size === 0) return
+    const gated = [...this.#gatedViews]
+    this.#gatedViews.clear()
+    for (const view of gated) if (view.recompute()) view.notify()
+  }
+
+  /**
+   * New view initial recompute: now, or deferred while overlay is torn
+   * (snapshot gating).
+   */
+  #initialCompute(view: RawRead): void {
+    if (this.#chainBusy) this.#gatedViews.add(view)
+    else view.recompute()
+  }
+
+  // --- the optimistic overlay ----------------------------------------------
+
+  /**
+   * Open held savepoint and replay pendings onto base; record `#overlayTables`.
+   * Clears/drains the write-table accumulator so priors never leak. Sync when
+   * every body is sync; returns a Promise once a body awaits (caller awaits
+   * settle — exclusive chain, ADR-0019).
+   */
+  #openOverlay(): Awaitable<void> {
+    this.#db.drainWrittenTables()
+    this.#db.exec(`SAVEPOINT ${OPTIMISTIC_SAVEPOINT}`)
+    this.#overlayOpen = true
+    this.#optimisticFailed.clear()
+    return thenMaybe(this.#replayFrom(0), () => {
+      this.#overlayTables = consumerTables(this.#db.drainWrittenTables())
+    })
+  }
+
+  /**
+   * Replay pendings from `index` in order. Stays sync across sync bodies; an
+   * await then tail-recurses so ordering is strict without microtask tax.
+   */
+  #replayFrom(index: number): Awaitable<void> {
+    for (let i = index; i < this.#pending.length; i++) {
+      const running = this.#replayBody(this.#pending[i] as PendingMutation)
+      if (isThenable(running))
+        return running.then(() => this.#replayFrom(i + 1))
+    }
+  }
+
+  /** Roll overlay to base and release (autocommit). */
+  #closeOverlay(): void {
+    if (!this.#overlayOpen) return
+    this.#db.exec(`ROLLBACK TO ${OPTIMISTIC_SAVEPOINT}`)
+    this.#db.exec(`RELEASE ${OPTIMISTIC_SAVEPOINT}`)
+    this.#overlayOpen = false
+  }
+
+  /**
+   * Rebase envelope for every durable change (mutate, poke, reject): close
+   * overlay, run `durable` in a committed base transaction (outside savepoint),
+   * reopen with survivor replay. Returns union of tables removed by rollback,
+   * written by durable, and written by new overlay — so pure disappearances
+   * still re-project.
+   *
+   * `durable` is sync; only survivor replay may await. Exclusive chain holds
+   * other ops until overlay is rebuilt.
+   */
+  #rebase(durable: () => void): Awaitable<Set<string>> {
+    const removed = this.#overlayTables
+    this.#closeOverlay()
+    this.#db.drainWrittenTables()
+    this.#db.exec('BEGIN')
+    try {
+      durable()
+      this.#db.exec('COMMIT')
+    } catch (error) {
+      // Leave DB clean for caller recovery (wipe-and-resync): roll durable body,
+      // restore overlay, then rethrow.
+      this.#db.exec('ROLLBACK')
+      return thenMaybe(this.#openOverlay(), () => {
+        throw error
+      })
+    }
+    const applied = consumerTables(this.#db.drainWrittenTables())
+    return thenMaybe(
+      this.#openOverlay(),
+      () => new Set([...removed, ...applied, ...this.#overlayTables]),
+    )
+  }
+
+  /**
+   * Replay one pending body in a nested savepoint so a throw rolls back only
+   * itself and survivors still apply. Failure lands in `#optimisticFailed` for
+   * `client` reject; caller decides drop (initial apply / body-throw contract)
+   * vs keep (later rebase — Origin decides). Async bodies release the savepoint
+   * only after settle.
+   */
+  #replayBody(p: PendingMutation): Awaitable<void> {
+    const db = this.#db
+    db.exec(`SAVEPOINT ${BODY_SAVEPOINT}`)
+    let running: Awaitable<void>
+    try {
+      const entry = this.#mutations[p.name]
+      if (entry === undefined) throw new Error(`unknown mutation "${p.name}"`)
+      running = asClientMutation(entry).handler(p.args, this.#ctx, this.#tx())
+    } catch (error) {
+      this.#failBody(p.mutationId, error)
+      return
+    }
+    if (isThenable(running)) {
+      return running.then(
+        () => this.#releaseBody(p.mutationId),
+        (error: unknown) => this.#failBody(p.mutationId, error),
+      )
+    }
+    this.#releaseBody(p.mutationId)
+  }
+
+  /** Clean body: release savepoint, clear prior failure. */
+  #releaseBody(id: number): void {
+    this.#db.exec(`RELEASE ${BODY_SAVEPOINT}`)
+    this.#optimisticFailed.delete(id)
+  }
+
+  /** Thrown body: roll savepoint back and record the error. */
+  #failBody(id: number, error: unknown): void {
+    this.#db.exec(`ROLLBACK TO ${BODY_SAVEPOINT}`)
+    this.#db.exec(`RELEASE ${BODY_SAVEPOINT}`)
+    this.#optimisticFailed.set(id, error)
+  }
+
+  /** Mutation-body write surface (exec returns rows, ADR-0021). */
+  #tx(): ClientMutationTx {
+    return { exec: (query, ...params) => this.#db.exec(query, ...params) }
+  }
+
+  /**
+   * `push` frame (ADR-0016): `{name, args}` + durable id, never the optimistic
+   * result. `wireArgs` is reserved-key encoded at enqueue/reload (ADR-0031 /
+   * #231) so clean-apply and reconnect outbox share one blob.
+   */
+  #sendPush(p: PendingMutation): void {
+    this.#socket.send({
+      type: 'push',
+      clientId: this.#clientId,
+      mutationId: p.mutationId,
+      name: p.name,
+      args: p.wireArgs,
+    })
+  }
+
+  // --- mutate ---------------------------------------------------------------
+
+  mutate<Args = unknown>(
+    mutation: MutationDefinition<Args>,
+    args: Args,
+    options?: MutationOptions,
+  ): MutationResult {
+    const key = options?.key
+    if (key !== undefined) {
+      const existing = this.#keyed.get(key)
+      if (existing !== undefined) return existing
+    }
+
+    // Definition is a typed name stamp only (ADR-0021 / #161): resolve body +
+    // validator from THIS engine's registry. Passed object body is never run.
+    const name = mutation.name
+    if (name === undefined || name === '') {
+      return settledRejection(
+        new Error(
+          'doync: mutate requires a registered mutation — wrap it in defineMutations(...) so it carries a dotted name',
+        ),
+      )
+    }
+
+    const entry = this.#mutations[name]
+    if (entry === undefined) {
+      return settledRejection(new Error(`doync: unknown mutation "${name}"`))
+    }
+    const registered = asClientMutation(entry)
+    let liveArgs: unknown
+    let wireArgs: unknown
+    try {
+      // Device-side unrepresentable-leaf guard before enqueue (ADR-0031 /
+      // #231/#232). Binary allowed (`encodeArgs` tags it); bigint/NaN/±Inf/
+      // mangled-id-zone ints rejected. Runs for EVERY mutation ahead of the
+      // schema gate — bare handlers skip `validateMutationArgs`. Throw is
+      // sync fail-fast: nothing enqueued, `client` rejects.
+      assertWireRepresentable(args, 'mutation args', { allowBinary: true })
+      // TypedArray/DataView → ArrayBuffer before schema + body (same as Origin
+      // / query resolve). Encode the post-schema value so wire and durable
+      // queue match what the optimistic body saw (validators assumed
+      // pass-through / idempotent).
+      const canonical = canonicalizeArgsBinary(args)
+      liveArgs =
+        registered.args !== undefined
+          ? validateMutationArgs(registered.args, canonical)
+          : canonical
+      wireArgs = encodeArgs(liveArgs, 'mutation args')
+    } catch (error) {
+      return settledRejection(error)
+    }
+
+    // Pair returned sync; mutid allocated ON THE CHAIN in `#applyMutate` so
+    // mutate-during-replay only defers its paint, fail-fast throws consume no
+    // id, and the Origin cursor never sees a gap.
+    const promise = this.#makePromise(false)
+    if (key !== undefined) this.#keyed.set(key, promise.pair)
+    this.#exclusive(() =>
+      this.#applyMutate({ name, args: liveArgs, wireArgs, key, promise }),
+    )
+    return promise.pair
+  }
+
+  /**
+   * Optimistic apply on the exclusive chain (ADR-0019): allocate id, durable
+   * queue row + counter outside the savepoint, rebase all pendings into a fresh
+   * overlay, settle `client`. Counter rolls back via `#dropPending` on
+   * fail-fast so only pushed mutids are consumed.
+   */
+  #applyMutate(request: {
+    name: string
+    args: unknown
+    wireArgs: unknown
+    key: string | undefined
+    promise: PendingPromise
+  }): Awaitable<void> {
+    const db = this.#db
+    const id = this.#nextMutationId
+    this.#promises.set(id, request.promise)
+    // Memory: live args for replay. Durable: encoded wire (ADR-0031 / #231).
+    const record: PendingMutation = {
+      mutationId: id,
+      name: request.name,
+      args: request.args,
+      wireArgs: request.wireArgs,
+      key: request.key,
+    }
+    const touched = this.#rebase(() => {
+      db.exec(
+        `INSERT INTO __doync_pending (mutation_id, name, args, idem_key) VALUES (?, ?, ?, ?)`,
+        id,
+        record.name,
+        JSON.stringify(record.wireArgs ?? null),
+        record.key ?? null,
+      )
+      this.#nextMutationId = id + 1
+      writeMeta(db, 'next_mutation_id', String(this.#nextMutationId))
+      this.#pending.push(record)
+    })
+    return thenMaybe(touched, (t) => this.#settleInitialApply(record, t))
+  }
+
+  /**
+   * Settle first optimistic apply (ADR-0019/0021). Clean ⇒ resolve `client`,
+   * re-project, PUSH (`{name, args}` only). Thrown body ⇒ client-body-throw
+   * (#103): drop pending (never pushed; body savepoint already rolled back),
+   * reject both promises (`server` can never ack a never-pushed mut).
+   */
+  #settleInitialApply(
+    record: PendingMutation,
+    touched: Set<string>,
+  ): Awaitable<void> {
+    const id = record.mutationId
+    if (!this.#optimisticFailed.has(id)) {
+      this.#settleClient(id, null)
+      this.#notifyChange(touched)
+      if (this.#connected) this.#sendPush(record)
+      return
+    }
+    const failure = this.#optimisticFailed.get(id)
+    const pair = this.#promises.get(id)?.pair
+    // Release idempotency key so a same-key retry re-evaluates (condition may
+    // have cleared) instead of returning the cached rejection.
+    if (record.key !== undefined) this.#keyed.delete(record.key)
+    // Never-pushed ⇒ roll high-water so Origin cursor sees no gap.
+    return thenMaybe(this.#dropPending(id, true), (dropped) => {
+      this.#settleClient(id, failure)
+      this.#settleServer(id, failure)
+      // Swallow unhandled rejection if consumer awaits only `client`.
+      pair?.client.catch(() => {})
+      pair?.server.catch(() => {})
+      this.#notifyChange(new Set([...touched, ...dropped]))
+    })
+  }
+
+  /**
+   * Drop one pending and rebase survivors (ADR-0019). Shared by body-throw
+   * (`rollbackCounter`) and server reject. `rollbackCounter` only on fail-fast
+   * (id never pushed); server reject consumes the id (Origin advanced).
+   */
+  #dropPending(id: number, rollbackCounter = false): Awaitable<Set<string>> {
+    const db = this.#db
+    return this.#rebase(() => {
+      db.exec(`DELETE FROM __doync_pending WHERE mutation_id = ?`, id)
+      this.#pending = this.#pending.filter((p) => p.mutationId !== id)
+      if (rollbackCounter) {
+        this.#nextMutationId = id
+        writeMeta(db, 'next_mutation_id', String(id))
+      }
+    })
+  }
+
+  // --- auth (ADR-0018, closeio/doync#102) -----------------------------------
+
+  /**
+   * Adopt a refreshed SAME-USER identity triple (#167). When connected with a
+   * bearer, send in-band `updateAuth` (ADR-0018 / #85) so the Mirror extends
+   * auth without reconnect when userId matches and `issuedAt` is newer.
+   * Identity CHANGE (different `userId`, incl. anon↔user) is topology-level
+   * replica swap — SharedWorker routes only same-user refreshes here.
+   *
+   * Token is stored for the next reconnect (#92: surviving SharedWorker must
+   * not reuse a stale token). `ctx`/`userId` asserted, never derived. Halted
+   * engines never emit.
+   */
+  updateAuth(
+    token: string | null | undefined,
+    ctx?: Record<string, unknown>,
+    userId?: string | null,
+  ): void {
+    this.#token = token ?? undefined
+    if (userId !== undefined) this.#userId = userId
+    if (ctx !== undefined) this.#ctx = ctx
+    if (
+      this.#connected &&
+      !this.#halted &&
+      typeof token === 'string' &&
+      token !== ''
+    ) {
+      this.#socket.send({ type: 'updateAuth', jwt: token })
+    }
+  }
+
+  // --- reactive reads -------------------------------------------------------
+
+  /**
+   * Subscribe to a registered query (ADR-0021): resolve under args+ctx,
+   * register upstream, return a reactive {@link View}. Local snapshots run
+   * resolved SQL over base+overlay (RYOW). Re-project only when a local change
+   * touches the instance's server Read-set.
+   *
+   * Bound form only (ADR-0027 / #200): {@link BoundQuery} or falsy →
+   * SkippedView. `options.skip` is also an inert View with no desire.
+   */
+  subscribe<Row extends Record<string, unknown> = Record<string, SqlValue>>(
+    query: BoundQuery<Row, boolean> | FalsyQuery,
+    options?: SubscribeOptions,
+  ): View<Row> {
+    // Falsy ⇒ inert SkippedView, no desire/wire (ADR-0027). Distinct from
+    // `options.skip` on a real bound query.
+    if (isFalsyQuery(query)) {
+      return new SkippedView() as unknown as View<Row>
+    }
+    const {
+      query: leaf,
+      args,
+      options: opts,
+    } = normalizeQuerySurface('subscribe', query, options)
+    // Skipped (#104): no desire, no re-execution. Un-skip is a fresh subscribe
+    // at the hook (#105), never in-place. Not keyed — holds no resources.
+    if (opts?.skip) {
+      return new SkippedView() as unknown as View<Row>
+    }
+    const name = leaf.name as string
+    // Pure compute (ADR-0023/Q3): mint handle only. `retain()` is ownership.
+    // Resolve here (engine consumption), never at BoundQuery bind (ADR-0027).
+    const resolved = leaf.resolve({ args, ctx: this.#ctx })
+    const statement: LocalStatement = {
+      sql: resolved.sql,
+      params: resolved.params,
+    }
+    const identity = resolved.identity
+    const spec = { name, args, ttl: opts?.ttl, statement }
+    const decode = resolved.decode
+    const one = resolved.one ?? false
+    return new ViewHandle(
+      {
+        peek: () => this.#desired.get(identity)?.read ?? null,
+        retain: () => this.#retainSubscription(identity, spec),
+        release: () => this.#releaseSubscription(identity),
+        compute: () => {
+          // Snapshot-gated like once(): mid-replay → empty seed.
+          if (this.#chainBusy) {
+            return { rows: EMPTY_ROWS, status: UNKNOWN_STATUS }
+          }
+          const raw = this.#db.exec(statement.sql, ...statement.params)
+          const entry = this.#desired.get(identity)
+          return {
+            rows: decode ? decode(raw) : raw,
+            status: phaseToStatus(entry?.phase ?? 'pending', entry?.error),
+          }
+        },
+      },
+      decode,
+      one,
+    ) as unknown as View<Row>
+  }
+
+  /**
+   * Warm the replica without materializing a View (#104, ADR-0019/0021):
+   * register upstream so pokes hydrate rows other queries read, at zero local
+   * recompute of the preload statement. Refcounts the same desired instance as
+   * a live subscribe (byte-identical statement). `{cleanup}` releases into TTL
+   * grace (ADR-0014). Bound form only (ADR-0027 / #200); falsy → no-op handle.
+   */
+  preload(
+    query: BoundQuery | FalsyQuery,
+    options?: PreloadOptions,
+  ): PreloadHandle {
+    if (isFalsyQuery(query)) {
+      return NOOP_PRELOAD
+    }
+    const {
+      query: leaf,
+      args,
+      options: opts,
+    } = normalizeQuerySurface('preload', query, options)
+    const name = leaf.name as string
+    const resolved = leaf.resolve({ args, ctx: this.#ctx })
+    const identity = resolved.identity
+    this.#retainPreload(identity, {
+      name,
+      args,
+      ttl: opts?.ttl,
+      statement: { sql: resolved.sql, params: resolved.params },
+    })
+    let released = false
+    return {
+      cleanup: () => {
+        // Idempotent — double cleanup must not under-count a shared instance.
+        if (released) return
+        released = true
+        this.#releaseSubscription(identity)
+      },
+    }
+  }
+
+  /**
+   * Desire half of retain (subscribe AND preload): 0→1 entry + wire
+   * `subscribe`, error-phase retry (#104/#114), ttl ratchet (#102, deviation
+   * below).
+   */
+  #retainDesire(identity: string, spec: SubscriptionSpec): DesiredEntry {
+    let entry = this.#desired.get(identity)
+    if (entry === undefined) {
+      // Capture heldAt BEFORE marking desired / dropping the stamp (ADR-0029 /
+      // #225). `#heldAtFor` prefers desired+live → current cookie; doing those
+      // first would attest the advanced cookie and trip the server's ahead
+      // verdict against the parked baseline.
+      const heldAt = this.#heldAtFor(identity)
+      entry = {
+        name: spec.name,
+        args: spec.args,
+        ttl: spec.ttl,
+        count: 0,
+        read: null,
+        phase: 'pending',
+        error: undefined,
+      }
+      this.#desired.set(identity, entry)
+      // Drop parked stamp — only released instances keep one (ADR-0014 / #224).
+      // Via `#sideWrite` so the delete doesn't join the open overlay (#139).
+      this.#sideWrite(() => deleteReleaseStamp(this.#db, identity))
+      if (this.#connected) {
+        this.#socket.send({
+          type: 'subscribe',
+          queries: [this.#desiredQuery(identity, { heldAt })],
+        })
+      }
+    } else if (entry.phase === 'error' && this.#connected) {
+      // Fresh mount retries a failed subscribe (#setPhase notifies holders).
+      this.#setPhase(identity, 'pending')
+      this.#socket.send({
+        type: 'subscribe',
+        queries: [this.#desiredQuery(identity)],
+      })
+    } else if (
+      spec.ttl !== undefined &&
+      (entry.ttl === undefined || spec.ttl > entry.ttl)
+    ) {
+      // Raised ttl (#102): widen Mirror grace with a cheap re-send (ADR-0015).
+      // DELIBERATE ratchet (max-of-EVER, not max-of-live) — lowering would need
+      // per-holder ttl tracking. Cost: wider storage-only grace after a high-ttl
+      // mount leaves (ADR-0014, 24h server clamp); wire lifetime (Q2) unchanged.
+      entry.ttl = spec.ttl
+      if (this.#connected) {
+        this.#socket.send({
+          type: 'subscribe',
+          queries: [this.#desiredQuery(identity)],
+        })
+      }
+    }
+    entry.count += 1
+    return entry
+  }
+
+  /**
+   * Commit ownership for one subscription: {@link #retainDesire} plus the shared
+   * {@link RawRead} (reclaim warm, else build and catch up).
+   */
+  #retainSubscription(identity: string, spec: SubscriptionSpec): RawRead {
+    const entry = this.#retainDesire(identity, spec)
+    if (entry.read === null) {
+      // Prefer warm reclaim (zero re-exec); else build the shared read.
+      const warm = this.#warmReads.get(identity)
+      if (warm !== undefined) {
+        clearTimeout(warm.timer)
+        this.#warmReads.delete(identity)
+        entry.read = warm.read
+        // Parked reads miss fan-out; catch up on reclaim. rowsEqual dedups so
+        // unchanged → one SELECT, no notify; handles only move forward (Q1).
+        this.#initialCompute(warm.read)
+      } else {
+        const read = new RawRead(
+          {
+            run: (st) => this.#db.exec(st.sql, ...st.params),
+            readSet: () => {
+              const info = this.#instanceInfo.get(identity)
+              return info === undefined ? undefined : new Set(info.readSet)
+            },
+          },
+          spec.statement,
+          identity,
+          phaseToStatus(entry.phase, entry.error),
+        )
+        entry.read = read
+        this.#initialCompute(read)
+      }
+    }
+    return entry.read
+  }
+
+  /**
+   * Preload ownership (#104): same desire as subscribe (shared instance on
+   * byte-identical statements), no local read — poke hydrates. Cleanup is
+   * ordinary release.
+   */
+  #retainPreload(identity: string, spec: SubscriptionSpec): void {
+    this.#retainDesire(identity, spec)
+  }
+
+  /**
+   * Drop one desire ref (#104, #120). Last release removes the entry and, when
+   * connected, sends `unsubscribe` (name+args; Mirror re-resolves under its
+   * ctx). Mirror moves into ADR-0014 TTL grace (out of Sweep, membership warm)
+   * so a re-subscribe is pk-list catch-up. Non-last release only decrements.
+   *
+   * Wire fires immediately on last drop — no client linger (#120/Q2). Warm pool
+   * is ONLY local paint budget (StrictMode / hop-back); Mirror TTL is the
+   * durable warmth. Re-retain within the tick re-sends `subscribe` (cheap via
+   * #225 `heldAt`).
+   *
+   * Offline/halted (`#connected` false): drop desire silently, queue nothing —
+   * next handshake rebuilds from {@link #desired}, which already omits this
+   * instance. Racing an already-inactive Mirror sub is a no-op server-side.
+   */
+  #releaseSubscription(identity: string): void {
+    const entry = this.#desired.get(identity)
+    if (entry === undefined || --entry.count > 0) return
+    // Leave declared truth immediately; wire unsubscribes NOW (Q2); rows → Warm.
+    this.#desired.delete(identity)
+    if (this.#connected) {
+      this.#socket.send({
+        type: 'unsubscribe',
+        queries: [
+          {
+            name: entry.name,
+            args:
+              entry.args === undefined
+                ? undefined
+                : encodeArgs(entry.args, 'query args'),
+          },
+        ],
+      })
+    }
+    // Stamp park position with the unsubscribe (ADR-0014 / #224) for heldAt
+    // (#225) and GC (#226). No cookie ⇒ no stamp. Must not join the optimistic
+    // SAVEPOINT (#139 / #223) — use the stamp envelope (also piggybacks clock).
+    this.#stampLastRelease(identity, entry.ttl)
+    if (entry.read !== null) this.#warmRead(identity, entry.read)
+  }
+
+  /**
+   * Last-release stamp (ADR-0014 / #224). No-ops without a scalar cookie. Same
+   * envelope runs membership GC (#226) and persists the connected clock (#223)
+   * — GC may delete fully-orphaned rows, so notify the touched set (not the
+   * meta-only {@link #sideWrite} path).
+   */
+  #stampLastRelease(identity: string, declaredTtl: number | undefined): void {
+    const cookie = this.#cookie
+    if (cookie === null) return
+    const stamp: ReleaseStamp = {
+      instance: identity,
+      cookie,
+      releasedAt: this.#connectedClock,
+      ttlMs: resolveReleaseTtlMs(declaredTtl),
+    }
+    this.#exclusive(() =>
+      thenMaybe(
+        this.#rebase(() => {
+          upsertReleaseStamp(this.#db, stamp)
+          // After stamp: non-positive ttl self-collects; aged/stampless siblings
+          // ride the same write (`#desired` live ⇒ stampless of undesired is
+          // safe). Clock always piggybacks on a stamp write (#223).
+          this.#runMembershipGc({ includeStampless: true })
+          this.#persistConnectedClock()
+        }),
+        (touched) => this.#notifyChange(touched),
+      ),
+    )
+  }
+
+  /**
+   * Persist connected-clock reading (ADR-0014 / #223). Caller provides the
+   * durable envelope. Never a naive standalone writeMeta (#139).
+   */
+  #persistConnectedClock(): void {
+    writeMeta(
+      this.#db,
+      __CONNECTED_CLOCK_META_KEY,
+      String(this.#connectedClock),
+    )
+  }
+
+  /**
+   * Membership GC (ADR-0014 / #226) via ADR-0028 {@link #breakStaleInstance}
+   * (memberships + stamp + fully-orphaned rows).
+   *
+   * Eligible when not desired, and either: stamp with `ttlMs <= 0`; stamp age
+   * `connectedClock - releasedAt > ttlMs`; or no stamp at all when
+   * `includeStampless` (in-session only — boot `#desired` is empty, stampless
+   * would wipe live failover survivors). Hygiene only under ADR-0029 (early ⇒
+   * full hydrate; late ⇒ server already forgot). Inside a durable envelope;
+   * piggybacks the clock when it breaks anything.
+   */
+  #runMembershipGc(opts: { includeStampless: boolean }): void {
+    const victims = this.#gcEligibleInstances(opts.includeStampless)
+    if (victims.length === 0) return
+    for (const instance of victims) this.#breakStaleInstance(instance)
+    this.#persistConnectedClock()
+  }
+
+  /** Instances eligible for membership GC this sweep (order unspecified). */
+  #gcEligibleInstances(includeStampless: boolean): string[] {
+    const desired = this.#desired
+    const stamps = listReleaseStamps(this.#db)
+    const stamped = new Set(stamps.map((s) => s.instance))
+    const eligible: string[] = []
+
+    // Stampless of un-desired — only with a live desired set (see GC doc).
+    if (includeStampless) {
+      const held = this.#db.exec<{ instance: SqlValue }>(
+        `SELECT DISTINCT instance FROM __doync_membership`,
+      )
+      for (const row of held) {
+        const instance = String(row.instance)
+        if (desired.has(instance) || stamped.has(instance)) continue
+        eligible.push(instance)
+      }
+    }
+
+    // Stamped releases past (or non-positive) ttl.
+    const clock = this.#connectedClock
+    for (const stamp of stamps) {
+      if (desired.has(stamp.instance)) continue
+      if (stamp.ttlMs <= 0 || clock - stamp.releasedAt > stamp.ttlMs) {
+        eligible.push(stamp.instance)
+      }
+    }
+    return eligible
+  }
+
+  /**
+   * Park a released read in the Warm pool (CONTEXT.md; ADR-0023) for one policy
+   * tick ({@link WARM_POOL_TICK_MS}) — re-retain reclaims without re-exec
+   * (StrictMode, j/k hops). Wire half already fired.
+   */
+  #warmRead(key: string, read: RawRead): void {
+    const prior = this.#warmReads.get(key)
+    if (prior !== undefined) clearTimeout(prior.timer)
+    this.#warmReads.set(key, {
+      read,
+      timer: setTimeout(() => {
+        const parked = this.#warmReads.get(key)
+        if (parked === undefined || parked.read !== read) return
+        this.#warmReads.delete(key)
+        this.#gatedViews.delete(read)
+      }, WARM_POOL_TICK_MS),
+    })
+  }
+
+  /**
+   * Once (ADR-0012 / ADR-0021): cache-and-network. Local replica first (real
+   * SQL `[]` when empty); Mirror executes once under its ctx. Local
+   * exec/decode/shape errors throw at call (#141). Leaves no
+   * Subscription/CVR/Membership. Bound form only (ADR-0027 / #200); falsy never
+   * starts the network half.
+   */
+  once<Row extends Record<string, unknown> = Record<string, SqlValue>>(
+    query: BoundQuery<Row, boolean> | FalsyQuery,
+  ): OnceView<Row> {
+    if (isFalsyQuery(query)) {
+      return new SkippedOnceView() as unknown as OnceView<Row>
+    }
+    const { query: leaf, args } = normalizeQuerySurface('once', query)
+    const name = leaf.name as string
+    const resolved = leaf.resolve({ args, ctx: this.#ctx })
+    // Cache half; gate only mid-async-replay (torn overlay). Fail-loud.
+    let cached: readonly Record<string, unknown>[]
+    if (this.#chainBusy) {
+      cached = []
+    } else {
+      const raw = this.#db.exec(resolved.sql, ...resolved.params)
+      cached = resolved.decode ? resolved.decode(raw) : raw
+    }
+    const id = `once-${this.#nextOnceSeq++}`
+    // Decode also applies to the server answer. Pure construction (Q3/Q7):
+    // network on first use; dispose deferred one Warm tick for StrictMode.
+    // Encode wire args once (ADR-0031 / #230) for reconnect re-issue.
+    const wireArgs =
+      args === undefined ? undefined : encodeArgs(args, 'query args')
+    const view = new OnceViewImpl(cached, resolved.decode, {
+      start: () => {
+        this.#onceRequests.set(id, { view, name, args: wireArgs })
+        if (this.#connected) {
+          this.#socket.send({ type: 'once', id, name, args: wireArgs })
+        }
+      },
+      drop: () => {
+        this.#onceRequests.delete(id)
+        this.#onceBuffers.delete(id)
+      },
+    })
+    return view as unknown as OnceView<Row>
+  }
+
+  /**
+   * Local read (ADR-0019/0021): arbitrary SQL over the replica, never upstream;
+   * re-run on any local commit (unhinted).
+   */
+  local<Row extends Record<string, unknown> = Record<string, SqlValue>>(
+    sql: string,
+    ...params: SqlValue[]
+  ): View<Row> {
+    // Pure compute twin of subscribe (ADR-0023/Q3). Always `complete` — local
+    // answer is authoritative (#104).
+    const key = `local:${sql}\u0000${JSON.stringify(params)}`
+    const statement: LocalStatement = { sql, params }
+    return new ViewHandle(
+      {
+        peek: () => this.#localReads.get(key)?.read ?? null,
+        retain: () => this.#retainLocal(key, statement),
+        release: () => this.#releaseLocal(key),
+        compute: () => {
+          if (this.#chainBusy) {
+            return { rows: EMPTY_ROWS, status: UNKNOWN_STATUS }
+          }
+          return {
+            rows: this.#db.exec(statement.sql, ...statement.params),
+            status: COMPLETE_STATUS,
+          }
+        },
+      },
+      undefined,
+      undefined,
+    ) as unknown as View<Row>
+  }
+
+  /** Local-read retain (subscription twin, no wire). */
+  #retainLocal(key: string, statement: LocalStatement): RawRead {
+    let entry = this.#localReads.get(key)
+    if (entry === undefined) {
+      entry = { count: 0, read: null }
+      this.#localReads.set(key, entry)
+    }
+    entry.count += 1
+    if (entry.read === null) {
+      const warm = this.#warmReads.get(key)
+      if (warm !== undefined) {
+        clearTimeout(warm.timer)
+        this.#warmReads.delete(key)
+        entry.read = warm.read
+        // Catch up across the parked window (see the subscription reclaim).
+        this.#initialCompute(warm.read)
+      } else {
+        const read = new RawRead(
+          {
+            run: (st) => this.#db.exec(st.sql, ...st.params),
+            readSet: () => undefined,
+          },
+          statement,
+          undefined,
+          COMPLETE_STATUS,
+        )
+        entry.read = read
+        this.#initialCompute(read)
+      }
+    }
+    return entry.read
+  }
+
+  #releaseLocal(key: string): void {
+    const entry = this.#localReads.get(key)
+    if (entry === undefined || --entry.count > 0) return
+    this.#localReads.delete(key)
+    if (entry.read !== null) this.#warmRead(key, entry.read)
+  }
+
+  // --- socket handlers ------------------------------------------------------
+
+  #onOpen(): void {
+    // Reload skew: never re-handshake until the app reloads.
+    if (this.#halted) return
+    // First pong after (re)connect contributes zero (ADR-0014 / #223).
+    this.#lastPongAt = null
+    this.#setConnected(true)
+    this.#sendHandshake()
+  }
+
+  /**
+   * Connected-time tick on keepalive pong (ADR-0014 / #223): elapsed wall time
+   * since the previous pong of THIS connection; first pong only re-anchors.
+   * Memory-only — durable persist rides the next poke apply.
+   */
+  #onPong(): void {
+    const now = this.#now()
+    if (this.#lastPongAt !== null) {
+      const delta = now - this.#lastPongAt
+      // Never count backward Wall-clock skew.
+      if (delta > 0) this.#connectedClock += delta
+    }
+    this.#lastPongAt = now
+  }
+
+  /**
+   * Handshake + durable outbox in order (ADR-0016). `connect` carries
+   * `schemaVersion` (ADR-0020) and cookie; server dedups re-pushes by lmid.
+   * Used on (re)connect and post-wipe resync.
+   */
+  #sendHandshake(): void {
+    // Every (re)connect must reconfirm session: desired → `pending` (#104).
+    // First connect is a no-op notify for already-pending; reconnect drops
+    // `complete` back to unknown until ack + poke.
+    for (const identity of this.#desired.keys()) {
+      this.#setPhase(identity, 'pending')
+    }
+    this.#socket.send({
+      type: 'connect',
+      clientId: this.#clientId,
+      // Bearer on every handshake (ADR-0016/0018) — not only the upgrade cookie
+      // a surviving SharedWorker may have captured pre-login (#92).
+      ...(this.#token !== undefined ? { jwt: this.#token } : {}),
+      cookie: this.#cookie,
+      // heldAt from memberships + stamps (ADR-0029); no memberships → no claim.
+      desiredQueries: [...this.#desired.keys()].map((id) =>
+        this.#desiredQuery(id),
+      ),
+      schemaVersion: this.#bundleVersion,
+    })
+    for (const p of this.#pending) this.#sendPush(p)
+    // Once is not durable (ADR-0012): re-ask; cache holds until answer. Fresh
+    // onceStart resets a mid-stream partial buffer.
+    for (const [id, once] of this.#onceRequests) {
+      this.#socket.send({
+        type: 'once',
+        id,
+        name: once.name,
+        args: once.args,
+      })
+    }
+  }
+
+  /**
+   * Wire `DesiredQuery` (ADR-0029 / #225). Optional `opts.heldAt` for re-desire
+   * that must capture the claim BEFORE stamp drop / becoming desired — else
+   * `#heldAtFor` would treat a warm remount as live at the advanced cookie.
+   * Present `opts` with `heldAt === undefined` is a real absence (do not
+   * re-derive).
+   *
+   * Args reserved-key encoded here (ADR-0031 / #230) so every subscribe path
+   * shares one choke point; in-memory desire keeps live values for resolve.
+   */
+  #desiredQuery(
+    identity: string,
+    opts?: { readonly heldAt: number | undefined },
+  ): DesiredQuery {
+    const entry = this.#desired.get(identity)
+    // opts present ⇒ caller-derived (before desired/stamp mutations).
+    const heldAt = opts !== undefined ? opts.heldAt : this.#heldAtFor(identity)
+    return {
+      name: entry?.name ?? identity,
+      args:
+        entry?.args === undefined
+          ? undefined
+          : encodeArgs(entry.args, 'query args'),
+      ...(entry?.ttl !== undefined ? { ttl: entry.ttl } : {}),
+      ...(heldAt !== undefined ? { heldAt } : {}),
+    }
+  }
+
+  /**
+   * HeldAt (ADR-0029): no memberships → absent; desired → current cookie; stamp
+   * → park cookie; memberships without stamp and not desired → absent
+   * (crash-gap). After the membership gate: desired first, then stamp. Callers
+   * mutating desired capture first and pass override to {@link #desiredQuery}.
+   */
+  #heldAtFor(identity: string): number | undefined {
+    const hasMembership =
+      this.#db.exec(
+        `SELECT 1 FROM __doync_membership WHERE instance = ? LIMIT 1`,
+        identity,
+      ).length > 0
+    if (!hasMembership) return undefined
+    if (this.#desired.has(identity)) {
+      return this.#cookie ?? undefined
+    }
+    const stamp = readReleaseStamp(this.#db, identity)
+    if (stamp !== null) return stamp.cookie
+    // Crash-gap / pre-feature: honest silence → server full-hydrates.
+    return undefined
+  }
+
+  #onMessage(message: ServerMessage): void {
+    // Reload skew: ignore all but framed errors (new-shape frames would corrupt).
+    if (this.#halted) {
+      if (message.type === 'error') this.#errors.push(message.message)
+      return
+    }
+    // Keepalive pong (ADR-0014 / #223): ticks clock; not handshake proof (never
+    // clears needs-auth; hub parity). Before auth inference.
+    if (message.type === 'pong') {
+      this.#onPong()
+      return
+    }
+    // Auth inference (#136, ADR-0018; hub parity): `unauthorized` => sticky
+    // needs-auth; any substantive later frame clears it. Framed `error` does
+    // not. Engine-owned — seam never reports needs-auth.
+    if (message.type === 'unauthorized') {
+      this.#errors.push(message.message)
+      this.#setNeedsAuth(true)
+      return
+    }
+    if (this.#needsAuth && message.type !== 'error') {
+      this.#setNeedsAuth(false)
+    }
+    switch (message.type) {
+      case 'schemaSkew':
+        this.#onSchemaSkew(message)
+        break
+      case 'schema':
+        this.#onSchemaDirective(message)
+        break
+      case 'subscribeAck':
+        // Ack proves handshake accepted — clear transient back-off / resync.
+        this.#clearTransientSchemaEvent()
+        for (const info of message.instances) {
+          this.#instanceInfo.set(info.instance, info)
+          // Half of complete (#104): -> acked until hydration pokeEnd. Clears
+          // prior error; never regresses already-complete.
+          const entry = this.#desired.get(info.instance)
+          if (entry !== undefined && entry.phase !== 'complete') {
+            this.#setPhase(info.instance, 'acked')
+          }
+        }
+        break
+      case 'pokeStart':
+        this.#clearTransientSchemaEvent()
+        this.#pokeBuffer = []
+        break
+      case 'pokePart':
+        if (this.#pokeBuffer === null) {
+          this.#errors.push('doync: pokePart arrived with no open poke')
+        } else {
+          this.#pokeBuffer.push(...message.patches)
+        }
+        break
+      case 'pokeEnd':
+        if (this.#pokeBuffer === null) {
+          this.#errors.push('doync: pokeEnd arrived with no open poke')
+        } else {
+          this.#applyPoke(
+            message.cookie,
+            message.lastMutationId,
+            message.confirms,
+          )
+        }
+        break
+      case 'pokeReject':
+        this.#handleReject(message.mutationId, message.error)
+        break
+      case 'onceStart':
+        // Fresh Once accumulator (ADR-0012); reconnect re-issue resets partial.
+        this.#onceBuffers.set(message.id, [])
+        break
+      case 'oncePart': {
+        const buffer = this.#onceBuffers.get(message.id)
+        if (buffer === undefined) {
+          this.#errors.push('doync: oncePart arrived with no open once')
+        } else {
+          buffer.push(...message.rows)
+        }
+        break
+      }
+      case 'onceEnd':
+        this.#handleOnceEnd(message)
+        break
+      case 'resyncRequired':
+        // heldAt-ahead tripwire (ADR-0029 / #225): resync self-heal (keep
+        // clientId + pendings). First-class frame, not phrase-matched.
+        this.#errors.push(message.message)
+        this.#exclusive(() =>
+          this.#wipeAndResync(
+            `heldAt ahead of vouched baseline (instance ${message.instance}: heldAt=${message.heldAt} baseline=${message.baseline}) — ${message.message}`,
+          ),
+        )
+        break
+      case 'error':
+        this.#errors.push(message.message)
+        // Cookie-above-head (ADR-0020 addendum): wipe/redeploy makes every
+        // returning cookie above head — heal via wipe-and-resync (keep pending
+        // + clientId), not permanent sub error. Pendings re-push (ADR-0015).
+        if (isCookieAboveHeadError(message.message)) {
+          this.#exclusive(() =>
+            this.#wipeAndResync(
+              `cookie above the Origin head (server reset) — ${message.message}`,
+            ),
+          )
+          break
+        }
+        // Named instances -> exact fail (#114); else coarse tar unconfirmed.
+        if (message.instances !== undefined) {
+          this.#failInstances(message.instances, message.message)
+        } else {
+          this.#failUnconfirmed(message.message)
+        }
+        break
+      default:
+        // Unknown ServerMessage type => Mirror ahead of bundle — surface loud.
+        this.#errors.push(
+          `doync: unknown ServerMessage type ${String(
+            (message as { type?: unknown }).type,
+          )}`,
+        )
+    }
+  }
+
+  /**
+   * Fail exactly the instances the Mirror named on an `error` frame (#114).
+   * Skips already-complete/dropped; later ack recovers. Fallback for un-named
+   * errors is {@link #failUnconfirmed}.
+   */
+  #failInstances(instances: readonly string[], message: string): void {
+    const error = new Error(message)
+    for (const identity of instances) {
+      const entry = this.#desired.get(identity)
+      if (
+        entry !== undefined &&
+        (entry.phase === 'pending' || entry.phase === 'acked')
+      ) {
+        this.#setPhase(identity, 'error', error)
+      }
+    }
+  }
+
+  /**
+   * Un-attributable framed `error` -> every pending/acked instance (#104/#114).
+   * Complete untouched; later ack recovers. Prefer {@link #failInstances}.
+   */
+  #failUnconfirmed(message: string): void {
+    const error = new Error(message)
+    for (const [identity, entry] of this.#desired) {
+      if (entry.phase === 'pending' || entry.phase === 'acked') {
+        this.#setPhase(identity, 'error', error)
+      }
+    }
+  }
+
+  /**
+   * OnceEnd (ADR-0012): deliver accumulated parts to {@link OnceViewImpl} or
+   * reject on framed error. No cookie/lmid. Stray onceEnd (disposed / already
+   * settled) is benign — drop it.
+   */
+  #handleOnceEnd(message: OnceEndMessage): void {
+    const buffered = this.#onceBuffers.get(message.id) ?? []
+    this.#onceBuffers.delete(message.id)
+    const pending = this.#onceRequests.get(message.id)
+    if (pending === undefined) return
+    this.#onceRequests.delete(message.id)
+    if (message.error !== undefined) {
+      pending.view.settleError(new Error(message.error))
+      return
+    }
+    pending.view.deliver(buffered.map(decodeOnceRow))
+  }
+
+  // --- rebase ---------------------------------------------------------------
+
+  /**
+   * PokeEnd apply (ADR-0013/0016/0019). Capture buffer sync (next poke may
+   * reset it), then exclusive chain so poke never rolls an overlay mid-await.
+   * Rolls overlay, applies patches (puts before dels), drops rejected-then-
+   * acked, persists cookie with batch, replays survivors.
+   */
+  #applyPoke(
+    cookie: number,
+    lastMutationId: number | null,
+    confirms: readonly string[] | undefined,
+  ): void {
+    const patches = this.#pokeBuffer ?? []
+    this.#pokeBuffer = null
+    this.#exclusive(() =>
+      this.#doApplyPoke(patches, cookie, lastMutationId, confirms),
+    )
+  }
+
+  #doApplyPoke(
+    patches: readonly Patch[],
+    cookie: number,
+    lastMutationId: number | null,
+    confirms: readonly string[] | undefined,
+  ): Awaitable<void> {
+    const db = this.#db
+    const acked: number[] = []
+
+    const touched = this.#rebase(() => {
+      // Puts before dels/prunes (ADR-0013) — row moving instances never flaps.
+      for (const patch of patches) if (patch.op === 'put') this.#applyPut(patch)
+      for (const patch of patches) if (patch.op === 'del') this.#applyDel(patch)
+      // pks (ADR-0013/0015): after puts, prune held rows absent from the list
+      // (cookie-filtered / warm reactivation). Same EXISTS refcount as dels.
+      for (const patch of patches) if (patch.op === 'pks') this.#applyPks(patch)
+
+      // Drop rejected-then-acked (order): rejected already gone; lmid settles
+      // only non-rejected; rejected ids covered by lmid stay rejected.
+      if (lastMutationId !== null) {
+        for (const p of this.#pending) {
+          if (
+            p.mutationId <= lastMutationId &&
+            !this.#rejected.has(p.mutationId)
+          ) {
+            acked.push(p.mutationId)
+          }
+        }
+        for (const id of acked) {
+          db.exec(`DELETE FROM __doync_pending WHERE mutation_id = ?`, id)
+        }
+      }
+
+      // Cookie advances only here, with the batch (ADR-0016).
+      this.#cookie = cookie
+      writeMeta(db, 'cookie', String(cookie))
+      // Connected clock on same txn (ADR-0014 / #223); crash => slow (safe).
+      this.#persistConnectedClock()
+      this.#pending = this.#pending.filter((p) => !acked.includes(p.mutationId))
+    })
+
+    return thenMaybe(touched, (t) => {
+      for (const id of acked) this.#settleServer(id, null)
+      for (const id of acked) this.#rejected.delete(id)
+      this.#notifyChange(t)
+      // Other half of complete (#104/#114): promote named `confirms` after
+      // rows (rows-then-status). Empty hydration still completes.
+      this.#promoteConfirmed(confirms)
+    })
+  }
+
+  /**
+   * Promote hydration/reactivation `confirms` to `complete` (#114). Marker-
+   * only — a Sweep poke with no/empty confirms promotes nothing (#114 race).
+   * Only `acked` promotes; pending waits for ack; already-complete is no-op.
+   */
+  #promoteConfirmed(confirms: readonly string[] | undefined): void {
+    if (confirms === undefined) return
+    for (const identity of confirms) {
+      const entry = this.#desired.get(identity)
+      if (entry !== undefined && entry.phase === 'acked') {
+        this.#setPhase(identity, 'complete')
+      }
+    }
+  }
+
+  /** Apply one put (ADR-0013): membership + upsert (delete-by-pk then insert). */
+  #applyPut(patch: Extract<Patch, { op: 'put' }>): void {
+    const db = this.#db
+    const table = this.#tableFor(patch.instance, patch.level)
+    db.exec(
+      `INSERT INTO __doync_membership (instance, level, tbl, pk) VALUES (?, ?, ?, ?)
+         ON CONFLICT (instance, level, pk) DO UPDATE SET tbl = excluded.tbl`,
+      patch.instance,
+      patch.level,
+      table.name,
+      patch.pk,
+    )
+    const pkValues = parsePk(patch.pk, table)
+    db.exec(
+      `DELETE FROM ${quoteIdent(table.name)} WHERE ${pkWhereClause(table)}`,
+      ...pkValues,
+    )
+    const { columns, values } = decodePatchImage(table, patch.image)
+    db.exec(
+      `INSERT INTO ${quoteIdent(table.name)} (${columns.map(quoteIdent).join(', ')})
+         VALUES (${columns.map(() => '?').join(', ')})`,
+      ...values,
+    )
+  }
+
+  /**
+   * Apply one del (ADR-0013): drop membership; delete row only when last ref is
+   * gone (EXISTS).
+   */
+  #applyDel(patch: Extract<Patch, { op: 'del' }>): void {
+    this.#retractRow(patch.instance, patch.level, patch.pk)
+  }
+
+  /**
+   * Apply one pks patch (ADR-0013/0015): complete pk-list for (instance,
+   * level). Prune held rows absent from the list via the same EXISTS retract as
+   * del.
+   */
+  #applyPks(patch: PksPatch): void {
+    const keep = new Set(patch.pks)
+    const held = this.#db.exec<{ pk: SqlValue }>(
+      `SELECT pk FROM __doync_membership WHERE instance = ? AND level = ?`,
+      patch.instance,
+      patch.level,
+    )
+    for (const row of held) {
+      const pk = String(row.pk)
+      if (!keep.has(pk)) this.#retractRow(patch.instance, patch.level, pk)
+    }
+  }
+
+  /**
+   * Retract one membership (ADR-0013/0028): drop ref; delete row when no
+   * DESIRED holder remains (#215). Released holders must not pin
+   * authoritatively retracted rows. Only-stale remaining => delete row and
+   * {@link #breakStaleInstance} so next subscribe omits heldAt.
+   */
+  #retractRow(instance: string, level: number, pk: string): void {
+    const db = this.#db
+    const table = this.#tableFor(instance, level)
+    db.exec(
+      `DELETE FROM __doync_membership WHERE instance = ? AND level = ? AND pk = ?`,
+      instance,
+      level,
+      pk,
+    )
+    const holders = db.exec<{ instance: string }>(
+      `SELECT DISTINCT instance FROM __doync_membership WHERE tbl = ? AND pk = ?`,
+      table.name,
+      pk,
+    )
+    // Desired holder keeps the row (ADR-0013 EXISTS).
+    if (holders.some((h) => this.#desired.has(String(h.instance)))) return
+    db.exec(
+      `DELETE FROM ${quoteIdent(table.name)} WHERE ${pkWhereClause(table)}`,
+      ...parsePk(pk, table),
+    )
+    // Only stale holders: retraction outranks warmth (ADR-0028).
+    for (const h of holders) this.#breakStaleInstance(String(h.instance))
+  }
+
+  /**
+   * Break stale (undesired) warmth (ADR-0028): drop all memberships and orphan
+   * rows. Authoritative retraction proved parked state stale; clearing
+   * memberships makes next subscribe's heldAt honestly absent (full rehydrate).
+   * Rows still referenced elsewhere survive.
+   */
+  #breakStaleInstance(instance: string): void {
+    const db = this.#db
+    const refs = db.exec<{ tbl: string; pk: string }>(
+      `SELECT DISTINCT tbl, pk FROM __doync_membership WHERE instance = ?`,
+      instance,
+    )
+    db.exec(`DELETE FROM __doync_membership WHERE instance = ?`, instance)
+    // Drop stamp with memberships (ADR-0028 / #224) so next subscribe cannot
+    // claim a stale heldAt. Caller supplies durable envelope (poke apply or GC).
+    deleteReleaseStamp(db, instance)
+    for (const ref of refs) {
+      const tblName = String(ref.tbl)
+      const pk = String(ref.pk)
+      const stillReferenced = db.exec(
+        `SELECT 1 FROM __doync_membership WHERE tbl = ? AND pk = ? LIMIT 1`,
+        tblName,
+        pk,
+      )
+      if (stillReferenced.length === 0) {
+        const table = requireTable(this.#schema, tblName)
+        db.exec(
+          `DELETE FROM ${quoteIdent(table.name)} WHERE ${pkWhereClause(table)}`,
+          ...parsePk(pk, table),
+        )
+      }
+    }
+  }
+
+  #tableFor(instance: string, level: number): ReturnType<typeof requireTable> {
+    const info = this.#instanceInfo.get(instance)
+    if (info === undefined) {
+      throw new Error(
+        `doync: patch for unknown instance ${instance} — a subscribeAck must precede its hydration poke`,
+      )
+    }
+    const levelInfo = info.levels.find((l) => l.level === level)
+    if (levelInfo === undefined) {
+      throw new Error(
+        `doync: instance ${instance} has no Level ${level} in its subscribeAck`,
+      )
+    }
+    return requireTable(this.#schema, levelInfo.table)
+  }
+
+  /**
+   * Rejection (ADR-0016/0019): mark rejected immediately (lmid cannot resolve
+   * it even under race), then exclusive-chain drop pending, reject `server`,
+   * re-project (optimistic effect vanishes).
+   */
+  #handleReject(mutationId: number, error: string): void {
+    this.#rejected.add(mutationId)
+    this.#exclusive(() =>
+      thenMaybe(this.#dropPending(mutationId), (touched) => {
+        this.#settleServer(mutationId, new Error(error))
+        this.#notifyChange(touched)
+      }),
+    )
+  }
+
+  // --- schema handling (ADR-0020) -------------------------------------------
+
+  /**
+   * Schema-skew handshake answer (ADR-0020, reject-don't-project): -
+   * `client-stale` — bundle behind Mirror; emit reload and HALT. -
+   * `client-ahead` — mid-deploy Mirror; back off via socket reconnect (adapter
+   * owns timer); clears on later successful handshake.
+   */
+  #onSchemaSkew(message: SchemaSkewMessage): void {
+    const server =
+      message.serverVersion === undefined
+        ? ''
+        : ` (server v${message.serverVersion})`
+    if (message.reason === 'client-stale') {
+      this.#emitSchemaEvent(
+        'reload',
+        `schema client-stale: bundle v${this.#bundleVersion} is behind the Mirror${server} — reload for the new bundle`,
+      )
+      this.#halt()
+    } else {
+      this.#emitSchemaEvent(
+        'server-behind',
+        `schema client-ahead: bundle v${this.#bundleVersion} is ahead of the Mirror${server} — backing off until it deploys`,
+      )
+      this.#setConnected(false)
+      this.#socket.reconnect()
+    }
+  }
+
+  /**
+   * Mid-session `schema` directive (ADR-0020): apply OWN bundled DDL at this
+   * feed position (never wire SQL).
+   *
+   * - Version > bundle → reload + HALT
+   * - Version <= applied → idempotent no-op (redelivery)
+   * - Else apply `(applied, version]`; failure → wipe-and-resync
+   */
+  #onSchemaDirective(message: SchemaDirectiveMessage): void {
+    const version = message.version
+    if (version > this.#bundleVersion) {
+      this.#emitSchemaEvent(
+        'reload',
+        `schema directive v${version} is above the bundled track v${this.#bundleVersion} — reload for the new bundle`,
+      )
+      this.#halt()
+      return
+    }
+    if (version <= this.#appliedVersion) return
+    // Schema apply on exclusive chain like every overlay touching op.
+    this.#exclusive(() => this.#applySchemaDirective(version))
+  }
+
+  #applySchemaDirective(version: number): Awaitable<void> {
+    const failReason = (error: unknown): string =>
+      `local migration to schema v${version} failed: ${errorMessage(error)}`
+    let touched: Awaitable<Set<string>>
+    try {
+      touched = this.#rebase(() => {
+        applyBundledMigrations(
+          this.#db,
+          this.#schema,
+          this.#appliedVersion,
+          version,
+        )
+      })
+    } catch (error) {
+      // Sync migration failure (ADR-0020): #rebase left a clean handle.
+      return this.#wipeAndResync(failReason(error))
+    }
+    return thenMaybeCatch(
+      touched,
+      (t) => {
+        this.#appliedVersion = version
+        // Shape change can touch every read — re-project all consumer tables.
+        this.#notifyChange(new Set([...t, ...this.#allConsumerTables()]))
+      },
+      // Async migration failure: same wipe via rejected rebase promise.
+      (error) => this.#wipeAndResync(failReason(error)),
+    )
+  }
+
+  // --- recovery surface (ADR-0022) ------------------------------------------
+
+  /**
+   * Rebuild sync state (ADR-0022 resync): wipe replica/memberships/cookie, KEEP
+   * clientId + pending, rebootstrap. Same core as failed-migration and
+   * cookie-above-head heals ({@link #wipeAndResync}). Exclusive chain; offline
+   * rebootstrap rides next reconnect.
+   */
+  resync(): void {
+    this.#exclusive(() =>
+      this.#wipeAndResync('resync() requested by the consumer'),
+    )
+  }
+
+  /**
+   * Erase this identity's local data (ADR-0022 forget): wipe replica,
+   * memberships, pending, and all meta (clientId), then fresh first-sight under
+   * a new clientId. Erases WHO, not just WHAT. Awaiters of forgotten writes are
+   * rejected. Topology can swap OPFS on active forget (#134); this resets the
+   * current store. Exclusive chain.
+   */
+  forget(): void {
+    this.#exclusive(() =>
+      this.#forgetAndReset('forget() requested by the consumer'),
+    )
+  }
+
+  // --- durable meta side-writes (ADR-0022, closeio/doync#139) ---------------
+
+  /**
+   * Durably set {@link LogoutBehavior} at runtime ({@link
+   * DoyncClient.setLogoutBehavior}). Via {@link #sideWriteMeta} so it commits
+   * outside the optimistic overlay (#135 / ADR-0019). Direct engine stores for
+   * RN; web DB worker reports to hub.
+   */
+  setLogoutBehavior(behavior: LogoutBehavior): void {
+    this.#sideWriteMeta(__LOGOUT_BEHAVIOR_META_KEY, behavior)
+  }
+
+  /**
+   * Durable `__doync_meta` side write via rebase envelope (#139). For low-
+   * frequency runtime flags ({@link setLogoutBehavior}). High-frequency values
+   * (connected clock #223) stay in memory and piggyback poke apply — full
+   * rebase per tick is wrong. Exclusive chain + {@link #rebase} so the write
+   * commits on the base, not the overlay SAVEPOINT. Meta-only → discard touched
+   * set.
+   */
+  #sideWriteMeta(key: string, value: string): void {
+    this.#sideWrite(() => writeMeta(this.#db, key, value))
+  }
+
+  /**
+   * Durable side-body through overlay envelope (#139/#223/#224): exclusive +
+   * {@link #rebase}. For meta and release stamps. Must NOT nest inside an
+   * in-flight durable body (self-queue); those exec SQL on `this.#db` directly
+   * (see `#breakStaleInstance`).
+   */
+  #sideWrite(body: () => void): void {
+    this.#exclusive(() => thenMaybe(this.#rebase(body), () => {}))
+  }
+
+  /**
+   * Store-erase core for forget / corrupt-meta heal: drop consumer tables,
+   * memberships, pending, all meta; re-replay bundled track from empty. Caller
+   * mints identity. FKs already off (ADR-0009).
+   */
+  #forgetStore(db: LocalDb): void {
+    dropConsumerTables(db, this.#schema)
+    db.exec('DELETE FROM __doync_membership')
+    // Wipe stamps with memberships (ADR-0014 / #224); table shape stays.
+    clearReleaseStamps(db)
+    db.exec('DELETE FROM __doync_pending')
+    // All meta gone => genuine first-sight boot.
+    db.exec('DELETE FROM __doync_meta')
+    // Full bundled track from empty (re-records schema_version).
+    applyBundledMigrations(db, this.#schema, 0, this.#bundleVersion)
+  }
+
+  /**
+   * Mid-session forget (ADR-0022): erase store, mint fresh identity, re-
+   * handshake (or next reconnect). Unlike resync, discards identity and
+   * pending.
+   */
+  #forgetAndReset(reason: string): Awaitable<void> {
+    const db = this.#db
+    const touched = this.#rebase(() => {
+      // Reject awaiters before clearing the queue under them.
+      this.#rejectAllPending(
+        new Error(`doync: ${reason} — pending writes were forgotten`),
+      )
+      this.#forgetStore(db)
+      // Fresh first-sight identity; old server state lapses (ADR-0015).
+      this.#clientId = this.#generateId()
+      writeMeta(db, 'client_id', this.#clientId)
+      this.#cookie = null
+      this.#nextMutationId = 1
+      // Fresh identity => zero connected-time (memory coherent with wiped store).
+      this.#connectedClock = 0
+      this.#lastPongAt = null
+      this.#pending = []
+    })
+    return this.#rebootstrapAfterReset(
+      touched,
+      'forget',
+      `forgot the local store — ${reason}`,
+    )
+  }
+
+  /**
+   * Rebootstrap tail for {@link #wipeAndResync} and {@link #forgetAndReset}: mark
+   * fresh, clear instance info, emit event, handshake once (or next reconnect),
+   * re-project all consumer tables.
+   */
+  #rebootstrapAfterReset(
+    touched: Awaitable<Set<string>>,
+    kind: SchemaEventKind,
+    message: string,
+  ): Awaitable<void> {
+    return thenMaybe(touched, (t) => {
+      this.#appliedVersion = this.#bundleVersion
+      this.#instanceInfo.clear()
+      this.#emitSchemaEvent(kind, message)
+      if (this.#connected) this.#sendHandshake()
+      this.#notifyChange(new Set([...t, ...this.#allConsumerTables()]))
+    })
+  }
+
+  /**
+   * Reject every outstanding mutation promise (forget discards their queue).
+   * Idempotent; orphaneds swallow — frees in-flight callers only.
+   */
+  #rejectAllPending(error: Error): void {
+    // Safe: Map iteration skips removed keys; settleServer deletes when done.
+    for (const id of this.#promises.keys()) {
+      this.#settleClient(id, error)
+      this.#settleServer(id, error)
+    }
+    this.#keyed.clear()
+    this.#recoveredKeys.clear()
+    this.#rejected.clear()
+    this.#optimisticFailed.clear()
+  }
+
+  /**
+   * Wipe-replica-and-resync core (ADR-0020) for resync verb, failed migration,
+   * and cookie-above-head. Drop consumer tables, re-replay bundle, null cookie,
+   * rebootstrap. SURVIVE: pending, clientId, next-mutid, `__doync_engine`
+   * ledger (ADR-0024). Survivors re-push (ADR-0015 pending-without-cursor).
+   */
+  #wipeAndResync(reason: string): Awaitable<void> {
+    const db = this.#db
+    const touched = this.#rebase(() => {
+      dropConsumerTables(db, this.#schema)
+      // Memberships of dropped rows go; pending/clientId/next-id/ledger stay.
+      db.exec('DELETE FROM __doync_membership')
+      // Stamps with memberships (ADR-0014 / #224); table shape stays.
+      clearReleaseStamps(db)
+      // Full bundled track from empty base.
+      writeMeta(db, 'schema_version', '0')
+      applyBundledMigrations(db, this.#schema, 0, this.#bundleVersion)
+      // Null cookie => full rebootstrap on handshake.
+      this.#cookie = null
+      db.exec('DELETE FROM __doync_meta WHERE k = ?', 'cookie')
+    })
+    // Survivors re-push on rebootstrap.
+    return this.#rebootstrapAfterReset(
+      touched,
+      'resync',
+      `wiped and resyncing — ${reason}`,
+    )
+  }
+
+  /** Every consumer table name (untargeted re-projection set). */
+  #allConsumerTables(): string[] {
+    return this.#schema.tables.map((t) => t.name)
+  }
+
+  /**
+   * Schema-state transitions including silent clear (#89) so hooks re-read
+   * {@link schemaStatus} and banners don't stick after recovery.
+   */
+  onSchemaChange(listener: () => void): () => void {
+    this.#schemaListeners.add(listener)
+    return () => this.#schemaListeners.delete(listener)
+  }
+
+  /** Record a schema-state transition and notify listeners/callback. */
+  #emitSchemaEvent(kind: SchemaEventKind, message: string): void {
+    const event: SchemaEvent = { kind, message }
+    this.#schemaEvent = event
+    this.#onSchemaEvent?.(event)
+    this.#notifySchema()
+  }
+
+  /**
+   * Clear transient schema state once sync resumes (ack/poke after
+   * re-handshake): server-behind / resync / forget. `reload` is terminal
+   * (halted ignores frames). Notifies subscribers; config callback has no
+   * cleared kind.
+   */
+  #clearTransientSchemaEvent(): void {
+    const kind = this.#schemaEvent?.kind
+    if (kind === 'server-behind' || kind === 'resync' || kind === 'forget') {
+      this.#schemaEvent = null
+      this.#notifySchema()
+    }
+  }
+
+  /** Notify schema-state subscribers (set or clear). */
+  #notifySchema(): void {
+    for (const listener of this.#schemaListeners) listener()
+  }
+
+  /** Stop handshakes and frame apply until app reload (reload skew). */
+  #halt(): void {
+    this.#halted = true
+    this.#setConnected(false)
+  }
+
+  // --- connection status (closeio/doync#105, #136) --------------------------
+
+  /**
+   * {@link ConnectionStatus} to the Mirror (#105/#136). Precedence: 1.
+   * `needs-auth` — engine inference off framed `unauthorized` (ADR-0018),
+   * sticky until a real frame proves the refreshed handshake; outranks seam and
+   * even a reopened socket. 2. `connected` — live open outranks a stale seam
+   * report. 3. Last {@link SeamStatus}, else `disconnected`.
+   *
+   * Full five states when the seam reports; degraded adapters (no seam) get
+   * connected/disconnected (+ needs-auth). Parity with shared-hub.ts.
+   */
+  get connectionStatus(): ConnectionStatus {
+    if (this.#needsAuth) return 'needs-auth'
+    if (this.#connected) return 'connected'
+    return this.#seamStatus ?? 'disconnected'
+  }
+
+  /** Subscribe to connection-status transitions (#105). */
+  onConnectionChange(listener: () => void): () => void {
+    this.#connectionListeners.add(listener)
+    return () => this.#connectionListeners.delete(listener)
+  }
+
+  /**
+   * Flip handshake-live (#136). Live open clears stale seam status; needs-auth
+   * untouched (clears only on proven frame). {@link #transitionConnection}
+   * notifies only on visible change.
+   */
+  #setConnected(value: boolean): void {
+    this.#transitionConnection(() => {
+      this.#connected = value
+      if (value) this.#seamStatus = null
+    })
+  }
+
+  /**
+   * Seam transient (#136): connecting/error. Stored even while outranked so it
+   * surfaces when higher precedence clears.
+   */
+  #onSeamStatus(status: SeamStatus): void {
+    this.#transitionConnection(() => {
+      this.#seamStatus = status
+    })
+  }
+
+  /** Set/clear sticky auth-failure (#136, ADR-0018). */
+  #setNeedsAuth(value: boolean): void {
+    this.#transitionConnection(() => {
+      this.#needsAuth = value
+    })
+  }
+
+  /**
+   * Mutate connection state; notify only when visible {@link connectionStatus}
+   * changes (outranked inputs stay silent).
+   */
+  #transitionConnection(mutate: () => void): void {
+    const before = this.connectionStatus
+    mutate()
+    if (this.connectionStatus === before) return
+    for (const listener of this.#connectionListeners) listener()
+  }
+
+  // --- reactivity -----------------------------------------------------------
+
+  /**
+   * Re-project after a local change: subscription re-runs when Read-set
+   * intersects touched consumer tables; Local (no Read-set) always re-runs.
+   * Unchanged rows => no notify.
+   *
+   * Target TOUCHED TABLES (ADR-0019 delta 3), not patched instances — shared
+   * replica means A's patch can change B's SQL over the same table.
+   */
+  #notifyChange(touched: ReadonlySet<string>): void {
+    const consumerTouched = consumerTables(touched)
+    // Overlay settled: flush views gated during the just-finished replay.
+    // Re-entrant gating inside notify() is picked up by `#flushGatedViews`.
+    const wasGated = new Set(this.#gatedViews)
+    this.#gatedViews.clear()
+    for (const read of this.#liveReads()) {
+      const readSet = read.readSet
+      const affected =
+        wasGated.has(read) ||
+        readSet === undefined ||
+        [...readSet].some((t) => consumerTouched.has(t))
+      if (affected && read.recompute()) read.notify()
+    }
+  }
+
+  /** Every live reactive read: desired + local (ADR-0023). */
+  *#liveReads(): IterableIterator<RawRead> {
+    for (const entry of this.#desired.values()) {
+      if (entry.read !== null) yield entry.read
+    }
+    for (const entry of this.#localReads.values()) {
+      if (entry.read !== null) yield entry.read
+    }
+  }
+
+  // --- status lifecycle (closeio/doync#104) ---------------------------------
+
+  /**
+   * Set desire phase and push visible {@link ViewStatus} (#104). No-op if
+   * unknown. pending→acked is invisible (stable status, no notify).
+   */
+  #setPhase(identity: string, phase: SubPhase, error?: Error): void {
+    const entry = this.#desired.get(identity)
+    if (entry === undefined) return
+    entry.phase = phase
+    entry.error = error
+    const next = phaseToStatus(phase, error)
+    if (entry.read !== null && entry.read.updateStatus(next)) {
+      entry.read.notify()
+    }
+  }
+
+  // --- promise bookkeeping --------------------------------------------------
+
+  #ensurePromise(id: number, orphan: boolean): PendingPromise {
+    const existing = this.#promises.get(id)
+    if (existing !== undefined) return existing
+    const promise = this.#makePromise(orphan)
+    this.#promises.set(id, promise)
+    return promise
+  }
+
+  /**
+   * Make `{client, server}` without id keying. mutate returns sync; id is
+   * allocated on the chain so fail-fast consumes none.
+   */
+  #makePromise(orphan: boolean): PendingPromise {
+    let resolveClient!: () => void
+    let rejectClient!: (error: unknown) => void
+    let resolveServer!: () => void
+    let rejectServer!: (error: unknown) => void
+    const client = new Promise<void>((res, rej) => {
+      resolveClient = res
+      rejectClient = rej
+    })
+    const server = new Promise<void>((res, rej) => {
+      resolveServer = res
+      rejectServer = rej
+    })
+    if (orphan) {
+      // Orphan: swallow settlement (no caller in this process).
+      client.catch(() => {})
+      server.catch(() => {})
+    }
+    return {
+      pair: { client, server },
+      resolveClient,
+      rejectClient,
+      resolveServer,
+      rejectServer,
+      clientSettled: false,
+      serverSettled: false,
+    }
+  }
+
+  #settleClient(id: number, error: unknown): void {
+    const promise = this.#promises.get(id)
+    if (promise === undefined) {
+      // Unknown id would hang a waiting mutate — surface instead of silent no-op.
+      this.#errors.push(
+        `doync: settleClient for unknown mutation ${id} — no pending promise (a mutate() awaiting it would hang)`,
+      )
+      return
+    }
+    if (promise.clientSettled) return
+    promise.clientSettled = true
+    if (error === null) promise.resolveClient()
+    else promise.rejectClient(error)
+  }
+
+  #settleServer(id: number, error: unknown): void {
+    const promise = this.#promises.get(id)
+    if (promise === undefined) {
+      this.#errors.push(
+        `doync: settleServer for unknown mutation ${id} — no pending promise (a mutate() awaiting it would hang)`,
+      )
+      return
+    }
+    if (promise.serverSettled) return
+    promise.serverSettled = true
+    if (error === null) promise.resolveServer()
+    else promise.rejectServer(error)
+    if (promise.clientSettled) this.#promises.delete(id)
+  }
+}
+
+/**
+ * Sync-or-async overlay currency (ADR-0019 addendum): ops return T now or a
+ * Promise. Chained via isThenable / thenMaybe without microtasking the all-
+ * sync path.
+ */
+type Awaitable<T> = T | Promise<T>
+
+/** One overlay-touching step on the exclusive chain (ADR-0019 addendum). */
+type ChainStep = () => Awaitable<void>
+
+function isThenable(value: unknown): value is Promise<unknown> {
+  return value instanceof Promise
+}
+
+/** Continue with `fn` sync when already settled, else via Promise. */
+function thenMaybe<T, R>(
+  value: Awaitable<T>,
+  fn: (value: T) => Awaitable<R>,
+): Awaitable<R> {
+  return value instanceof Promise ? value.then(fn) : fn(value)
+}
+
+/**
+ * {@link thenMaybe} with async rejection continuation. Sync values only run
+ * `onOk` (caller try/catch already handled sync throws).
+ */
+function thenMaybeCatch<T, R>(
+  value: Awaitable<T>,
+  onOk: (value: T) => Awaitable<R>,
+  onErr: (error: unknown) => Awaitable<R>,
+): Awaitable<R> {
+  return value instanceof Promise ? value.then(onOk, onErr) : onOk(value)
+}
+
+type AnyRow = Record<string, SqlValue>
+
+/**
+ * Inert {@link View} for skipped subscribe (#104): no desire, no re-exec, empty
+ * rows, status unknown, no-op retain/release. Not keyed. Un-skip = fresh
+ * subscribe at the hook (#105).
+ */
+class SkippedView implements View<Record<string, unknown>> {
+  current(): readonly Record<string, unknown>[] {
+    return EMPTY_ROWS
+  }
+
+  status(): ViewStatus {
+    return UNKNOWN_STATUS
+  }
+
+  onChange(): () => void {
+    return () => {}
+  }
+
+  retain(): void {}
+
+  release(): void {}
+}
+
+/**
+ * In-flight Once handle (ADR-0012/0021): local cache first, server answer
+ * later, `server` promise for hook status. Internal over {@link AnyRow}; typed
+ * at boundary.
+ */
+class OnceViewImpl implements OnceView<Record<string, unknown>> {
+  #snapshot: readonly Record<string, unknown>[]
+  readonly #listeners = new Set<() => void>()
+  #started = false
+  #disposed = false
+  #serverPromiseWithResolvers =
+    Promise.withResolvers<readonly Record<string, unknown>[]>()
+  #disposeTimer: ReturnType<typeof setTimeout> | null = null
+  /** Nested-relation decode; applied to server answer too. */
+  readonly #decode: RowDecoder | undefined
+  readonly #startNetwork: () => void
+  readonly #drop: () => void
+
+  constructor(
+    cached: readonly Record<string, unknown>[],
+    decode: RowDecoder | undefined,
+    hooks: { start: () => void; drop: () => void },
+  ) {
+    this.#snapshot = cached
+    this.#decode = decode
+    this.#startNetwork = hooks.start
+    this.#drop = hooks.drop
+  }
+
+  current(): readonly Record<string, unknown>[] {
+    // First read arms the network half (#91). StrictMode-discarded renders
+    // never read (uSES after subscribe), so construction stays pure.
+    this.#ensureOpen()
+    return this.#snapshot
+  }
+
+  onChange(listener: () => void): () => void {
+    this.#ensureOpen()
+    this.#listeners.add(listener)
+    return () => this.#listeners.delete(listener)
+  }
+
+  /** Lazily arm the network half (Q7 commit-owns); first onChange/server starts. */
+  get server(): Promise<readonly Record<string, unknown>[]> {
+    this.#ensureOpen()
+    return this.#serverPromiseWithResolvers.promise
+  }
+
+  /** Server answer landed: decode, swap snapshot, resolve, notify. */
+  deliver(rows: AnyRow[]): void {
+    if (this.#disposed) return
+    const decoded = this.#decode ? this.#decode(rows) : rows
+    this.#snapshot = decoded
+    this.#serverPromiseWithResolvers.resolve(decoded)
+    for (const listener of this.#listeners) listener()
+  }
+
+  /** Mirror could not answer: reject `server`. */
+  settleError(error: unknown): void {
+    if (this.#disposed) return
+    this.#serverPromiseWithResolvers.reject(error)
+  }
+
+  /**
+   * Drop after one Warm tick. Idempotent; re-open within tick cancels
+   * (StrictMode).
+   */
+  dispose(): void {
+    if (this.#disposed) return
+    if (this.#disposeTimer !== null) return
+    this.#disposeTimer = setTimeout(() => {
+      this.#disposeTimer = null
+      if (this.#disposed) return
+      this.#disposed = true
+      this.#listeners.clear()
+      this.#drop()
+    }, WARM_POOL_TICK_MS)
+  }
+
+  #ensureOpen(): void {
+    if (this.#disposed) return
+    if (this.#disposeTimer !== null) {
+      clearTimeout(this.#disposeTimer)
+      this.#disposeTimer = null
+    }
+    if (this.#started) return
+    this.#started = true
+    this.#serverPromiseWithResolvers =
+      Promise.withResolvers<readonly Record<string, unknown>[]>()
+    // Swallow server rejection if caller never awaits (no unhandled rejection).
+    this.#serverPromiseWithResolvers.promise.catch(() => {})
+    this.#startNetwork()
+  }
+}
+
+/**
+ * `false | null | undefined` — the "no query" sentinel (ADR-0027 /
+ * closeio/doync#195/#200). Exported so adapters reuse the same predicate the
+ * direct engine uses rather than shadowing a three-literal check.
+ */
+export function isFalsyQuery(value: unknown): value is FalsyQuery {
+  return value === false || value === null || value === undefined
+}
+
+/**
+ * Bound-form surface normalize (ADR-0027 / closeio/doync#200): peel a
+ * {@link BoundQuery} into `{leaf, args, options?}`, or reject a truthy non-bound
+ * impostor with a surface-named error. An uncalled RegisteredQuery (a function)
+ * hits "did you forget to call it?" — registration is a type-level fact, so the
+ * legacy definition arm is gone.
+ *
+ * Exported from `@doync/client` so the web topology and mobile wrapper share
+ * one surface check with the direct engine — no per-adapter copy of the
+ * impostor wording.
+ */
+export function normalizeQuerySurface<Options = never>(
+  surface: 'subscribe' | 'once' | 'preload',
+  queryOrBound: unknown,
+  options?: Options,
+): {
+  query: BoundQuery['query']
+  args: unknown
+  options: Options | undefined
+} {
+  if (isBoundQuery(queryOrBound)) {
+    // Cast erases the bound leaf's `One` phantom — resolve/name are all the
+    // engine needs from here on; Row/One flow from the public overloads only.
+    return {
+      query: queryOrBound.query,
+      args: queryOrBound.args,
+      options,
+    }
+  }
+  throw querySurfaceImpostorError(surface, queryOrBound)
+}
+
+/**
+ * Named impostor rejection for a truthy non-bound value on a query surface
+ * (ADR-0027): one error shape per surface, with the received-a-function case
+ * called out as the uncalled-query mistake.
+ */
+function querySurfaceImpostorError(surface: string, value: unknown): Error {
+  if (typeof value === 'function') {
+    return new Error(
+      `doync: client.${surface} expected a BoundQuery — received a function; did you forget to call it?`,
+    )
+  }
+  return new Error(
+    `doync: client.${surface} expected a BoundQuery, got ${describeImpostor(value)}`,
+  )
+}
+
+/** Short runtime description for an impostor value (never dumps large objects). */
+function describeImpostor(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'an array'
+  const type = typeof value
+  if (type === 'object') {
+    const kind = (value as { kind?: unknown }).kind
+    if (typeof kind === 'string') return `an object with kind "${kind}"`
+    return 'an object'
+  }
+  return type
+}
+
+/**
+ * Inert {@link OnceView} for falsy Once (ADR-0027 / #195): no network, empty
+ * cache, never-settling `server` (hooks map to skipped). Safe no-op methods.
+ */
+class SkippedOnceView implements OnceView<Record<string, unknown>> {
+  current(): readonly Record<string, unknown>[] {
+    return EMPTY_ROWS
+  }
+
+  onChange(): () => void {
+    return () => {}
+  }
+
+  get server(): Promise<readonly Record<string, unknown>[]> {
+    // Never settles — network never started; hook layer owns the skipped status.
+    return new Promise(() => {})
+  }
+
+  dispose(): void {}
+}
+
+/** No-op {@link PreloadHandle} for preload(falsy) (ADR-0027). */
+const NOOP_PRELOAD: PreloadHandle = {
+  cleanup(): void {},
+}
+
+/** Decode a codec-encoded Once row (ADR-0010). */
+function decodeOnceRow(image: Record<string, unknown>): AnyRow {
+  const row: AnyRow = {}
+  for (const [column, value] of Object.entries(image)) {
+    row[column] = decodeImageValue(value)
+  }
+  return row
+}
+
+/** Drop `__doync_`-internal tables from a set (ADR-0007). */
+function consumerTables(tables: ReadonlySet<string>): Set<string> {
+  return new Set([...tables].filter((t) => !isInternalTable(t)))
+}
+
+/**
+ * A `mutate()` whose failure is known synchronously (unknown name, bad args).
+ * Exported for the web topology's tab-side `mutate`, which shares the
+ * never-throw contract (#161).
+ */
+export function settledRejection(error: unknown): MutationResult {
+  const client = Promise.reject(error)
+  const server = Promise.reject(error)
+  // The caller may await only one of the pair; swallow the other so a validation
+  // error never surfaces as an unhandled rejection.
+  client.catch(() => {})
+  server.catch(() => {})
+  return { client, server }
+}
+
+/** Message of a thrown value (Error or otherwise). */
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Warm pool retention (CONTEXT.md; ADR-0023) — one knob (StrictMode /
+ * soft-nav). Future count/time bounds change only this value's shape.
+ */
+const WARM_POOL_TICK_MS = 0
+
+/** Shared empty-rows snapshot for skipped/unseeded Views (stable). */
+const EMPTY_ROWS: readonly Record<string, unknown>[] = Object.freeze([])
+/** Shared unknown/complete status snapshots (stable, #104). */
+const UNKNOWN_STATUS: ViewStatus = Object.freeze({ status: 'unknown' })
+const COMPLETE_STATUS: ViewStatus = Object.freeze({ status: 'complete' })
+
+/**
+ * {@link SubPhase} -> visible {@link ViewStatus} (#104): pending/acked share
+ * frozen unknown; complete uses frozen singleton; error is a fresh object.
+ */
+function phaseToStatus(phase: SubPhase, error: Error | undefined): ViewStatus {
+  if (phase === 'complete') return COMPLETE_STATUS
+  if (phase === 'error') {
+    return error === undefined
+      ? { status: 'error' }
+      : { status: 'error', error }
+  }
+  return UNKNOWN_STATUS
+}
+
+const defaultGenerateID = (): string => {
+  const g = globalThis as { crypto?: { randomUUID?: () => string } }
+  const uuid = g.crypto?.randomUUID?.()
+  if (uuid !== undefined) return uuid
+  return `client-${Math.random().toString(16).slice(2)}-${Date.now().toString(16)}`
+}
+
+/**
+ * Durable int meta keys for boot corruption scan (ADR-0022). Excludes connected
+ * clock (#223 — never on wire; lenient zero reset, not forget-heal).
+ */
+const DURABLE_INT_META_KEYS = ['schema_version', 'next_mutation_id', 'cookie']
+
+/**
+ * First durable-int meta key with a present non-integer, or null (ADR-0022).
+ * Boot scan before store read — corrupt counter => loud forget-heal, not refuse
+ * (#128 C6). Same keys `#durableInt` later reads.
+ */
+function corruptMetaKey(db: LocalDb): string | null {
+  for (const key of DURABLE_INT_META_KEYS) {
+    const raw = readMeta(db, key)
+    if (raw !== null && !Number.isInteger(Number(raw))) return key
+  }
+  return null
+}
+
+/**
+ * Cookie-above-Origin-head framed error (ADR-0016/0020): keys on the harness-
+ * pinned phrase; heal via automatic resync, not permanent sub error.
+ */
+function isCookieAboveHeadError(message: string): boolean {
+  return message.includes('above the Origin head')
+}