@lunora/client 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/packem_shared/{lunora-client.d-DGvyuJ_p.d.ts → lunora-client.d-CL9inoxa.d.ts}

@@ -120,6 +120,40 @@ interface PersistenceAdapter {
   remove: (id: string) => Promise<void>;
 }
 /**
+* One write handed to an {@link OutboxSink}. Mirrors {@link PersistedMutation}
+* plus the custom-mutator identity (`clientId`/`mutationId`/`idempotencyKey`)
+* the durable outbox needs to dedupe and watermark replays.
+*/
+interface OutboxMutation {
+  args: Record<string, unknown>;
+  /** Stable per-client id; pairs with {@link OutboxMutation.mutationId} as `idempotencyKey`. */
+  clientId: string;
+  functionPath: string;
+  /** `${clientId}:${mutationId}` — sent as `x-lunora-mutation-id` so a replay is server-idempotent. */
+  idempotencyKey: string;
+  /** Issuing identity fingerprint (`null` = signed out); drives the sink's identity guard. */
+  identity: string | null;
+  /** Monotonic per-client mutation id, backing the server `__client_watermark`. */
+  mutationId: number;
+  shardKey?: string;
+}
+/**
+* Pluggable durable outbox seam. When set on {@link LunoraClientOptions.outbox},
+* the client delegates offline write durability + at-least-once replay to this
+* sink instead of its built-in {@link PersistenceAdapter}-backed `OfflineQueue`.
+* `@lunora/db` supplies the blessed implementation (`createExecutorOutboxSink`,
+* backed by the TanStack `OfflineExecutor`); the interface itself is
+* dependency-free so `@lunora/client` stays TanStack-free.
+*/
+interface OutboxSink {
+  /**
+  * Persist and schedule a write for replay. Rejects with an
+  * `OFFLINE_QUEUE_OVERFLOW`-coded error when the sink's cap is exceeded, so
+  * the caller can surface back-pressure to the issuing mutation.
+  */
+  enqueue: (mutation: OutboxMutation) => Promise<void>;
+}
+/**
 * One persisted query result in the durable read cache (Pillar 2). Keyed in the
 * store by `shardKey + functionPath + argsKey`; the record carries everything
 * needed to render offline on reload and to resume the live subscription.
@@ -177,6 +211,16 @@ interface LunoraClientOptions {
   authBasePath?: string;
   bookmarkStorage?: BookmarkStorage;
   /**
+  * Stable per-client id backing the custom-mutator watermark. Sent on the
+  * `connect` envelope (so the server can scope this client's
+  * `__client_watermark`) and stamped onto every {@link OutboxMutation} the
+  * {@link LunoraClientOptions.outbox} sink persists, where it pairs with the
+  * monotonic mutation id to form the idempotency key. The `@lunora/db` path
+  * persists a stable id alongside the outbox and passes it here; omit for the
+  * standalone client, which generates an ephemeral per-session id.
+  */
+  clientId?: string;
+  /**
   * Default app context sent in the `connect` envelope right after each socket
   * opens, forwarded to the server's `onConnect`/`onDisconnect` lifecycle hooks
   * as `event.context`. A per-shard context registered via
@@ -184,6 +228,16 @@ interface LunoraClientOptions {
   * hook needs connection context.
   */
   connectionContext?: Record<string, unknown>;
+  /**
+  * Fail-fast timeout (ms) for opening a subscription WebSocket. If the
+  * handshake doesn't complete within this window — a hung dev proxy or a cold
+  * worker that never upgrades — the client force-closes the socket and routes
+  * through its normal reconnect/backoff (surfacing `offline` status) instead
+  * of leaving the live channel silently stuck on the browser's much longer
+  * default. Does not affect HTTP queries/mutations (those never ride the WS).
+  * Defaults to 10000 (10s); set to `0` (or negative) to disable.
+  */
+  connectTimeoutMs?: number;
   fetch?: typeof fetch;
   /**
   * Interval (ms) between keepalive pings sent on each open subscription
@@ -194,6 +248,14 @@ interface LunoraClientOptions {
   */
   heartbeatIntervalMs?: number;
   offlineQueue?: OfflineQueueOptions;
