@doync/client 0.1.0 → 0.2.0

package/src/engine.ts

@@ -1,7 +1,9 @@
 import type {
+  AuthContext,
   BoundQuery,
   DoyncSchema,
   MutationDefinition,
+  MutationExec,
   RowDecoder,
   SqlValue,
 } from '@doync/core'
@@ -18,21 +20,18 @@ import type {
 
 import { isBoundQuery } from '@doync/core/internal'
 import {
-  assertWireRepresentable,
-  canonicalizeArgsBinary,
   declaredSchemaVersion,
   decodeArgs,
   decodeImageValue,
   encodeArgs,
   isInternalTable,
+  prepareArgs,
 } 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 { type LocalStatement, RawRead } from './raw-read'
 import {
   applyBundledMigrations,
   assertNoReservedTables,
@@ -47,12 +46,13 @@ import {
   quoteIdent,
   readMeta,
   readReleaseStamp,
+  type ReleaseStamp,
   replayMigrations,
   requireTable,
   resolveReleaseTtlMs,
   upsertReleaseStamp,
   writeMeta,
-  type ReleaseStamp,
+  writePref,
 } from './replica'
 
 /**
@@ -76,12 +76,12 @@ export interface MutationResult {
 export type LogoutBehavior = 'keep' | 'forget'
 
 /**
- * The `__doync_meta` key the durable {@link LogoutBehavior} lives under
+ * The `__doync_prefs` 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'
+export const __LOGOUT_BEHAVIOR_PREF_KEY = 'logout_behavior'
 
 /**
  * The `__doync_meta` key the Client's durable connected-time counter lives
@@ -99,12 +99,22 @@ export const __CONNECTED_CLOCK_META_KEY = 'connected_clock'
  *   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.
+ * - `resync` — local sync state wiped and rebuilding as a fresh Client under the
+ *   same identity (pending writes dropped, new clientId). Transient; clears
+ *   when sync resumes.
+ * - `reaped` — same fresh-client rebuild as `resync`, but the Origin forgot this
+ *   Client (gone past the client-state lifetime). Transient; clears when sync
+ *   resumes. Distinct so the app can say "you were away too long" rather than
+ *   "data refreshed".
  * - `forget` — local store erased (including identity); boots as a fresh client.
  *   Transient; clears when sync resumes.
  */
-export type SchemaEventKind = 'reload' | 'server-behind' | 'resync' | 'forget'
+export type SchemaEventKind =
+  | 'reload'
+  | 'server-behind'
+  | 'resync'
+  | 'reaped'
+  | 'forget'
 
 /**
  * One schema-status transition: `kind` plus a human-readable `message` for
@@ -274,17 +284,18 @@ export interface DoyncClient {
    */
   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 —
+   * Rebuild sync state as a fresh Client under the same identity: drop pending
+   * writes, mint a new clientId, wipe the replica, and rebootstrap. Destructive
+   * to unsent work — not a harmless refresh. Optional on the interface —
    * platform clients implement it.
    */
-  resync?(): void
+  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
+  forget(identity?: string): void
   /**
    * Durably set {@link LogoutBehavior} at runtime (e.g. a "remember me"
    * checkbox). Survives restart. Optional — platform clients implement it.
@@ -363,15 +374,15 @@ export interface ClientEngineConfig {
    * Named mutation bodies resolved on `push` — deterministic, DB-only
    * (ADR-0017/0021).
    */
-  readonly mutations: ClientMutationRegistry
+  readonly mutations: Record<string, MutationDefinition>
   /** 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 `{}`.
+   * decode. `null` when anonymous.
    */
-  readonly ctx?: Record<string, unknown>
+  readonly ctx?: AuthContext
   /**
    * Transport credential PRESENTED as `connect{jwt}` (ADR-0016/0018) — the
    * Mirror resolves token-first. Auth must ride the HANDSHAKE, not only the
@@ -678,13 +689,13 @@ class ViewHandle implements View<Record<string, unknown>> {
 export class ClientEngine implements DoyncClient {
   readonly #db: LocalDb
   readonly #schema: DoyncSchema
-  readonly #mutations: ClientMutationRegistry
+  readonly #mutations: Record<string, MutationDefinition>
   readonly #socket: SyncSocket
   /**
    * Projected auth ctx (ADR-0018) for queries/bodies. Updated by
-   * {@link updateAuth} on same-user refresh (#102).
+   * {@link updateAuth} on same-user refresh (#102). `null` when anonymous.
    */
-  #ctx: Record<string, unknown>
+  #ctx: AuthContext
   /**
    * Bearer for every handshake (ADR-0016/0018). Updated by {@link updateAuth} so
    * refresh rides in-band update AND the next reconnect (#102).
@@ -850,7 +861,7 @@ export class ClientEngine implements DoyncClient {
     this.#schema = config.schema
     this.#mutations = config.mutations
     this.#socket = config.socket
-    this.#ctx = config.ctx ?? {}
+    this.#ctx = config.ctx ?? null
     this.#token = config.token
     // Asserted identity (#167) — never from the token.
     this.#userId = config.userId ?? null
@@ -953,19 +964,12 @@ export class ClientEngine implements DoyncClient {
     // 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),
-      )
+      // Consumer half of wipe-and-resync. Boot mints a fresh clientId because
+      // the stored one goes with the rest of the cookie/cursor state. The
+      // bundle version is passed explicitly — `#bundleVersion` is assigned
+      // below, after the track settles.
+      this.#wipeStore(db, declaredSchemaVersion(this.#schema))
       this.#cookie = null
-      db.exec('DELETE FROM __doync_meta WHERE k = ?', 'cookie')
     } else {
       replayMigrations(db, this.#schema)
     }
@@ -1262,7 +1266,7 @@ export class ClientEngine implements DoyncClient {
     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())
+      running = entry.body({ args: p.args, ctx: this.#ctx, sql: this.#tx() })
     } catch (error) {
       this.#failBody(p.mutationId, error)
       return
@@ -1290,8 +1294,16 @@ export class ClientEngine implements DoyncClient {
   }
 
   /** Mutation-body write surface (exec returns rows, ADR-0021). */
-  #tx(): ClientMutationTx {
-    return { exec: (query, ...params) => this.#db.exec(query, ...params) }
+  #tx(): MutationExec {
+    // Booleans canonicalize to 1/0 at the seam — the LocalDb port speaks
+    // SqlValue only (SQLite has no boolean affinity).
+    return {
+      exec: (query, ...params) =>
+        this.#db.exec(
+          query,
+          ...params.map((p) => (typeof p === 'boolean' ? (p ? 1 : 0) : p)),
+        ),
+    }
   }
 
   /**
@@ -1337,25 +1349,15 @@ export class ClientEngine implements DoyncClient {
     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
+      // The one args-preparation path (ADR-0031), shared with the Origin push
+      // seam: guard, canonicalize, validate through the definition's schema.
+      // Throw is sync fail-fast: nothing enqueued, `client` rejects. Encode
+      // the post-schema value so wire and durable queue match what the
+      // optimistic body saw (validators assumed pass-through / idempotent).
+      liveArgs = prepareArgs(entry.args, args, 'mutation args')
       wireArgs = encodeArgs(liveArgs, 'mutation args')
     } catch (error) {
       return settledRejection(error)
@@ -1464,19 +1466,19 @@ export class ClientEngine implements DoyncClient {
   // --- 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.
+   * Adopt a refreshed SAME-USER identity (#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.
+   * engines never emit. Pass `ctx: null` for anonymous.
    */
   updateAuth(
     token: string | null | undefined,
-    ctx?: Record<string, unknown>,
+    ctx?: AuthContext,
     userId?: string | null,
   ): void {
     this.#token = token ?? undefined
@@ -2147,7 +2149,7 @@ export class ClientEngine implements DoyncClient {
         }
         break
       case 'pokeReject':
-        this.#handleReject(message.mutationId, message.error)
+        this.#handleReject(message.mutationId, message.error, message.reason)
         break
       case 'onceStart':
         // Fresh Once accumulator (ADR-0012); reconnect re-issue resets partial.
@@ -2166,8 +2168,8 @@ export class ClientEngine implements DoyncClient {
         this.#handleOnceEnd(message)
         break
       case 'resyncRequired':
-        // heldAt-ahead tripwire (ADR-0029 / #225): resync self-heal (keep
-        // clientId + pendings). First-class frame, not phrase-matched.
+        // heldAt-ahead tripwire (ADR-0029 / #225): resync self-heal as a fresh
+        // client. First-class frame, not phrase-matched.
         this.#errors.push(message.message)
         this.#exclusive(() =>
           this.#wipeAndResync(
@@ -2178,8 +2180,8 @@ export class ClientEngine implements DoyncClient {
       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).
+        // returning cookie above head — heal via wipe-and-resync as a fresh
+        // client, not a permanent subscription error.
         if (isCookieAboveHeadError(message.message)) {
           this.#exclusive(() =>
             this.#wipeAndResync(
@@ -2475,9 +2477,24 @@ export class ClientEngine implements DoyncClient {
    * 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).
+   *
+   * `reason: 'reaped'` (ADR-0015 / ADR-0037) is recovery, not a per-mutation
+   * failure: the Origin has no cursor for this Client, so every pending is
+   * dropped as a fresh-client heal — first-class tag, never phrase-matched.
    */
-  #handleReject(mutationId: number, error: string): void {
+  #handleReject(mutationId: number, error: string, reason?: 'reaped'): void {
     this.#rejected.add(mutationId)
+    if (reason === 'reaped') {
+      const dropped = this.#pending.length
+      this.#errors.push(error)
+      this.#exclusive(() =>
+        this.#wipeAndResync(
+          `server forgot this client (reaped) — dropped ${dropped} pending write${dropped === 1 ? '' : 's'} — ${error}`,
+          'reaped',
+        ),
+      )
+      return
+    }
     this.#exclusive(() =>
       thenMaybe(this.#dropPending(mutationId), (touched) => {
         this.#settleServer(mutationId, new Error(error))
@@ -2567,13 +2584,15 @@ export class ClientEngine implements DoyncClient {
     )
   }
 
-  // --- recovery surface (ADR-0022) ------------------------------------------
+  // --- recovery surface (ADR-0022 / ADR-0037) --------------------------------
 
   /**
-   * 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.
+   * Rebuild sync state as a fresh Client under the same identity (ADR-0022 /
+   * ADR-0037 resync): drop pending writes, mint a new clientId, wipe replica /
+   * memberships / cookie, rebootstrap. Same core as failed-migration,
+   * cookie-above-head, and heldAt-ahead heals ({@link #wipeAndResync}).
+   * Exclusive chain; offline rebootstrap rides next reconnect. Preferences
+   * survive (`__doync_prefs`).
    */
   resync(): void {
     this.#exclusive(() =>
@@ -2583,10 +2602,10 @@ export class ClientEngine implements DoyncClient {
 
   /**
    * 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.
+   * memberships, pending, meta, and preferences, then fresh first-sight under a
+   * new clientId. Erases WHO, not just WHAT. Awaiters of forgotten writes are
+   * rejected. Topology can erase the identity's database file on active forget
+   * (#134); this resets the current store. Exclusive chain.
    */
   forget(): void {
     this.#exclusive(() =>
@@ -2598,24 +2617,24 @@ export class ClientEngine implements DoyncClient {
 
   /**
    * Durably set {@link LogoutBehavior} at runtime ({@link
-   * DoyncClient.setLogoutBehavior}). Via {@link #sideWriteMeta} so it commits
+   * DoyncClient.setLogoutBehavior}). Via {@link #sideWritePref} 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)
+    this.#sideWritePref(__LOGOUT_BEHAVIOR_PREF_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.
+   * Durable `__doync_prefs` side write via rebase envelope (#139). For low-
+   * frequency runtime preferences ({@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. Pref-only → discard
+   * touched set.
    */
-  #sideWriteMeta(key: string, value: string): void {
-    this.#sideWrite(() => writeMeta(this.#db, key, value))
+  #sideWritePref(key: string, value: string): void {
+    this.#sideWrite(() => writePref(this.#db, key, value))
   }
 
   /**
@@ -2629,44 +2648,66 @@ export class ClientEngine implements DoyncClient {
   }
 
   /**
-   * 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).
+   * Shared fresh-client store wipe for Resync, Forget, and the boot-time
+   * ledger-rollback heal (ADR-0037): drop consumer tables, memberships, stamps,
+   * pending queue, and all sync meta; re-replay the bundled track from empty.
+   * Preferences (`__doync_prefs`) and the engine ledger stay. Caller mints the
+   * fresh identity. FKs already off (ADR-0009).
+   *
+   * `bundleVersion` defaults to the engine's, and is passed explicitly from
+   * boot, which runs before that field is assigned.
    */
-  #forgetStore(db: LocalDb): void {
+  #wipeStore(db: LocalDb, bundleVersion = this.#bundleVersion): 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.
+    // All sync meta gone — cookie, clientId, next-mutid, connected clock.
     db.exec('DELETE FROM __doync_meta')
     // Full bundled track from empty (re-records schema_version).
-    applyBundledMigrations(db, this.#schema, 0, this.#bundleVersion)
+    applyBundledMigrations(db, this.#schema, 0, bundleVersion)
+  }
+
+  /**
+   * Store-erase core for forget / corrupt-meta heal: shared wipe plus
+   * preferences. Caller mints identity. Topology may also erase the database
+   * file.
+   */
+  #forgetStore(db: LocalDb): void {
+    this.#wipeStore(db)
+    db.exec('DELETE FROM __doync_prefs')
   }
 
   /**
-   * Mid-session forget (ADR-0022): erase store, mint fresh identity, re-
-   * handshake (or next reconnect). Unlike resync, discards identity and
-   * pending.
+   * Shared memory reset after a store wipe: reject awaiters, mint a fresh
+   * clientId, empty the pending queue, null the cookie, reset the mutation
+   * counter and connected clock.
+   */
+  #resetToFreshClient(dropError: Error): void {
+    const db = this.#db
+    this.#rejectAllPending(dropError)
+    this.#clientId = this.#generateId()
+    writeMeta(db, 'client_id', this.#clientId)
+    this.#cookie = null
+    this.#nextMutationId = 1
+    this.#connectedClock = 0
+    this.#lastPongAt = null
+    this.#pending = []
+  }
+
+  /**
+   * Mid-session forget (ADR-0022): erase store (including preferences), mint
+   * fresh identity, re-handshake (or next reconnect). Topology may also erase
+   * the identity's database file.
    */
   #forgetAndReset(reason: string): Awaitable<void> {
     const db = this.#db
     const touched = this.#rebase(() => {
-      // Reject awaiters before clearing the queue under them.
-      this.#rejectAllPending(
+      this.#forgetStore(db)
+      this.#resetToFreshClient(
         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,
@@ -2677,8 +2718,9 @@ export class ClientEngine implements DoyncClient {
 
   /**
    * 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.
+   * fresh, clear instance info, emit event, drop-and-redial when live so the
+   * new clientId rides the upgrade pin (ADR-0016), re-project all consumer
+   * tables. Offline tanks until the next connect (no live socket to drop).
    */
   #rebootstrapAfterReset(
     touched: Awaitable<Set<string>>,
@@ -2689,14 +2731,20 @@ export class ClientEngine implements DoyncClient {
       this.#appliedVersion = this.#bundleVersion
       this.#instanceInfo.clear()
       this.#emitSchemaEvent(kind, message)
-      if (this.#connected) this.#sendHandshake()
+      // Fresh clientId cannot ride an already-pinned socket (ADR-0016 upgrade
+      // pin). Drop and redial so the next open re-handshakes as the new Client
+      // — same posture as client-ahead skew backoff.
+      if (this.#connected) {
+        this.#setConnected(false)
+        this.#socket.reconnect()
+      }
       this.#notifyChange(new Set([...t, ...this.#allConsumerTables()]))
     })
   }
 
   /**
-   * Reject every outstanding mutation promise (forget discards their queue).
-   * Idempotent; orphaneds swallow — frees in-flight callers only.
+   * Reject every outstanding mutation promise (resync/forget discard their
+   * queue). Idempotent; orphaneds swallow — frees in-flight callers only.
    */
   #rejectAllPending(error: Error): void {
     // Safe: Map iteration skips removed keys; settleServer deletes when done.
@@ -2711,31 +2759,32 @@ export class ClientEngine implements DoyncClient {
   }
 
   /**
-   * 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).
+   * Wipe-replica-and-resync core (ADR-0020 / ADR-0037) for the resync verb,
+   * failed migration, cookie-above-head, heldAt-ahead, and client-state reap:
+   * drop consumer tables, pending writes, and sync meta; mint a fresh clientId;
+   * re-replay the bundle; rebootstrap. Preferences (`__doync_prefs`) and the
+   * `__doync_engine` ledger survive. A clientId the Origin has never seen
+   * starts its mutation counter at 1 by construction. `kind` is `reaped` when
+   * the Origin forgot the Client so the consumer can distinguish that from an
+   * ordinary repair; the default is `resync`.
    */
-  #wipeAndResync(reason: string): Awaitable<void> {
+  #wipeAndResync(
+    reason: string,
+    kind: 'resync' | 'reaped' = 'resync',
+  ): 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')
+      this.#wipeStore(db)
+      this.#resetToFreshClient(
+        new Error(`doync: ${reason} — pending writes were dropped`),
+      )
     })
-    // Survivors re-push on rebootstrap.
     return this.#rebootstrapAfterReset(
       touched,
-      'resync',
-      `wiped and resyncing — ${reason}`,
+      kind,
+      kind === 'reaped'
+        ? `client state was reaped — ${reason}`
+        : `wiped and resyncing — ${reason}`,
     )
   }
 
