@lunora/client 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/packem_shared/{lunora-client.d-DGvyuJ_p.d.mts → lunora-client.d-BYkEjCEJ.d.mts}

@@ -1,4 +1,59 @@
-import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthSession } from '@lunora/runtime';
+import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
+/**
+* The machine-readable error codes a client can observe on a failed
+* RPC/batch/subscription. Mirrors the server's `CODE_STATUS` keys
+* (`@lunora/server`'s `error.ts`) by hand — the client is framework-neutral and
+* must never import the server package (wrong dependency direction / would pull
+* the server into the browser bundle). Keep this list in sync when a server code
+* is added or removed (see the drift-guard note in the plan/maintenance docs).
+*/
+declare const LUNORA_ERROR_CODES: readonly ["BAD_REQUEST", "CONFLICT", "COUNT_RLS_UNSUPPORTED", "FORBIDDEN", "INTERNAL_SERVER_ERROR", "MASK_UNSUPPORTED", "NOT_FOUND", "NOT_IMPLEMENTED", "RELATION_PREDICATE_UNSUPPORTED", "TOO_MANY_REQUESTS", "UNAUTHORIZED", "UNPROCESSABLE"];
+/** A machine-readable error `code` the client may observe. Mirror of the server's `LunoraErrorCode`. */
+type LunoraErrorCode = (typeof LUNORA_ERROR_CODES)[number];
+/** Error code the server uses for optimistic-concurrency conflicts (HTTP 409). */
+declare const CONFLICT_ERROR_CODE = "CONFLICT";
+/**
+* Whether an unknown rejection is an optimistic-concurrency conflict — the
+* server lost a write race and the caller should refetch and retry (or surface
+* the conflict). Structural check on the `code` property the client attaches
+* when decoding the worker's `{ error: { code, message } }` envelope.
+*/
+declare const isConflictError: (error: unknown) => error is Error & {
+  code: "CONFLICT";
+};
+/**
+* Whether a rejection is an RLS/policy denial (`FORBIDDEN`, HTTP 403) — the
+* caller is authenticated but not permitted to read/write the row. The most
+* common per-call error a UI must handle in an RLS-first app.
+*/
+declare const isForbiddenError: (error: unknown) => error is Error & {
+  code: "FORBIDDEN";
+};
+/** Whether a rejection is an authentication failure (`UNAUTHORIZED`, HTTP 401) — no/invalid identity. */
+declare const isUnauthorizedError: (error: unknown) => error is Error & {
+  code: "UNAUTHORIZED";
+};
+/**
+* Whether a rejection is a rate-limit denial (`TOO_MANY_REQUESTS`, HTTP 429).
+* The retry hint (if the server sent one) is read with {@link getRetryAfterMs}.
+*/
+declare const isRateLimitedError: (error: unknown) => error is Error & {
+  code: "TOO_MANY_REQUESTS";
+};
+/**
+* Read the server's machine-readable `code` off a rejection, narrowed to the
+* known {@link LunoraErrorCode} union. Returns `undefined` for a non-`Error`, a
+* missing code, or an unrecognized code string (forward-compat server codes read
+* as `undefined` here rather than being falsely narrowed).
+*/
+declare const getErrorCode: (error: unknown) => LunoraErrorCode | undefined;
+/**
+* Read the rate-limit retry hint (`data.retryAfterMs`) off a
+* `TOO_MANY_REQUESTS` rejection without hand-casting the `unknown` `data`
+* payload. Returns the finite millisecond value the server sent, or `undefined`
+* when absent/non-numeric. Pair with {@link isRateLimitedError}.
+*/
+declare const getRetryAfterMs: (error: unknown) => number | undefined;
 /** The registered function kinds a {@link FunctionReference} can describe. `stream` is a query that yields multiple frames over the WS. */
 type FunctionKind = "action" | "mutation" | "query" | "stream";
 /**
@@ -98,6 +153,14 @@ interface PersistedMutation {
   */
   identity?: string | null;
   shardKey?: string;
+  /**
+  * App/schema version stamped at enqueue (from `LunoraClientOptions.persistenceVersion`).
+  * On hydrate, a record whose `version` doesn't match the current one is dropped
+  * and purged rather than replayed — so a write persisted by an older deploy
+  * (with a now-changed function signature) can't replay against the new schema.
+  * Absent when no `persistenceVersion` is configured (no version gating).
+  */
+  version?: string;
 }
 /**
 * Durable store for the offline mutation queue. The default client keeps the
@@ -120,6 +183,40 @@ interface PersistenceAdapter {
   remove: (id: string) => Promise<void>;
 }
 /**
+* One write handed to an {@link OutboxSink}. Mirrors {@link PersistedMutation}
+* plus the custom-mutator identity (`clientId`/`mutationId`/`idempotencyKey`)
+* the durable outbox needs to dedupe and watermark replays.
+*/
+interface OutboxMutation {
+  args: Record<string, unknown>;
+  /** Stable per-client id; pairs with {@link OutboxMutation.mutationId} as `idempotencyKey`. */
+  clientId: string;
+  functionPath: string;
+  /** `${clientId}:${mutationId}` — sent as `x-lunora-mutation-id` so a replay is server-idempotent. */
+  idempotencyKey: string;
+  /** Issuing identity fingerprint (`null` = signed out); drives the sink's identity guard. */
+  identity: string | null;
+  /** Monotonic per-client mutation id, backing the server `__client_watermark`. */
+  mutationId: number;
+  shardKey?: string;
+}
+/**
+* Pluggable durable outbox seam. When set on {@link LunoraClientOptions.outbox},
+* the client delegates offline write durability + at-least-once replay to this
+* sink instead of its built-in {@link PersistenceAdapter}-backed `OfflineQueue`.
+* `@lunora/db` supplies the blessed implementation (`createExecutorOutboxSink`,
+* backed by the TanStack `OfflineExecutor`); the interface itself is
+* dependency-free so `@lunora/client` stays TanStack-free.
+*/
+interface OutboxSink {
+  /**
+  * Persist and schedule a write for replay. Rejects with an
+  * `OFFLINE_QUEUE_OVERFLOW`-coded error when the sink's cap is exceeded, so
+  * the caller can surface back-pressure to the issuing mutation.
+  */
+  enqueue: (mutation: OutboxMutation) => Promise<void>;
+}
+/**
 * One persisted query result in the durable read cache (Pillar 2). Keyed in the
 * store by `shardKey + functionPath + argsKey`; the record carries everything
 * needed to render offline on reload and to resume the live subscription.
@@ -148,6 +245,13 @@ interface CachedQuery {
   ts: number;
   /** The full query result last seen from the server. */
   value: unknown;
+  /**
+  * App/schema version stamped when persisted (from `LunoraClientOptions.persistenceVersion`).
+  * A cached value whose `version` doesn't match the current one is not hydrated —
+  * so a result of a now-changed shape from an older deploy can't render. Absent
+  * when no `persistenceVersion` is configured (no version gating).
+  */
+  version?: string;
 }
 /**
 * Durable store for the client read cache (Pillar 2): query results survive a
@@ -177,6 +281,16 @@ interface LunoraClientOptions {
   authBasePath?: string;
   bookmarkStorage?: BookmarkStorage;
   /**
+  * Stable per-client id backing the custom-mutator watermark. Sent on the
+  * `connect` envelope (so the server can scope this client's
+  * `__client_watermark`) and stamped onto every {@link OutboxMutation} the
+  * {@link LunoraClientOptions.outbox} sink persists, where it pairs with the
+  * monotonic mutation id to form the idempotency key. The `@lunora/db` path
+  * persists a stable id alongside the outbox and passes it here; omit for the
+  * standalone client, which generates an ephemeral per-session id.
+  */
+  clientId?: string;
+  /**
   * Default app context sent in the `connect` envelope right after each socket
   * opens, forwarded to the server's `onConnect`/`onDisconnect` lifecycle hooks
   * as `event.context`. A per-shard context registered via
@@ -184,6 +298,16 @@ interface LunoraClientOptions {
   * hook needs connection context.
   */
   connectionContext?: Record<string, unknown>;
+  /**
+  * Fail-fast timeout (ms) for opening a subscription WebSocket. If the
+  * handshake doesn't complete within this window — a hung dev proxy or a cold
+  * worker that never upgrades — the client force-closes the socket and routes
+  * through its normal reconnect/backoff (surfacing `offline` status) instead
+  * of leaving the live channel silently stuck on the browser's much longer
+  * default. Does not affect HTTP queries/mutations (those never ride the WS).
+  * Defaults to 10000 (10s); set to `0` (or negative) to disable.
+  */
+  connectTimeoutMs?: number;
   fetch?: typeof fetch;
   /**
   * Interval (ms) between keepalive pings sent on each open subscription
@@ -194,14 +318,47 @@ interface LunoraClientOptions {
   */
   heartbeatIntervalMs?: number;
   offlineQueue?: OfflineQueueOptions;