+  /**
+  * Durable outbox seam for offline writes. When supplied (the `@lunora/db`
+  * path wires `createExecutorOutboxSink`), offline mutations are delegated to
+  * the sink and the built-in {@link PersistenceAdapter}-backed `OfflineQueue`
+  * is bypassed, so a db app has exactly one durable write path. Omit for the
+  * standalone client, which keeps using {@link LunoraClientOptions.persistence}.
+  */
+  outbox?: OutboxSink;
   /** Durable store for the offline mutation queue; omit to keep it in memory. */
   persistence?: PersistenceAdapter;
   /**
@@ -222,17 +284,43 @@ interface LunoraClientOptions {
 /** Wire envelope sent on `POST /_lunora/rpc`. */
 interface RpcEnvelope {
   args?: Record<string, unknown>;
+  /**
+  * Stable per-client identifier (custom-mutator push path). Pairs with
+  * {@link RpcEnvelope.mutationId} to form `idempotencyKey` and scope the
+  * server `__client_watermark`. Absent on plain `client.mutation` calls.
+  */
+  clientId?: string;
   functionPath: string;
+  /**
+  * Idempotency key (`${clientId}:${mutationId}`) for the custom-mutator push
+  * path, mirrored into the `x-lunora-mutation-id` header. Absent on plain
+  * `client.mutation` calls.
+  */
+  idempotencyKey?: string;
+  /**
+  * Monotonic per-client mutation id (custom-mutator push path), backing the
+  * server-side per-client watermark: `id &lt;= watermark` is a replay (skipped),
+  * `id == watermark + 1` runs authoritatively, `id > watermark + 1` halts the
+  * batch so the client resends from `watermark + 1`. Absent on plain
+  * `client.mutation` calls.
+  */
+  mutationId?: number;
   shardKey?: string;
 }