@@ -2763,13 +2812,18 @@ export class ClientEngine implements DoyncClient {
 
   /**
    * 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.
+   * re-handshake): server-behind / resync / reaped / 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') {
+    if (
+      kind === 'server-behind' ||
+      kind === 'resync' ||
+      kind === 'reaped' ||
+      kind === 'forget'
+    ) {
       this.#schemaEvent = null
       this.#notifySchema()
     }

package/src/index.ts

@@ -12,6 +12,7 @@
  */
 
 export type { LogoutBehavior } from './client'
+export type { AuthData } from '@doync/core'
 export type {
   ConnectionStatus,
   DoyncClient,
@@ -28,9 +29,3 @@ export type {
   View,
   ViewStatus,
 } from './engine'
-export type {
-  ClientMutation,
-  ClientMutationHandler,
-  ClientMutationRegistry,
-  ClientMutationTx,
-} from './mutations'

package/src/internal.ts

@@ -7,12 +7,11 @@
  * entries, not here (no double-listing).
  */
 
-export { createClientEngine } from './client'
-export { toClientMutationRegistry } from './client-mutation-registry'
+export { createClientEngine, resolveClientAuthData } from './client'
 export {
   ClientEngine,
   __CONNECTED_CLOCK_META_KEY,
-  __LOGOUT_BEHAVIOR_META_KEY,
+  __LOGOUT_BEHAVIOR_PREF_KEY,
   settledRejection,
   isFalsyQuery,
   normalizeQuerySurface,
@@ -25,13 +24,14 @@ export {
   splitClientStatements,
   type ClientStatementKind,
 } from './migrate'
-export { asClientMutation, validateMutationArgs } from './mutations'
 export { extractWriteTable } from './port'
 export {
   applyBundledMigrations,
   createEngineTables,
   dropConsumerTables,
   readMeta,
+  readPref,
   replayMigrations,
   writeMeta,
+  writePref,
 } from './replica'

package/src/migrate.ts

@@ -4,8 +4,8 @@ import {
   parse,
   parseAll,
   SQLiteParserError,
-  unparse,
   type Statement,
+  unparse,
 } from '@doync/sqlite-parser'
 
 /**

package/src/replica/db/0002_prefs_table.sql

@@ -0,0 +1,9 @@
+CREATE TABLE `__doync_prefs` (
+	`k` text PRIMARY KEY NOT NULL,
+	`v` blob
+) WITHOUT ROWID;
+--> statement-breakpoint
+INSERT INTO `__doync_prefs` (`k`, `v`)
+	SELECT `k`, `v` FROM `__doync_meta` WHERE `k` = 'logout_behavior';
+--> statement-breakpoint
+DELETE FROM `__doync_meta` WHERE `k` = 'logout_behavior';