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

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-BYkEjCEJ.mjs";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/auth/index.d.ts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-BYkEjCEJ.js";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DGvyuJ_p.mjs";
-export { type C as CachedQuery, type e as ClientMessage, type f as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type g as FunctionArgumentDescriptor, type h as FunctionDescriptor, type G as GlobalFacetResult, type i as GlobalFacetValue, type j as GlobalFilterClause, type k as GlobalTableInfo, type l as GlobalTablePage, L as LunoraClient, type m as LunoraClientOptions, type n as OptimisticLocalStore, type o as OptimisticUpdate, type p as PersistedMutation, type P as Preloaded, type q as RpcEnvelope, type r as RpcResponseBody, type s as ScheduleRecord, type t as SchedulerPoolStatus, type u as SchedulerStatus, type v as ServerMessage, type w as ShardTrafficEntry, type x as ShardTrafficResult, type y as StorageListPage, type z as StorageObject, type E as StreamHandle, type H as StreamIterable, type I as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, J as SubscriptionRegistry, type K as SubscriptionState, type a as Unsubscribe, type U as User, type W as WorkflowInstanceAction, type N as WorkflowInstanceDetail, type T as WorkflowInstancePage, type V as WorkflowInstanceStatus, type X as WorkflowInstanceSummary, type Y as WorkflowStepDetail, Z as createLocalStore, _ as createStream } from "./packem_shared/lunora-client.d-DGvyuJ_p.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-dSaRMuhL.mjs";
-export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
+import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-BYkEjCEJ.mjs";
+export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientShapeSubscribeMessage, type i as ClientShapeUnsubscribeMessage, type j as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type k as FunctionArgumentDescriptor, type l as FunctionDescriptor, type G as GlobalFacetResult, type m as GlobalFacetValue, type n as GlobalFilterClause, type o as GlobalTableInfo, type p as GlobalTablePage, L as LunoraClient, type q as LunoraClientError, type r as LunoraClientOptions, type s as LunoraErrorCode, type t as MutationSettledEvent, type u as OptimisticLocalStore, type v as OptimisticUpdate, type w as OutboxMutation, type x as OutboxSink, type y as PersistedMutation, type P as Preloaded, type z as RowOp, type E as RpcEnvelope, type H as RpcResponseBody, type I as ScheduleRecord, type J as SchedulerPoolStatus, type K as SchedulerStatus, type N as ServerMessage, type T as ServerPokeEndMessage, type V as ServerPokePartMessage, type W as ServerPokeStartMessage, type X as ShardTrafficEntry, type Y as ShardTrafficResult, type Z as StorageListPage, type _ as StorageObject, type $ as StreamHandle, type a0 as StreamIterable, type a1 as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a2 as SubscriptionRegistry, type a3 as SubscriptionState, type a4 as SyncWatermark, type a as Unsubscribe, type U as User, type a5 as WorkflowInstanceAction, type a6 as WorkflowInstanceDetail, type a7 as WorkflowInstancePage, type a8 as WorkflowInstanceStatus, type a9 as WorkflowInstanceSummary, type aa as WorkflowStepDetail, ab as createLocalStore, ac as createStream, ad as getErrorCode, ae as getRetryAfterMs, af as isConflictError, ag as isForbiddenError, ah as isRateLimitedError, ai as isUnauthorizedError } from "./packem_shared/lunora-client.d-BYkEjCEJ.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-DrfuisCE.mjs";
+export type { AuthCapabilities, AuthConfigInfo, AuthImpersonation, AuthPage, AuthSession, AuthUser, AuthUserFieldSpec, CronJobInfo, KvKeyEntry, KvKeyListResult, KvNamespaceSummary, KvValueResult, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —
 * Expo `SecureStore`, a wrapped `localForage`, an in-memory map in tests) this
@@ -95,17 +95,6 @@ declare const isMutationDelta: (value: unknown) => value is MutationDelta;
 * when an `insert`/`update` delta carries no `row` to splice in.
 */
 declare const applyDelta: (current: unknown, delta: MutationDelta) => undefined | unknown[];