-  /** Durable store for the offline mutation queue; omit to keep it in memory. */
-  persistence?: PersistenceAdapter;
   /**
-  * Durable store for the read cache (Pillar 2). When supplied, query results
+  * Durable outbox seam for offline writes. When supplied (the `@lunora/db`
+  * path wires `createExecutorOutboxSink`), offline mutations are delegated to
+  * the sink and the built-in {@link PersistenceAdapter}-backed `OfflineQueue`
+  * is bypassed, so a db app has exactly one durable write path. Omit for the
+  * standalone client, which keeps using {@link LunoraClientOptions.persistence}.
+  */
+  outbox?: OutboxSink;
+  /**
+  * Durable store for the offline mutation queue. Tri-state — an explicit
+  * {@link PersistenceAdapter} is used as-is; `false` opts out (the queue stays
+  * in memory, lost on reload); omitted (the default) auto-probes a durable
+  * IndexedDB store when the `indexedDB` global is present (browsers), otherwise
+  * in-memory, so SSR/Node/React-Native keep the in-memory behaviour and only
+  * environments that can persist do. Pass `createAsyncStoragePersistence()` on
+  * React Native.
+  */
+  persistence?: false | PersistenceAdapter;
+  /**
+  * App/schema version stamped onto every persisted queued write and cached
+  * read. Bump it on a breaking change to a function signature or query shape:
+  * on the next boot, persisted writes / cached reads stamped with a different
+  * version are dropped (and purged) rather than replayed / hydrated against the
+  * new schema. Omit to disable version gating (records are never invalidated by
+  * version).
+  *
+  * **Adoption is itself an invalidation event:** records written before you set
+  * `persistenceVersion` carry no version, so the first boot after enabling it
+  * purges all currently-queued offline writes (and cached reads) as stale. Adopt
+  * it on a build where that clean slate is acceptable — typically the same
+  * breaking deploy you're protecting against — not purely speculatively.
+  */
+  persistenceVersion?: string;
+  /**
+  * Durable store for the read cache (Pillar 2). When active, query results
   * are persisted as their subscriptions advance and hydrated on construction
   * so a reload renders cached data before the socket reconnects, then resumes
-  * the live subscription from the persisted cursor. Omit (or pass `false`) to
-  * keep reads in memory only — the default, unchanged behaviour.
+  * the live subscription from the persisted cursor. Tri-state — an explicit
+  * {@link QueryCacheAdapter} is used as-is; `false` opts out (reads stay in
+  * memory only); omitted (the default) auto-probes IndexedDB exactly like
+  * {@link LunoraClientOptions.persistence}.
   */
   queryCache?: QueryCacheAdapter | false;
   reconnect?: ReconnectOptions;