-/** Wire response from the shard's `/rpc` endpoint (forwarded by the runtime). */
+/**
+* Wire response from the shard's `/rpc` endpoint (forwarded by the runtime). A
+* watermarked custom-mutator push additionally carries `lastMutationId` — the
+* highest per-client sequence the DO has applied — which the client uses to keep
+* its `clientSeq` generator monotonic across reloads (see `LunoraClient.callMutator`).
+*/
 type RpcResponseBody = {
-  result: unknown;
-} | {
   error: {
     code: string;
     message: string;
   };
+} | {
+  lastMutationId?: number;
+  result: unknown;
 };
 /** Subscription protocol — client → server. */
 interface ClientSubscribeMessage {
@@ -265,10 +353,51 @@ interface ClientUnsubscribeMessage {
 * `onDisconnect` when the socket drops.
 */
 interface ClientConnectMessage {
+  /**
+  * Stable per-client id (persisted alongside the outbox). Lets the server
+  * scope this connection's `__client_watermark` so custom-mutator pokes can
+  * echo the right per-client `lastMutationId`. Omitted by clients that don't
+  * use custom mutators.
+  */
+  clientId?: string;
   context?: Record<string, unknown>;
   id: string;
   type: "connect";
 }
+/**
+* Subscribe to a declarative **shape** — server-side partial replication scoped
+* by `shardBy` + the shape's predicate + RLS. The client sends the shape *name*
+* + validated `args`; the server resolves the trusted `where` (identity/RLS
+* `baseWhere` the client can't forge) and streams the matching rowset, then live
+* {@link ServerPokePartMessage} diffs. `id` namespaces the subscription and is
+* echoed as `shapeId` on every poke part.
+*/
+interface ClientShapeSubscribeMessage {
+  id: string;
+  shape: {
+    args?: Record<string, unknown>;
+    name: string;
+  };
+  /**
+  * Resume from this checkpoint (the `__cdc_log` cursor the client last
+  * applied for this shape). When absent or below the server's retained floor
+  * (`minCdcSeq`), the server re-seeds with a full insert-poke instead of a
+  * delta.
+  */
+  sinceCheckpoint?: number;
+  /**
+  * The CDC epoch {@link ClientShapeSubscribeMessage.sinceCheckpoint} belongs
+  * to. A mismatch (forked changelog timeline) forces a full re-seed even when
+  * the cursor is numerically in range.
+  */
+  sinceEpoch?: string;
+  type: "shape_subscribe";
+}
+/** Cancel a shape subscription started with the same `id`. */
+interface ClientShapeUnsubscribeMessage {
+  id: string;
+  type: "shape_unsubscribe";
+}
 interface ClientAckMessage {
   id: string;
   type: "ack";
@@ -309,7 +438,7 @@ interface ClientWhisperMessage {
   topic: string;
   type: "whisper";
 }
-type ClientMessage = ClientAckMessage | ClientConnectMessage | ClientStreamMessage | ClientSubscribeMessage | ClientUnsubscribeMessage | ClientWhisperMessage | ClientWhisperSubscribeMessage;
+type ClientMessage = ClientAckMessage | ClientConnectMessage | ClientShapeSubscribeMessage | ClientShapeUnsubscribeMessage | ClientStreamMessage | ClientSubscribeMessage | ClientUnsubscribeMessage | ClientWhisperMessage | ClientWhisperSubscribeMessage;
 /** Subscription protocol — server → client. */
 interface ServerDataMessage {
   /**
@@ -323,6 +452,13 @@ interface ServerDataMessage {
   /** The CDC epoch this frame's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
   epoch?: string;
   id: string;
+  /**
+  * The highest custom-mutator `mutationId` from this client the server has
+  * now applied (the per-client `__client_watermark`). Echoed so the client's
+  * outbox can drop confirmed pending mutations and let TanStack DB collapse
+  * the matching optimistic overlay. Absent on shards without custom mutators.
+  */
+  lastMutationId?: number;
   type: "data" | "delta";
 }
 /**
@@ -336,6 +472,8 @@ interface ServerResumeMessage {
   /** The CDC epoch this resume's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
   epoch?: string;
   id: string;
+  /** Per-client custom-mutator watermark (see {@link ServerDataMessage.lastMutationId}). */
+  lastMutationId?: number;
   type: "resume";
 }
 interface ServerErrorMessage {
@@ -370,7 +508,65 @@ interface ServerWhisperMessage {
   topic: string;
   type: "whisper";
 }
-type ServerMessage = ServerAckMessage | ServerChunkMessage | ServerCompleteMessage | ServerDataMessage | ServerErrorMessage | ServerResumeMessage | ServerWhisperMessage;
+/**
+* One row-level change in a shape's replication stream — the wire form of the
+* DO's `__cdc_log` `CdcChange`. `insert`/`update` carry the post-image in
+* `value` (projected to the shape's `columns`); `delete` omits it, identifying
+* the removed row by `key` alone. The client applies these to its local
+* collection; an unknown `key` on a `delete` is a safe no-op (a row the client
+* never had in this shape).
+*/
+interface RowOp {
+  /** Row primary key (`_id`). */
+  key: string;
+  op: "delete" | "insert" | "update";
+  /** Logical table the row belongs to. */
+  table: string;
+  /** Post-image document for insert/update; absent on delete. */
+  value?: Record<string, unknown>;
+}
+/**
+* Opens a **poke** — an atomically-applied batch of shape diffs (Zero's poke
+* protocol). A `pokeStart` is followed by zero or more {@link ServerPokePartMessage}
+* frames and closed by exactly one {@link ServerPokeEndMessage}; the client
+* buffers every part and applies them in a single transaction at `pokeEnd`, so a
+* socket that drops mid-poke simply re-seeds on reconnect (no torn view).
+*/
+interface ServerPokeStartMessage {
+  /** The checkpoint the client's view is expected to be at before this poke applies (for ordering/gap detection). */
+  baseCheckpoint?: number;
+  /** CDC epoch this poke belongs to; a mismatch forces the client to re-seed rather than apply. */
+  epoch?: string;
+  /** Correlates this poke's `pokeStart`/`pokePart`/`pokeEnd` frames. */
+  pokeId: string;
+  type: "pokeStart";
+}
+/** One shape's slice of an in-flight poke: the row-ops to apply for `shapeId`. */
+interface ServerPokePartMessage {
+  /** Per-client custom-mutator watermark carried with this slice (see {@link ServerDataMessage.lastMutationId}). */
+  lastMutationId?: number;
+  pokeId: string;
+  /** Ordered row-level changes for this shape, applied in sequence at `pokeEnd`. */
+  rowsPatch: RowOp[];
+  /** The {@link ClientShapeSubscribeMessage.id} these row-ops belong to. */
+  shapeId: string;
+  type: "pokePart";
+}
+/**
+* Closes a poke: the client commits the buffered parts atomically and advances
+* its checkpoint to {@link ServerPokeEndMessage.checkpoint} (the `__cdc_log`
+* cursor high-watermark the view now reflects), replayed as `sinceCheckpoint` on
+* the next reconnect.
+*/
+interface ServerPokeEndMessage {
+  /** The `__cdc_log` cursor the view is at after applying this poke. */
+  checkpoint?: number;
+  /** CDC epoch the {@link ServerPokeEndMessage.checkpoint} belongs to. */
+  epoch?: string;
+  pokeId: string;
+  type: "pokeEnd";
+}
+type ServerMessage = ServerAckMessage | ServerChunkMessage | ServerCompleteMessage | ServerDataMessage | ServerErrorMessage | ServerPokeEndMessage | ServerPokePartMessage | ServerPokeStartMessage | ServerResumeMessage | ServerWhisperMessage;
 /**
 * The authenticated user as exposed client-side, mirroring better-auth's
 * `user` row (the `user` field of the `get-session` response). Kept minimal
@@ -582,6 +778,13 @@ interface WorkflowInstanceDetail extends WorkflowInstanceSummary {
 }
 /** A page of workflow instances. */
 interface WorkflowInstancePage {
+  /**
+  * Whether workflow inspection is configured on the worker (a Cloudflare
+  * account id + API token). `false` when the admin proxy reports it can't
+  * inspect instances; omitted (treated as configured) otherwise. Lets a
+  * caller render a "set credentials" state without a failed request.
+  */
+  configured?: boolean;
   instances: WorkflowInstanceSummary[];
   page: number;
   perPage: number;
@@ -637,8 +840,11 @@ interface SubscriptionState {
 }
 /**
 * Active subscription registry. The client keys subscriptions by
-* `(functionPath, JSON.stringify(args), shardKey)` so duplicate calls share a
-* single server-side registration.
+* `(functionPath, stableStringify(args), shardKey)` so duplicate calls share a
+* single server-side registration. Args are stably encoded (keys sorted at every
+* depth) so two structurally-equal arg records constructed with a different key
+* order (`{ a, b }` vs `{ b, a }`) collapse to the same key instead of leaking a
+* duplicate subscription.
 */
 declare class SubscriptionRegistry {
   static key(functionPath: string, args: Record<string, unknown>, shardKey?: string): string;
@@ -760,6 +966,13 @@ type ConnectionStatus = "connected" | "connecting" | "idle" | "offline";
 * re-declaring it.
 */
 interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unknown> {
+  /**
+  * Override the auto-generated idempotency key (`x-lunora-mutation-id`). Lets a
+  * durable outbox replay a committed-but-unacked write under its *original* key
+  * so the server dedups it instead of applying it twice. Omit for normal calls —
+  * each then gets a fresh key.
+  */
+  mutationId?: string;
   optimistic?: (current: TCurrent | undefined) => TValue;
   /**
   * Convex-parity multi-query optimistic update. Receives an
@@ -770,6 +983,19 @@ interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unkn
   optimisticUpdate?: OptimisticUpdate<TArgs>;
   shardKey?: string;
 }
+/** Callback a shape subscription invokes with its materialized rowset on every applied poke. */
+type ShapeCallback = (rows: Record<string, unknown>[]) => void;
+/**
+* The high-water marks a shape poke has now synced to the client: `checkpoint`
+* is the op-log cursor and `mutationId` the highest custom-mutator id the server
+* echoed for this client. A `@lunora/db` collection feeds these into its
+* checkpoint registry to drop optimistic overlays once the server's authoritative
+* rows have landed.
+*/
+interface SyncWatermark {
+  checkpoint?: number;
+  mutationId?: number;
+}
 /**
 * Lunora browser/edge client. Talks RPC over HTTP and real-time deltas over
 * a single multiplexed WebSocket.
@@ -778,6 +1004,8 @@ interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unkn
 * see the package README for the wire protocol.
 */
 declare class LunoraClient {
+  /** Hard cap on concurrently-buffered pokes — a backstop that reclaims buffers abandoned by a mid-poke disconnect (no `pokeEnd`). Far above any real concurrent-in-flight count. */
+  private static readonly MAX_POKE_BUFFERS;
   readonly url: string;
   readonly wsUrl: string;
   private wsToken;
@@ -787,9 +1015,30 @@ declare class LunoraClient {
   private readonly WebSocketImpl;
   private readonly bookmark;
   private readonly reconnectOptions;
+  /** WS connect timeout (ms); `0` disables it. See {@link LunoraClientOptions.connectTimeoutMs}. */
+  private readonly connectTimeoutMs;
   /** Keepalive cadence (ms); `0` disables the heartbeat. See {@link LunoraClientOptions.heartbeatIntervalMs}. */
   private readonly heartbeatIntervalMs;
   private readonly offlineQueue;
+  /**
+  * Durable outbox seam (the `@lunora/db` `createExecutorOutboxSink`). When
+  * set, offline writes are delegated here and the built-in {@link OfflineQueue}
+  * is bypassed, so a db app has exactly one durable write path.
+  */
+  private readonly outbox;
+  /** Stable per-client id stamped onto every `OutboxMutation` (custom-mutator watermark). */
+  private readonly clientId;
+  /**
+  * Highest custom-mutator watermark the server has echoed for this client,
+  * keyed by shard bucket (`shardKey ?? ""`) since the DO tracks one
+  * `__client_watermark` per shard. `callMutator` bumps it from every
+  * ack; the `@lunora/db` mutator runtime seeds its `clientSeq` generator from
+  * it so a reload (which resets the in-memory counter) never reissues a stale
+  * sequence the server would silently swallow as a replay.
+  */
+  private readonly clientWatermarks;
+  /** Monotonic per-client mutation counter backing the server `__client_watermark`. */
+  private outboxMutationCounter;
   private readonly onPersistenceError;
   private readonly persistence;
   /** Durable read cache (Pillar 2); `undefined` when `queryCache` is omitted or `false`. */
@@ -866,6 +1115,11 @@ declare class LunoraClient {
   * calls `.cancel()` or the iterator is garbage-collected.
   */
   private readonly streams;
+  /** Live shape subscriptions (partial replication), keyed by their wire id. */
+  private readonly shapeSubscriptions;
+  /** In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by `pokeId`. */
+  private readonly pokeBuffers;
+  private nextShapeId;
   constructor(options: LunoraClientOptions);
   /**
   * Set (or clear) the bearer token sent on every HTTP RPC. Notifies any
@@ -880,6 +1134,47 @@ declare class LunoraClient {
   setAuthToken(token: string | null): void;
   getAuthToken(): string | null;
   /**
+  * The current identity fingerprint (the same stamp queued offline writes
+  * carry). Exposed so a durable {@link OutboxSink}'s replay handler — which
+  * owns its own at-least-once replay outside the built-in `OfflineQueue` —
+  * can drop a persisted write whose captured `identity` no longer matches the
+  * signed-in user, the guard the queue path applies in `flushOfflineQueue`.
+  */
+  currentIdentity(): string | null;
+  /** This client's stable identifier — the watermark key the server's custom-mutator protocol advances per `clientSeq`. */
+  clientIdentifier(): string;
+  /**
+  * The highest custom-mutator watermark the server has echoed for this client
+  * on the given shard (0 if none yet). The `@lunora/db` mutator runtime seeds
+  * its `clientSeq` generator from this so a reload never reissues a sequence
+  * the server has already applied (which it would swallow as a replay, silently
+  * dropping the write).
+  */
+  confirmedMutationWatermark(shardKey?: string): number;
+  /**
+  * Push a custom mutator to its authoritative server impl over the watermark
+  * protocol (Phase 4): the request carries `x-lunora-client-id` + a monotonic
+  * `x-lunora-client-seq`, so the DO runs it exactly once and advances this
+  * client's `__client_watermark`.
+  *
+  * Returns the server `result` plus `applied`: `true` when the DO ran this push
+  * as the next-in-order mutation, `false` when it was a replay ack (`clientSeq`
+  * was at or below the stored watermark — e.g. a stale sequence after a reload).
+  * A `false` verdict tells the caller to reissue above the now-known watermark
+  * (echoed into {@link confirmedMutationWatermark}) rather than treat the benign
+  * ack as a confirmed write. Every ack — applied or not — bumps the watermark.
+  *
+  * This is the online transport for `@lunora/db`'s client-mutator runtime; the
+  * optimistic overlay + durable-outbox concerns live in that runtime, not here.
+  */
+  callMutator(functionPath: string, args: Record<string, unknown>, options?: {
+    clientSeq?: number;
+    shardKey?: string;
+  }): Promise<{
+    applied: boolean;
+    result: unknown;
+  }>;
+  /**
   * Subscribe to auth-token changes. Returns an unsubscribe function. The
   * listener is NOT invoked on registration — use {@link getAuthToken} for
   * the current value.
@@ -1069,8 +1364,12 @@ declare class LunoraClient {
   * List a workflow's instances via the admin Workflows proxy
   * (`/_lunora/admin/workflows/instances`) — the Cloudflare control-plane data
   * the `Workflow` binding can't expose. Requires the worker to be built with a
-  * `workflowsClient` (Cloudflare account id + API token); otherwise the proxy
-  * responds 501 and this rejects. `name` is the deployed workflow name.
+  * `workflowsClient` (Cloudflare account id + API token). When one isn't
+  * configured this does NOT reject: the proxy returns a `200 { configured:
+  * false }` sentinel, so the result resolves with `configured === false` and an
+  * empty `instances` list — callers should branch on that flag rather than
+  * try/catch. (The instance-detail / status endpoints still reject with 501.)
+  * `name` is the deployed workflow name.
   */
   listWorkflowInstances(options: {
     name: string;
@@ -1404,6 +1703,26 @@ declare class LunoraClient {
     shardKey?: string;
   }): Unsubscribe;
   /**
+  * Subscribe to a declarative **shape** — server-side partial replication
+  * scoped by `shardBy` + the shape's predicate + RLS. The parallel to
+  * {@link subscribe} for the poke protocol: the client sends the shape *name* +
+  * validated `args` (never a `where` the client could forge), the server seeds
+  * the current membership as an insert-poke and streams live membership diffs.
+  * Each applied poke materializes the shape's rowset and invokes `callback`.
+  *
+  * Unlike {@link subscribe}, shape subscriptions are NOT deduped by
+  * (name, args): the server resolves them under the socket's verified identity,
+  * so every call gets its own id + view. The returned function unsubscribes.
+  */
+  subscribeShape(shape: {
+    args?: Record<string, unknown>;
+    name: string;
+  }, callback: ShapeCallback, options?: {
+    onCheckpoint?: (watermark: SyncWatermark) => void;
+    onError?: SubscriptionErrorCallback;
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
   * 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
@@ -1427,6 +1746,18 @@ declare class LunoraClient {
   }): StreamIterable<ReturnOf<F>>;
   close(): void;
   /**
+  * Persist a mutation that can't go out on the wire right now (offline, or
+  * mid-reconnect after a prior connect). The optimistic update has already
+  * been applied by `mutation`; this only chooses the durable write path and
+  * rolls the optimistic write back if persistence is rejected.
+  *
+  * Two paths: when an `outbox` sink is wired (the `@lunora/db` executor) it
+  * owns persistence + at-least-once replay, so we delegate and return
+  * optimistically (confirmation rides the synced view). Otherwise the
+  * built-in `OfflineQueue` resolves/rejects the returned promise on replay.
+  */
+  private enqueueOfflineMutation;
+  /**
   * Restore offline mutations persisted in a prior session and open a socket
   * for each shard they target so they flush once the WS reconnects. Failures
   * are swallowed — a broken durable store must not stop the client booting.
@@ -1523,6 +1854,13 @@ declare class LunoraClient {
   * to the lifecycle dispatch.
   */
   private sendConnectEnvelope;
+  /**
+  * Re-send every shape subscription bound to `shardKey` over its (now open)
+  * socket. Each frame carries the shape's last applied checkpoint, so the
+  * server resumes from it — or re-seeds when the cursor fell below CDC
+  * retention or the epoch forked.
+  */
+  private resendShapeSubscriptions;
   private ensureSocket;
   private handleDisconnect;
   /**
@@ -1538,8 +1876,14 @@ declare class LunoraClient {
   /** Mark every subscription bound to `shardKey` as needing a fresh ack. */
   private markShardPendingAck;
   private sendSubscribeIfOpen;
+  private sendShapeSubscribeIfOpen;
   private handleServerMessage;
   private handleErrorMessage;
+  private handlePokeStart;
+  private handlePokePart;
+  private handlePokeEnd;
+  /** Materialize a shape's keyed view to an array and invoke its callbacks. */
+  private emitShapeRows;
   private handleDataMessage;
   /**
   * Handle a `resume` frame (Pillar 1b): the server proved nothing the
@@ -1594,4 +1938,4 @@ declare class LunoraClient {
   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 };
+export { SyncWatermark as $, ArgsOf as A, BookmarkStorage as B, CachedQuery as C, DEFAULT_MAX_BUFFER as D, ServerMessage as E, FunctionReference as F, GlobalFacetResult as G, ServerPokeEndMessage as H, ServerPokePartMessage as I, ServerPokeStartMessage as J, ShardTrafficEntry as K, LunoraClient as L, MutationCallOptions as M, ShardTrafficResult as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, StorageListPage as T, User as U, StorageObject as V, StreamHandle as W, StreamIterable as X, SubscriptionCallback as Y, SubscriptionRegistry as Z, SubscriptionState as _, Unsubscribe as a, WorkflowInstanceAction as a0, WorkflowInstanceDetail as a1, WorkflowInstancePage as a2, WorkflowInstanceStatus as a3, WorkflowInstanceSummary as a4, WorkflowStepDetail as a5, createLocalStore as a6, createStream as a7, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, ClientMessage as e, ClientShapeSubscribeMessage as f, ClientShapeUnsubscribeMessage as g, ConnectionStatus as h, FunctionArgumentDescriptor as i, FunctionDescriptor as j, GlobalFacetValue as k, GlobalFilterClause as l, GlobalTableInfo as m, GlobalTablePage as n, LunoraClientOptions as o, OptimisticLocalStore as p, OptimisticUpdate as q, OutboxMutation as r, OutboxSink as s, PersistedMutation as t, RowOp as u, RpcEnvelope as v, RpcResponseBody as w, ScheduleRecord as x, SchedulerPoolStatus as y, SchedulerStatus as z };

package/dist/packem_shared/{preload.d-BoDmFqSG.d.ts → preload.d-B0O7Zm9z.d.ts}

@@ -1,4 +1,4 @@
-import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-DGvyuJ_p.js";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CL9inoxa.js";
 /**
 * Run a query once on the server (during SSR) and capture its result in a
 * serializable {@link Preloaded} token. Embed the token in the rendered HTML and

package/dist/packem_shared/{preload.d-dSaRMuhL.d.mts → preload.d-Da_yjk6L.d.mts}

@@ -1,4 +1,4 @@
-import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-DGvyuJ_p.mjs";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CL9inoxa.mjs";
 /**
 * Run a query once on the server (during SSR) and capture its result in a
 * serializable {@link Preloaded} token. Embed the token in the rendered HTML and

package/dist/packem_shared/subscription-C1Jy7HiF.mjs

@@ -0,0 +1,55 @@
+const compareKeys = (a, b) => {
+  if (a < b) {
+    return -1;
+  }
+  return a > b ? 1 : 0;
+};
+const stableStringify = (value) => {
+  if (value === void 0) {
+    return "null";
+  }
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const record = value;
+  const keys = Object.keys(record).toSorted(compareKeys);
+  const parts = [];
+  for (const key of keys) {
+    const raw = record[key];
+    if (raw === void 0) {
+      continue;
+    }
+    parts.push(`${JSON.stringify(key)}:${stableStringify(raw)}`);
+  }
+  return `{${parts.join(",")}}`;
+};
+
+class SubscriptionRegistry {
+  static key(functionPath, args, shardKey) {
+    return `${functionPath}::${stableStringify(args)}::${shardKey ?? ""}`;
+  }
+  byKey = /* @__PURE__ */ new Map();
+  byId = /* @__PURE__ */ new Map();
+  get(key) {
+    return this.byKey.get(key);
+  }
+  getById(id) {
+    return this.byId.get(id);
+  }
+  add(state) {
+    this.byKey.set(SubscriptionRegistry.key(state.fn.__lunoraRef, state.args, state.shardKey), state);
+    this.byId.set(state.id, state);
+  }
+  remove(state) {
+    this.byKey.delete(SubscriptionRegistry.key(state.fn.__lunoraRef, state.args, state.shardKey));
+    this.byId.delete(state.id);
+  }
+  all() {
+    return [...this.byKey.values()];
+  }
+}
+
+export { SubscriptionRegistry as S, stableStringify as s };

package/dist/query/index.d.mts

@@ -1,5 +1,5 @@
-import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-CL9inoxa.mjs";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CL9inoxa.mjs";
 import '@lunora/runtime';
 /**
 * The sentinel a framework adapter resolves its reactive args to when it wants

package/dist/query/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-CL9inoxa.js";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CL9inoxa.js";
 import '@lunora/runtime';
 /**
 * The sentinel a framework adapter resolves its reactive args to when it wants

package/dist/ssr/index.d.mts

@@ -1,6 +1,6 @@
-import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
-export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-dSaRMuhL.mjs";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-CL9inoxa.mjs";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-CL9inoxa.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-Da_yjk6L.mjs";
 import '@lunora/runtime';
 /**
 * Structural shape of a better-auth `getSession` call's resolved value.

package/dist/ssr/index.d.ts

@@ -1,6 +1,6 @@
-import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
-export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-BoDmFqSG.js";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-CL9inoxa.js";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-CL9inoxa.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-B0O7Zm9z.js";
 import '@lunora/runtime';
 /**
 * Structural shape of a better-auth `getSession` call's resolved value.

package/dist/ssr/index.mjs

@@ -1,4 +1,4 @@
 export { getServerSession } from '../packem_shared/getServerSession-8jXewqxd.mjs';
 export { deserializePreloaded, serializePreloaded } from '../packem_shared/deserializePreloaded-C0eJTY_W.mjs';
-export { createServerClient } from '../packem_shared/createServerClient-BjZc3gD8.mjs';
+export { createServerClient } from '../packem_shared/createServerClient-BgzEOQ46.mjs';
 export { preloadQuery, preloadedQueryResult } from '../packem_shared/preloadQuery-lobFkD2Z.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/client",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Lunora browser SDK: WebSocket transport, optimistic updates, and an offline mutation queue",
   "keywords": [
     "cloudflare",