-/** 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";
-};
 /** The single transport method a mutation runner needs — narrowed so adapters can test against a stub. */
 interface MutationCapableClient<F extends FunctionReference> {
   mutation: (function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
@@ -136,6 +125,59 @@ interface MutationRunnerSinks<R> {
 * pass straight through to `client.mutation`.
 */
 declare const createMutationRunner: <F extends FunctionReference>(client: MutationCapableClient<F>, function_: F, sinks: MutationRunnerSinks<ReturnOf<F>>) => ((args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>);
+/**
+* The structural surface of a TanStack `Transaction` a bound custom mutator
+* returns — its `isPersisted.promise` resolves once the write is persisted and
+* rejects on failure. Typed structurally so the framework adapters need not
+* depend on `@tanstack/db` or `@lunora/db` (the handle is created app-side by
+* `bindMutators`).
+*/
+interface MutatorTransaction {
+  isPersisted: {
+    promise: Promise<unknown>;
+  };
+}
+/**
+* A bound custom-mutator handle produced by `bindMutators(client, ctx, mutators)`
+* in `@lunora/db`. Calling it applies the optimistic overlay to the local
+* collections and pushes the authoritative server write; it returns the TanStack
+* transaction whose `isPersisted` promise tracks completion.
+*/
+type MutatorHandle<TArgs> = (args: TArgs) => MutatorTransaction;
+/**
+* Reactive sinks an adapter binds to its own primitive's setters (a React
+* `useState`, a Solid signal, a Vue ref, a Svelte store). The runner pushes into
+* them; how they store the value is the adapter's concern.
+*/
+interface MutatorRunnerSinks {
+  /** Receives the normalized {@link Error} when an invocation rejects, or `undefined` on success / reset. */
+  setError: (error: Error | undefined) => void;
+  /** Receives `true` while at least one invocation is in flight (ref-counted across overlapping calls), else `false`. */
+  setPending: (pending: boolean) => void;
+}
+/**
+* Build the framework-neutral `mutate` / `reset` pair of an adapter's
+* custom-mutator hook (`useMutator` / `createMutator` / `mutator`).
+*
+* Owns the orchestration every adapter otherwise copy-pastes: ref-counts
+* overlapping invocations into `setPending` (so it only clears once the last
+* settles), awaits the bound handle's `isPersisted` promise, normalizes a thrown
+* non-`Error`, and routes failure to `setError` (clearing it on success) before
+* re-throwing. Each adapter (`@lunora/react`, `/solid`, `/svelte`, `/vue`) binds
+* the two sinks to its own reactive setters, so this logic lives in exactly one
+* place. The optimistic overlay + server push are owned by the bound handle.
+*
+* `error` tracks the LATEST invocation, not the last to settle: overlapping
+* calls can resolve out of order, so an earlier call that finishes later must
+* not clobber a newer call's outcome. Each invocation takes a monotonic token
+* and only writes `setError` while it is still the most recent one — otherwise
+* `error`/`isError` could surface a stale success or failure (the documented
+* "latest invocation's error" contract every adapter advertises).
+*/
+declare const createMutatorRunner: <TArgs>(handle: MutatorHandle<TArgs>, sinks: MutatorRunnerSinks) => {
+  mutate: (args: TArgs) => Promise<void>;
+  reset: () => void;
+};
 interface QueuedMutation<T = unknown> {
   readonly args: Record<string, unknown>;
   readonly functionPath: string;
@@ -146,12 +188,57 @@ interface QueuedMutation<T = unknown> {
   * signed out). Absent on hydrated legacy records, which replay ambiently.
   */
   readonly identity?: string | null;
+  /**
+  * `true` when a live caller is still awaiting this write's `mutation()`
+  * Promise; `false`/absent for a write restored from durable storage after a
+  * reload (its original awaiter is gone). Carried so terminal-verdict
+  * observers can distinguish "the caller already saw this" from "nothing else
+  * will report this". Maps to the public `MutationSettledEvent.hadAwaiter`.
+  */
+  liveAwaiter?: boolean;
+  /**
+  * Invoked on a successful replay with the server's echoed commit CDC cursor,
+  * so a live per-call optimistic layer drops gaplessly once a frame reaches it.
+  * Absent on hydrated records (the optimistic write lived in a prior session).
+  */
+  readonly onCommit?: (commitCursor: number | undefined) => void;
   /** Rejects if the mutation can no longer be replayed. */
   readonly reject: (error: unknown) => void;
   /** Resolves once the mutation has been replayed against the server. */
   readonly resolve: (value: T) => void;
   readonly shardKey?: string;
 }
+/**
+* Invoked when the queue itself discards an entry on overflow (capacity
+* eviction), so the client can surface the dropped write on its
+* terminal-verdict observer even when the entry has no live awaiter (a hydrated
+* record). The `error` carries the `OFFLINE_QUEUE_OVERFLOW` code.
+*/
+type EvictHandler = (entry: QueuedMutation, error: Error & {
+  code?: string;
+}) => void;
+/** Injected dependencies for {@link OfflineQueue} (kept off the user-facing {@link OfflineQueueOptions}). */
+interface OfflineQueueDeps {
+  /** Invoked when an entry is discarded on capacity overflow (carries `OFFLINE_QUEUE_OVERFLOW`). */
+  onEvict?: EvictHandler;
+  /** Invoked with the new depth after any size change (drives the client's pending-sync count). */
+  onSizeChange?: (size: number) => void;
+  /** Durable store; when present, writes are mirrored and restored across reloads. */
+  persistence?: PersistenceAdapter;
+  /** App/schema version stamped on persisted writes; mismatched records are purged on hydrate. */
+  version?: string;
+}
+/**
+* A process-unique id, used both per-mutation and as the fallback `clientId`. It
+* MUST be globally unique: the server scopes a custom mutator's replay watermark
+* by `(verifiedIdentity, clientId)`, and an anonymous push has no verified
+* identity — so two anonymous clients that collide on `clientId` would share one
+* watermark namespace, letting one stall/suppress the other's ordered mutations.
+* `crypto.randomUUID` covers every modern runtime; the fallback still mixes
+* crypto-quality (or `Math.random`) entropy with the timestamp + counter so it
+* can't collide across two clients started in the same millisecond.
+*/
+
 /**
 * Bounded FIFO queue. Mutations issued while the client is offline are
 * enqueued and replayed in the order they were submitted once the WS
@@ -170,8 +257,12 @@ declare class OfflineQueue {
   private readonly maxItems;
   private readonly onPersistenceError;
   private readonly persistence;
+  private readonly onEvict;
+  private readonly onSizeChange;
+  /** App/schema version stamped on persisted writes; mismatched records are purged on hydrate. */
+  private readonly version;
   private readonly items;
-  constructor(options?: OfflineQueueOptions, persistence?: PersistenceAdapter);
+  constructor(options?: OfflineQueueOptions, deps?: OfflineQueueDeps);
   get size(): number;
   enqueue<T>(entry: QueuedMutation<T>): void;
   /**
@@ -198,6 +289,8 @@ declare class OfflineQueue {
   */
   requeue(items: QueuedMutation[]): void;
   clear(): void;
+  /** Notify the size observer (the client's pending-sync count) after any change. */
+  private notifySize;
 }
 /**
 * In-memory {@link PersistenceAdapter}. Doesn't survive a reload — it exists so
@@ -207,7 +300,7 @@ declare class OfflineQueue {
 */
 declare const createInMemoryPersistence: () => PersistenceAdapter;
 interface IndexedDbPersistenceOptions {
-  /** Database name; defaults to `"lunora"`. */
+  /** Database name; defaults to `"lunora-outbox"` (its own DB, separate from the read cache). */
   databaseName?: string;
   /** Injectable `IDBFactory` (e.g. `fake-indexeddb` in tests); defaults to the global `indexedDB`. */
   indexedDB?: IDBFactory;
@@ -225,6 +318,24 @@ interface IndexedDbPersistenceOptions {
 */
 declare const createIndexedDbPersistence: (options?: IndexedDbPersistenceOptions) => PersistenceAdapter;
 /**
+* Resolve the effective offline-queue persistence from the user option,
+* defaulting to a durable IndexedDB store when the environment supports one.
+*
+* An explicit adapter is used as-is; `false` opts out (the caller keeps an
+* in-memory queue, lost on reload); `undefined` (the default) auto-probes
+* IndexedDB when the global is present (browsers) and `autoProbe` is set,
+* otherwise `undefined` — so SSR/Node/React-Native keep today's in-memory
+* behaviour and only environments that can persist do.
+*
+* `autoProbe` is `false` when the `@lunora/db` outbox is wired: that sink is the
+* single durable write path, so the built-in queue must stay in memory rather
+* than persist a second, never-flushed copy. An explicit adapter is still
+* honoured (the caller asked for it); only the implicit default is suppressed.
+*
+* The IndexedDB adapter opens its connection lazily, so constructing it here is
+* cheap and never throws (the `indexedDB` global is verified present first).
+*/
+/**
 * Compose the read-cache key for a subscription. Mirrors how
 * `SubscriptionRegistry` keys live subscriptions so a hydrated value lines up
 * with the subscription that will consume it. `shardKey` defaults to `""` (the
@@ -242,7 +353,7 @@ declare const createInMemoryQueryCache: (options?: {
   maxEntries?: number;
 }) => QueryCacheAdapter;
 interface IndexedDbQueryCacheOptions {
-  /** Database name; defaults to `"lunora"` (shared with the offline-mutation store). */
+  /** Database name; defaults to `"lunora-query-cache"` (its own DB, separate from the offline outbox). */
   databaseName?: string;
   /** Injectable `IDBFactory` (e.g. `fake-indexeddb` in tests); defaults to the global `indexedDB`. */
   indexedDB?: IDBFactory;
@@ -257,14 +368,23 @@ interface IndexedDbQueryCacheOptions {
 * LRU eviction. The store handle is opened lazily and cached, so repeated ops
 * reuse one connection.
 *
-* The store lives in the same `lunora` database as the offline-mutation queue
-* (bumped to schema v2). Opening it upgrades a v1 database in place, adding the
-* `query-cache` store without touching `offline-mutations`. Throws eagerly if no
-* `IDBFactory` is available — callers in non-browser environments should use
-* {@link createInMemoryQueryCache}.
+* The store lives in its own `lunora-query-cache` database — deliberately
+* separate from the offline-mutation outbox's `lunora-outbox` database so the two
+* independently-toggleable adapters never share (and drift on) a schema version.
+* Throws eagerly if no `IDBFactory` is available — callers in non-browser
+* environments should use {@link createInMemoryQueryCache}.
 */
 declare const createIndexedDbQueryCache: (options?: IndexedDbQueryCacheOptions) => QueryCacheAdapter;
 /**
+* Resolve the effective read-cache from the user option, defaulting to a durable
+* IndexedDB store when the environment supports one. Same tri-state semantics as
+* `resolvePersistenceAdapter` in `./persistence`:
+*
+* - an explicit adapter is used as-is;
+* - `false` opts out — reads stay in memory only;
+* - `undefined` (the default) auto-probes IndexedDB (browsers), else `undefined`.
+*/
+/**
 * Exponential backoff calculator with optional jitter.
 *
 * `next()` doubles the delay each call up to `maxDelayMs`. When `jitter` is
@@ -278,4 +398,4 @@ interface ReconnectCalculator {
   reset: () => void;
 }
 declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
-export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, CONFLICT_ERROR_CODE, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };
+export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isMutationDelta, queryCacheKey };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DGvyuJ_p.js";
-export { type C as CachedQuery, type e as ClientMessage, type f as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type g as FunctionArgumentDescriptor, type h as FunctionDescriptor, type G as GlobalFacetResult, type i as GlobalFacetValue, type j as GlobalFilterClause, type k as GlobalTableInfo, type l as GlobalTablePage, L as LunoraClient, type m as LunoraClientOptions, type n as OptimisticLocalStore, type o as OptimisticUpdate, type p as PersistedMutation, type P as Preloaded, type q as RpcEnvelope, type r as RpcResponseBody, type s as ScheduleRecord, type t as SchedulerPoolStatus, type u as SchedulerStatus, type v as ServerMessage, type w as ShardTrafficEntry, type x as ShardTrafficResult, type y as StorageListPage, type z as StorageObject, type E as StreamHandle, type H as StreamIterable, type I as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, J as SubscriptionRegistry, type K as SubscriptionState, type a as Unsubscribe, type U as User, type W as WorkflowInstanceAction, type N as WorkflowInstanceDetail, type T as WorkflowInstancePage, type V as WorkflowInstanceStatus, type X as WorkflowInstanceSummary, type Y as WorkflowStepDetail, Z as createLocalStore, _ as createStream } from "./packem_shared/lunora-client.d-DGvyuJ_p.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-BoDmFqSG.js";
-export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
+import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-BYkEjCEJ.js";
+export { type e as BatchSlot, C as CONFLICT_ERROR_CODE, type f as CachedQuery, type g as ClientMessage, type h as ClientShapeSubscribeMessage, type i as ClientShapeUnsubscribeMessage, type j as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type k as FunctionArgumentDescriptor, type l as FunctionDescriptor, type G as GlobalFacetResult, type m as GlobalFacetValue, type n as GlobalFilterClause, type o as GlobalTableInfo, type p as GlobalTablePage, L as LunoraClient, type q as LunoraClientError, type r as LunoraClientOptions, type s as LunoraErrorCode, type t as MutationSettledEvent, type u as OptimisticLocalStore, type v as OptimisticUpdate, type w as OutboxMutation, type x as OutboxSink, type y as PersistedMutation, type P as Preloaded, type z as RowOp, type E as RpcEnvelope, type H as RpcResponseBody, type I as ScheduleRecord, type J as SchedulerPoolStatus, type K as SchedulerStatus, type N as ServerMessage, type T as ServerPokeEndMessage, type V as ServerPokePartMessage, type W as ServerPokeStartMessage, type X as ShardTrafficEntry, type Y as ShardTrafficResult, type Z as StorageListPage, type _ as StorageObject, type $ as StreamHandle, type a0 as StreamIterable, type a1 as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, a2 as SubscriptionRegistry, type a3 as SubscriptionState, type a4 as SyncWatermark, type a as Unsubscribe, type U as User, type a5 as WorkflowInstanceAction, type a6 as WorkflowInstanceDetail, type a7 as WorkflowInstancePage, type a8 as WorkflowInstanceStatus, type a9 as WorkflowInstanceSummary, type aa as WorkflowStepDetail, ab as createLocalStore, ac as createStream, ad as getErrorCode, ae as getRetryAfterMs, af as isConflictError, ag as isForbiddenError, ah as isRateLimitedError, ai as isUnauthorizedError } from "./packem_shared/lunora-client.d-BYkEjCEJ.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-B-vyHnml.js";
+export type { AuthCapabilities, AuthConfigInfo, AuthImpersonation, AuthPage, AuthSession, AuthUser, AuthUserFieldSpec, CronJobInfo, KvKeyEntry, KvKeyListResult, KvNamespaceSummary, KvValueResult, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —
 * Expo `SecureStore`, a wrapped `localForage`, an in-memory map in tests) this
@@ -95,17 +95,6 @@ declare const isMutationDelta: (value: unknown) => value is MutationDelta;
 * when an `insert`/`update` delta carries no `row` to splice in.
 */
 declare const applyDelta: (current: unknown, delta: MutationDelta) => undefined | unknown[];
-/** 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";
-};
 /** The single transport method a mutation runner needs — narrowed so adapters can test against a stub. */
 interface MutationCapableClient<F extends FunctionReference> {
   mutation: (function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
@@ -136,6 +125,59 @@ interface MutationRunnerSinks<R> {
 * pass straight through to `client.mutation`.
 */
 declare const createMutationRunner: <F extends FunctionReference>(client: MutationCapableClient<F>, function_: F, sinks: MutationRunnerSinks<ReturnOf<F>>) => ((args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>);
+/**
+* The structural surface of a TanStack `Transaction` a bound custom mutator
+* returns — its `isPersisted.promise` resolves once the write is persisted and
+* rejects on failure. Typed structurally so the framework adapters need not
+* depend on `@tanstack/db` or `@lunora/db` (the handle is created app-side by
+* `bindMutators`).
+*/
+interface MutatorTransaction {
+  isPersisted: {
+    promise: Promise<unknown>;
+  };
+}
+/**
+* A bound custom-mutator handle produced by `bindMutators(client, ctx, mutators)`
+* in `@lunora/db`. Calling it applies the optimistic overlay to the local
+* collections and pushes the authoritative server write; it returns the TanStack
+* transaction whose `isPersisted` promise tracks completion.
+*/
+type MutatorHandle<TArgs> = (args: TArgs) => MutatorTransaction;
+/**
+* Reactive sinks an adapter binds to its own primitive's setters (a React
+* `useState`, a Solid signal, a Vue ref, a Svelte store). The runner pushes into
+* them; how they store the value is the adapter's concern.
+*/
+interface MutatorRunnerSinks {
+  /** Receives the normalized {@link Error} when an invocation rejects, or `undefined` on success / reset. */
+  setError: (error: Error | undefined) => void;
+  /** Receives `true` while at least one invocation is in flight (ref-counted across overlapping calls), else `false`. */
+  setPending: (pending: boolean) => void;
+}
+/**
+* Build the framework-neutral `mutate` / `reset` pair of an adapter's
+* custom-mutator hook (`useMutator` / `createMutator` / `mutator`).
+*
+* Owns the orchestration every adapter otherwise copy-pastes: ref-counts
+* overlapping invocations into `setPending` (so it only clears once the last
+* settles), awaits the bound handle's `isPersisted` promise, normalizes a thrown
+* non-`Error`, and routes failure to `setError` (clearing it on success) before
+* re-throwing. Each adapter (`@lunora/react`, `/solid`, `/svelte`, `/vue`) binds
+* the two sinks to its own reactive setters, so this logic lives in exactly one
+* place. The optimistic overlay + server push are owned by the bound handle.
+*
+* `error` tracks the LATEST invocation, not the last to settle: overlapping
+* calls can resolve out of order, so an earlier call that finishes later must
+* not clobber a newer call's outcome. Each invocation takes a monotonic token
+* and only writes `setError` while it is still the most recent one — otherwise
+* `error`/`isError` could surface a stale success or failure (the documented
+* "latest invocation's error" contract every adapter advertises).
+*/
+declare const createMutatorRunner: <TArgs>(handle: MutatorHandle<TArgs>, sinks: MutatorRunnerSinks) => {
+  mutate: (args: TArgs) => Promise<void>;
+  reset: () => void;
+};
 interface QueuedMutation<T = unknown> {
   readonly args: Record<string, unknown>;
   readonly functionPath: string;
@@ -146,12 +188,57 @@ interface QueuedMutation<T = unknown> {
   * signed out). Absent on hydrated legacy records, which replay ambiently.
   */
   readonly identity?: string | null;
+  /**
+  * `true` when a live caller is still awaiting this write's `mutation()`
+  * Promise; `false`/absent for a write restored from durable storage after a
+  * reload (its original awaiter is gone). Carried so terminal-verdict
+  * observers can distinguish "the caller already saw this" from "nothing else
+  * will report this". Maps to the public `MutationSettledEvent.hadAwaiter`.
+  */
+  liveAwaiter?: boolean;
+  /**
+  * Invoked on a successful replay with the server's echoed commit CDC cursor,
+  * so a live per-call optimistic layer drops gaplessly once a frame reaches it.
+  * Absent on hydrated records (the optimistic write lived in a prior session).
+  */
+  readonly onCommit?: (commitCursor: number | undefined) => void;
   /** Rejects if the mutation can no longer be replayed. */
   readonly reject: (error: unknown) => void;
   /** Resolves once the mutation has been replayed against the server. */
   readonly resolve: (value: T) => void;
   readonly shardKey?: string;
 }
+/**
+* Invoked when the queue itself discards an entry on overflow (capacity
+* eviction), so the client can surface the dropped write on its
+* terminal-verdict observer even when the entry has no live awaiter (a hydrated
+* record). The `error` carries the `OFFLINE_QUEUE_OVERFLOW` code.
+*/
+type EvictHandler = (entry: QueuedMutation, error: Error & {
+  code?: string;
+}) => void;
+/** Injected dependencies for {@link OfflineQueue} (kept off the user-facing {@link OfflineQueueOptions}). */
+interface OfflineQueueDeps {
+  /** Invoked when an entry is discarded on capacity overflow (carries `OFFLINE_QUEUE_OVERFLOW`). */
+  onEvict?: EvictHandler;
+  /** Invoked with the new depth after any size change (drives the client's pending-sync count). */
+  onSizeChange?: (size: number) => void;
+  /** Durable store; when present, writes are mirrored and restored across reloads. */
+  persistence?: PersistenceAdapter;
+  /** App/schema version stamped on persisted writes; mismatched records are purged on hydrate. */
+  version?: string;
+}
+/**
+* A process-unique id, used both per-mutation and as the fallback `clientId`. It
+* MUST be globally unique: the server scopes a custom mutator's replay watermark
+* by `(verifiedIdentity, clientId)`, and an anonymous push has no verified
+* identity — so two anonymous clients that collide on `clientId` would share one
+* watermark namespace, letting one stall/suppress the other's ordered mutations.
+* `crypto.randomUUID` covers every modern runtime; the fallback still mixes
+* crypto-quality (or `Math.random`) entropy with the timestamp + counter so it
+* can't collide across two clients started in the same millisecond.
+*/
+
 /**
 * Bounded FIFO queue. Mutations issued while the client is offline are
 * enqueued and replayed in the order they were submitted once the WS
@@ -170,8 +257,12 @@ declare class OfflineQueue {
   private readonly maxItems;
   private readonly onPersistenceError;
   private readonly persistence;
+  private readonly onEvict;
+  private readonly onSizeChange;
+  /** App/schema version stamped on persisted writes; mismatched records are purged on hydrate. */
+  private readonly version;
   private readonly items;
-  constructor(options?: OfflineQueueOptions, persistence?: PersistenceAdapter);
+  constructor(options?: OfflineQueueOptions, deps?: OfflineQueueDeps);
   get size(): number;
   enqueue<T>(entry: QueuedMutation<T>): void;
   /**
@@ -198,6 +289,8 @@ declare class OfflineQueue {
   */
   requeue(items: QueuedMutation[]): void;
   clear(): void;
+  /** Notify the size observer (the client's pending-sync count) after any change. */
+  private notifySize;
 }
 /**
 * In-memory {@link PersistenceAdapter}. Doesn't survive a reload — it exists so
@@ -207,7 +300,7 @@ declare class OfflineQueue {
 */
 declare const createInMemoryPersistence: () => PersistenceAdapter;
 interface IndexedDbPersistenceOptions {
-  /** Database name; defaults to `"lunora"`. */
+  /** Database name; defaults to `"lunora-outbox"` (its own DB, separate from the read cache). */
   databaseName?: string;
   /** Injectable `IDBFactory` (e.g. `fake-indexeddb` in tests); defaults to the global `indexedDB`. */
   indexedDB?: IDBFactory;
@@ -225,6 +318,24 @@ interface IndexedDbPersistenceOptions {
 */
 declare const createIndexedDbPersistence: (options?: IndexedDbPersistenceOptions) => PersistenceAdapter;
 /**
+* Resolve the effective offline-queue persistence from the user option,
+* defaulting to a durable IndexedDB store when the environment supports one.
+*
+* An explicit adapter is used as-is; `false` opts out (the caller keeps an
+* in-memory queue, lost on reload); `undefined` (the default) auto-probes
+* IndexedDB when the global is present (browsers) and `autoProbe` is set,
+* otherwise `undefined` — so SSR/Node/React-Native keep today's in-memory
+* behaviour and only environments that can persist do.
+*
+* `autoProbe` is `false` when the `@lunora/db` outbox is wired: that sink is the
+* single durable write path, so the built-in queue must stay in memory rather
+* than persist a second, never-flushed copy. An explicit adapter is still
+* honoured (the caller asked for it); only the implicit default is suppressed.
+*
+* The IndexedDB adapter opens its connection lazily, so constructing it here is
+* cheap and never throws (the `indexedDB` global is verified present first).
+*/
+/**
 * Compose the read-cache key for a subscription. Mirrors how
 * `SubscriptionRegistry` keys live subscriptions so a hydrated value lines up
 * with the subscription that will consume it. `shardKey` defaults to `""` (the
@@ -242,7 +353,7 @@ declare const createInMemoryQueryCache: (options?: {
   maxEntries?: number;
 }) => QueryCacheAdapter;
 interface IndexedDbQueryCacheOptions {
-  /** Database name; defaults to `"lunora"` (shared with the offline-mutation store). */
+  /** Database name; defaults to `"lunora-query-cache"` (its own DB, separate from the offline outbox). */
   databaseName?: string;
   /** Injectable `IDBFactory` (e.g. `fake-indexeddb` in tests); defaults to the global `indexedDB`. */
   indexedDB?: IDBFactory;
@@ -257,14 +368,23 @@ interface IndexedDbQueryCacheOptions {
 * LRU eviction. The store handle is opened lazily and cached, so repeated ops
 * reuse one connection.
 *
-* The store lives in the same `lunora` database as the offline-mutation queue
-* (bumped to schema v2). Opening it upgrades a v1 database in place, adding the
-* `query-cache` store without touching `offline-mutations`. Throws eagerly if no
-* `IDBFactory` is available — callers in non-browser environments should use
-* {@link createInMemoryQueryCache}.
+* The store lives in its own `lunora-query-cache` database — deliberately
+* separate from the offline-mutation outbox's `lunora-outbox` database so the two
+* independently-toggleable adapters never share (and drift on) a schema version.
+* Throws eagerly if no `IDBFactory` is available — callers in non-browser
+* environments should use {@link createInMemoryQueryCache}.
 */
 declare const createIndexedDbQueryCache: (options?: IndexedDbQueryCacheOptions) => QueryCacheAdapter;
 /**
+* Resolve the effective read-cache from the user option, defaulting to a durable
+* IndexedDB store when the environment supports one. Same tri-state semantics as
+* `resolvePersistenceAdapter` in `./persistence`:
+*
+* - an explicit adapter is used as-is;
+* - `false` opts out — reads stay in memory only;
+* - `undefined` (the default) auto-probes IndexedDB (browsers), else `undefined`.
+*/
+/**
 * Exponential backoff calculator with optional jitter.
 *
 * `next()` doubles the delay each call up to `maxDelayMs`. When `jitter` is
@@ -278,4 +398,4 @@ interface ReconnectCalculator {
   reset: () => void;
 }
 declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
-export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, CONFLICT_ERROR_CODE, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };
+export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isMutationDelta, queryCacheKey };

package/dist/index.mjs

@@ -1,14 +1,15 @@
 export { createAsyncStoragePersistence } from './packem_shared/createAsyncStoragePersistence-1Z5BZ8RC.mjs';
 export { default as createInMemoryBookmarkStorage } from './packem_shared/createInMemoryBookmarkStorage-BoN7a7TH.mjs';
-export { applyDelta, isMutationDelta } from './packem_shared/applyDelta-4jFGTPA3.mjs';
-export { CONFLICT_ERROR_CODE, isConflictError } from './packem_shared/CONFLICT_ERROR_CODE-aUdVbEDw.mjs';
-export { createLocalStore } from './packem_shared/createLocalStore-DSUfoLqY.mjs';
-export { LunoraClient } from './packem_shared/LunoraClient-UiULzH_1.mjs';
+export { applyDelta, isMutationDelta } from './packem_shared/applyDelta-CRKZ1PBt.mjs';
+export { CONFLICT_ERROR_CODE, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from './packem_shared/CONFLICT_ERROR_CODE-B8gQ8tyU.mjs';
+export { c as createLocalStore } from './packem_shared/local-store-BveBeFEo.mjs';
+export { LunoraClient } from './packem_shared/LunoraClient-kXpHNyaE.mjs';
 export { createMutationRunner } from './packem_shared/createMutationRunner-BqsavzvG.mjs';
-export { OfflineQueue } from './packem_shared/OfflineQueue-D5p_QgF_.mjs';
-export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createInMemoryPersistence-CW82inU5.mjs';
+export { createMutatorRunner } from './packem_shared/createMutatorRunner-BETvCd0p.mjs';
+export { O as OfflineQueue } from './packem_shared/offline-queue-B9vfdSqp.mjs';
+export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createInMemoryPersistence-DZ2VHWgm.mjs';
 export { preloadQuery, preloadedQueryResult } from './packem_shared/preloadQuery-lobFkD2Z.mjs';
-export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createInMemoryQueryCache-B1PQ9Twl.mjs';
+export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createInMemoryQueryCache-DiaGZkA2.mjs';
 export { createReconnect } from './packem_shared/createReconnect-Di_-oHH7.mjs';
-export { DEFAULT_MAX_BUFFER, createStream } from './packem_shared/DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
-export { SubscriptionRegistry } from './packem_shared/SubscriptionRegistry-B-Qx_Gux.mjs';
+export { DEFAULT_MAX_BUFFER, createStream } from './packem_shared/DEFAULT_MAX_BUFFER-7hFnzNk9.mjs';
+export { S as SubscriptionRegistry } from './packem_shared/subscription-BjynOXCU.mjs';

package/dist/packem_shared/CONFLICT_ERROR_CODE-B8gQ8tyU.mjs

@@ -0,0 +1,33 @@
+const LUNORA_ERROR_CODES = [
+  "BAD_REQUEST",
+  "CONFLICT",
+  "COUNT_RLS_UNSUPPORTED",
+  "FORBIDDEN",
+  "INTERNAL_SERVER_ERROR",
+  "MASK_UNSUPPORTED",
+  "NOT_FOUND",
+  "NOT_IMPLEMENTED",
+  "RELATION_PREDICATE_UNSUPPORTED",
+  "TOO_MANY_REQUESTS",
+  "UNAUTHORIZED",
+  "UNPROCESSABLE"
+];
+const KNOWN_ERROR_CODES = new Set(LUNORA_ERROR_CODES);
+const CONFLICT_ERROR_CODE = "CONFLICT";
+const isConflictError = (error) => error instanceof Error && error.code === CONFLICT_ERROR_CODE;
+const isForbiddenError = (error) => error instanceof Error && error.code === "FORBIDDEN";
+const isUnauthorizedError = (error) => error instanceof Error && error.code === "UNAUTHORIZED";
+const isRateLimitedError = (error) => error instanceof Error && error.code === "TOO_MANY_REQUESTS";
+const getErrorCode = (error) => {
+  if (!(error instanceof Error)) {
+    return void 0;
+  }
+  const { code } = error;
+  return typeof code === "string" && KNOWN_ERROR_CODES.has(code) ? code : void 0;
+};
+const getRetryAfterMs = (error) => {
+  const value = error?.data?.retryAfterMs;
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+};
+
+export { CONFLICT_ERROR_CODE, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError };

package/dist/packem_shared/{DEFAULT_MAX_BUFFER-BDkqO5PW.mjs → DEFAULT_MAX_BUFFER-7hFnzNk9.mjs}

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const DEFAULT_MAX_BUFFER = 1024;
 const createStream = (options) => {
   const maxBuffer = options.maxBuffer ?? DEFAULT_MAX_BUFFER;
@@ -51,9 +53,10 @@ const createStream = (options) => {
       }
       if (buffer.length >= maxBuffer) {
         handle.fail(
-          Object.assign(new Error(`stream buffer overflow (max=${maxBuffer.toString()}); the consumer cannot keep up with the producer`), {
-            code: "STREAM_BACKPRESSURE"
-          })
+          new LunoraError(
+            "STREAM_BACKPRESSURE",
+            `stream buffer overflow (max=${maxBuffer.toString()}); the consumer cannot keep up with the producer`
+          )
         );
         return;
       }