@lunora/client 0.0.0 → 1.0.0-alpha.2

package/dist/auth/index.d.mts

@@ -0,0 +1,20 @@
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
+import '@lunora/runtime';
+interface IdentityStore {
+  /** Read the current resolved user, or `null` when signed out / not yet resolved. */
+  getUser: () => User | null;
+  /**
+  * Subscribe to identity changes. `onChange` is called whenever the user or
+  * token changes. Returns an unsubscribe handle.
+  */
+  subscribe: (onChange: () => void) => () => void;
+}
+/**
+* Return the per-client identity store, creating it on first access.
+*
+* The store is cached via a `WeakMap` so it is GC'd when the client is dropped,
+* and creation is idempotent — calling this multiple times with the same client
+* returns the same store, keeping the single-fetch / fan-out invariant.
+*/
+declare const getIdentityStore: (client: LunoraClient) => IdentityStore;
+export { type IdentityStore, getIdentityStore };

package/dist/auth/index.d.ts

@@ -0,0 +1,20 @@
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
+import '@lunora/runtime';
+interface IdentityStore {
+  /** Read the current resolved user, or `null` when signed out / not yet resolved. */
+  getUser: () => User | null;
+  /**
+  * Subscribe to identity changes. `onChange` is called whenever the user or
+  * token changes. Returns an unsubscribe handle.
+  */
+  subscribe: (onChange: () => void) => () => void;
+}
+/**
+* Return the per-client identity store, creating it on first access.
+*
+* The store is cached via a `WeakMap` so it is GC'd when the client is dropped,
+* and creation is idempotent — calling this multiple times with the same client
+* returns the same store, keeping the single-fetch / fan-out invariant.
+*/
+declare const getIdentityStore: (client: LunoraClient) => IdentityStore;
+export { type IdentityStore, getIdentityStore };

package/dist/auth/index.mjs