@@ -222,17 +379,47 @@ interface LunoraClientOptions {
 /** Wire envelope sent on `POST /_lunora/rpc`. */
 interface RpcEnvelope {
   args?: Record<string, unknown>;
+  /**
+  * Stable per-client identifier (custom-mutator push path). Pairs with
+  * {@link RpcEnvelope.mutationId} to form `idempotencyKey` and scope the
+  * server `__client_watermark`. Absent on plain `client.mutation` calls.
+  */
+  clientId?: string;
   functionPath: string;
+  /**
+  * Idempotency key (`${clientId}:${mutationId}`) for the custom-mutator push
+  * path, mirrored into the `x-lunora-mutation-id` header. Absent on plain
+  * `client.mutation` calls.
+  */
+  idempotencyKey?: string;
+  /**
+  * Monotonic per-client mutation id (custom-mutator push path), backing the
+  * server-side per-client watermark: `id &lt;= watermark` is a replay (skipped),
+  * `id == watermark + 1` runs authoritatively, `id > watermark + 1` halts the
+  * batch so the client resends from `watermark + 1`. Absent on plain
+  * `client.mutation` calls.
+  */
+  mutationId?: number;
   shardKey?: string;
 }
-/** Wire response from the shard's `/rpc` endpoint (forwarded by the runtime). */
+/**
+* Wire response from the shard's `/rpc` endpoint (forwarded by the runtime). A
+* watermarked custom-mutator push additionally carries `lastMutationId` — the
+* highest per-client sequence the DO has applied — which the client uses to keep
+* its `clientSeq` generator monotonic across reloads (see `LunoraClient.callMutator`).
+* A plain mutation on a CDC shard carries `commitCursor` — the cursor the write
+* committed at — which gates the drop of a per-call optimistic layer.
+*/
 type RpcResponseBody = {
-  result: unknown;
-} | {
   error: {
     code: string;
+    data?: unknown;
     message: string;
   };
+} | {
+  commitCursor?: number;
+  lastMutationId?: number;
+  result: unknown;
 };
 /** Subscription protocol — client → server. */
 interface ClientSubscribeMessage {
@@ -265,10 +452,51 @@ interface ClientUnsubscribeMessage {
 * `onDisconnect` when the socket drops.
 */
 interface ClientConnectMessage {
+  /**
+  * Stable per-client id (persisted alongside the outbox). Lets the server
+  * scope this connection's `__client_watermark` so custom-mutator pokes can
+  * echo the right per-client `lastMutationId`. Omitted by clients that don't
+  * use custom mutators.
+  */
+  clientId?: string;
   context?: Record<string, unknown>;
   id: string;
   type: "connect";
 }
+/**
+* Subscribe to a declarative **shape** — server-side partial replication scoped
+* by `shardBy` + the shape's predicate + RLS. The client sends the shape *name*
+* + validated `args`; the server resolves the trusted `where` (identity/RLS
+* `baseWhere` the client can't forge) and streams the matching rowset, then live
+* {@link ServerPokePartMessage} diffs. `id` namespaces the subscription and is
+* echoed as `shapeId` on every poke part.
+*/
+interface ClientShapeSubscribeMessage {
+  id: string;
+  shape: {
+    args?: Record<string, unknown>;
+    name: string;
+  };
+  /**
+  * Resume from this checkpoint (the `__cdc_log` cursor the client last
+  * applied for this shape). When absent or below the server's retained floor
+  * (`minCdcSeq`), the server re-seeds with a full insert-poke instead of a
+  * delta.
+  */
+  sinceCheckpoint?: number;
+  /**
+  * The CDC epoch {@link ClientShapeSubscribeMessage.sinceCheckpoint} belongs
+  * to. A mismatch (forked changelog timeline) forces a full re-seed even when
+  * the cursor is numerically in range.
+  */
+  sinceEpoch?: string;
+  type: "shape_subscribe";
+}
+/** Cancel a shape subscription started with the same `id`. */
+interface ClientShapeUnsubscribeMessage {
+  id: string;
+  type: "shape_unsubscribe";
+}
 interface ClientAckMessage {
   id: string;
   type: "ack";
@@ -309,7 +537,7 @@ interface ClientWhisperMessage {
   topic: string;
   type: "whisper";
 }
-type ClientMessage = ClientAckMessage | ClientConnectMessage | ClientStreamMessage | ClientSubscribeMessage | ClientUnsubscribeMessage | ClientWhisperMessage | ClientWhisperSubscribeMessage;
+type ClientMessage = ClientAckMessage | ClientConnectMessage | ClientShapeSubscribeMessage | ClientShapeUnsubscribeMessage | ClientStreamMessage | ClientSubscribeMessage | ClientUnsubscribeMessage | ClientWhisperMessage | ClientWhisperSubscribeMessage;
 /** Subscription protocol — server → client. */
 interface ServerDataMessage {
   /**
@@ -323,6 +551,13 @@ interface ServerDataMessage {
   /** The CDC epoch this frame's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
   epoch?: string;
   id: string;
+  /**
+  * The highest custom-mutator `mutationId` from this client the server has
+  * now applied (the per-client `__client_watermark`). Echoed so the client's
+  * outbox can drop confirmed pending mutations and let TanStack DB collapse
+  * the matching optimistic overlay. Absent on shards without custom mutators.
+  */
+  lastMutationId?: number;
   type: "data" | "delta";
 }
 /**
@@ -336,8 +571,33 @@ interface ServerResumeMessage {
   /** The CDC epoch this resume's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
   epoch?: string;
   id: string;
+  /** Per-client custom-mutator watermark (see {@link ServerDataMessage.lastMutationId}). */
+  lastMutationId?: number;
   type: "resume";
 }
+/**
+* Settled acknowledgement for a **list** subscription: a write touched one of
+* the subscription's read tables but produced a byte-identical result, so the
+* server suppressed the data frame. Sent ONLY to a `@lunora/db` custom-mutator
+* client (one that announced a `clientId`, hence has a server-side
+* `__client_watermark`) so its optimistic list overlay drops even when no data
+* frame arrives. Plain `useQuery` subscribers never receive it, and an older
+* client safely ignores the unknown frame.
+*/
+interface ServerSettledMessage {
+  cursor?: number;
+  /** The CDC epoch this settled frame's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
+  epoch?: string;
+  id: string;
+  /**
+  * The highest custom-mutator `mutationId` from this client the server has
+  * now applied (the per-client `__client_watermark`). Forwarded to a
+  * collection's `onCheckpoint` so it can drop the overlay for the confirmed
+  * write whose result didn't change this list.
+  */
+  lastMutationId?: number;
+  type: "settled";
+}
 interface ServerErrorMessage {
   error?: unknown;
   id?: string;
@@ -370,7 +630,65 @@ interface ServerWhisperMessage {
   topic: string;
   type: "whisper";
 }
-type ServerMessage = ServerAckMessage | ServerChunkMessage | ServerCompleteMessage | ServerDataMessage | ServerErrorMessage | ServerResumeMessage | ServerWhisperMessage;
+/**
+* One row-level change in a shape's replication stream — the wire form of the
+* DO's `__cdc_log` `CdcChange`. `insert`/`update` carry the post-image in
+* `value` (projected to the shape's `columns`); `delete` omits it, identifying
+* the removed row by `key` alone. The client applies these to its local
+* collection; an unknown `key` on a `delete` is a safe no-op (a row the client
+* never had in this shape).
+*/
+interface RowOp {
+  /** Row primary key (`_id`). */
+  key: string;
+  op: "delete" | "insert" | "update";
+  /** Logical table the row belongs to. */
+  table: string;
+  /** Post-image document for insert/update; absent on delete. */
+  value?: Record<string, unknown>;
+}
+/**
+* Opens a **poke** — an atomically-applied batch of shape diffs (Zero's poke
+* protocol). A `pokeStart` is followed by zero or more {@link ServerPokePartMessage}
+* frames and closed by exactly one {@link ServerPokeEndMessage}; the client
+* buffers every part and applies them in a single transaction at `pokeEnd`, so a
+* socket that drops mid-poke simply re-seeds on reconnect (no torn view).
+*/
+interface ServerPokeStartMessage {
+  /** The checkpoint the client's view is expected to be at before this poke applies (for ordering/gap detection). */
+  baseCheckpoint?: number;
+  /** CDC epoch this poke belongs to; a mismatch forces the client to re-seed rather than apply. */
+  epoch?: string;
+  /** Correlates this poke's `pokeStart`/`pokePart`/`pokeEnd` frames. */
+  pokeId: string;
+  type: "pokeStart";
+}
+/** One shape's slice of an in-flight poke: the row-ops to apply for `shapeId`. */
+interface ServerPokePartMessage {
+  /** Per-client custom-mutator watermark carried with this slice (see {@link ServerSettledMessage.lastMutationId}). */
+  lastMutationId?: number;
+  pokeId: string;
+  /** Ordered row-level changes for this shape, applied in sequence at `pokeEnd`. */
+  rowsPatch: RowOp[];
+  /** The {@link ClientShapeSubscribeMessage.id} these row-ops belong to. */
+  shapeId: string;
+  type: "pokePart";
+}
+/**
+* Closes a poke: the client commits the buffered parts atomically and advances
+* its checkpoint to {@link ServerPokeEndMessage.checkpoint} (the `__cdc_log`
+* cursor high-watermark the view now reflects), replayed as `sinceCheckpoint` on
+* the next reconnect.
+*/
+interface ServerPokeEndMessage {
+  /** The `__cdc_log` cursor the view is at after applying this poke. */
+  checkpoint?: number;
+  /** CDC epoch the {@link ServerPokeEndMessage.checkpoint} belongs to. */
+  epoch?: string;
+  pokeId: string;
+  type: "pokeEnd";
+}
+type ServerMessage = ServerAckMessage | ServerChunkMessage | ServerCompleteMessage | ServerDataMessage | ServerErrorMessage | ServerPokeEndMessage | ServerPokePartMessage | ServerPokeStartMessage | ServerResumeMessage | ServerSettledMessage | ServerWhisperMessage;
 /**
 * The authenticated user as exposed client-side, mirroring better-auth's
 * `user` row (the `user` field of the `get-session` response). Kept minimal
@@ -582,6 +900,13 @@ interface WorkflowInstanceDetail extends WorkflowInstanceSummary {
 }
 /** A page of workflow instances. */
 interface WorkflowInstancePage {
+  /**
+  * Whether workflow inspection is configured on the worker (a Cloudflare
+  * account id + API token). `false` when the admin proxy reports it can't
+  * inspect instances; omitted (treated as configured) otherwise. Lets a
+  * caller render a "set credentials" state without a failed request.
+  */
+  configured?: boolean;
   instances: WorkflowInstanceSummary[];
   page: number;
   perPage: number;
@@ -594,6 +919,23 @@ interface SubscriptionError {
   message: string;
 }
 type SubscriptionErrorCallback = (error: SubscriptionError) => void;
+/**
+* One active per-call optimistic transform layered onto a subscription. The
+* displayed value is the authoritative {@link SubscriptionState.serverBase}
+* folded through every layer's `transform`, in order — so an incoming server
+* frame re-folds the still-pending layers onto the new base (rebasing) instead
+* of clobbering them. A layer is dropped — gaplessly — once a `data`/`delta`
+* frame whose `cursor >= commitCursor` arrives (its write is now reflected in
+* `serverBase`); `commitCursor` is the CDC cursor the server echoed on the
+* mutation's response, and stays `undefined` while the write is still queued/
+* in-flight (so the overlay survives unrelated deltas until confirmed).
+*/
+interface OptimisticLayer {
+  /** The committed CDC cursor (from the mutation response); `undefined` until confirmed. */
+  commitCursor?: number;
+  readonly id: symbol;
+  readonly transform: (current: unknown) => unknown;
+}
 interface SubscriptionState {
   /** True once the server has acked the subscription on the current socket. */
   acked: boolean;
@@ -605,13 +947,52 @@ interface SubscriptionState {
   */
   readonly argsKey: string;
   readonly callbacks: Set<SubscriptionCallback>;
+  /**
+  * Notified when a `settled` frame advances this subscription's watermark — a
+  * write touched the subscription's tables but the result was byte-identical,
+  * so the server suppressed the data frame. A `@lunora/db` list collection
+  * uses this to drop the optimistic overlay for the confirmed write.
+  *
+  * A SET (not a single slot) because `SubscriptionState` is SHARED across
+  * every subscriber to the same `(fn, args, shardKey)`: a `@lunora/db`
+  * collection may subscribe to a query a plain `useQuery` already opened, so
+  * each subscriber registers its own callback (mirroring `callbacks` /
+  * `errorCallbacks`) and a `settled` frame fans out to all of them. Plain
+  * `useQuery` consumers register nothing, leaving the set empty.
+  */
+  readonly checkpointCallbacks: Set<(watermark: {
+    checkpoint?: number;
+    mutationId?: number;
+  }) => void>;
   /** Notified when the server rejects this subscription (e.g. admin auth). */
   readonly errorCallbacks: Set<SubscriptionErrorCallback>;
   readonly fn: FunctionReference;
   readonly id: string;
+  /**
+  * The highest custom-mutator `mutationId` from this client the server has
+  * applied, captured from the last `settled` frame (the suppressed-list-frame
+  * watermark). Forwarded to {@link SubscriptionState.checkpointCallbacks}.
+  * Absent until a `settled` frame arrives.
+  */
+  lastMutationId?: number;
   /** Last known value, used to short-circuit `useQuery`-style consumers. */
   lastValue: unknown;
   /**
+  * Active per-call optimistic layers, in application order (see
+  * {@link OptimisticLayer}). Empty for subscriptions with no pending per-call
+  * optimistic write — the common case, where `lastValue` tracks `serverBase`
+  * exactly and behaviour is identical to a plain server-value assignment.
+  */
+  optimisticLayers: OptimisticLayer[];
+  /**
+  * The authoritative server value the optimistic layers fold onto — the value
+  * with NO optimistic overlay. Tracks `lastValue` exactly whenever no layers
+  * are active; diverges only while a per-call optimistic write is pending. A
+  * server frame updates this (and re-folds the layers); the durable read cache
+  * persists this, never the optimistic overlay.
+  */
+  serverBase: unknown;
+  /**
   * The `__cdc_log` high-watermark (`cursor`) the `lastValue` reflects,
   * captured from the last `data`/`delta`/`resume` frame. Persisted to the
   * durable read cache and replayed as `sinceSeq` on reconnect so the server
@@ -627,18 +1008,15 @@ interface SubscriptionState {
   * until the first epoch-stamped frame arrives.
   */
   serverEpoch?: string;
-  /**
-  * Monotonic counter incremented on every server-pushed delta or data.
-  * Used by optimistic-update rollback to detect whether the server has
-  * already moved past the value we'd otherwise restore.
-  */
-  serverVersion: number;
   readonly shardKey?: string;
 }
 /**
 * Active subscription registry. The client keys subscriptions by
-* `(functionPath, JSON.stringify(args), shardKey)` so duplicate calls share a
-* single server-side registration.
+* `(functionPath, stableStringify(args), shardKey)` so duplicate calls share a
+* single server-side registration. Args are stably encoded (keys sorted at every
+* depth) so two structurally-equal arg records constructed with a different key
+* order (`{ a, b }` vs `{ b, a }`) collapse to the same key instead of leaking a
+* duplicate subscription.
 */
 declare class SubscriptionRegistry {
   static key(functionPath: string, args: Record<string, unknown>, shardKey?: string): string;
@@ -656,10 +1034,10 @@ declare class SubscriptionRegistry {
 * many subscribed queries at once (Convex's `OptimisticLocalStore` model).
 *
 * `getQuery` reads the current value (server value or any still-pending
-* optimistic override) of a subscribed query; `setQuery` writes an optimistic
-* override on top. Every write is collected as a rollback closure so the whole
-* batch unwinds atomically when the mutation settles or the server advances
-* past it — the same per-subscription rollback machinery the legacy
+* optimistic override) of a subscribed query; `setQuery` registers a constant
+* optimistic layer on top. The whole batch rebases onto incoming deltas and
+* settles together — confirmed on the mutation's commit cursor, or rolled back
+* on failure — the same per-subscription layer machinery the single-query
 * per-call `optimistic` transform uses, generalized to N queries.
 */
 interface OptimisticLocalStore {
@@ -689,30 +1067,20 @@ interface OptimisticLocalStore {
 /** A mutation's multi-query optimistic update: read/write the cache via `localStore`. */
 type OptimisticUpdate<Args> = (localStore: OptimisticLocalStore, args: Args) => void;
 /**
-* Build an {@link OptimisticLocalStore} bound to a subscription registry, the
-* mutation's shard key, and the `writeOptimisticToState` primitive. Returns the
-* store plus the ordered rollback closures every `setQuery` produced, so the
-* caller can unwind the whole batch (LIFO) if the mutation later fails — and
-* leave them in place to be GC'd alongside the subscription on success.
+* Build an {@link OptimisticLocalStore} bound to a subscription registry and the
+* mutation's shard key. Each `setQuery(value)` registers a constant-value layer
+* on its target subscription (via `applyOptimisticLayer`): the predicted value
+* survives incoming server deltas (re-clamped, masking concurrent changes to that
+* query — not merged) and drops gaplessly on the mutation's commit cursor, like
+* the single-query per-call `optimistic` path. Returns the store plus the ordered
+* `confirm` (success) and `rollback` (failure) closures every `setQuery` produced,
+* so the caller settles the whole batch when the mutation does.
 */
-declare const createLocalStore: (subscriptions: SubscriptionRegistry, shardKey: string | undefined, write: (state: SubscriptionState, next: unknown) => () => void, stableStringify: (value: unknown) => string) => {
+declare const createLocalStore: (subscriptions: SubscriptionRegistry, shardKey: string | undefined) => {
+  confirms: ((commitCursor: number | undefined) => void)[];
   rollbacks: (() => void)[];
   store: OptimisticLocalStore;
 };
-/**
-* Bounded async-iterator queue backing `LunoraClient.stream`.
-*
-* The server pushes one server `chunk` message per yielded value while the
-* client iterates with `for await (const chunk of stream)`. A producer that
-* outruns its consumer would otherwise OOM the page, so the buffer is bounded
-* — exceeding {@link DEFAULT_MAX_BUFFER} surfaces a `STREAM_BACKPRESSURE`
-* error to the iterator (and to the server-side cancel path).
-*
-* The queue is closed exactly once via {@link StreamHandle.complete} (success)
-* or {@link StreamHandle.fail} (transport / server error). Subsequent calls
-* are silent no-ops so a duplicate `complete` frame after a cancel doesn't
-* crash the page.
-*/
 declare const DEFAULT_MAX_BUFFER = 1024;
 interface StreamHandle<T = unknown> {
   /** Mark the stream complete (no more chunks); resolves any pending consumer to `done:true`. */
@@ -753,6 +1121,41 @@ declare const createStream: <T>(options: {
 */
 type ConnectionStatus = "connected" | "connecting" | "idle" | "offline";
 /**
+* Terminal verdict for a mutation that passed through the offline queue,
+* delivered to {@link LunoraClient.onMutationSettled}.
+*
+* Unlike the Promise returned by {@link LunoraClient.mutation} — which only the
+* original caller can await, and which no longer exists after a reload — this
+* fires for *every* queued write the server (or the queue) reaches a verdict on,
+* including writes restored from durable storage in a later session. It is the
+* channel a UI uses to tell the user "your queued change couldn't be saved"
+* instead of silently dropping a rolled-back optimistic row.
+*
+* `status: "rejected"` carries the failure `code` (e.g. `CONFLICT`,
+* `OFFLINE_QUEUE_OVERFLOW`, `OFFLINE_IDENTITY_CHANGED`) and the `error`.
+* `hadAwaiter` is `false` for a write whose original `mutation()` Promise is
+* gone (a hydrated/post-reload replay or an eviction), so a listener can tell
+* "the caller already saw this" apart from "nothing else will report this".
+*/
+interface MutationSettledEvent {
+  /** The write's args, so a listener can describe or re-offer the change. */
+  readonly args: Record<string, unknown>;
+  /** Server/queue error code on `rejected` (e.g. `CONFLICT`), when present. */
+  readonly code?: string;
+  /** The rejection error on `status: "rejected"`. */
+  readonly error?: unknown;
+  /** The `&lt;file>:&lt;function>` reference of the mutation. */
+  readonly functionPath: string;
+  /** Whether a live caller was still awaiting this write's `mutation()` Promise. */
+  readonly hadAwaiter: boolean;
+  /** The write's stable id (idempotency key / queue id). */
+  readonly id: string;
+  /** Shard the write targeted, if any. */
+  readonly shardKey?: string;
+  /** Terminal outcome. */
+  readonly status: "committed" | "rejected";
+}
+/**
 * Per-call options for {@link LunoraClient.mutation} — the optimistic-update
 * machinery plus `shardKey`. Exported (at the end of this file) so the framework
 * adapters (`@lunora/react`, `/solid`, `/svelte`, `/vue`) can type their
@@ -760,6 +1163,13 @@ type ConnectionStatus = "connected" | "connecting" | "idle" | "offline";
 * re-declaring it.
 */
 interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unknown> {
+  /**
+  * Override the auto-generated idempotency key (`x-lunora-mutation-id`). Lets a
+  * durable outbox replay a committed-but-unacked write under its *original* key
+  * so the server dedups it instead of applying it twice. Omit for normal calls —
+  * each then gets a fresh key.
+  */
+  mutationId?: string;
   optimistic?: (current: TCurrent | undefined) => TValue;
   /**
   * Convex-parity multi-query optimistic update. Receives an
@@ -770,6 +1180,42 @@ interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unkn
   optimisticUpdate?: OptimisticUpdate<TArgs>;
   shardKey?: string;
 }
+/** Callback a shape subscription invokes with its materialized rowset on every applied poke. */
+type ShapeCallback = (rows: Record<string, unknown>[]) => void;
+/**
+* The high-water marks a shape poke has now synced to the client: `checkpoint`
+* is the op-log cursor and `mutationId` the highest custom-mutator id the server
+* echoed for this client. A `@lunora/db` collection feeds these into its
+* checkpoint registry to drop optimistic overlays once the server's authoritative
+* rows have landed.
+*/
+interface SyncWatermark {
+  checkpoint?: number;
+  mutationId?: number;
+}
+/**
+* An `Error` carrying the server's machine-readable `code` and (for a
+* `LunoraError`) structured `data`, plus an optional actionable `hint` (Markdown)
+* and `docsUrl` resolved from the central error catalog. The client's public
+* error contract for RPC/batch failures — a UI can render `hint`/`docsUrl` to
+* tell the user how to fix the error. The `(string & {})` arm keeps
+* forward-compat/unknown server codes assignable without losing autocomplete on
+* the known {@link LunoraErrorCode} union.
+*/
+type LunoraClientError = Error & {
+  code?: LunoraErrorCode | (string & {});
+  data?: unknown;
+  docsUrl?: string;
+  hint?: string | string[];
+};
+/** One demuxed result slot of a {@link LunoraClient.batch} call (plan 088). */
+type BatchSlot = {
+  error: LunoraClientError;
+  ok: false;
+} | {
+  ok: true;
+  value: unknown;
+};
 /**
 * Lunora browser/edge client. Talks RPC over HTTP and real-time deltas over
 * a single multiplexed WebSocket.
@@ -778,6 +1224,8 @@ interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unkn
 * see the package README for the wire protocol.
 */
 declare class LunoraClient {
+  /** Hard cap on concurrently-buffered pokes — a backstop that reclaims buffers abandoned by a mid-poke disconnect (no `pokeEnd`). Far above any real concurrent-in-flight count. */
+  private static readonly MAX_POKE_BUFFERS;
   readonly url: string;
   readonly wsUrl: string;
   private wsToken;
@@ -787,11 +1235,36 @@ declare class LunoraClient {
   private readonly WebSocketImpl;
   private readonly bookmark;
   private readonly reconnectOptions;
+  /** WS connect timeout (ms); `0` disables it. See {@link LunoraClientOptions.connectTimeoutMs}. */
+  private readonly connectTimeoutMs;
   /** Keepalive cadence (ms); `0` disables the heartbeat. See {@link LunoraClientOptions.heartbeatIntervalMs}. */
   private readonly heartbeatIntervalMs;
   private readonly offlineQueue;
+  /**
+  * Durable outbox seam (the `@lunora/db` `createExecutorOutboxSink`). When
+  * set, offline writes are delegated here and the built-in {@link OfflineQueue}
+  * is bypassed, so a db app has exactly one durable write path.
+  */
+  private readonly outbox;
+  /** Stable per-client id stamped onto every `OutboxMutation` (custom-mutator watermark). */
+  private readonly clientId;
+  /**
+  * Highest custom-mutator watermark the server has echoed for this client,
+  * keyed by shard bucket (`shardKey ?? ""`) since the DO tracks one
+  * `__client_watermark` per shard. `callMutator` bumps it from every
+  * ack; the `@lunora/db` mutator runtime seeds its `clientSeq` generator from
+  * it so a reload (which resets the in-memory counter) never reissues a stale
+  * sequence the server would silently swallow as a replay.
+  */
+  private readonly clientWatermarks;
+  /** Monotonic per-client mutation counter backing the server `__client_watermark`. */
+  private outboxMutationCounter;
   private readonly onPersistenceError;
   private readonly persistence;
+  /** App/schema version stamped on persisted writes + cached reads; mismatches are purged. */
+  private readonly persistenceVersion;
+  /** Releases the multi-tab outbox-leader Web Lock on close (see `hydrateAsOutboxLeader`). */
+  private outboxLeaderRelease;
   /** Durable read cache (Pillar 2); `undefined` when `queryCache` is omitted or `false`. */
   private readonly queryCache;
   /**
@@ -835,6 +1308,14 @@ declare class LunoraClient {
   private readonly connectionContextHolders;
   private authToken;
   /**
+  * Optional STABLE identity subject (a user id), the basis of the offline-queue
+  * identity stamp when supplied. Keeps a same-user token *refresh* from looking
+  * like an identity change (which would discard queued writes). `undefined` =
+  * not supplied, so identity falls back to a hash of the raw token. See
+  * `setAuthToken` / `identityFingerprint`.
+  */
+  private authSubject;
+  /**
   * Identity stamp recorded against each queued offline mutation, keyed by
   * the queue-assigned mutation id. Captured at enqueue from the auth token
   * in effect at the time, and re-checked at flush so a queued write can
@@ -849,6 +1330,10 @@ declare class LunoraClient {
   private readonly statusListeners;
   /** Subscribers notified when the server drops a socket for an expired token (see `onTokenExpired`). */
   private readonly tokenExpiredListeners;
+  /** Subscribers to offline-queued mutation verdicts (see `onMutationSettled`). */
+  private readonly mutationSettledListeners;
+  /** Subscribers to the offline-queue pending-count (see `onPendingChange`). */
+  private readonly pendingChangeListeners;
   /**
   * Whisper-topic handlers, keyed by `connectionKey(shardKey)` → topic → set
   * of callbacks. Membership doubles as the resubscribe set replayed on every
@@ -866,20 +1351,78 @@ declare class LunoraClient {
   * calls `.cancel()` or the iterator is garbage-collected.
   */
   private readonly streams;
+  /** Live shape subscriptions (partial replication), keyed by their wire id. */
+  private readonly shapeSubscriptions;
+  /** In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by `pokeId`. */
+  private readonly pokeBuffers;
+  private nextShapeId;
   constructor(options: LunoraClientOptions);
   /**
   * Set (or clear) the bearer token sent on every HTTP RPC. Notifies any
   * {@link onAuthTokenChange} listeners so React hooks like `useAuth` stay in
   * sync across all mounted instances.
   *
+  * Pass a STABLE `subject` (the user id) to key the offline-queue identity on
+  * it instead of the token bytes, so a token *refresh* (same user, new JWT)
+  * doesn't read as an identity change and discard queued writes. The subject is
+  * **sticky**: a later call that omits it (or passes `undefined`) keeps the
+  * established subject — so `setAuthToken(refreshedToken)` after a prior
+  * `setAuthToken(token, user.id)` retains the identity. Pass `null` to clear it
+  * (an explicit sign-out). Establishing the subject for the first time on an
+  * UNCHANGED token (e.g. the user id resolves a tick after the token was set)
+  * re-stamps any in-flight queued writes rather than dropping them — same
+  * credential, just a more stable label. A real user switch (the token AND
+  * subject both change) still drops the previous user's writes.
+  *
   * Does NOT update the WebSocket auth — the WS token is fixed at upgrade
   * time and lives in the URL. To refresh live WS auth, call
   * {@link setWsToken} explicitly, which closes existing shard sockets to
   * force a reconnect with the new credential.
   */
-  setAuthToken(token: string | null): void;
+  setAuthToken(token: string | null, subject?: string | null): void;
   getAuthToken(): string | null;
   /**
+  * The current identity fingerprint (the same stamp queued offline writes
+  * carry). Exposed so a durable {@link OutboxSink}'s replay handler — which
+  * owns its own at-least-once replay outside the built-in `OfflineQueue` —
+  * can drop a persisted write whose captured `identity` no longer matches the
+  * signed-in user, the guard the queue path applies in `flushOfflineQueue`.
+  */
+  currentIdentity(): string | null;
+  /** This client's stable identifier — the watermark key the server's custom-mutator protocol advances per `clientSeq`. */
+  clientIdentifier(): string;
+  /**
+  * The highest custom-mutator watermark the server has echoed for this client
+  * on the given shard (0 if none yet). The `@lunora/db` mutator runtime seeds
+  * its `clientSeq` generator from this so a reload never reissues a sequence
+  * the server has already applied (which it would swallow as a replay, silently
+  * dropping the write).
+  */
+  confirmedMutationWatermark(shardKey?: string): number;
+  /**
+  * Push a custom mutator to its authoritative server impl over the watermark
+  * protocol (Phase 4): the request carries `x-lunora-client-id` + a monotonic
+  * `x-lunora-client-seq`, so the DO runs it exactly once and advances this
+  * client's `__client_watermark`.
+  *
+  * Returns the server `result` plus `applied`: `true` when the DO ran this push
+  * as the next-in-order mutation, `false` when it was a replay ack (`clientSeq`
+  * was at or below the stored watermark — e.g. a stale sequence after a reload).
+  * A `false` verdict tells the caller to reissue above the now-known watermark
+  * (echoed into {@link confirmedMutationWatermark}) rather than treat the benign
+  * ack as a confirmed write. Every ack — applied or not — bumps the watermark.
+  *
+  * This is the online transport for `@lunora/db`'s client-mutator runtime; the
+  * optimistic overlay + durable-outbox concerns live in that runtime, not here.
+  */
+  callMutator(functionPath: string, args: Record<string, unknown>, options?: {
+    clientSeq?: number;
+    shardKey?: string;
+  }): Promise<{
+    applied: boolean;
+    result: unknown;
+  }>;
+  /**
   * Subscribe to auth-token changes. Returns an unsubscribe function. The
   * listener is NOT invoked on registration — use {@link getAuthToken} for
   * the current value.
@@ -990,10 +1533,55 @@ declare class LunoraClient {
   * unsubscribe function.
   */
   onConnectionStatus(listener: (status: ConnectionStatus) => void): Unsubscribe;
+  /**
+  * Number of offline writes waiting in the built-in queue to be sent — the
+  * depth for a "N changes waiting to sync" indicator. Counts writes that are
+  * queued (offline / mid-reconnect), not ones already in flight on the wire.
+  * A `@lunora/db` app whose writes ride the unified outbox should read
+  * `LunoraDb.pendingCount()` instead (this counts only the built-in queue).
+  */
+  pendingCount(): number;
+  /**
+  * Subscribe to changes in {@link pendingCount}. Invokes `listener` immediately
+  * with the current count, then whenever the queue depth changes (a write is
+  * enqueued, flushed, or discarded). Returns an unsubscribe function.
+  */
+  onPendingChange(listener: (pending: number) => void): Unsubscribe;
+  /**
+  * Subscribe to terminal verdicts for offline-queued mutations. The listener
+  * fires once per queued write that commits or is rejected — including a write
+  * restored from durable storage after a reload, whose original `mutation()`
+  * Promise no longer exists (`hadAwaiter: false`), and a write the queue
+  * evicts on overflow or discards on an identity change. This is the durable
+  * channel for surfacing a rolled-back optimistic write to the UI; an online
+  * mutation that never queued still surfaces through the Promise `mutation()`
+  * returns. The listener is NOT invoked on registration. Returns an
+  * unsubscribe function. See {@link MutationSettledEvent}.
+  */
+  onMutationSettled(listener: (event: MutationSettledEvent) => void): Unsubscribe;
   query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: {
     shardKey?: string;
   }): Promise<ReturnOf<F>>;
   /**
+  * Batch several independent calls into ONE round trip (plan 088). Each call is
+  * dispatched server-side exactly as an individual RPC — per-shard
+  * authorization, `(identity, mutationId)` idempotency, and custom-mutator
+  * watermark ordering are all preserved — and the worker splits the batch by
+  * shard so calls to different shards fan out to their own DOs. Results are
+  * demuxed back in input order; a failing call does NOT fail the batch (its
+  * slot carries `{ ok: false, error }`, with `.code`/`.data` reconstructed like
+  * a single call). Args/results ride the value codec (bytes/bigint survive).
+  *
+  * No promise pipelining and no capability passing — a call's args cannot
+  * reference another call's result (see plan 088 §fence; capabilities are
+  * incompatible with DO hibernation).
+  */
+  batch(calls: ReadonlyArray<{
+    args?: Record<string, unknown>;
+    fn: FunctionReference;
+    shardKey?: string;
+  }>): Promise<BatchSlot[]>;
+  /**
   * Invoke a mutation. Errors propagate as rejections.
   *
   * Offline-queue semantics: a mutation is queued (and replayed on reconnect)
@@ -1069,8 +1657,12 @@ declare class LunoraClient {
   * List a workflow's instances via the admin Workflows proxy
   * (`/_lunora/admin/workflows/instances`) — the Cloudflare control-plane data
   * the `Workflow` binding can't expose. Requires the worker to be built with a
-  * `workflowsClient` (Cloudflare account id + API token); otherwise the proxy
-  * responds 501 and this rejects. `name` is the deployed workflow name.
+  * `workflowsClient` (Cloudflare account id + API token). When one isn't
+  * configured this does NOT reject: the proxy returns a `200 { configured:
+  * false }` sentinel, so the result resolves with `configured === false` and an
+  * empty `instances` list — callers should branch on that flag rather than
+  * try/catch. (The instance-detail / status endpoints still reject with 501.)
+  * `name` is the deployed workflow name.
   */
   listWorkflowInstances(options: {
     name: string;
@@ -1269,6 +1861,55 @@ declare class LunoraClient {
     topK?: number;
   }): Promise<VectorQueryMatch[]>;
   /**
+  * List the worker's registered Workers KV namespaces (binding names). Hits
+  * the admin-gated `GET /_lunora/admin/kv/namespaces` endpoint — the worker
+  * must be built with a `kvIntrospector` and `adminToken`. Powers the
+  * studio's KV browser.
+  */
+  listKvNamespaces(): Promise<KvNamespaceSummary[]>;
+  /**
+  * List keys in a KV namespace, optionally filtered by `prefix` and
+  * paginated via `cursor`. Hits the admin-gated
+  * `GET /_lunora/admin/kv/keys` endpoint.
+  */
+  listKvKeys(options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }): Promise<KvKeyListResult>;
+  /**
+  * Read a KV value (as text) and its metadata. Hits the admin-gated
+  * `GET /_lunora/admin/kv/value` endpoint. Returns `{ value: null, metadata: null }`
+  * when the key is absent.
+  */
+  getKvValue(options: {
+    key: string;
+    namespace: string;
+  }): Promise<KvValueResult>;
+  /**
+  * Write a string value to a KV namespace. Accepts an absolute `expiration`
+  * (Unix seconds) or a relative `expirationTtl`, plus optional `metadata` —
+  * re-send the loaded values on edit so a save preserves rather than clears
+  * them. Hits the admin-gated `PUT /_lunora/admin/kv/value` endpoint.
+  */
+  putKvValue(options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }): Promise<void>;
+  /**
+  * Delete a key from a KV namespace. No-op when the key is absent. Hits the
+  * admin-gated `DELETE /_lunora/admin/kv/value` endpoint.
+  */
+  deleteKvKey(options: {
+    key: string;
+    namespace: string;
+  }): Promise<void>;
+  /**
   * List authenticated users, paged and optionally searched / filtered / sorted.
   * Hits the admin-gated `GET /_lunora/admin/auth/users` endpoint — the worker
   * must be built with an `authAdmin` and `adminToken`. Powers the studio's
@@ -1393,6 +2034,107 @@ declare class LunoraClient {
   cancelAuthOrgInvitation(input: {
     invitationId: string;
   }): Promise<void>;
+  /**
+  * Report the deployment's auth configuration — enabled plugins, sign-in
+  * methods, user-settable create-user fields, organization sub-features
+  * (teams / roles), and session / rate-limit policy. Drives the config panel
+  * and the dynamic create-user form. Never carries a secret.
+  */
+  getAuthConfig(): Promise<AuthConfigInfo>;
+  /** Create an organization; optionally seed an `owner` member for `ownerId`. */
+  createAuthOrganization(input: {
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    name: string;
+    ownerId?: string;
+    slug?: string;
+  }): Promise<Record<string, unknown>>;
+  /** Update an organization's name/slug/logo/metadata. */
+  updateAuthOrganization(input: {
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    organizationId: string;
+    slug?: string;
+  }): Promise<Record<string, unknown>>;
+  /** Delete an organization and cascade its members, invitations, teams, and custom roles. */
+  deleteAuthOrganization(input: {
+    organizationId: string;
+  }): Promise<void>;
+  /** Directly add an existing user to an organization (no invitation/acceptance). */
+  addAuthOrgMember(input: {
+    organizationId: string;
+    role?: string;
+    userId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Create a pending email invitation to an organization. */
+  inviteAuthOrgMember(input: {
+    email: string;
+    inviterId?: string;
+    organizationId: string;
+    role?: string;
+  }): Promise<Record<string, unknown>>;
+  /** Change a member's role. */
+  setAuthOrgMemberRole(input: {
+    memberId: string;
+    role: string | string[];
+  }): Promise<Record<string, unknown>>;
+  /** List an organization's teams (requires the organization plugin with teams enabled). */
+  listAuthOrgTeams(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Create a team under an organization. */
+  createAuthOrgTeam(input: {
+    name: string;
+    organizationId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Rename a team. */
+  updateAuthOrgTeam(input: {
+    name: string;
+    teamId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Delete a team and its memberships. */
+  removeAuthOrgTeam(input: {
+    teamId: string;
+  }): Promise<void>;
+  /** List a team's members. */
+  listAuthOrgTeamMembers(input: {
+    limit?: number;
+    offset?: number;
+    teamId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Add a user to a team. */
+  addAuthOrgTeamMember(input: {
+    teamId: string;
+    userId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Remove a member from a team. */
+  removeAuthOrgTeamMember(input: {
+    teamMemberId: string;
+  }): Promise<void>;
+  /** List an organization's custom roles (requires the organization plugin with dynamic access control). */
+  listAuthOrgRoles(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Create a custom org role with a permission grant (a `resource -> actions[]` map). */
+  createAuthOrgRole(input: {
+    organizationId: string;
+    permission: Record<string, string[]>;
+    role: string;
+  }): Promise<Record<string, unknown>>;
+  /** Replace a custom org role's permission grant. */
+  updateAuthOrgRole(input: {
+    permission: Record<string, string[]>;
+    roleId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Delete a custom org role. */
+  deleteAuthOrgRole(input: {
+    roleId: string;
+  }): Promise<void>;
   /** List auth sessions, paged and optionally filtered to one user. */
   listAuthSessions(options?: {
     limit?: number;
@@ -1400,6 +2142,27 @@ declare class LunoraClient {
     userId?: string;
   }): Promise<AuthPage<AuthSession>>;
   subscribe<F extends FunctionReference>(function_: F, args: ArgsOf<F>, callback: (data: ReturnOf<F>) => void, options?: {
+    onCheckpoint?: (watermark: SyncWatermark) => void;
+    onError?: SubscriptionErrorCallback;
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
+  * Subscribe to a declarative **shape** — server-side partial replication
+  * scoped by `shardBy` + the shape's predicate + RLS. The parallel to
+  * {@link subscribe} for the poke protocol: the client sends the shape *name* +
+  * validated `args` (never a `where` the client could forge), the server seeds
+  * the current membership as an insert-poke and streams live membership diffs.
+  * Each applied poke materializes the shape's rowset and invokes `callback`.
+  *
+  * Unlike {@link subscribe}, shape subscriptions are NOT deduped by
+  * (name, args): the server resolves them under the socket's verified identity,
+  * so every call gets its own id + view. The returned function unsubscribes.
+  */
+  subscribeShape(shape: {
+    args?: Record<string, unknown>;
+    name: string;
+  }, callback: ShapeCallback, options?: {
+    onCheckpoint?: (watermark: SyncWatermark) => void;
     onError?: SubscriptionErrorCallback;
     shardKey?: string;
   }): Unsubscribe;
@@ -1427,12 +2190,35 @@ declare class LunoraClient {
   }): StreamIterable<ReturnOf<F>>;
   close(): void;
   /**
+  * Persist a mutation that can't go out on the wire right now (offline, or
+  * mid-reconnect after a prior connect). The optimistic update has already
+  * been applied by `mutation`; this only chooses the durable write path and
+  * rolls the optimistic write back if persistence is rejected.
+  *
+  * Two paths: when an `outbox` sink is wired (the `@lunora/db` executor) it
+  * owns persistence + at-least-once replay, so we delegate and return
+  * optimistically (confirmation rides the synced view). Otherwise the
+  * built-in `OfflineQueue` resolves/rejects the returned promise on replay.
+  */
+  private enqueueOfflineMutation;
+  /**
   * Restore offline mutations persisted in a prior session and open a socket
   * for each shard they target so they flush once the WS reconnects. Failures
   * are swallowed — a broken durable store must not stop the client booting.
   */
   private hydratePersistedQueue;
   /**
+  * Re-queue the durable offline writes — but only as the multi-tab LEADER. The
+  * persisted queue is shared across a profile's tabs; without coordination
+  * every tab would re-queue and replay the same writes (correct only because
+  * the server dedups by idempotency key, but wasteful + racy). A Web Lock makes
+  * exactly one tab hydrate; it holds the lock for its lifetime, so when it
+  * closes another tab acquires the lock and takes over. Falls back to
+  * unconditional hydration where Web Locks are unavailable (React Native, older
+  * browsers, SSR) — single-context there, so no coordination is needed.
+  */
+  private hydrateAsOutboxLeader;
+  /**
   * Load every cached query into {@link hydratedQueryCache} so the next
   * `subscribe()` for each key seeds its initial value off disk. A
   * subscription created before this resolves simply misses the cache (it
@@ -1462,21 +2248,37 @@ declare class LunoraClient {
   /** Recompute the aggregate status and notify listeners if it changed. */
   private emitConnectionStatus;
   /**
-  * Apply an optimistic update to every subscription that matches the
-  * mutation's function ref, shard key, and args, returning the rollback
-  * callbacks to invoke if the mutation later fails. Scoping to the same
-  * (fn, shardKey, args) keeps one user's mutation from clobbering another
-  * subscriber's value on the same function (e.g. two users on different rooms).
+  * Build a {@link MutationSettledEvent} from a queued entry and emit it on the
+  * {@link onMutationSettled} channel. `item.id` is always assigned by the time
+  * a write settles (`enqueue`/`hydrate` guarantee it), so the `?? ""` fallback
+  * is unreachable — present only to satisfy the optional queue-id type.
+  */
+  private emitItemSettled;
+  /**
+  * Apply an optimistic update to the subscription that matches the mutation's
+  * `(functionRef, args, shardKey)` triple, returning the rollback callbacks to
+  * invoke if the mutation later fails.
+  *
+  * The registry is already indexed by exactly this triple via
+  * `SubscriptionRegistry.key`, so at most one subscription can match. A direct
+  * O(1) keyed lookup replaces the former O(N) linear scan over all subscriptions.
+  *
+  * `shardKey` normalization: both `undefined` and `""` map to the empty string
+  * inside `SubscriptionRegistry.key` (via `?? ""`), so a mutation fired without
+  * a shardKey correctly matches a subscription registered without one regardless
+  * of whether the caller passed `undefined` or omitted the field.
   */
   private applyOptimisticUpdates;
   /**
   * Run a Convex-parity `optimisticUpdate` callback against a localStore bound
-  * to the live subscription registry, appending each `setQuery` write's
-  * rollback to `optimisticRollbacks` (the same LIFO list the legacy path uses,
-  * unwound on settle/error). A throwing callback unwinds its own partial
-  * writes — LIFO over just the rollbacks it produced — and is swallowed, so a
-  * buggy optimistic update can never fail the mutation or leave a partial
-  * patch live, mirroring the legacy transform's throw handling.
+  * to the live subscription registry. Each `setQuery` registers a constant
+  * optimistic LAYER on its target subscription (via the same engine the
+  * per-call `optimistic` path uses), so the multi-query patch rebases onto
+  * incoming deltas and drops gaplessly on its commit cursor — its `confirm` /
+  * `rollback` closures are appended to the mutation's settle lists. A throwing
+  * callback unwinds its own partial writes — LIFO over just the rollbacks it
+  * produced — and is swallowed, so a buggy optimistic update can never fail the
+  * mutation or leave a partial patch live.
   */
   private applyOptimisticUpdate;
   private getConnection;
@@ -1523,6 +2325,13 @@ declare class LunoraClient {
   * to the lifecycle dispatch.
   */
   private sendConnectEnvelope;
+  /**
+  * Re-send every shape subscription bound to `shardKey` over its (now open)
+  * socket. Each frame carries the shape's last applied checkpoint, so the
+  * server resumes from it — or re-seeds when the cursor fell below CDC
+  * retention or the epoch forked.
+  */
+  private resendShapeSubscriptions;
   private ensureSocket;
   private handleDisconnect;
   /**
@@ -1538,8 +2347,14 @@ declare class LunoraClient {
   /** Mark every subscription bound to `shardKey` as needing a fresh ack. */
   private markShardPendingAck;
   private sendSubscribeIfOpen;
+  private sendShapeSubscribeIfOpen;
   private handleServerMessage;
   private handleErrorMessage;
+  private handlePokeStart;
+  private handlePokePart;
+  private handlePokeEnd;
+  /** Materialize a shape's keyed view to an array and invoke its callbacks. */
+  private emitShapeRows;
   private handleDataMessage;
   /**
   * Handle a `resume` frame (Pillar 1b): the server proved nothing the
@@ -1551,6 +2366,25 @@ declare class LunoraClient {
   */
   private handleResumeMessage;
   /**
+  * Handle a `settled` frame: a write touched one of this subscription's read
+  * tables but produced a byte-identical result, so the server suppressed the
+  * data frame. Like {@link handleResumeMessage} the value didn't change — we
+  * advance the resume position and re-persist — but we ALSO surface the echoed
+  * custom-mutator watermark via `onCheckpoint` so a `@lunora/db` list
+  * collection drops the optimistic overlay for the confirmed write (otherwise
+  * its checkpoint gate, fed only by data frames, would hang forever). Sent
+  * only to custom-mutator clients; plain `useQuery` subscribers leave
+  * `onCheckpoint` unset and this is a near no-op.
+  */
+  private handleSettledMessage;
+  /**
+  * Mark `state` acked and, when the frame carries a newer cursor/epoch than
+  * the cached position, advance the resume watermark and re-persist. Shared by
+  * the `resume` and `settled` frame handlers — both acknowledge "nothing the
+  * client must re-render changed, but the resume position may have moved".
+  */
+  private ackAndAdvanceCursor;
+  /**
   * Resolve the value to publish for a `data`/`delta` frame.
   *
   * A `data` frame is an authoritative snapshot (the server re-execution path)
@@ -1578,6 +2412,34 @@ declare class LunoraClient {
   */
   private identityFingerprint;
   /**
+  * Stable token-hash fingerprint of a bearer token (the `&lt;len>:&lt;fnv>:&lt;djb2>`
+  * format a token-stamped queued write carries). Extracted so the replay gate
+  * can recompute the hash of the current credential and recognise a write
+  * stamped under it — even after the fingerprint was relabelled to a subject.
+  *
+  * Two independent 32-bit passes (FNV-1a + djb2) give a ~64-bit digest, so
+  * two distinct equal-length tokens are astronomically unlikely to share a
+  * fingerprint. A single 32-bit hash collides ~1-in-4e9 per equal-length
+  * pair — enough that, on a shared device, user B could hydrate A's cached
+  * reads. Different algorithms (not the same FNV with a different seed, which
+  * would be affine-related) keep the two passes genuinely independent.
+  * Still synchronous (no crypto) and stable across surrogate pairs.
+  */
+  private hashToken;
+  /**
+  * True when `stamped` is a token-hash of the SAME credential still held now,
+  * even though the live identity has since been relabelled to a subject. Covers
+  * `setAuthToken(token, userId)` where the subject resolved a tick after the
+  * token was set: a write persisted (or requeued) under the token hash must
+  * still replay — the credential never changed, only its label — instead of
+  * being dropped as an identity mismatch. This is the durable counterpart to
+  * {@link restampQueuedIdentity}, which only relabels the in-memory live stamp
+  * (consumed on the first flush) and never touches `item.identity` or the
+  * persisted record, so a reload or a transient-failure requeue would otherwise
+  * fall back to the stale token-hash and wrongly reject the same user's write.
+  */
+  private isSameCredentialUnderTokenHash;
+  /**
   * Drain every in-memory offline write and reject it because the auth
   * identity changed. Durable entries are also dropped from persistence so a
   * later `hydrate` can't resurrect another user's writes. Stamps are cleared
@@ -1586,6 +2448,15 @@ declare class LunoraClient {
   */
   private rejectQueuedForIdentityChange;
   /**
+  * Migrate every live identity stamp from `from` to `to` — used when the auth
+  * identity label changes but the underlying credential (token) does NOT, e.g.
+  * the user id resolves a tick after the token was set. The in-memory
+  * `queuedIdentities` map is the flush-time source of truth, so re-stamping it
+  * keeps the in-flight writes replayable under the new (more stable) identity
+  * instead of the flush guard discarding them as a mismatch.
+  */
+  private restampQueuedIdentity;
+  /**
   * Drop the durable read cache on an identity change so a cached value stamped
   * under the previous identity can never hydrate into a new session. Clears
   * the in-flight write batch and the not-yet-consumed hydrated entries too;
@@ -1593,5 +2464,77 @@ declare class LunoraClient {
   */
   private clearQueryCacheForIdentityChange;
   private flushOfflineQueue;
+  /**
+  * Partition already-gated writes into the encodable ones (returned) and reject
+  * the rest terminally. A write whose args can't be wire-encoded (e.g. a RegExp
+  * or class instance in a `v.any()` field) can NEVER replay — the codec failure
+  * is deterministic, not transient. Rejecting here is essential: otherwise
+  * `encodeWire` throws mid-flush, is classified as transient (a codec error has
+  * no `.code`), and re-queues forever — a silent hang where the caller's Promise
+  * never settles and the optimistic write never rolls back. Encoding is cheap;
+  * the flush is the slow reconnect path.
+  */
+  private encodableOrSettleTerminal;
+  /**
+  * Identity guard for one queued write about to replay: a write stamped under
+  * one identity must never replay under another. The live `queuedIdentities`
+  * map is the source of truth for the current session; a hydrated write whose
+  * id isn't in the map falls back to the stamp persisted with the record
+  * (`item.identity`), so a reload can't replay another user's queued writes.
+  * Only legacy records (persisted before stamps were durable —
+  * `item.identity === undefined`) replay under whatever identity is current.
+  *
+  * `Map.get` returns `undefined` for unstamped/hydrated ids and `item.identity`
+  * is `undefined` for legacy records; a persisted `null` (queued while signed
+  * out) is a real value that must not collapse into `undefined` — hence the
+  * explicit `=== undefined` check rather than `??`. Returns `true` when the
+  * write may replay; otherwise settles it `OFFLINE_IDENTITY_CHANGED` and returns
+  * `false`. Either way the live stamp is consumed.
+  */
+  private passesReplayIdentityGate;
+  /** Settle a write that replayed successfully: confirm its optimistic layer against the echoed commit cursor BEFORE resolving, so the gapless drop is in place when the awaiter (and any confirming frame) observes the settle. */
+  private settleReplaySuccess;
+  /** Settle a write the server reached a coded verdict on: replaying would re-trigger the same failure (a poison-message loop), so drop it. */
+  private settleReplayTerminal;
+  /**
+  * Replay already-identity-gated writes one at a time on the single-call `/rpc`
+  * path, preserving FIFO order (parallel `.then()` chains would race the
+  * ordering callers depend on). Each replays under its stable `mutationId` so
+  * the server dedups a write it already committed (exactly-once). A coded error
+  * is a server verdict (drop it); a codeless (transport/transient) failure stops
+  * the flush and re-queues this write and every unreplayed one for the next
+  * reconnect — their callers stay pending, and the identity guard re-applies on
+  * retry via each record's persisted stamp.
+  */
+  private replaySequential;
+  /**
+  * Coalesce already-identity-gated writes for a single shard into ONE
+  * `/_lunora/rpc-batch` round trip (plan 088 follow-on). The worker forwards
+  * them to the shard DO, which replays each through its single-call dispatch, so
+  * per-entry `mutationId` idempotency and in-order application are inherited from
+  * the proven path. Per-slot demux mirrors {@link replaySequential}'s
+  * classification: success confirms the optimistic layer against the echoed
+  * `commitCursor`; a coded application verdict is terminal; a transient shard
+  * failure (`SHARD_UNAVAILABLE`/`SHARD_ERROR`), a missing slot, or a whole-batch
+  * transport failure re-queues for the next reconnect (never dropping a durable
+  * write). A whole-batch coded rejection (bad request / authorization denial the
+  * server reached a verdict on) is terminal for every entry.
+  *
+  * Returns the writes that must be re-queued and `stop` — `true` when the whole
+  * chunk failed at the transport level, so the caller leaves later chunks queued
+  * rather than sending on. The caller re-queues once, in order, so requeuing is
+  * NOT done here.
+  */
+  private replayBatched;
+  /**
+  * Demux a `/_lunora/rpc-batch` reply back onto the queued writes it replayed,
+  * in input order. Each slot's envelope classifies its write the same way
+  * {@link replaySequential} does: a success confirms the optimistic layer
+  * against the echoed `commitCursor`; a coded application verdict is terminal;
+  * a transient shard failure ({@link TRANSIENT_BATCH_ERROR_CODES}) or a slot the
+  * server never returned is returned for the caller to re-queue.
+  * @returns the writes that must be re-queued (transient slots), in input order
+  */
+  private settleReplayBatchSlots;
 }
-export { ArgsOf as A, BookmarkStorage as B, CachedQuery as C, DEFAULT_MAX_BUFFER as D, StreamHandle as E, FunctionReference as F, GlobalFacetResult as G, StreamIterable as H, SubscriptionCallback as I, SubscriptionRegistry as J, SubscriptionState as K, LunoraClient as L, MutationCallOptions as M, WorkflowInstanceDetail as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, WorkflowInstancePage as T, User as U, WorkflowInstanceStatus as V, WorkflowInstanceAction as W, WorkflowInstanceSummary as X, WorkflowStepDetail as Y, createLocalStore as Z, createStream as _, Unsubscribe as a, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, ClientMessage as e, ConnectionStatus as f, FunctionArgumentDescriptor as g, FunctionDescriptor as h, GlobalFacetValue as i, GlobalFilterClause as j, GlobalTableInfo as k, GlobalTablePage as l, LunoraClientOptions as m, OptimisticLocalStore as n, OptimisticUpdate as o, PersistedMutation as p, RpcEnvelope as q, RpcResponseBody as r, ScheduleRecord as s, SchedulerPoolStatus as t, SchedulerStatus as u, ServerMessage as v, ShardTrafficEntry as w, ShardTrafficResult as x, StorageListPage as y, StorageObject as z };
+export { StreamHandle as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, RpcEnvelope as E, FunctionReference as F, GlobalFacetResult as G, RpcResponseBody as H, ScheduleRecord as I, SchedulerPoolStatus as J, SchedulerStatus as K, LunoraClient as L, MutationCallOptions as M, ServerMessage as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ServerPokeEndMessage as T, User as U, ServerPokePartMessage as V, ServerPokeStartMessage as W, ShardTrafficEntry as X, ShardTrafficResult as Y, StorageListPage as Z, StorageObject as _, Unsubscribe as a, StreamIterable as a0, SubscriptionCallback as a1, SubscriptionRegistry as a2, SubscriptionState as a3, SyncWatermark as a4, WorkflowInstanceAction as a5, WorkflowInstanceDetail as a6, WorkflowInstancePage as a7, WorkflowInstanceStatus as a8, WorkflowInstanceSummary as a9, WorkflowStepDetail as aa, createLocalStore as ab, createStream as ac, getErrorCode as ad, getRetryAfterMs as ae, isConflictError as af, isForbiddenError as ag, isRateLimitedError as ah, isUnauthorizedError as ai, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, BatchSlot as e, CachedQuery as f, ClientMessage as g, ClientShapeSubscribeMessage as h, ClientShapeUnsubscribeMessage as i, ConnectionStatus as j, FunctionArgumentDescriptor as k, FunctionDescriptor as l, GlobalFacetValue as m, GlobalFilterClause as n, GlobalTableInfo as o, GlobalTablePage as p, LunoraClientError as q, LunoraClientOptions as r, LunoraErrorCode as s, MutationSettledEvent as t, OptimisticLocalStore as u, OptimisticUpdate as v, OutboxMutation as w, OutboxSink as x, PersistedMutation as y, RowOp as z };