@lunora/client 1.0.0-alpha.70 → 1.0.0-alpha.72

package/dist/packem_shared/{lunora-client.d-DWDMVBKE.d.mts → lunora-client.d-6hU156nD.d.mts}

@@ -1,5 +1,5 @@
+import { LunoraErrorCodeInput, LunoraErrorCode } from '@lunora/errors';
 import { F as FunctionReference, A as ArgsOf, R as ReturnOf } from "./function-reference.d-Br_hsKje.mjs";
-import { LunoraErrorCode } from '@lunora/errors';
 import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, PipelineLogQuery, PipelineLogPage, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
 /**
  * Reactive key-value store for local-only client state.
@@ -113,7 +113,7 @@ interface ReconnectOptions {
   maxDelayMs?: number;
 }
 /** Which durable-storage operation failed, passed to {@link OfflineQueueOptions.onPersistenceError}. */
-type PersistenceOperation = "append" | "clear" | "load" | "remove";
+type PersistenceOperation = "append" | "clear" | "load" | "remove" | "replace";
 /** Context handed to a persistence-error handler. */
 interface PersistenceErrorContext {
   readonly error: unknown;
@@ -195,6 +195,22 @@ interface PersistenceAdapter {
   load: () => Promise<PersistedMutation[]>;
   /** Remove a mutation by id once it has been replayed (resolved or rejected). */
   remove: (id: string) => Promise<void>;
+  /**
+   * Overwrite an already-persisted mutation IN PLACE, keeping its position in
+   * FIFO order. Used when a queued write's identity stamp is rewritten after a
+   * sign-in / sign-out.
+   *
+   * Must be atomic: a `remove` + `append` pair has a window where a process
+   * stop leaves the mutation in no durable store at all, and the in-memory
+   * entry has already advanced, so a reload loses the write outright. It also
+   * moved the record to the BACK of the queue, replaying it out of the order
+   * it was issued in. Implementations do the whole swap under one transaction
+   * (or one serialized blob write).
+   *
+   * A mutation whose id is not present is left alone — the record was drained
+   * concurrently and re-inserting it would replay a settled write.
+   */
+  replace: (mutation: PersistedMutation) => Promise<void>;
 }
 /**
  * One write handed to an {@link OutboxSink}. Mirrors {@link PersistedMutation}
@@ -378,10 +394,17 @@ interface LunoraClientOptions {
    */
   heartbeatIntervalMs?: number;
   /**
-   * When `true` and a `queryCache` is active, framework hooks (React, Vue, …)
-   * wait for the durable cache to finish hydrating before their first render
-   * with an enabled subscription, so users see cached data instead of an
-   * undefined flash before the socket round-trip. Defaults to `false`.
+   * When `true` and a `queryCache` is active, React's `useQuery` holds its
+   * TanStack query disabled until the durable cache has finished loading
+   * (`whenReady()`), so its first enabled render can seed the cached value
+   * instead of issuing an HTTP read that the cache would immediately
+   * overwrite. Defaults to `false`.
+   *
+   * It is ONLY React's `useQuery` that defers — the Vue, Svelte, Solid and
+   * Angular hooks subscribe at mount regardless of this flag, and so does
+   * React's own subscription registry. They do not need the gate: a
+   * subscription opened before the load completes is seeded by the load
+   * itself, so a cached value reaches the first subscriber either way.
    *
    * Requires `queryCache` to be set (not `false`); silently ignored otherwise.
    */
@@ -1085,7 +1108,16 @@ interface WorkflowInstancePage {
 type SubscriptionCallback = (data: unknown) => void;
 /** A subscription-scoped error the server pushed for this subscription id. */
 interface SubscriptionError {
-  code?: string;
+  /**
+   * The coded reason, when the frame carried one. `LunoraErrorCodeInput`, not
+   * `LunoraErrorCode`: the catalog codes autocomplete for a consumer branching
+   * on this (the shard sends `BAD_SUBSCRIPTION_ARGS`, `TOO_MANY_SUBSCRIPTIONS`,
+   * `SUBSCRIPTION_PERSIST_FAILED`, …; the client itself adds
+   * `WIRE_DECODE_FAILED` for a frame `decodeWire` refuses), but this value is
+   * read verbatim off the wire and nothing validates it against the catalog,
+   * so narrowing it to `LunoraErrorCode` would be a lie a newer server tells.
+   */
+  code?: LunoraErrorCodeInput;
   message: string;
 }
 type SubscriptionErrorCallback = (error: SubscriptionError) => void;
@@ -1180,6 +1212,19 @@ interface SubscriptionState {
    */
   serverEpoch?: string;
   readonly shardKey?: string;
+  /**
+   * The wire-encoded form of `args`, computed once at `subscribe` time (so an
+   * unsupported value fails loud at the call site, not inside a reconnect's
+   * open handler). Sent on every `subscribe` frame — identical to `args` for
+   * pure JSON, tagged tokens for `bigint`/`Date`/bytes/… (the shard
+   * `decodeWire`s them at its subscribe entry point).
+   *
+   * A SNAPSHOT, not a view: `args` is the caller's own object, retained by
+   * reference and never copied, so a caller that mutates it after subscribing
+   * would otherwise poison every later resubscribe. `encodeWire` rebuilds
+   * every container, so this copy is immune to that.
+   */
+  readonly wireArgs: Record<string, unknown>;
 }
 /**
  * Active subscription registry. The client keys subscriptions by
@@ -1193,6 +1238,14 @@ interface SubscriptionState {
  */
 declare class SubscriptionRegistry {
   static key(functionPath: string, args: Record<string, unknown>, shardKey?: string): string;
+  /**
+   * The registry key of an already-registered state, from its cached
+   * {@link SubscriptionState.argsKey}. Re-deriving it from `state.args` would
+   * re-read the caller's own (mutable) args object, so a caller that mutated
+   * its args after subscribing would compute a DIFFERENT key on unsubscribe
+   * and leak the registration forever.
+   */
+  static keyOf(state: SubscriptionState): string;
   private readonly byKey;
   private readonly byId;
   get(key: string): SubscriptionState | undefined;
@@ -1719,6 +1772,26 @@ declare class LunoraClient {
    *    racing write was never in the queue.
    */
   private readonly offlineFlushes;
+  /**
+   * Per-shard replay backoff, keyed by {@link connectionKey} exactly as the
+   * flushes and their timers are: `delayMs` is the longest hint the CURRENT
+   * flush of that key was given (written by
+   * {@link LunoraClient.noteReplayRetryDelay}, consumed once by
+   * {@link LunoraClient.scheduleRateLimitedRetry} at the end of the drain), and
+   * `attempts` counts its consecutive failed flushes, which is what the
+   * hintless backoff ramps on.
+   *
+   * Keyed, not a single field: flushes are per shard key and run concurrently,
+   * so one field means one limited shard sets the wait for every other shard
+   * and two flushes overwrite — then consume — each other's delay, leaving one
+   * of them with nothing scheduled at all. Evicted by
+   * {@link LunoraClient.scheduleRateLimitedRetry} the moment a key has nothing
+   * left to retry, so an app that shards per document does not accumulate an
+   * entry per document it ever wrote.
+   */
+  private readonly replayRetryState;
+  /** Pending rate-limit retry flushes, keyed by {@link connectionKey}, so `close()` can cancel them. */
+  private readonly replayRetryTimers;
   private readonly shapeSubscriptions;
   /**
    * In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by
@@ -2782,10 +2855,12 @@ declare class LunoraClient {
    * `subscribe` for the same triple joins the existing registration and shares
    * its value, cursor and optimistic layers.
    *
-   * Not available on a `crossTabSync` FOLLOWER tab: the cross-tab channel only
-   * carries the LEADER's own subscriptions outward, so a follower would receive
-   * this query's frames only if the leader happened to hold it too. Throws
-   * `NOT_IMPLEMENTED` there — see {@link LunoraClientOptions.crossTabSync}.
+   * Available on a `crossTabSync` FOLLOWER tab, unlike the other socket-backed
+   * surfaces: registering here is exactly what lets the cross-tab relay deliver
+   * the leader's broadcasts (see the note in the body). The caveat is that the
+   * channel only carries the LEADER's own subscriptions outward, so a follower
+   * sees this query's frames only while the leader holds it too — see
+   * {@link LunoraClientOptions.crossTabSync}.
    */
   subscribe<F extends FunctionReference>(function_: F, args: ArgsOf<F>, callback: (data: ReturnOf<F>) => void, options?: {
     onCheckpoint?: (watermark: SyncWatermark) => void;
@@ -2967,13 +3042,35 @@ declare class LunoraClient {
    */
   private hydrateAsOutboxLeader;
   /**
-   * Load every cached query into {@link hydratedQueryCache} so the next
-   * `subscribe()` for each key seeds its initial value off disk. A
-   * subscription created before this resolves simply misses the cache (it
-   * gets a live snapshot as before); the gate at seed time also drops any
-   * entry whose stamped identity no longer matches the current one.
+   * Load every cached query so a `subscribe()` for the key seeds its initial
+   * value off disk.
+   *
+   * The load is asynchronous but every framework adapter subscribes
+   * SYNCHRONOUSLY at mount, so the subscriptions that most want the cache
+   * already exist by the time it lands. Those are seeded here and their entry
+   * is dropped: an entry that stayed in {@link hydratedQueryCache} behind a
+   * live subscription would be consumed by the NEXT subscribe of the same key
+   * (a remount after navigating away) and replay the previous session's value
+   * over whatever the socket had since delivered. A cache entry therefore
+   * never outlives a live subscription for its key — it is either handed to
+   * that subscription or discarded.
+   *
+   * Only keys with no live subscription are held for a later `subscribe()`;
+   * the identity gate applies to both paths, so a signed-out cache never leaks
+   * into a new session.
    */
   private hydrateQueryCache;
+  /**
+   * Hand a loaded read-cache entry to a subscription that was opened before
+   * the load resolved — the same value, cursor and epoch {@link subscribe}
+   * would have taken from {@link takeHydratedCache} had the load finished
+   * first, so the cursor still rides the `subscribe` frame as `sinceSeq` (that
+   * frame only goes out once the socket opens, well after this microtask).
+   *
+   * A no-op once the socket has delivered anything for this key: a live value
+   * always beats the cache. Identity-gated exactly like `takeHydratedCache`.
+   */
+  private seedSubscriptionFromCache;
   /**
    * 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
@@ -3363,6 +3460,29 @@ declare class LunoraClient {
    */
   private flushOfflineQueue;
   private drainOfflineQueue;
+  /**
+   * Remember the longest delay this shard's flush was told (or worked out) to
+   * wait, so the drain can honour it before trying again
+   * ({@link LunoraClient.replayRetryState}). Counts the attempt either way:
+   * that is what a hintless refusal backs off on.
+   */
+  private noteReplayRetryDelay;
+  /**
+   * Consume this shard's retry delay and re-flush it once the delay has
+   * elapsed.
+   *
+   * Only a failure the server or an edge ANSWERED schedules anything (see
+   * {@link replayRetryDelayMs}): a `fetch` that never landed is already covered
+   * by the reconnect that will flush the queue, whereas a refused flush happens
+   * over a socket that stays open — so without this the writes sit queued
+   * indefinitely. One pending timer per shard; a second delay replaces it
+   * rather than stacking flushes.
+   *
+   * Nothing left to retry on this key (drained, closed, or no delay) drops its
+   * backoff state, which is both the reset after progress and what bounds the
+   * map.
+   */
+  private scheduleRateLimitedRetry;
   /**
    * Partition already-gated writes into the encodable ones (returned) and reject
    * the rest terminally. A write whose args can't be wire-encoded (e.g. a RegExp
@@ -3430,11 +3550,14 @@ declare class LunoraClient {
    * Replay already-identity-gated writes one at a time on the single-call `/rpc`
    * path, preserving FIFO order (parallel `.then()` chains would race the
    * ordering callers depend on). Each replays under its stable `mutationId` so
-   * the server dedups a write it already committed (exactly-once). A coded error
-   * is a server verdict (drop it); a codeless (transport/transient) failure stops
-   * the flush and re-queues this write and every unreplayed one for the next
-   * reconnect — their callers stay pending, and the identity guard re-applies on
-   * retry via each record's persisted stamp.
+   * the server dedups a write it already committed (exactly-once). A server verdict
+   * drops the write; a transient failure ({@link isTransientReplayFailure} — a
+   * transport error, a shard the worker couldn't reach, a rate-limit refusal, or a
+   * non-2xx carrying no `{ error }` envelope) stops the flush and re-queues this
+   * write and every unreplayed one for the next reconnect — their callers stay
+   * pending, and the identity guard re-applies on retry via each record's persisted
+   * stamp. The batch path classifies a slot by the same rule, so a durable write's
+   * fate never depends on how many siblings happened to be queued alongside it.
    */
   private replaySequential;
   /**
@@ -3444,24 +3567,47 @@ declare class LunoraClient {
    * per-entry `mutationId` idempotency and in-order application are inherited from
    * the proven path. Per-slot demux mirrors {@link replaySequential}'s
    * classification: success confirms the optimistic layer against the echoed
-   * `commitCursor`; a coded application verdict is terminal; a transient shard
-   * failure (`SHARD_UNAVAILABLE`/`SHARD_ERROR`), a missing slot, or a whole-batch
+   * `commitCursor`; a coded application verdict is terminal; a {@link
+   * TRANSIENT_REPLAY_ERROR_CODES} code, a missing slot, or a whole-batch
    * transport failure re-queues for the next reconnect (never dropping a durable
    * write). A whole-batch coded rejection (bad request / authorization denial the
    * server reached a verdict on) is terminal for every entry.
    *
+   * The body is also held under {@link MAX_BATCH_BODY_BYTES}: the worker caps a
+   * batch body at 1 MiB and answers `413`, which is ONE refusal covering every
+   * write in the chunk. An over-budget chunk is halved before it is sent, and a
+   * `413` for a chunk of more than one write halves it and retries rather than
+   * settling the whole chunk terminally — so a backlog of large writes still
+   * commits, one bisection deeper.
+   *
    * Returns the writes that must be re-queued and `stop` — `true` when the whole
    * chunk failed at the transport level, so the caller leaves later chunks queued
    * rather than sending on. The caller re-queues once, in order, so requeuing is
    * NOT done here.
    */
   private replayBatched;
+  /**
+   * Classify a `/_lunora/rpc-batch` reply that carried no per-slot results — one
+   * outcome covering every entry in the chunk. A {@link TRANSIENT_REPLAY_ERROR_CODES}
+   * code (an unreachable shard, a rate-limit refusal) or a
+   * {@link TransportError} (an edge reply with no verdict in it) leaves every
+   * write durable for the next attempt; anything else is a verdict reached on
+   * the request itself, and settles all of them.
+   */
+  private settleWholeBatchError;
+  /**
+   * Split an over-large batch chunk in half and replay each half, preserving
+   * FIFO order. Recurses through {@link replayBatched}, so a chunk keeps halving
+   * until it fits (or reaches one write, which is then the server's verdict to
+   * give). A `stop` on the first half leaves the second unsent and queued.
+   */
+  private replayBatchedHalves;
   /**
    * Demux a `/_lunora/rpc-batch` reply back onto the queued writes it replayed,
    * in input order. Each slot's envelope classifies its write the same way
    * {@link replaySequential} does: a success confirms the optimistic layer
    * against the echoed `commitCursor`; a coded application verdict is terminal;
-   * a transient shard failure ({@link TRANSIENT_BATCH_ERROR_CODES}) or a slot the
+   * a transient failure ({@link TRANSIENT_REPLAY_ERROR_CODES}) or a slot the
    * server never returned is returned for the caller to re-queue.
    * @returns the writes that must be re-queued (transient slots), in input order
    */

package/dist/packem_shared/{lunora-client.d-CLwpIj61.d.ts → lunora-client.d-B0t5v2n9.d.ts}

@@ -1,5 +1,5 @@
+import { LunoraErrorCodeInput, LunoraErrorCode } from '@lunora/errors';
 import { F as FunctionReference, A as ArgsOf, R as ReturnOf } from "./function-reference.d-Br_hsKje.js";
-import { LunoraErrorCode } from '@lunora/errors';
 import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, PipelineLogQuery, PipelineLogPage, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
 /**
  * Reactive key-value store for local-only client state.
@@ -113,7 +113,7 @@ interface ReconnectOptions {
   maxDelayMs?: number;
 }
 /** Which durable-storage operation failed, passed to {@link OfflineQueueOptions.onPersistenceError}. */
-type PersistenceOperation = "append" | "clear" | "load" | "remove";
+type PersistenceOperation = "append" | "clear" | "load" | "remove" | "replace";
 /** Context handed to a persistence-error handler. */
 interface PersistenceErrorContext {
   readonly error: unknown;
@@ -195,6 +195,22 @@ interface PersistenceAdapter {
   load: () => Promise<PersistedMutation[]>;
   /** Remove a mutation by id once it has been replayed (resolved or rejected). */
   remove: (id: string) => Promise<void>;
+  /**
+   * Overwrite an already-persisted mutation IN PLACE, keeping its position in
+   * FIFO order. Used when a queued write's identity stamp is rewritten after a
+   * sign-in / sign-out.
+   *
+   * Must be atomic: a `remove` + `append` pair has a window where a process
+   * stop leaves the mutation in no durable store at all, and the in-memory
+   * entry has already advanced, so a reload loses the write outright. It also
+   * moved the record to the BACK of the queue, replaying it out of the order
+   * it was issued in. Implementations do the whole swap under one transaction
+   * (or one serialized blob write).
+   *
+   * A mutation whose id is not present is left alone — the record was drained
+   * concurrently and re-inserting it would replay a settled write.
+   */
+  replace: (mutation: PersistedMutation) => Promise<void>;
 }
 /**
  * One write handed to an {@link OutboxSink}. Mirrors {@link PersistedMutation}
@@ -378,10 +394,17 @@ interface LunoraClientOptions {
    */
   heartbeatIntervalMs?: number;
   /**
-   * When `true` and a `queryCache` is active, framework hooks (React, Vue, …)
-   * wait for the durable cache to finish hydrating before their first render
-   * with an enabled subscription, so users see cached data instead of an
-   * undefined flash before the socket round-trip. Defaults to `false`.
+   * When `true` and a `queryCache` is active, React's `useQuery` holds its
+   * TanStack query disabled until the durable cache has finished loading
+   * (`whenReady()`), so its first enabled render can seed the cached value
+   * instead of issuing an HTTP read that the cache would immediately
+   * overwrite. Defaults to `false`.
+   *
+   * It is ONLY React's `useQuery` that defers — the Vue, Svelte, Solid and
+   * Angular hooks subscribe at mount regardless of this flag, and so does
+   * React's own subscription registry. They do not need the gate: a
+   * subscription opened before the load completes is seeded by the load
+   * itself, so a cached value reaches the first subscriber either way.
    *
    * Requires `queryCache` to be set (not `false`); silently ignored otherwise.
    */
@@ -1085,7 +1108,16 @@ interface WorkflowInstancePage {
 type SubscriptionCallback = (data: unknown) => void;
 /** A subscription-scoped error the server pushed for this subscription id. */
 interface SubscriptionError {
-  code?: string;
+  /**
+   * The coded reason, when the frame carried one. `LunoraErrorCodeInput`, not
+   * `LunoraErrorCode`: the catalog codes autocomplete for a consumer branching
+   * on this (the shard sends `BAD_SUBSCRIPTION_ARGS`, `TOO_MANY_SUBSCRIPTIONS`,
+   * `SUBSCRIPTION_PERSIST_FAILED`, …; the client itself adds
+   * `WIRE_DECODE_FAILED` for a frame `decodeWire` refuses), but this value is
+   * read verbatim off the wire and nothing validates it against the catalog,
+   * so narrowing it to `LunoraErrorCode` would be a lie a newer server tells.
+   */
+  code?: LunoraErrorCodeInput;
   message: string;
 }
 type SubscriptionErrorCallback = (error: SubscriptionError) => void;
@@ -1180,6 +1212,19 @@ interface SubscriptionState {
    */
   serverEpoch?: string;
   readonly shardKey?: string;
+  /**
+   * The wire-encoded form of `args`, computed once at `subscribe` time (so an
+   * unsupported value fails loud at the call site, not inside a reconnect's
+   * open handler). Sent on every `subscribe` frame — identical to `args` for
+   * pure JSON, tagged tokens for `bigint`/`Date`/bytes/… (the shard
+   * `decodeWire`s them at its subscribe entry point).
+   *
+   * A SNAPSHOT, not a view: `args` is the caller's own object, retained by
+   * reference and never copied, so a caller that mutates it after subscribing
+   * would otherwise poison every later resubscribe. `encodeWire` rebuilds
+   * every container, so this copy is immune to that.
+   */
+  readonly wireArgs: Record<string, unknown>;
 }
 /**
  * Active subscription registry. The client keys subscriptions by
@@ -1193,6 +1238,14 @@ interface SubscriptionState {
  */
 declare class SubscriptionRegistry {
   static key(functionPath: string, args: Record<string, unknown>, shardKey?: string): string;
+  /**
+   * The registry key of an already-registered state, from its cached
+   * {@link SubscriptionState.argsKey}. Re-deriving it from `state.args` would
+   * re-read the caller's own (mutable) args object, so a caller that mutated
+   * its args after subscribing would compute a DIFFERENT key on unsubscribe
+   * and leak the registration forever.
+   */
+  static keyOf(state: SubscriptionState): string;
   private readonly byKey;
   private readonly byId;
   get(key: string): SubscriptionState | undefined;
@@ -1719,6 +1772,26 @@ declare class LunoraClient {
    *    racing write was never in the queue.
    */
   private readonly offlineFlushes;
+  /**
+   * Per-shard replay backoff, keyed by {@link connectionKey} exactly as the
+   * flushes and their timers are: `delayMs` is the longest hint the CURRENT
+   * flush of that key was given (written by
+   * {@link LunoraClient.noteReplayRetryDelay}, consumed once by
+   * {@link LunoraClient.scheduleRateLimitedRetry} at the end of the drain), and
+   * `attempts` counts its consecutive failed flushes, which is what the
+   * hintless backoff ramps on.
+   *
+   * Keyed, not a single field: flushes are per shard key and run concurrently,
+   * so one field means one limited shard sets the wait for every other shard
+   * and two flushes overwrite — then consume — each other's delay, leaving one
+   * of them with nothing scheduled at all. Evicted by
+   * {@link LunoraClient.scheduleRateLimitedRetry} the moment a key has nothing
+   * left to retry, so an app that shards per document does not accumulate an
+   * entry per document it ever wrote.
+   */
+  private readonly replayRetryState;
+  /** Pending rate-limit retry flushes, keyed by {@link connectionKey}, so `close()` can cancel them. */
+  private readonly replayRetryTimers;
   private readonly shapeSubscriptions;
   /**
    * In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by
@@ -2782,10 +2855,12 @@ declare class LunoraClient {
    * `subscribe` for the same triple joins the existing registration and shares
    * its value, cursor and optimistic layers.
    *
-   * Not available on a `crossTabSync` FOLLOWER tab: the cross-tab channel only
-   * carries the LEADER's own subscriptions outward, so a follower would receive
-   * this query's frames only if the leader happened to hold it too. Throws
-   * `NOT_IMPLEMENTED` there — see {@link LunoraClientOptions.crossTabSync}.
+   * Available on a `crossTabSync` FOLLOWER tab, unlike the other socket-backed
+   * surfaces: registering here is exactly what lets the cross-tab relay deliver
+   * the leader's broadcasts (see the note in the body). The caveat is that the
+   * channel only carries the LEADER's own subscriptions outward, so a follower
+   * sees this query's frames only while the leader holds it too — see
+   * {@link LunoraClientOptions.crossTabSync}.
    */
   subscribe<F extends FunctionReference>(function_: F, args: ArgsOf<F>, callback: (data: ReturnOf<F>) => void, options?: {
     onCheckpoint?: (watermark: SyncWatermark) => void;
@@ -2967,13 +3042,35 @@ declare class LunoraClient {
    */
   private hydrateAsOutboxLeader;
   /**
-   * Load every cached query into {@link hydratedQueryCache} so the next
-   * `subscribe()` for each key seeds its initial value off disk. A
-   * subscription created before this resolves simply misses the cache (it
-   * gets a live snapshot as before); the gate at seed time also drops any
-   * entry whose stamped identity no longer matches the current one.
+   * Load every cached query so a `subscribe()` for the key seeds its initial
+   * value off disk.
+   *
+   * The load is asynchronous but every framework adapter subscribes
+   * SYNCHRONOUSLY at mount, so the subscriptions that most want the cache
+   * already exist by the time it lands. Those are seeded here and their entry
+   * is dropped: an entry that stayed in {@link hydratedQueryCache} behind a
+   * live subscription would be consumed by the NEXT subscribe of the same key
+   * (a remount after navigating away) and replay the previous session's value
+   * over whatever the socket had since delivered. A cache entry therefore
+   * never outlives a live subscription for its key — it is either handed to
+   * that subscription or discarded.
+   *
+   * Only keys with no live subscription are held for a later `subscribe()`;
+   * the identity gate applies to both paths, so a signed-out cache never leaks
+   * into a new session.
    */
   private hydrateQueryCache;
+  /**
+   * Hand a loaded read-cache entry to a subscription that was opened before
+   * the load resolved — the same value, cursor and epoch {@link subscribe}
+   * would have taken from {@link takeHydratedCache} had the load finished
+   * first, so the cursor still rides the `subscribe` frame as `sinceSeq` (that
+   * frame only goes out once the socket opens, well after this microtask).
+   *
+   * A no-op once the socket has delivered anything for this key: a live value
+   * always beats the cache. Identity-gated exactly like `takeHydratedCache`.
+   */
+  private seedSubscriptionFromCache;
   /**
    * 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
@@ -3363,6 +3460,29 @@ declare class LunoraClient {
    */
   private flushOfflineQueue;
   private drainOfflineQueue;
+  /**
+   * Remember the longest delay this shard's flush was told (or worked out) to
+   * wait, so the drain can honour it before trying again
+   * ({@link LunoraClient.replayRetryState}). Counts the attempt either way:
+   * that is what a hintless refusal backs off on.
+   */
+  private noteReplayRetryDelay;
+  /**
+   * Consume this shard's retry delay and re-flush it once the delay has
+   * elapsed.
+   *
+   * Only a failure the server or an edge ANSWERED schedules anything (see
+   * {@link replayRetryDelayMs}): a `fetch` that never landed is already covered
+   * by the reconnect that will flush the queue, whereas a refused flush happens
+   * over a socket that stays open — so without this the writes sit queued
+   * indefinitely. One pending timer per shard; a second delay replaces it
+   * rather than stacking flushes.
+   *
+   * Nothing left to retry on this key (drained, closed, or no delay) drops its
+   * backoff state, which is both the reset after progress and what bounds the
+   * map.
+   */
+  private scheduleRateLimitedRetry;
   /**
    * Partition already-gated writes into the encodable ones (returned) and reject
    * the rest terminally. A write whose args can't be wire-encoded (e.g. a RegExp
@@ -3430,11 +3550,14 @@ declare class LunoraClient {
    * Replay already-identity-gated writes one at a time on the single-call `/rpc`
    * path, preserving FIFO order (parallel `.then()` chains would race the
    * ordering callers depend on). Each replays under its stable `mutationId` so
-   * the server dedups a write it already committed (exactly-once). A coded error
-   * is a server verdict (drop it); a codeless (transport/transient) failure stops
-   * the flush and re-queues this write and every unreplayed one for the next
-   * reconnect — their callers stay pending, and the identity guard re-applies on
-   * retry via each record's persisted stamp.
+   * the server dedups a write it already committed (exactly-once). A server verdict
+   * drops the write; a transient failure ({@link isTransientReplayFailure} — a
+   * transport error, a shard the worker couldn't reach, a rate-limit refusal, or a
+   * non-2xx carrying no `{ error }` envelope) stops the flush and re-queues this
+   * write and every unreplayed one for the next reconnect — their callers stay
+   * pending, and the identity guard re-applies on retry via each record's persisted
+   * stamp. The batch path classifies a slot by the same rule, so a durable write's
+   * fate never depends on how many siblings happened to be queued alongside it.
    */
   private replaySequential;
   /**
@@ -3444,24 +3567,47 @@ declare class LunoraClient {
    * per-entry `mutationId` idempotency and in-order application are inherited from
    * the proven path. Per-slot demux mirrors {@link replaySequential}'s
    * classification: success confirms the optimistic layer against the echoed
-   * `commitCursor`; a coded application verdict is terminal; a transient shard
-   * failure (`SHARD_UNAVAILABLE`/`SHARD_ERROR`), a missing slot, or a whole-batch
+   * `commitCursor`; a coded application verdict is terminal; a {@link
+   * TRANSIENT_REPLAY_ERROR_CODES} code, a missing slot, or a whole-batch
    * transport failure re-queues for the next reconnect (never dropping a durable
    * write). A whole-batch coded rejection (bad request / authorization denial the
    * server reached a verdict on) is terminal for every entry.
    *
+   * The body is also held under {@link MAX_BATCH_BODY_BYTES}: the worker caps a
+   * batch body at 1 MiB and answers `413`, which is ONE refusal covering every
+   * write in the chunk. An over-budget chunk is halved before it is sent, and a
+   * `413` for a chunk of more than one write halves it and retries rather than
+   * settling the whole chunk terminally — so a backlog of large writes still
+   * commits, one bisection deeper.
+   *
    * Returns the writes that must be re-queued and `stop` — `true` when the whole
    * chunk failed at the transport level, so the caller leaves later chunks queued
    * rather than sending on. The caller re-queues once, in order, so requeuing is
    * NOT done here.
    */
   private replayBatched;
+  /**
+   * Classify a `/_lunora/rpc-batch` reply that carried no per-slot results — one
+   * outcome covering every entry in the chunk. A {@link TRANSIENT_REPLAY_ERROR_CODES}
+   * code (an unreachable shard, a rate-limit refusal) or a
+   * {@link TransportError} (an edge reply with no verdict in it) leaves every
+   * write durable for the next attempt; anything else is a verdict reached on
+   * the request itself, and settles all of them.
+   */
+  private settleWholeBatchError;
+  /**
+   * Split an over-large batch chunk in half and replay each half, preserving
+   * FIFO order. Recurses through {@link replayBatched}, so a chunk keeps halving
+   * until it fits (or reaches one write, which is then the server's verdict to
+   * give). A `stop` on the first half leaves the second unsent and queued.
+   */
+  private replayBatchedHalves;
   /**
    * Demux a `/_lunora/rpc-batch` reply back onto the queued writes it replayed,
    * in input order. Each slot's envelope classifies its write the same way
    * {@link replaySequential} does: a success confirms the optimistic layer
    * against the echoed `commitCursor`; a coded application verdict is terminal;
-   * a transient shard failure ({@link TRANSIENT_BATCH_ERROR_CODES}) or a slot the
+   * a transient failure ({@link TRANSIENT_REPLAY_ERROR_CODES}) or a slot the
    * server never returned is returned for the caller to re-queue.
    * @returns the writes that must be re-queued (transient slots), in input order
    */

package/dist/packem_shared/offline-queue-xntsWiKt.mjs

@@ -0,0 +1 @@
+let h=0;const d=()=>{if(typeof crypto<"u"&&typeof crypto.randomUUID=="function")return crypto.randomUUID();h+=1;const r=typeof crypto<"u"&&typeof crypto.getRandomValues=="function"?Array.from(crypto.getRandomValues(new Uint8Array(8)),t=>t.toString(16).padStart(2,"0")).join(""):Math.random().toString(16).slice(2,12);return`id_${Date.now().toString(36)}_${h.toString(36)}_${r}`},f=(r,t)=>r!==void 0&&t!==r,u=d,o=(r,t,e,i)=>{if(r)try{r({error:e,mutationId:i,operation:t});return}catch{}console.warn(`[lunora] offline-queue persistence ${t} failed`,e)};class m{queueBeforeFirstConnect;maxItems;onPersistenceError;persistence;onEvict;onSizeChange;version;items=[];constructor(t={},e={}){this.maxItems=t.maxItems??1e3,this.queueBeforeFirstConnect=t.queueBeforeFirstConnect??!1,this.onPersistenceError=t.onPersistenceError,this.persistence=e.persistence,this.onEvict=e.onEvict,this.onSizeChange=e.onSizeChange,this.version=e.version}get size(){return this.items.length}enqueue(t){const e=t;e.id??=u(),this.items.push(e),this.persistence?.append({args:e.args,clientId:e.clientId,functionPath:e.functionPath,id:e.id,identity:e.identity,shardKey:e.shardKey,...this.version===void 0?{}:{version:this.version}}).catch(i=>{o(this.onPersistenceError,"append",i,e.id)}),this.evictOverflow(),this.notifySize()}async hydrate(){if(!this.persistence)return[];let t;try{t=await this.persistence.load()}catch(s){throw o(this.onPersistenceError,"load",s),s}const e=[],i=new Set(this.items.map(s=>s.id));for(const s of t)if(!i.has(s.id)){if(f(this.version,s.version)){this.persistence.remove(s.id).catch(a=>{o(this.onPersistenceError,"remove",a,s.id)});continue}i.add(s.id),e.push({args:s.args,clientId:s.clientId,functionPath:s.functionPath,id:s.id,identity:s.identity,reject:()=>{},resolve:()=>{},shardKey:s.shardKey})}this.items.unshift(...e),this.evictOverflow(),this.notifySize();const n=new Set(this.items),c=new Set;for(const s of e)n.has(s)&&c.add(s.shardKey);return[...c]}restampIdentity(t,e){for(const i of this.items){if(i.identity!==t)continue;i.identity=e;const{id:n}=i;if(!this.persistence||n===void 0)continue;const c={args:i.args,clientId:i.clientId,functionPath:i.functionPath,id:n,identity:e,shardKey:i.shardKey,...this.version===void 0?{}:{version:this.version}};this.rewriteStamp(n,c).catch(s=>{o(this.onPersistenceError,"replace",s,n)})}}drain(t){if(!t){const n=[...this.items];return this.items.length=0,this.notifySize(),n}const e=[],i=[];for(const n of this.items)(t(n)?e:i).push(n);return this.items.length=0,this.items.push(...i),this.notifySize(),e}requeue(t){t.length!==0&&(this.items.unshift(...t),this.notifySize())}drainConflict(){const t=[],e=[];for(const i of this.items)if(i.precondition!==void 0&&!i.precondition()){const n=new Error("offline mutation skipped: precondition failed before replay");n.code="OFFLINE_PRECONDITION_FAILED",i.reject(n),t.push(i)}else e.push(i);return t.length>0&&(this.items.length=0,this.items.push(...e),this.notifySize()),t}clear(){for(const t of this.items){const e=new Error("CLIENT_CLOSED");e.code="CLIENT_CLOSED",t.reject(e)}this.items.length=0,this.notifySize()}async rewriteStamp(t,e){const i=this.persistence;if(i)try{await i.replace(e)}catch(n){o(this.onPersistenceError,"replace",n,t)}}evictOverflow(){for(;this.items.length>this.maxItems;){const t=this.items.shift();if(t){t.id&&this.persistence?.remove(t.id).catch(i=>{o(this.onPersistenceError,"remove",i,t.id)});const e=new Error("offline queue overflow");e.code="OFFLINE_QUEUE_OVERFLOW",t.reject(e),this.onEvict?.(t,e)}}}notifySize(){this.onSizeChange?.(this.items.length)}}export{m as O,f as i,u as n,o as r};

package/dist/packem_shared/{preload.d-ClHaOfOQ.d.ts → preload.d-Dl-ja0VQ.d.ts}

@@ -1,4 +1,4 @@
-import { L as LunoraClient, P as Preloaded } from "./lunora-client.d-CLwpIj61.js";
+import { L as LunoraClient, P as Preloaded } from "./lunora-client.d-B0t5v2n9.js";
 import { F as FunctionReference, A as ArgsOf, R as ReturnOf } from "./function-reference.d-Br_hsKje.js";
 /**
  * Run a query once on the server (during SSR) and capture its result in a

package/dist/packem_shared/{preload.d-BAazUwhn.d.mts → preload.d-M7qP6TwL.d.mts}

@@ -1,4 +1,4 @@
-import { L as LunoraClient, P as Preloaded } from "./lunora-client.d-DWDMVBKE.mjs";
+import { L as LunoraClient, P as Preloaded } from "./lunora-client.d-6hU156nD.mjs";
 import { F as FunctionReference, A as ArgsOf, R as ReturnOf } from "./function-reference.d-Br_hsKje.mjs";
 /**
  * Run a query once on the server (during SSR) and capture its result in a

package/dist/packem_shared/wire-codec-BfIZrTJe.mjs

@@ -0,0 +1 @@
+const m=e=>{let t="";for(let o=0;o<e.length;o+=32768)t+=String.fromCharCode(...e.subarray(o,o+32768));return btoa(t)},p=e=>{const t=atob(e),a=new Uint8Array(t.length);for(let o=0;o<t.length;o+=1)a[o]=t.codePointAt(o)??0;return a},i="$lunora.wire$";const w="__proto__",g={BigInt64Array,BigUint64Array,Float32Array,Float64Array,Int8Array,Int16Array,Int32Array,Uint8Array,Uint8ClampedArray,Uint16Array,Uint32Array},A={Error,EvalError,RangeError,ReferenceError,SyntaxError,TypeError,URIError},l=e=>{if(e===null||typeof e!="object")return!1;const t=Object.getPrototypeOf(e);return t===null||t===Object.prototype},u=(e,t=0)=>{if(t>64)throw new RangeError("wire-codec: value nesting exceeds the 64-level limit");if(e===void 0)return[i,"undefined"];if(e===null)return null;const a=typeof e;if(a==="bigint")return[i,"bigint",e.toString()];if(a==="number"){const r=e;return Number.isNaN(r)?[i,"nan"]:r===1/0?[i,"inf"]:r===-1/0?[i,"-inf"]:r}if(a!=="object")return e;if(e instanceof Date)return[i,"date",u(e.getTime(),t+1)];if(e instanceof Error){const r=e,n={};for(const f of Object.keys(r))r[f]!==void 0&&(n[f]=u(r[f],t+1));const c=[i,"error",r.name,r.message,n];return r.cause!==void 0&&c.push(u(r.cause,t+1)),c}if(e instanceof URL)return[i,"url",e.href];if(e instanceof Map)return[i,"map",[...e.entries()].map(([r,n])=>[u(r,t+1),u(n,t+1)])];if(e instanceof Set)return[i,"set",[...e].map(r=>u(r,t+1))];if(e instanceof ArrayBuffer)return[i,"bytes",m(new Uint8Array(e)),"ArrayBuffer"];if(ArrayBuffer.isView(e)){const r=e,n=r.constructor.name,c=new Uint8Array(r.buffer,r.byteOffset,r.byteLength);return n==="Uint8Array"?[i,"bytes",m(c)]:[i,"bytes",m(c),n]}if(Array.isArray(e)){const r=e.map(n=>u(n,t+1));return r.length>0&&r[0]===i?[i,"arr",r]:r}if(!l(e)){const r=e.constructor?.name??"value";throw new TypeError(`wire-codec: cannot encode a ${r} over the Lunora wire — only plain objects, arrays, and the supported built-ins (Date, Error, URL, Map, Set, ArrayBuffer/typed arrays, bigint) round-trip`)}const o=e,s={};for(const r of Object.keys(o)){const n=o[r];if(n===void 0)continue;const c=u(n,t+1);r===w?Object.defineProperty(s,r,{configurable:!0,enumerable:!0,value:c,writable:!0}):s[r]=c}return s},y=(e,t=0)=>{if(t>64)throw new RangeError("wire-codec: value nesting exceeds the 64-level limit");if(e===null||typeof e!="object")return e;if(Array.isArray(e)){if(e[0]===i)switch(e[1]){case"-inf":return-1/0;case"arr":return e[2].map(r=>y(r,t+1));case"bigint":{const r=e[2];if(typeof r!="string"||r.length>1024||!/^-?\d+$/.test(r))throw new RangeError("wire-codec: invalid or over-long bigint (max 1024 digits)");return BigInt(r)}case"date":{if(e.length<3)throw new TypeError("wire-codec: malformed date — missing payload");return new Date(y(e[2],t+1))}case"map":{const r=e[2];return new Map(r.map(n=>{if(!Array.isArray(n)||n.length!==2)throw new TypeError("wire-codec: malformed map entry — expected a [key, value] pair");return[y(n[0],t+1),y(n[1],t+1)]}))}case"set":return new Set(e[2].map(r=>y(r,t+1)));case"url":return new URL(e[2]);case"error":{const r=e[2],n=e[3],c=(Object.hasOwn(A,r)?A[r]:void 0)??Error,f=new c(n);f.name!==r&&Object.defineProperty(f,"name",{configurable:!0,value:r,writable:!0});const b=y(e[4],t+1);if(b===null||typeof b!="object"||Array.isArray(b))throw new TypeError("wire-codec: malformed error — props must be an object");for(const d of Object.keys(b))d===w?Object.defineProperty(f,d,{configurable:!0,enumerable:!0,value:b[d],writable:!0}):f[d]=b[d];return e.length>5&&Object.defineProperty(f,"cause",{configurable:!0,value:y(e[5],t+1),writable:!0}),f}case"bytes":{const r=p(e[2]),n=e[3]??"Uint8Array";if(n==="ArrayBuffer")return r.buffer.byteLength===r.byteLength?r.buffer:r.slice().buffer;const c=Object.hasOwn(g,n)?g[n]:void 0;return c?new c(r.slice().buffer):r}case"inf":return 1/0;case"nan":return Number.NaN;case"undefined":return;default:return e.map(r=>y(r,t+1))}return e.map(s=>y(s,t+1))}const a=e,o={};for(const s of Object.keys(a)){const r=y(a[s],t+1);s===w?Object.defineProperty(o,s,{configurable:!0,enumerable:!0,value:r,writable:!0}):o[s]=r}return o};export{y as d,u as e,l as i};

package/dist/packem_shared/{wire-key-Dl7EFWSD.mjs → wire-key-C9UKT-C3.mjs}

@@ -1 +1 @@
-import{e as a}from"./wire-codec-PBOTh_2d.mjs";const b=/["\\\u0000-\u001F\uD800-\uDFFF]/,y=t=>b.test(t)?JSON.stringify(t):`"${t}"`,i=t=>{if(t===void 0)return"null";if(typeof t=="bigint")throw new TypeError("stableStringify: cannot use a bigint in a stable JSON cache key — pass it as a string, or use stableWireKey");if(typeof t=="number"){if(Number.isNaN(t))return"nan";if(t===1/0)return"inf";if(t===-1/0)return"-inf";if(Object.is(t,-0))return"-0"}if(typeof t=="string")return y(t);if(t===null||typeof t!="object")return JSON.stringify(t);if(Array.isArray(t)){let r="[";for(let e=0;e<t.length;e++)e>0&&(r+=","),r+=i(t[e]);return r+"]"}const o=Object.getPrototypeOf(t);if(o!==null&&o!==Object.prototype){const r=t.constructor?.name??"value";throw new TypeError(`stableStringify: cannot use a ${r} in a stable JSON cache key — only plain objects, arrays, and JSON primitives are supported (wire-typed values key via stableWireKey)`)}const s=t,c=Object.keys(s).sort();let n="{",f=!0;for(const r of c){const e=s[r];e!==void 0&&(f?f=!1:n+=",",n+=y(r),n+=":",n+=i(e))}return n+"}"},u=t=>i(a(t));export{u as s};
+import{e as a}from"./wire-codec-BfIZrTJe.mjs";const b=/["\\\u0000-\u001F\uD800-\uDFFF]/,y=t=>b.test(t)?JSON.stringify(t):`"${t}"`,i=t=>{if(t===void 0)return"null";if(typeof t=="bigint")throw new TypeError("stableStringify: cannot use a bigint in a stable JSON cache key — pass it as a string, or use stableWireKey");if(typeof t=="number"){if(Number.isNaN(t))return"nan";if(t===1/0)return"inf";if(t===-1/0)return"-inf";if(Object.is(t,-0))return"-0"}if(typeof t=="string")return y(t);if(t===null||typeof t!="object")return JSON.stringify(t);if(Array.isArray(t)){let r="[";for(let e=0;e<t.length;e++)e>0&&(r+=","),r+=i(t[e]);return r+"]"}const o=Object.getPrototypeOf(t);if(o!==null&&o!==Object.prototype){const r=t.constructor?.name??"value";throw new TypeError(`stableStringify: cannot use a ${r} in a stable JSON cache key — only plain objects, arrays, and JSON primitives are supported (wire-typed values key via stableWireKey)`)}const s=t,c=Object.keys(s).sort();let n="{",f=!0;for(const r of c){const e=s[r];e!==void 0&&(f?f=!1:n+=",",n+=y(r),n+=":",n+=i(e))}return n+"}"},u=t=>i(a(t));export{u as s};