@@ -0,0 +1,60 @@
+const stores = /* @__PURE__ */ new WeakMap();
+const createIdentityStore = (client) => {
+  const listeners = /* @__PURE__ */ new Set();
+  let user = null;
+  let started = false;
+  const notify = () => {
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  let generation = 0;
+  const setUser = (next) => {
+    if (user !== next) {
+      user = next;
+      notify();
+    }
+  };
+  const refresh = () => {
+    generation += 1;
+    const current = generation;
+    if (client.getAuthToken() === null) {
+      setUser(null);
+      return;
+    }
+    client.getCurrentUser().then((next) => {
+      if (current === generation) {
+        setUser(next);
+      }
+      return void 0;
+    }).catch(() => {
+      if (current === generation) {
+        setUser(null);
+      }
+    });
+  };
+  client.onAuthTokenChange(refresh);
+  return {
+    getUser: () => user,
+    subscribe: (onChange) => {
+      listeners.add(onChange);
+      if (!started) {
+        started = true;
+        refresh();
+      }
+      return () => {
+        listeners.delete(onChange);
+      };
+    }
+  };
+};
+const getIdentityStore = (client) => {
+  let store = stores.get(client);
+  if (!store) {
+    store = createIdentityStore(client);
+    stores.set(client, store);
+  }
+  return store;
+};
+
+export { getIdentityStore };

package/dist/index.d.mts

@@ -0,0 +1,281 @@
+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';
+/**
+* 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
+* adapter needs. Matches `@react-native-async-storage/async-storage`'s core
+* surface, so you can pass the module straight in.
+*/
+interface AsyncStorageLike {
+  getItem: (key: string) => Promise<string | null>;
+  removeItem: (key: string) => Promise<void>;
+  setItem: (key: string, value: string) => Promise<void>;
+}
+interface AsyncStoragePersistenceOptions {
+  /** Storage key the FIFO mutation log is serialized under; defaults to `"lunora:offline-mutations"`. */
+  key?: string;
+  /** The async key/value store the log is read from and written to (e.g. React Native `AsyncStorage`). */
+  storage: AsyncStorageLike;
+}
+/**
+* Builds a {@link PersistenceAdapter} over an async key/value store — the React
+* Native / Expo counterpart to the IndexedDB adapter (`createIndexedDbPersistence`).
+* The whole FIFO mutation log is serialized to JSON under a single key (`key`),
+* so enqueue order is preserved and `load()` returns freshly-parsed records that
+* callers can't alias.
+*
+* AsyncStorage has no transactions, so every read-modify-write is funnelled
+* through a single promise chain — concurrent `append`/`remove` calls run one at
+* a time and can't clobber each other's writes.
+*/
+declare const createAsyncStoragePersistence: (options: AsyncStoragePersistenceOptions) => PersistenceAdapter;
+/** Default in-memory bookmark store. Survives the lifetime of the client. */
+declare const createInMemoryBookmarkStorage: () => BookmarkStorage;
+/**
+* Client-side incremental merging of structured mutation deltas.
+*
+* Lunora's live-query fan-out has two server paths:
+*
+* 1. Server re-execution (subscriptions carrying a `functionPath`) pushes a
+* full `data` snapshot whenever a write touches a table the query reads. These
+* already carry the authoritative result and are applied wholesale.
+* 2. Legacy delta fan-out (`broadcastDelta`) pushes a structured `MutationDelta`
+* as a `delta` frame to subscribers matched by table + args. The delta describes
+* a single row change (`insert` / `update` / `delete`) keyed by row id, so the
+* client can splice it into the cached list result without a full re-send.
+*
+* Historically the client treated the `delta` field as an opaque blob and
+* replaced the whole cached value with it on every message — which only made
+* sense for the rare delta payloads that already carried the full result. This
+* module lets the client recognise a structured delta and merge it into the
+* existing array (preserving order, no dup/loss), falling back to full
+* replacement when the payload isn't a recognisable row delta or can't be
+* applied cleanly against the current cached shape.
+*/
+/**
+* One row change as emitted by `@lunora/do`'s `broadcastDelta`. Mirrors
+* `MutationDelta` in `@lunora/do` structurally so the client carries no
+* dependency on it. `row` is absent on `delete` events (and may be absent on
+* older servers for any op).
+*/
+interface MutationDelta {
+  /** Row id (`_id`) the change applies to. */
+  key: string;
+  op: "delete" | "insert" | "update";
+  row?: Record<string, unknown>;
+  table: string;
+}
+/**
+* Structural guard: is `value` a `MutationDelta` the client knows how to merge?
+* We require `op`, `table`, and a string `key` so opaque payloads that merely
+* happen to be objects (e.g. an aggregate `{ count: 1 }` a query returns
+* verbatim) are never mistaken for a row delta and keep replacing the cached
+* value wholesale.
+*/
+declare const isMutationDelta: (value: unknown) => value is MutationDelta;
+/**
+* Apply a structured `MutationDelta` to a cached array result, returning a new
+* array (never mutating the input). Returns `undefined` when the delta can't be
+* applied cleanly — the caller should then fall back to the existing
+* full-replacement behaviour (or trust the next snapshot to reconcile).
+*
+* Mergeable shape: a plain array of id-bearing row objects, e.g. the result of
+* `db.query().collect()`.
+*
+* Insert / update / delete are matched by row `_id`:
+* - `insert`: appended (or placed by `_creationTime` order) if absent; treated
+* as an update if a row with the same id already exists (idempotent — guards
+* against a delta replayed after a snapshot already included it).
+* - `update`: replaces the matching row in place, preserving its position.
+* - `delete`: removes the matching row.
+*
+* Returns `undefined` when `current` isn't an array of id-keyable objects, or
+* 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>>;
+}
+/**
+* Reactive sinks an adapter binds to its own primitive's setters (a Solid
+* signal, a Vue ref, a Svelte store). The runner pushes into them; how they
+* store the value is the adapter's concern (e.g. Solid wraps function-valued
+* results in a thunk).
+*/
+interface MutationRunnerSinks<R> {
+  /** Receives the normalized {@link Error} when an invocation rejects. */
+  setError: (error: Error) => void;
+  /** Receives `true` while at least one invocation is in flight (ref-counted across overlapping calls), else `false`. */
+  setPending: (pending: boolean) => void;
+  /** Receives the resolved value when an invocation succeeds. */
+  setResult: (result: R) => void;
+}
+/**
+* Build the framework-neutral `mutate` half of an adapter's mutation hook.
+*
+* Owns the orchestration every adapter otherwise copy-pastes: ref-counts
+* overlapping invocations into `setPending` (so it only clears once the last
+* settles), normalizes a thrown non-`Error`, and routes success/failure to
+* `setResult`/`setError` before re-throwing. Each adapter (`@lunora/react`,
+* `/solid`, `/svelte`, `/vue`) binds the three sinks to its own reactive
+* setters, so this logic lives in exactly one place. Optimistic-update options
+* 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>>);
+interface QueuedMutation<T = unknown> {
+  readonly args: Record<string, unknown>;
+  readonly functionPath: string;
+  /** Stable id used to remove the entry from durable storage once replayed; assigned by the queue when absent. */
+  id?: string;
+  /**
+  * Issuing identity fingerprint carried through to durable storage (`null` =
+  * signed out). Absent on hydrated legacy records, which replay ambiently.
+  */
+  readonly identity?: string | null;
+  /** 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;
+}
+/**
+* Bounded FIFO queue. Mutations issued while the client is offline are
+* enqueued and replayed in the order they were submitted once the WS
+* reconnects and identifies. If the queue exceeds `maxItems` the oldest
+* entry is rejected with `OFFLINE_QUEUE_OVERFLOW`.
+*
+* When a {@link PersistenceAdapter} is supplied, enqueued mutations are mirrored
+* to durable storage so they survive a reload — {@link OfflineQueue.hydrate} restores them on
+* the next startup and the client replays them on reconnect. Durable removal is
+* the caller's responsibility *after* a successful replay (see `LunoraClient`);
+* the queue only persists on enqueue and un-persists on overflow.
+*/
+declare class OfflineQueue {
+  /** Opt-in to queueing mutations before the targeted shard's first connect. */
+  readonly queueBeforeFirstConnect: boolean;
+  private readonly maxItems;
+  private readonly onPersistenceError;
+  private readonly persistence;
+  private readonly items;
+  constructor(options?: OfflineQueueOptions, persistence?: PersistenceAdapter);
+  get size(): number;
+  enqueue<T>(entry: QueuedMutation<T>): void;
+  /**
+  * Restore mutations persisted in a prior session and re-queue them in FIFO
+  * order. Restored entries already live in durable storage, so they are not
+  * re-appended; they carry no-op `resolve`/`reject` (the original awaiter is
+  * gone after a reload). No-op when no persistence adapter is configured.
+  * Returns the distinct shard keys of the restored writes so the caller can
+  * open their sockets to trigger a flush.
+  */
+  hydrate(): Promise<(string | undefined)[]>;
+  /**
+  * Remove and return queued mutations. With no `predicate`, drains the whole
+  * queue. With one, drains only matching entries (preserving FIFO order) and
+  * leaves the rest queued — used to flush a single shard's writes when its
+  * socket reconnects while other shards are still down.
+  */
+  drain(predicate?: (item: QueuedMutation) => boolean): QueuedMutation[];
+  /**
+  * Return previously-drained mutations to the front of the queue, preserving
+  * their FIFO order, without re-persisting them — they were never unpersisted,
+  * so durable storage still holds them. Used when a flush aborts on a transient
+  * transport failure: the unreplayed writes stay queued for the next reconnect.
+  */
+  requeue(items: QueuedMutation[]): void;
+  clear(): void;
+}
+/**
+* In-memory {@link PersistenceAdapter}. Doesn't survive a reload — it exists so
+* the persistence wiring can be exercised without IndexedDB (tests, SSR, or as
+* a deliberate "no durable store" choice that still satisfies the interface).
+* Preserves enqueue order; `clone` keeps callers from mutating stored args.
+*/
+declare const createInMemoryPersistence: () => PersistenceAdapter;
+interface IndexedDbPersistenceOptions {
+  /** Database name; defaults to `"lunora"`. */
+  databaseName?: string;
+  /** Injectable `IDBFactory` (e.g. `fake-indexeddb` in tests); defaults to the global `indexedDB`. */
+  indexedDB?: IDBFactory;
+  /** Object-store name; defaults to `"offline-mutations"`. */
+  storeName?: string;
+}
+/**
+* IndexedDB-backed {@link PersistenceAdapter}. Each mutation is stored under an
+* autoincrementing key (so `load()` returns them in enqueue order regardless of
+* the string ids) with a unique secondary index on `id` for `remove()`.
+*
+* The store handle is opened lazily and the open promise is cached, so repeated
+* ops reuse one connection. Throws eagerly if no `IDBFactory` is available —
+* callers in non-browser environments should use {@link createInMemoryPersistence}.
+*/
+declare const createIndexedDbPersistence: (options?: IndexedDbPersistenceOptions) => PersistenceAdapter;
+/**
+* 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
+* root shard) exactly as the registry does.
+*/
+declare const queryCacheKey: (functionPath: string, argsKey: string, shardKey?: string) => string;
+/**
+* In-memory {@link QueryCacheAdapter}. Doesn't survive a reload — it exists so
+* the read-cache wiring can be exercised without IndexedDB (tests, SSR, or as a
+* deliberate "no durable store" choice that still satisfies the interface).
+* Enforces the same LRU row cap as the IndexedDB adapter; `clone` keeps callers
+* from mutating stored values.
+*/
+declare const createInMemoryQueryCache: (options?: {
+  maxEntries?: number;
+}) => QueryCacheAdapter;
+interface IndexedDbQueryCacheOptions {
+  /** Database name; defaults to `"lunora"` (shared with the offline-mutation store). */
+  databaseName?: string;
+  /** Injectable `IDBFactory` (e.g. `fake-indexeddb` in tests); defaults to the global `indexedDB`. */
+  indexedDB?: IDBFactory;
+  /** LRU row cap; defaults to 500. The oldest rows by `ts` are pruned on `put` once exceeded. */
+  maxEntries?: number;
+  /** Object-store name; defaults to `"query-cache"`. */
+  storeName?: string;
+}
+/**
+* IndexedDB-backed {@link QueryCacheAdapter}. Each query is stored under its
+* composite key (`functionPath::argsKey::shardKey`) with a `ts` index driving
+* 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}.
+*/
+declare const createIndexedDbQueryCache: (options?: IndexedDbQueryCacheOptions) => QueryCacheAdapter;
+/**
+* Exponential backoff calculator with optional jitter.
+*
+* `next()` doubles the delay each call up to `maxDelayMs`. When `jitter` is
+* enabled the returned value is randomized in `[delay/2, delay]` so a fleet
+* of clients reconnecting at the same time spread out their retries.
+*/
+interface ReconnectCalculator {
+  /** Returns the delay to wait before the next reconnect attempt. */
+  next: () => number;
+  /** Resets the backoff to the initial delay (call on successful reconnect). */
+  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 };

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+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';
+/**
+* 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
+* adapter needs. Matches `@react-native-async-storage/async-storage`'s core
+* surface, so you can pass the module straight in.
+*/
+interface AsyncStorageLike {
+  getItem: (key: string) => Promise<string | null>;
+  removeItem: (key: string) => Promise<void>;
+  setItem: (key: string, value: string) => Promise<void>;
+}
+interface AsyncStoragePersistenceOptions {
+  /** Storage key the FIFO mutation log is serialized under; defaults to `"lunora:offline-mutations"`. */
+  key?: string;
+  /** The async key/value store the log is read from and written to (e.g. React Native `AsyncStorage`). */
+  storage: AsyncStorageLike;
+}
+/**
+* Builds a {@link PersistenceAdapter} over an async key/value store — the React
+* Native / Expo counterpart to the IndexedDB adapter (`createIndexedDbPersistence`).
+* The whole FIFO mutation log is serialized to JSON under a single key (`key`),
+* so enqueue order is preserved and `load()` returns freshly-parsed records that
+* callers can't alias.
+*
+* AsyncStorage has no transactions, so every read-modify-write is funnelled
+* through a single promise chain — concurrent `append`/`remove` calls run one at
+* a time and can't clobber each other's writes.
+*/
+declare const createAsyncStoragePersistence: (options: AsyncStoragePersistenceOptions) => PersistenceAdapter;
+/** Default in-memory bookmark store. Survives the lifetime of the client. */
+declare const createInMemoryBookmarkStorage: () => BookmarkStorage;
+/**
+* Client-side incremental merging of structured mutation deltas.
+*
+* Lunora's live-query fan-out has two server paths:
+*
+* 1. Server re-execution (subscriptions carrying a `functionPath`) pushes a
+* full `data` snapshot whenever a write touches a table the query reads. These
+* already carry the authoritative result and are applied wholesale.
+* 2. Legacy delta fan-out (`broadcastDelta`) pushes a structured `MutationDelta`
+* as a `delta` frame to subscribers matched by table + args. The delta describes
+* a single row change (`insert` / `update` / `delete`) keyed by row id, so the
+* client can splice it into the cached list result without a full re-send.
+*
+* Historically the client treated the `delta` field as an opaque blob and
+* replaced the whole cached value with it on every message — which only made
+* sense for the rare delta payloads that already carried the full result. This
+* module lets the client recognise a structured delta and merge it into the
+* existing array (preserving order, no dup/loss), falling back to full
+* replacement when the payload isn't a recognisable row delta or can't be
+* applied cleanly against the current cached shape.
+*/
+/**
+* One row change as emitted by `@lunora/do`'s `broadcastDelta`. Mirrors
+* `MutationDelta` in `@lunora/do` structurally so the client carries no
+* dependency on it. `row` is absent on `delete` events (and may be absent on
+* older servers for any op).
+*/
+interface MutationDelta {
+  /** Row id (`_id`) the change applies to. */
+  key: string;
+  op: "delete" | "insert" | "update";
+  row?: Record<string, unknown>;
+  table: string;
+}
+/**
+* Structural guard: is `value` a `MutationDelta` the client knows how to merge?
+* We require `op`, `table`, and a string `key` so opaque payloads that merely
+* happen to be objects (e.g. an aggregate `{ count: 1 }` a query returns
+* verbatim) are never mistaken for a row delta and keep replacing the cached
+* value wholesale.
+*/
+declare const isMutationDelta: (value: unknown) => value is MutationDelta;
+/**
+* Apply a structured `MutationDelta` to a cached array result, returning a new
+* array (never mutating the input). Returns `undefined` when the delta can't be
+* applied cleanly — the caller should then fall back to the existing
+* full-replacement behaviour (or trust the next snapshot to reconcile).
+*
+* Mergeable shape: a plain array of id-bearing row objects, e.g. the result of
+* `db.query().collect()`.
+*
+* Insert / update / delete are matched by row `_id`:
+* - `insert`: appended (or placed by `_creationTime` order) if absent; treated
+* as an update if a row with the same id already exists (idempotent — guards
+* against a delta replayed after a snapshot already included it).
+* - `update`: replaces the matching row in place, preserving its position.
+* - `delete`: removes the matching row.
+*
+* Returns `undefined` when `current` isn't an array of id-keyable objects, or
+* 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>>;
+}
+/**
+* Reactive sinks an adapter binds to its own primitive's setters (a Solid
+* signal, a Vue ref, a Svelte store). The runner pushes into them; how they
+* store the value is the adapter's concern (e.g. Solid wraps function-valued
+* results in a thunk).
+*/
+interface MutationRunnerSinks<R> {
+  /** Receives the normalized {@link Error} when an invocation rejects. */
+  setError: (error: Error) => void;
+  /** Receives `true` while at least one invocation is in flight (ref-counted across overlapping calls), else `false`. */
+  setPending: (pending: boolean) => void;
+  /** Receives the resolved value when an invocation succeeds. */
+  setResult: (result: R) => void;
+}
+/**
+* Build the framework-neutral `mutate` half of an adapter's mutation hook.
+*
+* Owns the orchestration every adapter otherwise copy-pastes: ref-counts
+* overlapping invocations into `setPending` (so it only clears once the last
+* settles), normalizes a thrown non-`Error`, and routes success/failure to
+* `setResult`/`setError` before re-throwing. Each adapter (`@lunora/react`,
+* `/solid`, `/svelte`, `/vue`) binds the three sinks to its own reactive
+* setters, so this logic lives in exactly one place. Optimistic-update options
+* 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>>);
+interface QueuedMutation<T = unknown> {
+  readonly args: Record<string, unknown>;
+  readonly functionPath: string;
+  /** Stable id used to remove the entry from durable storage once replayed; assigned by the queue when absent. */
+  id?: string;
+  /**
+  * Issuing identity fingerprint carried through to durable storage (`null` =
+  * signed out). Absent on hydrated legacy records, which replay ambiently.
+  */
+  readonly identity?: string | null;
+  /** 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;
+}
+/**
+* Bounded FIFO queue. Mutations issued while the client is offline are
+* enqueued and replayed in the order they were submitted once the WS
+* reconnects and identifies. If the queue exceeds `maxItems` the oldest
+* entry is rejected with `OFFLINE_QUEUE_OVERFLOW`.
+*
+* When a {@link PersistenceAdapter} is supplied, enqueued mutations are mirrored
+* to durable storage so they survive a reload — {@link OfflineQueue.hydrate} restores them on
+* the next startup and the client replays them on reconnect. Durable removal is
+* the caller's responsibility *after* a successful replay (see `LunoraClient`);
+* the queue only persists on enqueue and un-persists on overflow.
+*/
+declare class OfflineQueue {
+  /** Opt-in to queueing mutations before the targeted shard's first connect. */
+  readonly queueBeforeFirstConnect: boolean;
+  private readonly maxItems;
+  private readonly onPersistenceError;
+  private readonly persistence;
+  private readonly items;
+  constructor(options?: OfflineQueueOptions, persistence?: PersistenceAdapter);
+  get size(): number;
+  enqueue<T>(entry: QueuedMutation<T>): void;
+  /**
+  * Restore mutations persisted in a prior session and re-queue them in FIFO
+  * order. Restored entries already live in durable storage, so they are not
+  * re-appended; they carry no-op `resolve`/`reject` (the original awaiter is
+  * gone after a reload). No-op when no persistence adapter is configured.
+  * Returns the distinct shard keys of the restored writes so the caller can
+  * open their sockets to trigger a flush.
+  */
+  hydrate(): Promise<(string | undefined)[]>;
+  /**
+  * Remove and return queued mutations. With no `predicate`, drains the whole
+  * queue. With one, drains only matching entries (preserving FIFO order) and
+  * leaves the rest queued — used to flush a single shard's writes when its
+  * socket reconnects while other shards are still down.
+  */
+  drain(predicate?: (item: QueuedMutation) => boolean): QueuedMutation[];
+  /**
+  * Return previously-drained mutations to the front of the queue, preserving
+  * their FIFO order, without re-persisting them — they were never unpersisted,
+  * so durable storage still holds them. Used when a flush aborts on a transient
+  * transport failure: the unreplayed writes stay queued for the next reconnect.
+  */
+  requeue(items: QueuedMutation[]): void;
+  clear(): void;
+}
+/**
+* In-memory {@link PersistenceAdapter}. Doesn't survive a reload — it exists so
+* the persistence wiring can be exercised without IndexedDB (tests, SSR, or as
+* a deliberate "no durable store" choice that still satisfies the interface).
+* Preserves enqueue order; `clone` keeps callers from mutating stored args.
+*/
+declare const createInMemoryPersistence: () => PersistenceAdapter;
+interface IndexedDbPersistenceOptions {
+  /** Database name; defaults to `"lunora"`. */
+  databaseName?: string;
+  /** Injectable `IDBFactory` (e.g. `fake-indexeddb` in tests); defaults to the global `indexedDB`. */
+  indexedDB?: IDBFactory;
+  /** Object-store name; defaults to `"offline-mutations"`. */
+  storeName?: string;
+}
+/**
+* IndexedDB-backed {@link PersistenceAdapter}. Each mutation is stored under an
+* autoincrementing key (so `load()` returns them in enqueue order regardless of
+* the string ids) with a unique secondary index on `id` for `remove()`.
+*
+* The store handle is opened lazily and the open promise is cached, so repeated
+* ops reuse one connection. Throws eagerly if no `IDBFactory` is available —
+* callers in non-browser environments should use {@link createInMemoryPersistence}.
+*/
+declare const createIndexedDbPersistence: (options?: IndexedDbPersistenceOptions) => PersistenceAdapter;
+/**
+* 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
+* root shard) exactly as the registry does.
+*/
+declare const queryCacheKey: (functionPath: string, argsKey: string, shardKey?: string) => string;
+/**
+* In-memory {@link QueryCacheAdapter}. Doesn't survive a reload — it exists so
+* the read-cache wiring can be exercised without IndexedDB (tests, SSR, or as a
+* deliberate "no durable store" choice that still satisfies the interface).
+* Enforces the same LRU row cap as the IndexedDB adapter; `clone` keeps callers
+* from mutating stored values.
+*/
+declare const createInMemoryQueryCache: (options?: {
+  maxEntries?: number;
+}) => QueryCacheAdapter;
+interface IndexedDbQueryCacheOptions {
+  /** Database name; defaults to `"lunora"` (shared with the offline-mutation store). */
+  databaseName?: string;
+  /** Injectable `IDBFactory` (e.g. `fake-indexeddb` in tests); defaults to the global `indexedDB`. */
+  indexedDB?: IDBFactory;
+  /** LRU row cap; defaults to 500. The oldest rows by `ts` are pruned on `put` once exceeded. */
+  maxEntries?: number;
+  /** Object-store name; defaults to `"query-cache"`. */
+  storeName?: string;
+}
+/**
+* IndexedDB-backed {@link QueryCacheAdapter}. Each query is stored under its
+* composite key (`functionPath::argsKey::shardKey`) with a `ts` index driving
+* 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}.
+*/
+declare const createIndexedDbQueryCache: (options?: IndexedDbQueryCacheOptions) => QueryCacheAdapter;
+/**
+* Exponential backoff calculator with optional jitter.
+*
+* `next()` doubles the delay each call up to `maxDelayMs`. When `jitter` is
+* enabled the returned value is randomized in `[delay/2, delay]` so a fleet
+* of clients reconnecting at the same time spread out their retries.
+*/
+interface ReconnectCalculator {
+  /** Returns the delay to wait before the next reconnect attempt. */
+  next: () => number;
+  /** Resets the backoff to the initial delay (call on successful reconnect). */
+  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 };