@lunora/client 0.0.0 → 1.0.0-alpha.2

package/dist/packem_shared/lunora-client.d-DGvyuJ_p.d.ts

@@ -0,0 +1,1597 @@
+import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthSession } from '@lunora/runtime';
+/** 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";
+/**
+* Opaque reference to a registered function emitted by `@lunora/codegen`.
+*
+* At runtime it carries the `<file>:<function>` identifier in `__lunoraRef`.
+* Generated declarations decorate this with phantom type parameters so the
+* client can infer args / return values per call site.
+*/
+interface FunctionReference<Kind extends FunctionKind = FunctionKind, Args = unknown, Return = unknown> {
+  /**
+  * Phantom marker carrying the `Kind`/`Args`/`Return` type parameters for
+  * inference. Never present at runtime; declared as a covariant (output)
+  * position so a concrete reference stays assignable to a widened one.
+  */
+  readonly __lunoraPhantom?: {
+    args: Args;
+    kind: Kind;
+    returns: Return;
+  };
+  readonly __lunoraRef: string;
+}
+/** Extract the args type from a {@link FunctionReference}. */
+type ArgsOf<F> = F extends FunctionReference<infer _K, infer A, infer _R> ? A : never;
+/** Extract the return type from a {@link FunctionReference}. */
+type ReturnOf<F> = F extends FunctionReference<infer _K, infer _A, infer R> ? R : never;
+type Unsubscribe = () => void;
+/**
+* Serializable result of `preloadQuery`. Produced on the server during SSR,
+* embedded in the rendered HTML, then handed to `usePreloadedQuery` on the
+* client so the first render shows the server value with no loading flash
+* before a live subscription attaches. Every field survives `JSON.stringify`.
+*/
+interface Preloaded<T = unknown> {
+  readonly __lunoraPreloaded: true;
+  readonly args: Record<string, unknown>;
+  readonly functionPath: string;
+  readonly shardKey?: string;
+  readonly value: T;
+}
+/**
+* Pluggable storage for the `x-d1-bookmark` value used to provide
+* read-your-writes between a mutation and subsequent queries.
+*/
+interface BookmarkStorage {
+  get: () => string | null;
+  set: (value: string | null) => void;
+}
+interface ReconnectOptions {
+  initialDelayMs?: number;
+  jitter?: boolean;
+  maxDelayMs?: number;
+}
+/** Which durable-storage operation failed, passed to {@link OfflineQueueOptions.onPersistenceError}. */
+type PersistenceOperation = "append" | "clear" | "load" | "remove";
+/** Context handed to a persistence-error handler. */
+interface PersistenceErrorContext {
+  readonly error: unknown;
+  /** The mutation id involved, when the failing op was scoped to one (`append`/`remove`). */
+  readonly mutationId?: string;
+  readonly operation: PersistenceOperation;
+}
+interface OfflineQueueOptions {
+  maxItems?: number;
+  /**
+  * Invoked when a {@link PersistenceAdapter} call rejects (e.g. IndexedDB quota
+  * exceeded). Without a handler, failures are logged via `console.warn` so they
+  * are never fully silent. Note: a failed `append` means the write is queued in
+  * memory but NOT durable — it will not survive a reload.
+  */
+  onPersistenceError?: (context: PersistenceErrorContext) => void;
+  /**
+  * Queue mutations issued before a shard's first successful WebSocket
+  * connect (defaults to `false`). The standard behaviour (`LunoraClient`'s
+  * `mutation()`) queues only when the targeted shard has been connected at
+  * least once (`wasEverConnected`), so the registry / resubscribe handshake
+  * has run. Set this to `true` for offline-first apps that want to enqueue
+  * writes on the very first session before the WS is up.
+  */
+  queueBeforeFirstConnect?: boolean;
+}
+/**
+* Serializable shape of an offline mutation, durably stored by a
+* {@link PersistenceAdapter} so queued writes survive a reload/crash. The live
+* `resolve`/`reject` callbacks of an in-flight `QueuedMutation` are *not*
+* persisted — a restored mutation is replayed with no original awaiter.
+*/
+interface PersistedMutation {
+  args: Record<string, unknown>;
+  functionPath: string;
+  id: string;
+  /**
+  * Issuing identity fingerprint, persisted so a hydrated write replays only
+  * under the identity that queued it (`null` = queued while signed out).
+  * Absent on records written by older client versions, which replay under
+  * the ambient identity for back-compat.
+  */
+  identity?: string | null;
+  shardKey?: string;
+}
+/**
+* Durable store for the offline mutation queue. The default client keeps the
+* queue in memory; supplying an adapter (e.g. `createIndexedDbPersistence`)
+* makes queued writes survive a page reload. Implementations must preserve FIFO
+* (enqueue) order in `PersistenceAdapter.load`.
+*
+* Replay semantics are at-least-once: a mutation is removed only after the
+* server confirms (or rejects) it, so a crash between commit and `remove` can
+* replay it again on the next load.
+*/
+interface PersistenceAdapter {
+  /** Append a mutation to durable storage (called on enqueue). */
+  append: (mutation: PersistedMutation) => Promise<void>;
+  /** Drop every persisted mutation (e.g. on logout). */
+  clear: () => Promise<void>;
+  /** Load all persisted mutations in FIFO order — called once at startup. */
+  load: () => Promise<PersistedMutation[]>;
+  /** Remove a mutation by id once it has been replayed (resolved or rejected). */
+  remove: (id: string) => 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.
+*/
+interface CachedQuery {
+  /**
+  * Issuing identity fingerprint (same shape the offline queue stamps). A
+  * cached value only hydrates when it matches the current identity, so a
+  * signed-out cache never leaks into a new session. `null` = cached while
+  * signed out.
+  */
+  identity: string | null;
+  /**
+  * The `cursor` high-watermark this value reflects, replayed as `sinceSeq`
+  * on reconnect so the server can resume instead of re-snapshotting. Absent
+  * when the value predates CDC / no cursor was advertised.
+  */
+  serverCursor?: number;
+  /**
+  * The CDC `epoch` the `serverCursor` belongs to, replayed as `sinceEpoch`
+  * on reconnect so the server only resumes when the client is still on the
+  * same changelog timeline. Absent when no epoch was advertised.
+  */
+  serverEpoch?: string;
+  /** Wall-clock millis the value was written — drives LRU eviction. */
+  ts: number;
+  /** The full query result last seen from the server. */
+  value: unknown;
+}
+/**
+* Durable store for the client read cache (Pillar 2): query results survive a
+* reload so reads hydrate from disk and render immediately while the socket
+* reconnects. Opt-in via {@link LunoraClientOptions.queryCache}; omit to keep
+* reads in memory only (today's behaviour). Mirrors {@link PersistenceAdapter}'s
+* shape over the same IndexedDB plumbing.
+*/
+interface QueryCacheAdapter {
+  /** Drop every cached query (e.g. on logout / identity change). */
+  clear: () => Promise<void>;
+  /** Load every cached query — called once at startup to hydrate reads. */
+  load: () => Promise<(CachedQuery & {
+    key: string;
+  })[]>;
+  /** Upsert one cached query by key (called when a subscription value advances). */
+  put: (key: string, entry: CachedQuery) => Promise<void>;
+  /** Remove one cached query by key. */
+  remove: (key: string) => Promise<void>;
+}
+interface LunoraClientOptions {
+  /**
+  * Base path the worker mounts better-auth at, used by the client's
+  * `getCurrentUser()` to reach the `get-session` route. Defaults to
+  * `/api/auth` (matching `@lunora/auth`'s `DEFAULT_AUTH_BASE_PATH`).
+  */
+  authBasePath?: string;
+  bookmarkStorage?: BookmarkStorage;
+  /**
+  * 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
+  * `setConnectionContext` overrides this for that shard. Omit when no lifecycle
+  * hook needs connection context.
+  */
+  connectionContext?: Record<string, unknown>;
+  fetch?: typeof fetch;
+  /**
+  * Interval (ms) between keepalive pings sent on each open subscription
+  * socket. The server answers them via the Durable Object's hibernation
+  * auto-response WITHOUT waking the DO, so an idle socket stays alive across
+  * hibernation without a billable wakeup. Defaults to 30000 (30s); set to
+  * `0` (or a negative value) to disable the heartbeat entirely.
+  */
+  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
+  * 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.
+  */
+  queryCache?: QueryCacheAdapter | false;
+  reconnect?: ReconnectOptions;
+  url: string;
+  WebSocket?: typeof WebSocket;
+  /**
+  * Token appended to the WebSocket URL as `?token=…`. The server matches it
+  * against `LUNORA_WS_BEARER` (to clear the upgrade gate) and/or
+  * `LUNORA_ADMIN_TOKEN` (to authorize `__lunora_admin__:*` subscriptions —
+  * what the studio sets it to). Browsers can't set headers on the
+  * `WebSocket` constructor, so the query parameter is the only channel; it
+  * ends up in server logs and history, so prefer a short-lived rotating
+  * token in production.
+  */
+  wsToken?: string;
+  wsUrl?: string;
+}
+/** Wire envelope sent on `POST /_lunora/rpc`. */
+interface RpcEnvelope {
+  args?: Record<string, unknown>;
+  functionPath: string;
+  shardKey?: string;
+}
+/** Wire response from the shard's `/rpc` endpoint (forwarded by the runtime). */
+type RpcResponseBody = {
+  result: unknown;
+} | {
+  error: {
+    code: string;
+    message: string;
+  };
+};
+/** Subscription protocol — client → server. */
+interface ClientSubscribeMessage {
+  id: string;
+  /**
+  * `sinceSeq` is the persisted `cursor` high-watermark the client last saw
+  * for this shard (Pillar 1b resume). Present only when a durable
+  * {@link QueryCacheAdapter} restored a cached value with a cursor; the
+  * server replies with a lightweight `resume` frame instead of a full
+  * snapshot when nothing the query reads changed since it. Absent on a
+  * first-time subscribe.
+  */
+  query: {
+    args?: Record<string, unknown>;
+    functionPath?: string;
+    sinceEpoch?: string;
+    sinceSeq?: number;
+    table?: string;
+  };
+  type: "subscribe";
+}
+interface ClientUnsubscribeMessage {
+  id: string;
+  type: "unsubscribe";
+}
+/**
+* One-shot control frame sent right after the socket opens. Registers the
+* connection's app `context` (e.g. `{ roomId, sessionId }`) with the server and
+* fires the `onConnect` lifecycle hooks; the same context is replayed to
+* `onDisconnect` when the socket drops.
+*/
+interface ClientConnectMessage {
+  context?: Record<string, unknown>;
+  id: string;
+  type: "connect";
+}
+interface ClientAckMessage {
+  id: string;
+  type: "ack";
+}
+/**
+* Start a streaming query. The id namespaces a fresh stream and is echoed on
+* every {@link ServerChunkMessage} the server pushes back. Cancel a running
+* stream by sending a {@link ClientUnsubscribeMessage} with the same id —
+* subscription and stream id-spaces share the cancel channel; the prefix
+* (`sub_*` vs `stream_*`) keeps the local registries searchable.
+*/
+interface ClientStreamMessage {
+  id: string;
+  query: {
+    args?: Record<string, unknown>;
+    functionPath: string;
+    shardKey?: string;
+  };
+  type: "stream";
+}
+/**
+* Join or leave a whisper `topic` — an app-chosen ephemeral channel scoped to a
+* shard. While joined, the client receives every {@link ServerWhisperMessage}
+* other members broadcast to the topic.
+*/
+interface ClientWhisperSubscribeMessage {
+  topic: string;
+  type: "whisper_subscribe" | "whisper_unsubscribe";
+}
+/**
+* Broadcast ephemeral `data` to the topic's other members on the shard. The
+* payload is relayed verbatim with no server-side persistence (no SQLite/CDC
+* write) — for typing indicators, live cursors, presence pings. The sender does
+* not receive its own whisper.
+*/
+interface ClientWhisperMessage {
+  data?: unknown;
+  topic: string;
+  type: "whisper";
+}
+type ClientMessage = ClientAckMessage | ClientConnectMessage | ClientStreamMessage | ClientSubscribeMessage | ClientUnsubscribeMessage | ClientWhisperMessage | ClientWhisperSubscribeMessage;
+/** Subscription protocol — server → client. */
+interface ServerDataMessage {
+  /**
+  * The `__cdc_log` high-watermark covered by this frame (Pillar 1b). The
+  * client persists it as the query's `serverCursor` and replays it as
+  * `sinceSeq` on the next reconnect. Absent on shards that never enabled CDC.
+  */
+  cursor?: number;
+  data?: unknown;
+  delta?: unknown;
+  /** The CDC epoch this frame's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
+  epoch?: string;
+  id: string;
+  type: "data" | "delta";
+}
+/**
+* Lightweight resume acknowledgement (Pillar 1b): the server determined that
+* nothing the subscription reads changed since the client's `sinceSeq`, so it
+* skips re-sending the snapshot. The client keeps its cached value and only
+* advances `serverCursor` to `cursor`.
+*/
+interface ServerResumeMessage {
+  cursor?: number;
+  /** The CDC epoch this resume's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
+  epoch?: string;
+  id: string;
+  type: "resume";
+}
+interface ServerErrorMessage {
+  error?: unknown;
+  id?: string;
+  message?: string;
+  type: "error";
+}
+interface ServerAckMessage {
+  id: string;
+  type: "ack";
+}
+interface ServerCompleteMessage {
+  id: string;
+  type: "complete";
+}
+/** One frame of a streaming query — `data` carries the user-yielded chunk. */
+interface ServerChunkMessage {
+  data: unknown;
+  id: string;
+  type: "chunk";
+}
+/**
+* An ephemeral whisper relayed from another member of `topic` on the same shard
+* (AnyCable-style whispering). `data` is the sender's payload verbatim; `from`
+* is the sender's verified user id when known (absent for an anonymous sender).
+* Never persisted server-side.
+*/
+interface ServerWhisperMessage {
+  data: unknown;
+  from?: string;
+  topic: string;
+  type: "whisper";
+}
+type ServerMessage = ServerAckMessage | ServerChunkMessage | ServerCompleteMessage | ServerDataMessage | ServerErrorMessage | ServerResumeMessage | ServerWhisperMessage;
+/**
+* The authenticated user as exposed client-side, mirroring better-auth's
+* `user` row (the `user` field of the `get-session` response). Kept minimal
+* and structural — only `id` is guaranteed; the rest are the common better-auth
+* fields, and the index signature carries any plugin-contributed extras.
+*/
+interface User {
+  readonly createdAt?: NullableTimestamp;
+  readonly email?: null | string;
+  readonly emailVerified?: boolean | null;
+  readonly id: string;
+  readonly image?: null | string;
+  readonly name?: null | string;
+  readonly [key: string]: unknown;
+  readonly updatedAt?: NullableTimestamp;
+}
+/**
+* One pending scheduled function, as returned by the worker's
+* `GET /_lunora/admin/scheduled` endpoint. Mirrors `@lunora/scheduler`'s
+* `ScheduleRecord` structurally so the client carries no dependency on it.
+*/
+interface ScheduleRecord {
+  args: Record<string, unknown>;
+  /**
+  * Dispatch attempts already made. Absent (treated as 0) until the first
+  * failure; on a dead-letter record it is the exhausted count (> the retry
+  * budget). Surfaced so the studio can show how hard a job tried before it
+  * was parked.
+  */
+  attempts?: number;
+  enqueuedAt: number;
+  functionPath: string;
+  id: string;
+  /** Logical workpool the job is routed to (concurrency-gated), when any. */
+  pool?: string;
+  scheduledFor: number;
+  shardKey?: string;
+}
+/**
+* One workpool's live backlog, as returned by the worker's
+* `GET /_lunora/admin/scheduled/status` endpoint. Mirrors `@lunora/scheduler`'s
+* `SchedulerPoolStatus` structurally so the client carries no dependency on it.
+*/
+interface SchedulerPoolStatus {
+  /** Jobs currently dispatched-but-not-yet-completed (the held concurrency slots). */
+  inFlight: number;
+  /** The pool's concurrency cap. */
+  maxConcurrency: number;
+  /** The logical workpool name. */
+  name: string;
+  /** Pending jobs routed to this pool but not yet dispatched. */
+  queued: number;
+}
+/**
+* The app-level scheduler backlog, as returned by the worker's
+* `GET /_lunora/admin/scheduled/status` endpoint. `pools` is the per-pool
+* breakdown; `backlog` and `inFlight` are the app-wide sums of `queued` and
+* `inFlight` across every pool — the headline numbers for the studio SLO
+* view. Mirrors `@lunora/scheduler`'s `SchedulerStatus` structurally.
+*/
+interface SchedulerStatus {
+  /** Sum of every pool's `queued` count — the total pending backlog. */
+  backlog: number;
+  /** Sum of every pool's `inFlight` count — the total held concurrency slots. */
+  inFlight: number;
+  /** Per-pool backlog breakdown. */
+  pools: SchedulerPoolStatus[];
+}
+/**
+* One shard's request volume, as returned by the worker's
+* `POST /_lunora/admin/shard-traffic` endpoint. The cross-shard traffic feed
+* the studio's `hot_shard` advisor lint consumes: `requests` is the shard's
+* lifetime dispatch total, `shardKey` the DO id name (`""` for the root shard).
+*/
+interface ShardTrafficEntry {
+  requests: number;
+  shardKey: string;
+}
+/**
+* The whole-shard-set traffic distribution returned by the worker's
+* `POST /_lunora/admin/shard-traffic` endpoint. `shards` is one entry per live
+* shard (a failed shard surfaces with `requests: 0`); `ok`/`failed` count the
+* shards that returned vs. errored. Shaped to feed the advisor's `hot_shard`
+* lint after the studio tags each entry with its sharded function `group`.
+*/
+interface ShardTrafficResult {
+  failed: number;
+  ok: number;
+  shards: ShardTrafficEntry[];
+}
+/**
+* One object in the storage bucket, as returned by the worker's
+* `GET /_lunora/admin/storage` endpoint. Mirrors `@lunora/storage`'s
+* `R2ObjectLike` structurally.
+*/
+interface StorageObject {
+  customMetadata?: Record<string, string>;
+  etag: string;
+  httpMetadata?: {
+    contentType?: string;
+  };
+  key: string;
+  size: number;
+  /**
+  * When the object was stored. R2 emits a `Date`, which JSON-serializes to an
+  * ISO string over the wire; a mock may supply epoch ms — so consumers should
+  * normalise via `new Date(uploaded)`. Absent if the backend didn't report it.
+  */
+  uploaded?: number | string;
+}
+/** One page of {@link StorageObject}s plus the cursor to fetch the next, if any. */
+interface StorageListPage {
+  cursor?: string;
+  objects: StorageObject[];
+}
+/**
+* One argument of a registered function, derived from its `v.*` validator by the
+* worker. A compact signature shape — enough to render a function's API without
+* the build-time codegen types.
+*/
+interface FunctionArgumentDescriptor {
+  /** Element validator kind for an `array` arg (one level), e.g. `string`. */
+  element?: string;
+  /** The (optional-unwrapped) validator kind, e.g. `string`, `id`, `object`. */
+  kind: string;
+  /** The argument name. */
+  name: string;
+  /** True when the arg is wrapped in `v.optional(...)`. */
+  optional: boolean;
+  /** Target table for an `id` arg (`v.id("table")`). */
+  table?: string;
+}
+/**
+* One registered function, as returned by the worker's
+* `GET /_lunora/admin/functions` endpoint: its `&lt;file>:&lt;function>` path, which
+* client method (`query` / `mutation` / `action`) invokes it, and its argument
+* signature. `args` is absent on responses from an older worker.
+*/
+interface FunctionDescriptor {
+  args?: FunctionArgumentDescriptor[];
+  kind: "action" | "mutation" | "query";
+  path: string;
+}
+/** A `.global()` (D1-backed) table plus its row count, from `/_lunora/admin/global/tables`. */
+interface GlobalTableInfo {
+  name: string;
+  rowCount: number;
+}
+/** A window of rows from one global table, from `/_lunora/admin/global/table`. */
+interface GlobalTablePage {
+  columns: string[];
+  /** FK columns (local column → referenced table) for external tables with real `REFERENCES` constraints, from `PRAGMA foreign_key_list`. */
+  refs?: Record<string, string>;
+  rows: Record<string, unknown>[];
+  total: number;
+}
+/**
+* One equality constraint a facet-value click adds to the global browser's view
+* (`column = value`). `value` is the raw stored scalar the facet returned, sent
+* as-is and bound server-side, so it never injects SQL.
+*/
+interface GlobalFilterClause {
+  column: string;
+  value: unknown;
+}
+/** One distinct value of a faceted global column with its row count, from `/_lunora/admin/global/facet`. */
+interface GlobalFacetValue {
+  count: number;
+  value: unknown;
+}
+/** Per-column distinct-value summary for the global browser, from `/_lunora/admin/global/facet`. */
+interface GlobalFacetResult {
+  truncated: boolean;
+  values: GlobalFacetValue[];
+}
+/** A nullable timestamp field as better-auth serializes it: epoch-ms, ISO string, or null. */
+type NullableTimestamp = null | number | string;
+/** A workflow instance's lifecycle status. Mirrors Cloudflare's `InstanceStatus`. */
+type WorkflowInstanceStatus = "complete" | "errored" | "paused" | "queued" | "running" | "terminated" | "unknown" | "waiting" | "waitingForPause";
+/** The lifecycle mutations the status endpoint accepts. */
+type WorkflowInstanceAction = "pause" | "resume" | "terminate";
+/** One row of the workflow-instances list. */
+interface WorkflowInstanceSummary {
+  createdOn?: string;
+  endedOn?: string;
+  id: string;
+  startedOn?: string;
+  status: WorkflowInstanceStatus;
+}
+/** One durable step of an instance's execution timeline. */
+interface WorkflowStepDetail {
+  /** 1-based attempt count (`> 1` means the step retried). */
+  attempts?: number;
+  end?: string;
+  error?: unknown;
+  name: string;
+  output?: unknown;
+  start?: string;
+  success?: boolean;
+  /** `step` / `sleep` / `waitForEvent` / … (Cloudflare's step `type`). */
+  type?: string;
+}
+/** A workflow instance's full detail: summary plus params/output/error and the step timeline. */
+interface WorkflowInstanceDetail extends WorkflowInstanceSummary {
+  error?: unknown;
+  output?: unknown;
+  params?: unknown;
+  steps: WorkflowStepDetail[];
+}
+/** A page of workflow instances. */
+interface WorkflowInstancePage {
+  instances: WorkflowInstanceSummary[];
+  page: number;
+  perPage: number;
+  totalCount?: number;
+}
+type SubscriptionCallback = (data: unknown) => void;
+/** A subscription-scoped error the server pushed for this subscription id. */
+interface SubscriptionError {
+  code?: string;
+  message: string;
+}
+type SubscriptionErrorCallback = (error: SubscriptionError) => void;
+interface SubscriptionState {
+  /** True once the server has acked the subscription on the current socket. */
+  acked: boolean;
+  readonly args: Record<string, unknown>;
+  /**
+  * Stable-stringified `args`, computed once at subscribe time. Cached so the
+  * optimistic-update fan-out can compare against a mutation's args key without
+  * re-serializing every subscription's args on every mutation.
+  */
+  readonly argsKey: string;
+  readonly callbacks: Set<SubscriptionCallback>;
+  /** Notified when the server rejects this subscription (e.g. admin auth). */
+  readonly errorCallbacks: Set<SubscriptionErrorCallback>;
+  readonly fn: FunctionReference;
+  readonly id: string;
+  /** Last known value, used to short-circuit `useQuery`-style consumers. */
+  lastValue: 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
+  * can resume instead of re-snapshotting (Pillar 1b/2). Absent until the
+  * first cursor-stamped frame arrives.
+  */
+  serverCursor?: number;
+  /**
+  * The CDC `epoch` token the `serverCursor` belongs to, captured from the
+  * same frame. Replayed as `sinceEpoch` on reconnect so the server resumes
+  * only when the client is still on the same changelog timeline — a reset or
+  * recycled shard advertises a new epoch, forcing a fresh snapshot. Absent
+  * 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.
+*/
+declare class SubscriptionRegistry {
+  static key(functionPath: string, args: Record<string, unknown>, shardKey?: string): string;
+  private readonly byKey;
+  private readonly byId;
+  get(key: string): SubscriptionState | undefined;
+  getById(id: string): SubscriptionState | undefined;
+  add(state: SubscriptionState): void;
+  remove(state: SubscriptionState): void;
+  all(): SubscriptionState[];
+}
+/**
+* Read/write handle over the client's live query cache, handed to a mutation's
+* `withOptimisticUpdate` callback so a single mutation can optimistically patch
+* 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
+* per-call `optimistic` transform uses, generalized to N queries.
+*/
+interface OptimisticLocalStore {
+  /**
+  * Every loaded subscription on `function_`, regardless of args, paired with
+  * the args it was subscribed under. Mirrors Convex's `getAllQueries` — handy
+  * when a write must patch every variant of a list query (all channels,
+  * all filters) without enumerating their args up front.
+  */
+  getAllQueries: <F extends FunctionReference>(function_: F) => {
+    args: ArgsOf<F>;
+    value: ReturnOf<F> | undefined;
+  }[];
+  /**
+  * Current cached value for the subscribed `(function_, args)` query, or
+  * `undefined` when nothing is subscribed/loaded for it. Reflects any
+  * optimistic override already written in this batch.
+  */
+  getQuery: <F extends FunctionReference>(function_: F, args: ArgsOf<F>) => ReturnOf<F> | undefined;
+  /**
+  * Write an optimistic override for the subscribed `(function_, args)`
+  * query. A no-op (returns without effect) when no subscription matches —
+  * mirroring Convex, where you only patch queries the page is watching.
+  */
+  setQuery: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, value: ReturnOf<F> | undefined) => void;
+}
+/** 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.
+*/
+declare const createLocalStore: (subscriptions: SubscriptionRegistry, shardKey: string | undefined, write: (state: SubscriptionState, next: unknown) => () => void, stableStringify: (value: unknown) => string) => {
+  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`. */
+  readonly complete: () => void;
+  /** Surface an error to any pending consumer; subsequent pushes are dropped. */
+  readonly fail: (error: Error) => void;
+  /**
+  * Push one chunk. Silent no-op once the stream is `complete`, `fail`-ed,
+  * or `cancel`-ed. When the buffer is already at `maxBuffer`, the stream
+  * is failed with a `STREAM_BACKPRESSURE` error and the push is dropped —
+  * the producer never sees a thrown exception.
+  */
+  readonly push: (value: T) => void;
+}
+interface StreamIterable<T> extends AsyncIterable<T> {
+  /** Cancel the stream from the consumer side: closes the iterator and notifies the registered canceller. */
+  cancel: () => void;
+}
+/**
+* Build a stream handle paired with an async-iterable. The handle is the
+* server-driven side (the WS dispatcher pushes chunks / completes / errors);
+* the iterable is what the user awaits. `onCancel` is invoked exactly once
+* when the consumer calls `.cancel()` (or `.return()`) so the client can
+* send a `{type:"unsubscribe"}` frame to the server.
+*/
+declare const createStream: <T>(options: {
+  maxBuffer?: number;
+  onCancel: () => void;
+}) => {
+  handle: StreamHandle<T>;
+  iterable: StreamIterable<T>;
+};
+/**
+* Aggregate live-socket health across every shard connection, for a UI status
+* indicator. `idle` = no socket opened yet; `connecting` = at least one socket
+* is (re)connecting and none is open; `connected` = at least one socket is open;
+* `offline` = sockets exist but all are down (between reconnect attempts).
+*/
+type ConnectionStatus = "connected" | "connecting" | "idle" | "offline";
+/**
+* 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
+* `mutate(args, options?)` against one canonical definition instead of
+* re-declaring it.
+*/
+interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unknown> {
+  optimistic?: (current: TCurrent | undefined) => TValue;
+  /**
+  * Convex-parity multi-query optimistic update. Receives an
+  * `OptimisticLocalStore` over the live subscription cache plus the
+  * mutation's args, so one mutation can patch many subscribed queries at
+  * once; every write is rolled back atomically if the mutation fails.
+  */
+  optimisticUpdate?: OptimisticUpdate<TArgs>;
+  shardKey?: string;
+}
+/**
+* Lunora browser/edge client. Talks RPC over HTTP and real-time deltas over
+* a single multiplexed WebSocket.
+*
+* Reconnect, offline queueing, and optimistic updates are all handled here;
+* see the package README for the wire protocol.
+*/
+declare class LunoraClient {
+  readonly url: string;
+  readonly wsUrl: string;
+  private wsToken;
+  /** Better-auth base path (trailing slash stripped) for the `get-session` lookup. */
+  private readonly authBasePath;
+  private readonly fetchImpl;
+  private readonly WebSocketImpl;
+  private readonly bookmark;
+  private readonly reconnectOptions;
+  /** Keepalive cadence (ms); `0` disables the heartbeat. See {@link LunoraClientOptions.heartbeatIntervalMs}. */
+  private readonly heartbeatIntervalMs;
+  private readonly offlineQueue;
+  private readonly onPersistenceError;
+  private readonly persistence;
+  /** Durable read cache (Pillar 2); `undefined` when `queryCache` is omitted or `false`. */
+  private readonly queryCache;
+  /**
+  * Values restored from the `queryCache` at construction, keyed by the
+  * read-cache key, awaiting the `subscribe()` that will consume them. A
+  * key is consumed (deleted) the first time its subscription is created, so
+  * the cache only ever seeds the initial value — live frames take over after.
+  */
+  private readonly hydratedQueryCache;
+  /**
+  * Coalesced read-cache writes: the latest value per key, flushed to
+  * the `queryCache` on a short debounce so a burst of deltas persists once.
+  */
+  private readonly pendingCacheWrites;
+  private cacheFlushTimer;
+  private readonly subscriptions;
+  /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
+  private readonly connections;
+  /** Default `connect`-envelope context applied to a shard with no explicit override. */
+  private readonly defaultConnectionContext;
+  /**
+  * Per-shard `connect`-envelope context registered via `setConnectionContext`
+  * (keyed by `shardKey ?? ""`), overriding `defaultConnectionContext`. Sent
+  * on every socket open so it replays across reconnects, and forwarded to the
+  * server's `onConnect`/`onDisconnect` lifecycle hooks. This holds only the
+  * imperative (last-writer-wins) override; refcounted holders registered via
+  * `acquireConnectionContext` live in `connectionContextHolders` and take
+  * precedence — see `effectiveConnectionContext`.
+  */
+  private readonly connectionContexts;
+  /**
+  * Per-shard stack of refcounted connection-context holders (keyed by
+  * `shardKey ?? ""`), registered via `acquireConnectionContext`. Each holder
+  * is an opaque token carrying its `context`; the most-recently acquired
+  * holder wins (last-writer-wins among live holders), and the context is only
+  * cleared for a shard once its last holder releases — so two concurrently
+  * mounted presence hooks on the same shard can't stomp each other's context
+  * on cleanup. A holder is identified by reference identity so a release
+  * removes exactly the right one regardless of stack position.
+  */
+  private readonly connectionContextHolders;
+  private authToken;
+  /**
+  * 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
+  * never replay under a different identity than the one that issued it.
+  * See `identityFingerprint` for the fingerprint shape.
+  */
+  private readonly queuedIdentities;
+  private closed;
+  /** Subscribers to auth-token changes (see `onAuthTokenChange`). */
+  private readonly authTokenListeners;
+  /** Subscribers to aggregate connection-status changes (see `onConnectionStatus`). */
+  private readonly statusListeners;
+  /** Subscribers notified when the server drops a socket for an expired token (see `onTokenExpired`). */
+  private readonly tokenExpiredListeners;
+  /**
+  * Whisper-topic handlers, keyed by `connectionKey(shardKey)` → topic → set
+  * of callbacks. Membership doubles as the resubscribe set replayed on every
+  * (re)connect so a topic survives a socket bounce.
+  */
+  private readonly whisperHandlers;
+  /** Last status broadcast, so we only notify listeners on an actual change. */
+  private lastStatus;
+  private nextSubId;
+  private nextStreamId;
+  /**
+  * In-flight client-side stream readers, keyed by the stream id sent on the
+  * wire. The handle drives the underlying iterator queue and `shardKey`
+  * tells us which socket to push the cancel frame onto when the consumer
+  * calls `.cancel()` or the iterator is garbage-collected.
+  */
+  private readonly streams;
+  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.
+  *
+  * 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;
+  getAuthToken(): string | null;
+  /**
+  * Subscribe to auth-token changes. Returns an unsubscribe function. The
+  * listener is NOT invoked on registration — use {@link getAuthToken} for
+  * the current value.
+  */
+  onAuthTokenChange(listener: (token: string | null) => void): Unsubscribe;
+  /**
+  * Fetch the currently authenticated user from better-auth's `get-session`
+  * endpoint, returning the `user` record or `null` when signed out. Sends
+  * the stored bearer token (if any) and `credentials: "include"` so a
+  * cookie-session is also honoured. A network/parse failure or a non-OK
+  * response resolves to `null` rather than throwing — callers treat "couldn't
+  * resolve identity" as "signed out".
+  *
+  * Framework-agnostic: pair it with {@link onAuthTokenChange} to refetch when
+  * the token changes (that's what `@lunora/react`'s `useAuth` does).
+  */
+  getCurrentUser(): Promise<User | null>;
+  /**
+  * Replace the token appended to WS upgrade URLs as `?token=…` and close
+  * every open shard socket so the reconnect picks up the new value. Call
+  * this whenever the user's WS credential changes (rotating the admin token
+  * in the studio, switching workspaces, etc.). Bearer tokens for HTTP
+  * RPC are independent — see {@link setAuthToken}.
+  */
+  setWsToken(token: string | undefined): void;
+  /**
+  * Register (or clear, with `undefined`) the app context sent in the `connect`
+  * envelope for a shard's socket, overriding the client-wide
+  * {@link LunoraClientOptions.connectionContext}. The server forwards it to the
+  * `onConnect`/`onDisconnect` lifecycle hooks as `event.context` — e.g.
+  * `@lunora/react`'s `usePresence` registers `{ roomId, sessionId }` so the
+  * presence row is removed the instant the socket drops, with no TTL lag.
+  *
+  * Stored per shard and replayed on every (re)connect. When a socket for the
+  * shard is already open, a fresh `connect` envelope is sent immediately so the
+  * server sees the new context without waiting for a reconnect.
+  */
+  setConnectionContext(context: Record<string, unknown> | undefined, options?: {
+    shardKey?: string;
+  }): void;
+  /**
+  * Refcounted variant of {@link setConnectionContext}: register a connection
+  * `context` for a shard and get back a release function. Unlike the imperative
+  * setter, the context is only cleared once the *last* acquired holder releases
+  * it — so two components (e.g. two mounted `usePresence` hooks) on the same
+  * shard no longer clobber each other's context when one of them unmounts. The
+  * most-recently acquired live holder wins (last-writer-wins), and releasing
+  * the top holder falls back to the previous one rather than clearing.
+  *
+  * With a single holder the behaviour is identical to a
+  * `setConnectionContext(context)` / `setConnectionContext(undefined)` pair.
+  * Releasing more than once is a no-op (the holder is matched by reference, so
+  * a double release can't drop a different holder).
+  */
+  acquireConnectionContext(context: Record<string, unknown>, options?: {
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
+  * Join a whisper `topic` and receive every ephemeral message other members
+  * broadcast to it on the same shard (typing indicators, live cursors,
+  * presence pings). Whispers never touch the server's durable state — there's
+  * no query, no row, no CDC entry. Returns an unsubscribe function; the topic
+  * is left on the server once its last local handler unsubscribes.
+  *
+  * `handler` receives the raw `data` and the sender's verified `from` user id
+  * (omitted for an anonymous sender). The topic is scoped to `options.shardKey`
+  * (the default shard when omitted) — use the same shard you target with the
+  * matching queries/mutations so members land on the same Durable Object.
+  *
+  * Security: whisper topics are NOT access-controlled beyond the shard
+  * boundary — any client that can open a socket to the shard can join, read,
+  * and inject on any topic name. `from` is server-stamped and unforgeable, but
+  * do not put data on a whisper topic that some shard members shouldn't see,
+  * and don't trust a whisper's `data` as authorization. Use a query/mutation
+  * (with RLS) for anything privileged; whispers are for transient awareness.
+  */
+  whisperSubscribe(topic: string, handler: (data: unknown, from?: string) => void, options?: {
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
+  * Broadcast an ephemeral `data` payload to the other members of a whisper
+  * `topic` on `options.shardKey`'s shard. Fire-and-forget: the frame is
+  * dropped when the shard socket isn't open (whispers are transient, never
+  * queued), and the server silently drops it if the sender exceeds its
+  * whisper rate budget. The sender never receives its own whisper. Omitting
+  * `data` delivers JSON `null` to receivers (not `undefined`).
+  */
+  whisper(topic: string, data?: unknown, options?: {
+    shardKey?: string;
+  }): void;
+  /**
+  * Subscribe to token-expiry events: invoked whenever the server drops a
+  * shard socket because the connection's credential lapsed (close code
+  * `4001`). The client already reconnects automatically (re-resolving
+  * identity from the cookie/token in effect); use this to refresh a
+  * short-lived token first — e.g. call {@link setWsToken} / {@link setAuthToken}
+  * with a freshly minted one. Returns an unsubscribe function.
+  */
+  onTokenExpired(listener: () => void): Unsubscribe;
+  /**
+  * Current aggregate live-socket status across all shard connections. See
+  * {@link ConnectionStatus}.
+  */
+  connectionStatus(): ConnectionStatus;
+  /**
+  * Subscribe to aggregate connection-status changes. Invokes `listener`
+  * immediately with the current status, then on every transition. Returns an
+  * unsubscribe function.
+  */
+  onConnectionStatus(listener: (status: ConnectionStatus) => void): Unsubscribe;
+  query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: {
+    shardKey?: string;
+  }): Promise<ReturnOf<F>>;
+  /**
+  * Invoke a mutation. Errors propagate as rejections.
+  *
+  * Offline-queue semantics: a mutation is queued (and replayed on reconnect)
+  * only when the targeted shard's socket was open at least once already
+  * (`wasEverConnected`), so the registry / resubscribe handshake has run.
+  * Mutations issued before the very first WS connect to a shard fail fast.
+  * Opt into queueing-before-first-connect via
+  * `OfflineQueueOptions.queueBeforeFirstConnect`.
+  */
+  mutation<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>): Promise<ReturnOf<F>>;
+  action<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: {
+    shardKey?: string;
+  }): Promise<ReturnOf<F>>;
+  /**
+  * Read the cross-shard request distribution for a `.shardBy(...)` table —
+  * the feed the studio's `hot_shard` advisor lint consumes. Hits the
+  * admin-gated `POST /_lunora/admin/shard-traffic` endpoint, which fans the
+  * cheap per-shard `getMetrics` read out across every live shard and returns
+  * each shard's `{ shardKey, requests }` total (a failed shard surfaces with
+  * `requests: 0`). Requires the worker to be built with a `queryCoordinator`
+  * and `adminToken`, and this client's auth token to match; defaults any
+  * absent field so an older worker yields an empty-but-valid shape.
+  */
+  shardTraffic(table: string): Promise<ShardTrafficResult>;
+  /**
+  * List the functions queued via `runAfter` / `runAt`, soonest-due last
+  * (the worker returns them in storage order). Hits the admin-gated
+  * `/_lunora/admin/scheduled` endpoint, so the worker must be built with a
+  * `schedulerDO` namespace and `adminToken`, and this client's auth token
+  * must match. Powers `@lunora/studio`'s scheduled-jobs panel.
+  */
+  listScheduledJobs(): Promise<ScheduleRecord[]>;
+  /**
+  * Read the app-level workpool backlog that powers `@lunora/studio`'s SLO
+  * view: per-pool `{ name, queued, inFlight, maxConcurrency }` plus the
+  * app-wide `backlog` (total queued) and `inFlight` (total held slots) sums.
+  * Hits the admin-gated `GET /_lunora/admin/scheduled/status` endpoint, so the
+  * same preconditions as {@link listScheduledJobs} apply (a `schedulerDO`
+  * namespace + `adminToken` on the worker and a matching auth token here).
+  * Defaults any absent field so an older worker still yields a valid shape.
+  */
+  schedulerStatus(): Promise<SchedulerStatus>;
+  /** Cancel a pending scheduled job by id. Returns whether a job was removed. */
+  cancelScheduledJob(id: string): Promise<{
+    cancelled: boolean;
+  }>;
+  /**
+  * List the dead-letter jobs: schedules that exhausted their retry budget
+  * and were parked instead of dropped. These never appear in
+  * {@link listScheduledJobs} (their live header is gone), so this is the only
+  * way the studio surfaces a permanently-failed job. Hits the admin-gated
+  * `GET /_lunora/admin/scheduled/dead`; same preconditions as
+  * {@link listScheduledJobs}. Powers `@lunora/studio`'s dead-letter panel.
+  */
+  listDeadJobs(): Promise<ScheduleRecord[]>;
+  /**
+  * Resurrect a dead-letter job by id: it re-enters the schedule with a fresh
+  * retry budget and fires on the next drain. Returns whether a parked record
+  * matched. Hits the admin-gated `POST /_lunora/admin/scheduled/dead/retry`.
+  */
+  retryDeadJob(id: string): Promise<{
+    retried: boolean;
+  }>;
+  /**
+  * Permanently drop a dead-letter job by id (the operator has decided not to
+  * recover it). Returns whether a parked record was removed. Hits the
+  * admin-gated `POST /_lunora/admin/scheduled/dead/cancel`.
+  */
+  removeDeadJob(id: string): Promise<{
+    removed: boolean;
+  }>;
+  /**
+  * 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.
+  */
+  listWorkflowInstances(options: {
+    name: string;
+    page?: number;
+    perPage?: number;
+    status?: WorkflowInstanceStatus;
+  }): Promise<WorkflowInstancePage>;
+  /** Read one workflow instance with its step timeline (`/_lunora/admin/workflows/instance`). */
+  getWorkflowInstance(options: {
+    id: string;
+    name: string;
+  }): Promise<WorkflowInstanceDetail>;
+  /** Pause / resume / terminate a workflow instance (`/_lunora/admin/workflows/status`). Needs an Edit-scoped Cloudflare token. */
+  setWorkflowInstanceStatus(options: {
+    action: WorkflowInstanceAction;
+    id: string;
+    name: string;
+  }): Promise<{
+    status: WorkflowInstanceStatus;
+  }>;
+  /**
+  * Subscribe to the live scheduled-jobs list over the SchedulerDO's admin
+  * WebSocket. `onJobs` fires with the full list on connect and on every
+  * change (schedule / cancel / alarm-fire). Reconnects with the client's
+  * configured backoff. Requires `wsToken` to be set to the admin token (the
+  * browser can't send an `Authorization` header on a WS). Returns an
+  * unsubscribe function that closes the socket and stops reconnecting.
+  */
+  subscribeScheduledJobs(onJobs: (jobs: ScheduleRecord[]) => void): Unsubscribe;
+  /**
+  * List the registered public functions (queries / mutations / actions) with
+  * their kinds. Hits the admin-gated `GET /_lunora/admin/functions` endpoint —
+  * the worker must be built with a `functions` registry and `adminToken`, and
+  * this client's auth token must match. Powers `@lunora/studio`'s function
+  * runner auto-discovery.
+  */
+  listFunctions(): Promise<FunctionDescriptor[]>;
+  /**
+  * List the code-defined cron triggers (the `cronJobs()` map injected on the
+  * worker), each flattened to its firing `cron` expression. Hits the
+  * admin-gated `GET /_lunora/admin/cron-jobs` endpoint — the worker must be
+  * built with a `cronJobs` map and `adminToken`, and this client's auth token
+  * must match. These are static (Cloudflare exposes no runtime cron
+  * introspection), so the studio renders them read-only alongside the dynamic
+  * scheduler jobs.
+  */
+  getCronJobs(): Promise<CronJobInfo[]>;
+  /**
+  * Manually fire one code-defined cron job by name — the same dispatch the
+  * scheduled trigger runs (dispatch the function, or start the durable
+  * workflow), on demand. Hits the admin-gated `POST /_lunora/admin/cron-jobs/run`
+  * endpoint; the worker must be built with a `cronJobs` map and `adminToken`,
+  * and this client's auth token must match. Resolves when the job has run (a
+  * function job's shard response is 2xx, or the workflow instance was created)
+  * and rejects with the dispatch error otherwise.
+  */
+  runCronJob(name: string): Promise<{
+    name: string;
+    ran: boolean;
+  }>;
+  /**
+  * Fetch the generated OpenAPI 3.1 document. Hits the admin-gated
+  * `GET /_lunora/admin/openapi` endpoint — the worker must be built with an
+  * `openApiSpec` and `adminToken`, and this client's auth token must match.
+  * Powers `@lunora/studio`'s API-reference (Scalar) view. When the worker has
+  * no spec wired, the endpoint still resolves with an empty-but-valid OpenAPI
+  * document (no `paths`), so callers can render a "not configured" state.
+  */
+  fetchOpenApi(): Promise<Record<string, unknown>>;
+  /**
+  * Fetch the generated OpenRPC 1.x document. Hits the admin-gated
+  * `GET /_lunora/admin/openrpc` endpoint — the worker must be built with an
+  * `openRpcSpec` and `adminToken`, and this client's auth token must match.
+  * OpenRPC is the RPC-native spec (a `methods` array over the JSON-RPC-shaped
+  * `POST /_lunora/rpc` transport); it documents the RPC functions only.
+  * Powers `@lunora/studio`'s OpenRPC API-reference view. When the worker has
+  * no spec wired, the endpoint still resolves with an empty-but-valid OpenRPC
+  * document (no `methods`), so callers can render a "not configured" state.
+  */
+  fetchOpenRpc(): Promise<Record<string, unknown>>;
+  /**
+  * List objects in the storage bucket, optionally under a `prefix` and from a
+  * pagination `cursor`. Hits the admin-gated `GET /_lunora/admin/storage`
+  * endpoint — the worker must be built with a `storageList` function and
+  * `adminToken`, and this client's auth token must match. Powers
+  * `@lunora/studio`'s file browser.
+  */
+  listStorageObjects(options?: {
+    bucket?: string;
+    cursor?: string;
+    limit?: number;
+    prefix?: string;
+  }): Promise<StorageListPage>;
+  /**
+  * Delete one object from the storage bucket by key. Hits the admin-gated
+  * `DELETE /_lunora/admin/storage?key=…` endpoint — the worker must be built
+  * with a `storageDelete` function and `adminToken`. Powers the studio file
+  * browser's per-row delete; resolves `{ deleted, key }`.
+  */
+  deleteStorageObject(key: string, options?: {
+    bucket?: string;
+  }): Promise<{
+    deleted: boolean;
+    key: string;
+  }>;
+  /**
+  * List the storage bucket names the worker exposes, for the studio file
+  * browser's bucket picker. Hits the admin-gated
+  * `GET /_lunora/admin/storage/buckets` endpoint — always resolves (an empty
+  * array when the worker configures no `storageBuckets`, i.e. single-bucket).
+  */
+  listStorageBuckets(): Promise<string[]>;
+  /**
+  * Upload one object to the storage bucket. Hits the admin-gated
+  * `PUT /_lunora/admin/storage?key=…` endpoint with the raw body and an
+  * optional `contentType` header — the worker must be built with a
+  * `storageUpload` function and `adminToken`. Powers the studio file
+  * browser's upload control; resolves `{ etag?, key }`.
+  */
+  uploadStorageObject(options: {
+    body: ArrayBuffer | Blob;
+    bucket?: string;
+    contentType?: string;
+    key: string;
+  }): Promise<{
+    etag?: string;
+    key: string;
+  }>;
+  /**
+  * Build a (signed or public) URL for one object. Hits the admin-gated
+  * `GET /_lunora/admin/storage/url?key=…` endpoint — the worker must be built
+  * with a `storageSignedUrl` function and `adminToken`. Powers the studio
+  * file browser's copy-URL action; resolves the URL string.
+  *
+  * `options.expiresInSeconds` requests a share-link lifetime, which is
+  * validated/clamped server-side. The options object mirrors the worker's
+  * `StorageSignedUrlFunction` options (a `password` / download-limit are noted
+  * as future fields there).
+  */
+  signedStorageUrl(key: string, options?: {
+    bucket?: string;
+    expiresInSeconds?: number;
+  }): Promise<string>;
+  /**
+  * List the `.global()` (D1-backed) tables with their row counts. Hits the
+  * admin-gated `GET /_lunora/admin/global/tables` endpoint — the worker must
+  * be built with a `globalIntrospector` and `adminToken`. Powers the data
+  * browser's global mode.
+  */
+  listGlobalTables(): Promise<GlobalTableInfo[]>;
+  /**
+  * Read a page of rows from one `.global()` table. `filters` AND-narrows the
+  * page to rows matching each `column = value` eq constraint — the drill-down a
+  * facet-value click applies; the array is JSON-encoded into the `filters`
+  * query param and the values are bound server-side.
+  */
+  readGlobalTablePage(options: {
+    filters?: GlobalFilterClause[];
+    limit?: number;
+    offset?: number;
+    table: string;
+  }): Promise<GlobalTablePage>;
+  /**
+  * Summarise the distinct values of one column in a `.global()` table over the
+  * active view (the same eq `filters` the browser is previewing) — the global
+  * twin of the shard browser's facet. Hits the admin-gated
+  * `GET /_lunora/admin/global/facet` endpoint; `column` is validated + bound
+  * server-side. Powers the global data browser's facet sidebar.
+  */
+  facetGlobalColumn(options: {
+    column: string;
+    filters?: GlobalFilterClause[];
+    limit?: number;
+    table: string;
+  }): Promise<GlobalFacetResult>;
+  /**
+  * List the schema's Vectorize indexes with their declared shape (table,
+  * field, dimensions, metric, metadata) and live stats (vector count,
+  * processing watermark) when the binding is reachable. Hits the admin-gated
+  * `GET /_lunora/admin/vector/indexes` endpoint — the worker must be built
+  * with a `vectorIntrospector` and `adminToken`. Powers the studio's vector
+  * browser. Vectorize can't enumerate indexes at runtime, so this list comes
+  * from the generated `LUNORA_VECTOR_INDEXES` registry.
+  */
+  listVectorIndexes(): Promise<VectorIndexSummary[]>;
+  /**
+  * Run a nearest-neighbour similarity query against one vector index: the
+  * worker embeds `text` via the index's embedder and returns the top matches.
+  * Hits the admin-gated `POST /_lunora/admin/vector/query` endpoint. Throws
+  * `VECTOR_QUERY_UNSUPPORTED` when the worker's introspector has no embedder
+  * wired (the index lists read-only).
+  */
+  queryVectorIndex(options: {
+    name: string;
+    text: string;
+    topK?: number;
+  }): Promise<VectorQueryMatch[]>;
+  /**
+  * 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
+  * users dashboard.
+  */
+  listAuthUsers(options?: {
+    filterField?: string;
+    filterValue?: string;
+    limit?: number;
+    offset?: number;
+    search?: string;
+    searchField?: string;
+    sortBy?: string;
+    sortDirection?: "asc" | "desc";
+  }): Promise<AuthPage<AuthUser>>;
+  /**
+  * Create a user. Hits the admin-gated `POST /_lunora/admin/auth/users/create`
+  * endpoint (requires the worker's `authAdmin` to implement `createUser`).
+  * `data` carries any app-defined `user.additionalFields`.
+  */
+  createAuthUser(input: {
+    data?: Record<string, unknown>;
+    email: string;
+    name: string;
+    password?: string;
+    role?: string | string[];
+  }): Promise<AuthUser>;
+  /** Set a user's role (string, or array joined comma-wise server-side). */
+  setAuthUserRole(input: {
+    role: string | string[];
+    userId: string;
+  }): Promise<AuthUser>;
+  /** Ban a user. `expiresInSeconds` sets a temporary ban; omit it for a permanent one. Revokes the user's live sessions. */
+  banAuthUser(input: {
+    expiresInSeconds?: number;
+    reason?: string;
+    userId: string;
+  }): Promise<AuthUser>;
+  /** Lift a user's ban. */
+  unbanAuthUser(input: {
+    userId: string;
+  }): Promise<AuthUser>;
+  /** Set a user's password (admin override — no current-password challenge). */
+  setAuthUserPassword(input: {
+    newPassword: string;
+    userId: string;
+  }): Promise<void>;
+  /** Permanently delete a user and revoke their sessions. */
+  removeAuthUser(input: {
+    userId: string;
+  }): Promise<void>;
+  /**
+  * Mint an impersonation session for a user, returning its bearer `token`.
+  * The caller is responsible for using the token (e.g. setting the session
+  * cookie); the server performs no cookie round-trip.
+  */
+  impersonateAuthUser(input: {
+    userId: string;
+  }): Promise<AuthImpersonation>;
+  /** Revoke a single session by its id (force sign-out of one device). */
+  revokeAuthSession(input: {
+    sessionId: string;
+  }): Promise<void>;
+  /** Revoke every session for a user (force sign-out everywhere). */
+  revokeAuthUserSessions(input: {
+    userId: string;
+  }): Promise<void>;
+  /**
+  * Report which auth dashboard surfaces are available — derived server-side
+  * from the enabled better-auth plugins. The studio renders only the panels
+  * whose capability is `true`.
+  */
+  getAuthCapabilities(): Promise<AuthCapabilities>;
+  /** Update a user's fields (name/email/app-defined `additionalFields`). */
+  updateAuthUser(input: {
+    data: Record<string, unknown>;
+    userId: string;
+  }): Promise<AuthUser>;
+  /** List a user's linked accounts (credential / OAuth providers). Token material is stripped server-side. */
+  listAuthAccounts(input: {
+    userId: string;
+  }): Promise<Record<string, unknown>[]>;
+  /** Unlink a linked account from a user. */
+  unlinkAuthAccount(input: {
+    accountId: string;
+    userId: string;
+  }): Promise<void>;
+  /** List a user's registered passkeys (requires the passkey plugin). */
+  listAuthPasskeys(input: {
+    userId: string;
+  }): Promise<Record<string, unknown>[]>;
+  /** Delete a passkey by id (requires the passkey plugin). */
+  deleteAuthPasskey(input: {
+    passkeyId: string;
+  }): Promise<void>;
+  /** Disable two-factor auth for a user (requires the two-factor plugin). */
+  disableAuthTwoFactor(input: {
+    userId: string;
+  }): Promise<void>;
+  /** List organizations, paged (requires the organization plugin). */
+  listAuthOrganizations(options?: {
+    limit?: number;
+    offset?: number;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** List the members of an organization (requires the organization plugin). */
+  listAuthOrgMembers(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** List an organization's pending invitations (requires the organization plugin). */
+  listAuthOrgInvitations(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Remove a member from an organization. */
+  removeAuthOrgMember(input: {
+    memberId: string;
+  }): Promise<void>;
+  /** Cancel a pending organization invitation. */
+  cancelAuthOrgInvitation(input: {
+    invitationId: string;
+  }): Promise<void>;
+  /** List auth sessions, paged and optionally filtered to one user. */
+  listAuthSessions(options?: {
+    limit?: number;
+    offset?: number;
+    userId?: string;
+  }): Promise<AuthPage<AuthSession>>;
+  subscribe<F extends FunctionReference>(function_: F, args: ArgsOf<F>, callback: (data: ReturnOf<F>) => void, options?: {
+    onError?: SubscriptionErrorCallback;
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
+  * Open a streaming query. The function reference must be a
+  * `kind:"stream"` registration (built with `c.query.input(...).stream(...)`);
+  * the type constraint catches accidental use of a query/mutation/action
+  * reference at compile time. The returned iterable yields one element per
+  * chunk frame the server pushes, terminating when the server sends
+  * `complete` or the consumer calls `.cancel()`. Errors arrive as a
+  * rejection on the next `next()`.
+  *
+  * Streams ride the same WS as subscriptions and share the unsubscribe
+  * channel: cancelling sends `{type:"unsubscribe", id}` with the stream id,
+  * which the DO recognises as an abort signal for the in-flight iterator.
+  *
+  * Stream-start frames buffered while the socket is (re)connecting are
+  * capped at {@link MAX_PENDING_STREAMS} per connection — overflowing the
+  * cap drops the oldest queued frame (and fails its consumer) so a stuck
+  * reconnect can't OOM the page.
+  */
+  stream<F extends FunctionReference<"stream">>(function_: F, args: ArgsOf<F>, options?: {
+    maxBuffer?: number;
+    shardKey?: string;
+  }): StreamIterable<ReturnOf<F>>;
+  close(): void;
+  /**
+  * 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;
+  /**
+  * 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
+  * gets a live snapshot as before); the gate at seed time also drops any
+  * entry whose stamped identity no longer matches the current one.
+  */
+  private hydrateQueryCache;
+  /**
+  * Consume the hydrated read-cache entry for a key (if any), gated on
+  * identity. The entry is removed whether or not it matches — the cache only
+  * ever seeds a subscription's first value. A mismatch (the cache was written
+  * under a different identity) yields `undefined` so a signed-out cache never
+  * leaks into a new session.
+  */
+  private takeHydratedCache;
+  /**
+  * Queue a coalesced read-cache write for a subscription's current value.
+  * Latest-wins per key; flushed on a short debounce so a delta burst writes
+  * once. No-op when the read cache is disabled or the value is undefined
+  * (nothing to render offline).
+  */
+  private persistQueryValue;
+  /** Drain {@link pendingCacheWrites} to the durable store. */
+  private flushQueryCacheWrites;
+  /** Derive the aggregate status from the per-shard socket states. */
+  private computeStatus;
+  /** 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).
+  */
+  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.
+  */
+  private applyOptimisticUpdate;
+  private getConnection;
+  private getOrCreateConnection;
+  private wsUrlFor;
+  /**
+  * Build the outbound RPC headers: JSON content type, optional bearer auth,
+  * the optional mutation-replay idempotency key, and the D1 read-your-writes
+  * bookmark when the caller opted into `attachBookmark`. The mutation id
+  * rides both the direct send and any offline-queue replay of the same write,
+  * so a mutation the server already committed returns its cached result
+  * instead of running twice.
+  */
+  private rpcRequestHeaders;
+  private rpc;
+  /**
+  * Authenticated request to a non-RPC admin endpoint (the scheduler list /
+  * cancel routes). Attaches the bearer token, parses JSON, and surfaces the
+  * worker's `{ error: { code, message } }` envelope as a coded `Error` —
+  * mirroring {@link rpc} so callers see the same failure shape.
+  */
+  private adminFetch;
+  /**
+  * Resolve the effective connection context for a shard: the most-recently
+  * acquired refcounted holder ({@link acquireConnectionContext}) wins, falling
+  * back to the imperative {@link setConnectionContext} override, then the
+  * client-wide default. Returns `undefined` when none apply.
+  */
+  private effectiveConnectionContext;
+  /** Re-send the `connect` envelope for a shard whose effective context just changed (if its socket is open). */
+  private refreshConnectionContext;
+  /**
+  * Send the one-shot `connect` envelope on an open shard socket. Always sent
+  * once per socket open, so the server's `onConnect` hooks fire symmetrically
+  * with `onDisconnect` (which the DO dispatches unconditionally at close for
+  * every lifecycle-aware socket). The DO no-ops cheaply when no `onConnect`
+  * hooks are registered, so the single frame costs nothing in the common case.
+  *
+  * The shard's registered context (or the client-wide default) rides along
+  * when one is set — the DO records it on the attachment for replay to
+  * `onDisconnect`. A socket with no registered context still announces itself;
+  * the envelope simply omits `context`, which is optional on the wire.
+  * Register a context — e.g. `setConnectionContext({})` — to attach app state
+  * to the lifecycle dispatch.
+  */
+  private sendConnectEnvelope;
+  private ensureSocket;
+  private handleDisconnect;
+  /**
+  * Begin the keepalive heartbeat on an open connection. Each tick sends a
+  * {@link WS_KEEPALIVE_PING} text frame the server answers from its
+  * hibernation auto-response without waking the DO. A no-op when the
+  * heartbeat is disabled (an interval of zero or less); idempotent — any
+  * existing timer is cleared first so a reconnect can't leak intervals.
+  */
+  private startHeartbeat;
+  /** Clear a connection's keepalive timer, if any. Safe to call repeatedly. */
+  private stopHeartbeat;
+  /** Mark every subscription bound to `shardKey` as needing a fresh ack. */
+  private markShardPendingAck;
+  private sendSubscribeIfOpen;
+  private handleServerMessage;
+  private handleErrorMessage;
+  private handleDataMessage;
+  /**
+  * Handle a `resume` frame (Pillar 1b): the server proved nothing the
+  * subscription reads changed since our `sinceSeq`, so the cached value is
+  * still current. We keep `lastValue` as-is, mark the sub acked, and advance
+  * the cursor (re-persisting so the next reconnect resumes from the newer
+  * watermark). No callback fires — the value didn't change, and `subscribe()`
+  * already replayed the cached value to every consumer synchronously.
+  */
+  private handleResumeMessage;
+  /**
+  * Resolve the value to publish for a `data`/`delta` frame.
+  *
+  * A `data` frame is an authoritative snapshot (the server re-execution path)
+  * and always replaces the cached value wholesale. A `delta` frame carrying a
+  * structured `MutationDelta` (the `broadcastDelta` row-change path) is
+  * merged incrementally into the cached list — preserving order, no dup/loss —
+  * so each subscription (including every paginated page) updates by delta
+  * rather than a full re-send. We fall back to full replacement when the
+  * delta isn't a recognisable row change, when there's no cached value yet,
+  * or when it can't be applied cleanly against the current cached shape.
+  */
+  private resolveDataPayload;
+  /** Route an inbound whisper to the topic's handlers on the originating shard. */
+  private dispatchWhisper;
+  /** Notify every {@link onTokenExpired} listener (best-effort, listener throws swallowed). */
+  private notifyTokenExpired;
+  private handleCompleteMessage;
+  private unpersist;
+  /**
+  * Stable, non-reversible fingerprint of the current auth identity used to
+  * stamp queued offline writes. `null` (signed out) is its own identity and
+  * never matches a bearer-token fingerprint. The raw token is never stored;
+  * a length-prefixed FNV-1a hash is enough to detect an identity *change*
+  * without keeping the credential around in the queue map.
+  */
+  private identityFingerprint;
+  /**
+  * 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
+  * alongside. Persisted entries restored without a live awaiter still get
+  * unpersisted here.
+  */
+  private rejectQueuedForIdentityChange;
+  /**
+  * 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;
+  * the durable `clear()` is best-effort.
+  */
+  private clearQueryCacheForIdentityChange;
+  private flushOfflineQueue;
+}
+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 };