@doync/client 0.1.0

package/dist/client-DHXO0dbf.d.cts

@@ -0,0 +1,812 @@
+import { BoundQuery, DoyncSchema, MutationDefinition, MutationTree, SqlValue } from "@doync/core";
+import { ClientMessage, ServerMessage } from "@doync/core/internal";
+
+//#region ../../node_modules/.pnpm/@standard-schema+spec@1.1.0/node_modules/@standard-schema/spec/dist/index.d.ts
+/** The Standard Typed interface. This is a base type extended by other specs. */
+interface StandardTypedV1<Input = unknown, Output = Input> {
+  /** The Standard properties. */
+  readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The Standard Typed types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Typed. */
+  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Typed. */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+/** The Standard JSON Schema interface. */
+//#endregion
+//#region src/port.d.ts
+/** One local-replica row: column name → {@link SqlValue}. */
+interface LocalRow {
+  [column: string]: SqlValue;
+}
+/**
+* Synchronous local SQLite port the client engine drives. Platform adapters
+* (wa-sqlite, node:sqlite, op-sqlite) implement this; app code does not.
+* Transactions and savepoints are ordinary SQL via {@link LocalDb.exec}.
+*/
+interface LocalDb {
+  /**
+  * Run one parameterized statement; return its rows (empty for writes/DDL/
+  * transaction control).
+  */
+  exec<T extends LocalRow = LocalRow>(sql: string, ...params: SqlValue[]): T[];
+  /**
+  * Run a multi-statement DDL script (no parameters). Used to replay bundled
+  * migrations when creating a fresh replica. Trusted input only.
+  */
+  execBatch(script: string): void;
+  /**
+  * Consumer tables written since the last call, then clear the set. Used so
+  * only affected subscriptions re-project after a mutation or rebase.
+  */
+  drainWrittenTables(): Set<string>;
+}
+/**
+* Extract the target table of one WRITE statement from its SQL text — the
+* adapter-side stand-in where no synchronous native change feed exists
+* (ADR-0019): node:sqlite has no update hook, and op-sqlite's hook delivers
+* callbacks via `invokeAsync` — a later event-loop turn, unusable for the
+* engine's drain-after-apply contract (closeio/doync#202 device pass).
+*
+* A real parse over `@doync/sqlite-parser`, not a keyword recognizer: the AST
+* attaches a `WITH …` CTE prefix to the DML node itself, so CTE-topped writes
+* (`WITH src AS (…) INSERT INTO t …`) extract their target with no string
+* games. Returns the unquoted table name for INSERT / REPLACE / UPDATE /
+* DELETE, or `null` for a non-write (SELECT, SAVEPOINT, PRAGMA, DDL) or
+* unparseable input.
+*
+* TRIGGER cascades remain invisible to statement text — and stay out of scope
+* by design: client replicas carry no triggers (the bundled-track replay strips
+* CREATE TRIGGER; ADR-0009 — clients apply state, never enforce).
+*/
+declare function extractWriteTable(sql: string): string | null;
+//#endregion
+//#region src/mutations.d.ts
+/**
+* Write surface a client mutation body runs against: one parameterized
+* statement at a time inside the mutation's savepoint, returning its rows. Same
+* shape the Origin uses, so a shared body runs identically on device and
+* server.
+*/
+interface ClientMutationTx {
+  exec<T extends LocalRow = LocalRow>(query: string, ...params: SqlValue[]): T[];
+}
+/**
+* Client mutation body `(args, ctx, sql)`. Must be deterministic and DB-only
+* (may still be async for local work). Generate ids on the client and pass them
+* in `args` — the body is replayed on rebase. External I/O belongs in a server
+* override, not the client bundle.
+*/
+type ClientMutationHandler = (args: unknown, ctx: Record<string, unknown>, sql: ClientMutationTx) => void | Promise<void>;
+/**
+* A registered client mutation: body plus optional standard-schema args
+* validator applied at `mutate()` time. A bare handler is also accepted.
+*/
+interface ClientMutation {
+  readonly args?: StandardSchemaV1;
+  readonly handler: ClientMutationHandler;
+}
+/**
+* Name-keyed client mutation registry. Keys match the server's dotted names so
+* a push reaches the matching authoritative body.
+*/
+type ClientMutationRegistry = Readonly<Record<string, ClientMutation | ClientMutationHandler>>;
+/**
+* Normalize a registry entry (bare handler or `{args, handler}`) to the object
+* form.
+*/
+declare function asClientMutation(entry: ClientMutation | ClientMutationHandler): ClientMutation;
+/**
+* Validate `args` through a standard-schema synchronously (mirrors
+* `@doync/core` query-args). Async validators refuse loudly — the body is
+* deterministic on both ends. Returns validated value or throws.
+*/
+declare function validateMutationArgs(schema: StandardSchemaV1, args: unknown): unknown;
+//#endregion
+//#region src/socket.d.ts
+/**
+* Minimal transport the client engine uses to talk to its Mirror. Platform
+* adapters supply WebSocket / reconnect policy behind this shape.
+*/
+interface SyncSocket {
+  /** Send one client→server frame (`connect` / `subscribe` / `push`). */
+  send(message: ClientMessage): void;
+  /**
+  * Register frame and lifecycle handlers (once at construction). `open` fires
+  * on every (re)connect so the engine can re-handshake; `close` pauses
+  * outbound traffic until the next `open`.
+  */
+  setHandlers(handlers: SyncSocketHandlers): void;
+  /**
+  * Drop and re-establish under the adapter's backoff. Used after a
+  * client-ahead schema skew; the next successful open triggers re-handshake.
+  */
+  reconnect(): void;
+}
+/**
+* Transient transport states a reconnecting adapter may report: `connecting`
+* (dial/backoff) and `error` (abnormal drop). Connected / disconnected ride
+* `open`/`close`; auth failure is inferred from frames.
+*/
+type SeamStatus = "connecting" | "error";
+/** Handlers the engine registers on a {@link SyncSocket}. */
+interface SyncSocketHandlers {
+  /** A server→client frame arrived. */
+  message(message: ServerMessage): void;
+  /** Socket (re)connected — engine handshakes and re-sends pending. */
+  open(): void;
+  /** Socket disconnected — engine queues writes until the next open. */
+  close(): void;
+  /**
+  * Optional transient status (`connecting` / `error`). Adapters without
+  * reconnect simply never call this.
+  */
+  status?(status: SeamStatus): void;
+}
+//#endregion
+//#region src/replica/meta.d.ts
+/**
+* Read one `__doync_meta` value, or `null` if unset. Columns are `k`/`v`
+* (ADR-0024).
+*/
+declare function readMeta(db: LocalDb, key: string): string | null;
+/** Upsert one `__doync_meta` value. Columns are `k`/`v` (ADR-0024). */
+declare function writeMeta(db: LocalDb, key: string, value: string): void;
+//#endregion
+//#region src/replica/stamps.d.ts
+/**
+* Durable release stamp for one parked Query instance (ADR-0014 client half /
+* closeio/doync#224). Shared infrastructure for `heldAt` (#225) and membership
+* GC (#226) — package-internal, no public consumer surface.
+*
+* Lifecycle: written at last-release; deleted on re-desire and on an ADR-0028
+* warmth-break; wiped with memberships on resync/forget (a stamp must never
+* outlive the memberships it vouches for).
+*/
+type ReleaseStamp = {
+  readonly instance: string; /** Client scalar cookie at last-release — the future `heldAt` claim. */
+  readonly cookie: number; /** Release moment in connected-clock units (ms). */
+  readonly releasedAt: number;
+  /**
+  * Resolved grace in ms — the Subscription's declared ttl, or the internal
+  * default (mirrors the server's DEFAULT_QUERY_TTL_MS; no public knob).
+  */
+  readonly ttlMs: number;
+};
+//#endregion
+//#region src/replica/index.d.ts
+/**
+* Apply the Replica engine track via `__doync_engine` ledger (ADR-0024 / #159).
+* LocalDb twin of server `runEngineTrack`. Returns whether rollback tripwire
+* fired (caller finishes consumer wipe-and-resync). Named `createEngineTables`
+* for stable call sites.
+*/
+declare function createEngineTables(db: LocalDb): {
+  rolledBack: boolean;
+};
+/**
+* Boot replica shape via DDL-only bundled track (ADR-0020). Fresh client is a
+* partial Mirror of the same migrations (triggers skipped, FKs off ADR-0009;
+* backfill skipped ADR-0006).
+*
+* - Fresh (no schema_version): full bundle track.
+* - Persisted: leave recorded shape; new migrations arrive mid-session as
+*   `schema` directives ({@link applyBundledMigrations}), not at boot.
+*/
+declare function replayMigrations(db: LocalDb, schema: DoyncSchema): void;
+/**
+* Apply the bundled track's non-trigger DDL for the migrations in
+* `(fromVersion, toVersion]` to the replica and record `toVersion` as the
+* applied `schema_version`. The single primitive behind both fresh boot replay
+* ({@link replayMigrations} with `fromVersion = 0`) and a mid-session catch-up
+* (`fromVersion =` the currently applied version). The DDL text is the client's
+* OWN bundle (never wire-carried — ADR-0020); a `CREATE TABLE` from a fresh
+* base and an `ALTER TABLE … ADD COLUMN` catch-up both keep any rows already
+* present (SQLite ADD COLUMN preserves rows). Throws if a statement fails — the
+* caller turns a failed local migration into wipe-and-resync (ADR-0020).
+*/
+declare function applyBundledMigrations(db: LocalDb, schema: DoyncSchema, fromVersion: number, toVersion: number): void;
+/**
+* Drop every consumer (synced) table (ADR-0020's wipe fallback): the first step
+* of wipe-replica-and-resync, run with foreign keys already off so no cascade
+* fires and drop order is irrelevant (ADR-0009). `__doync_`-prefixed engine
+* tables — the pending queue, clientId, and `__doync_engine` ledger that
+* SURVIVE the wipe — are left untouched.
+*/
+declare function dropConsumerTables(db: LocalDb, schema: DoyncSchema): void;
+//#endregion
+//#region src/engine.d.ts
+/**
+* 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.
+*/
+interface MutationResult {
+  readonly client: Promise<void>;
+  readonly server: Promise<void>;
+}
+/**
+* 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}.
+*/
+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.
+*/
+declare 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.
+*/
+declare const __CONNECTED_CLOCK_META_KEY = "connected_clock";
+/**
+* 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.
+*/
+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.
+*/
+interface SchemaEvent {
+  readonly kind: SchemaEventKind;
+  /** Human-readable reason (diagnostics; never a control signal). */
+  readonly message: string;
+}
+/** Options for one `mutate()` call. */
+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;
+}
+/**
+* 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}.
+*/
+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`.
+*/
+interface ViewStatus {
+  readonly status: QueryStatus;
+  /** Subscribe-failure detail; present only when `status` is `error`. */
+  readonly error?: Error;
+}
+/**
+* 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
+*/
+type ConnectionStatus = "connecting" | "connected" | "disconnected" | "error" | "needs-auth";
+/**
+* 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.
+*/
+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;
+}
+/**
+* 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).
+*/
+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.
+*/
+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.
+*/
+type FalsyQuery = false | null | undefined;
+/** Per-subscribe options. */
+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}. */
+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}. */
+interface PreloadHandle {
+  /**
+  * Release the preload. Idempotent; typically unused for a session-long
+  * preload.
+  */
+  cleanup(): void;
+}
+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;
+}
+declare class ClientEngine implements DoyncClient {
+  #private;
+  constructor(config: ClientEngineConfig);
+  /**
+  * In-memory connected-time ms (ADR-0014 / #223). Package-internal for release
+  * stamps (#224) and membership GC — not on {@link DoyncClient}.
+  */
+  get connectedClock(): number;
+  /**
+  * Durable release stamp for one instance, or `null` (ADR-0014 / #224).
+  * Package-internal for `heldAt` (#225) and GC (#226).
+  */
+  releaseStamp(instance: string): ReleaseStamp | null;
+  /**
+  * Every parked release stamp (#226 hygiene GC). Package-internal; order
+  * unspecified.
+  */
+  releaseStamps(): ReleaseStamp[];
+  /** Durable clientId (stable across restarts on the same DB). */
+  get clientId(): string;
+  /**
+  * 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;
+  /** Scalar cookie held now (`null` on first sight). */
+  get cookie(): number | null;
+  /** Framed protocol errors (`error` frames, stray poke parts). */
+  get errors(): readonly string[];
+  /**
+  * 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>;
+  /** Bundled schema version (ADR-0020) — declared on every handshake for skew. */
+  get schemaVersion(): number;
+  /**
+  * Schema-handling state, or `null` when nominal (ADR-0020). Sync counterpart
+  * to {@link ClientEngineConfig.onSchemaEvent} for reload/retry UI.
+  */
+  get schemaStatus(): SchemaEvent | null;
+  mutate<Args = unknown>(mutation: MutationDefinition<Args>, args: Args, options?: MutationOptions): MutationResult;
+  /**
+  * 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;
+  /**
+  * 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>;
+  /**
+  * 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;
+  /**
+  * 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>;
+  /**
+  * 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>;
+  /**
+  * 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;
+  /**
+  * 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;
+  /**
+  * 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;
+  /**
+  * Schema-state transitions including silent clear (#89) so hooks re-read
+  * {@link schemaStatus} and banners don't stick after recovery.
+  */
+  onSchemaChange(listener: () => void): () => void;
+  /**
+  * {@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;
+  /** Subscribe to connection-status transitions (#105). */
+  onConnectionChange(listener: () => void): () => void;
+}
+/**
+* `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.
+*/
+declare function isFalsyQuery(value: unknown): value is FalsyQuery;
+/**
+* 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.
+*/
+declare function normalizeQuerySurface<Options = never>(surface: "subscribe" | "once" | "preload", queryOrBound: unknown, options?: Options): {
+  query: BoundQuery["query"];
+  args: unknown;
+  options: Options | undefined;
+};
+/**
+* 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).
+*/
+declare function settledRejection(error: unknown): MutationResult;
+//#endregion
+//#region src/client.d.ts
+/**
+* Options for {@link createClient}. Platform adapters (`@doync/web`,
+* `@doync/mobile`) fill these; app code rarely calls `createClient` directly.
+*/
+interface CreateClientOptions<TAuthData = unknown> {
+  /** Synchronous local SQLite port (wa-sqlite / node:sqlite / op-sqlite). */
+  readonly db: LocalDb;
+  /** Synced schema shared with Origin and Mirror. */
+  readonly schema: DoyncSchema;
+  /**
+  * Shared mutation tree from `defineMutations(shared)` — no server overrides
+  * in the client bundle.
+  */
+  readonly mutations: MutationTree;
+  /** Transport to the Mirror. */
+  readonly socket: SyncSocket;
+  /**
+  * Bearer credential for the handshake. Does not drive `userId` or `ctx`. Omit
+  * for cookie-session auth.
+  */
+  readonly token?: string;
+  /**
+  * Projected auth context for optimistic query/mutation resolution (mirror
+  * your server `toContext`). Defaults to `{}`.
+  */
+  readonly ctx?: TAuthData;
+  /**
+  * Authenticated identity, or `null`/omit for anonymous. Never derived from
+  * `token`.
+  */
+  readonly userId?: string | null;
+  /** Pin a durable client id across restarts. */
+  readonly clientId?: string;
+  /** Observe schema/recovery transitions. */
+  readonly onSchemaEvent?: (event: SchemaEvent) => void;
+  /**
+  * Initial {@link LogoutBehavior}, written durably when provided. Omit to keep
+  * a previously stored choice (a restart will not revert `forget` to `keep`).
+  * Change later via {@link DoyncClient.setLogoutBehavior}.
+  */
+  readonly logoutBehavior?: LogoutBehavior;
+}
+/**
+* Construct a {@link DoyncClient} from local DB, schema, shared mutations, and a
+* Mirror socket. App code normally goes through `@doync/web` / `@doync/mobile`
+* instead.
+*/
+declare function createClient<TAuthData = unknown>(options: CreateClientOptions<TAuthData>): DoyncClient;
+/**
+* Concrete-engine factory (ADR-0033 / closeio/doync#241). Same construction as
+* {@link createClient}, but typed as {@link ClientEngine} so platform adapters
+* (web DB-worker, mobile wrapper) can reach engine-only fields like `clientId`
+* without an unchecked downcast. Exported on `@doync/client/internal` only.
+*/
+declare function createClientEngine<TAuthData = unknown>(options: CreateClientOptions<TAuthData>): ClientEngine;
+//#endregion
+export { readMeta as A, validateMutationArgs as B, isFalsyQuery as C, createEngineTables as D, applyBundledMigrations as E, ClientMutation as F, LocalRow as H, ClientMutationHandler as I, ClientMutationRegistry as L, SeamStatus as M, SyncSocket as N, dropConsumerTables as O, SyncSocketHandlers as P, ClientMutationTx as R, __LOGOUT_BEHAVIOR_META_KEY as S, settledRejection as T, extractWriteTable as U, LocalDb as V, SchemaEventKind as _, ClientEngineConfig as a, ViewStatus as b, FalsyQuery as c, MutationResult as d, OnceView as f, SchemaEvent as g, QueryStatus as h, ClientEngine as i, writeMeta as j, replayMigrations as k, LogoutBehavior as l, PreloadOptions as m, createClient as n, ConnectionStatus as o, PreloadHandle as p, createClientEngine as r, DoyncClient as s, CreateClientOptions as t, MutationOptions as u, SubscribeOptions as v, normalizeQuerySurface as w, __CONNECTED_CLOCK_META_KEY as x, View as y, asClientMutation as z };
+//# sourceMappingURL=client-DHXO0dbf.d.cts.map