@lunora/client 1.0.0-alpha.245 → 1.0.0-alpha.247

package/dist/packem_shared/{lunora-client.d-BGbRstqH.d.ts → lunora-client.d-7WaMRZUK.d.ts}

@@ -1,4 +1,4 @@
-import { LunoraErrorCodeInput, LunoraErrorCode } from '@lunora/errors';
+import { LunoraErrorCodeInput, LunoraErrorCode, LunoraError } from '@lunora/errors';
 import { F as FunctionReference, A as ArgsOf, R as ReturnOf } from "./function-reference.d-Br_hsKje.js";
 import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, PipelineLogQuery, PipelineLogPage, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
 /**
@@ -382,6 +382,14 @@ interface LunoraClientOptions {
    * `/api/auth` (matching `@lunora/auth`'s `DEFAULT_AUTH_BASE_PATH`).
    */
   authBasePath?: string;
+  /**
+   * Whether the `WebSocket` transport sends the `setAuthToken` bearer on the
+   * upgrade, as `@lunora/react-native` does on native. Then a
+   * sign-in from signed-out reconnects the shard sockets so the server sees the
+   * bearer. A browser socket cannot carry it, so the default `false` leaves its
+   * sockets (and their live values) alone.
+   */
+  authTokenOnUpgrade?: boolean;
   bookmarkStorage?: BookmarkStorage;
   /**
    * Stable per-client id backing the custom-mutator watermark. Sent on the
@@ -1320,8 +1328,13 @@ interface OptimisticLayer {
   readonly transform: (current: unknown) => unknown;
 }
 interface SubscriptionState {
-  /** True once the server has acked the subscription on the current socket. */
-  acked: boolean;
+  /**
+   * Where this subscription's `subscribe` frame stands on the current socket:
+   * none outstanding (`"idle"`), sent and not yet answered (`"inflight"`, so a
+   * second subscriber joins it instead of sending another), or acknowledged by
+   * the server (`"acked"`). Written only through {@link setSubscriptionAck}.
+   */
+  ack: "acked" | "idle" | "inflight";
   readonly args: Record<string, unknown>;
   /**
    * Stable wire-key of `args` (`stableWireKey`), computed once at subscribe
@@ -1470,12 +1483,17 @@ type LunoraClientError = Error & {
   code?: LunoraErrorCode | (string & {});
   data?: unknown;
   docsUrl?: string;
+  /**
+   * The headers of the reply this error came from. Set by the RPC, batch and replay paths; absent on
+   * a failure with no reply (a `fetch` that rejected, a timeout) and on the admin and stream paths.
+   */
+  headers?: Readonly<Record<string, string>>;
   hint?: string | string[];
   why?: string;
 };
 /** One demuxed result slot of a `LunoraClient.batch` call. */
 type BatchSlot = {
-  error: LunoraClientError;
+  error: LunoraClientError | LunoraError;
   ok: false;
 } | {
   ok: true;
@@ -1924,6 +1942,8 @@ declare class LunoraClient {
   private readonly pollingFallbackAfterFailedAttempts;
   /** Polling-fallback cadence (ms); `0` disables it. See {@link LunoraClientOptions.pollingFallback}. */
   private readonly pollingFallbackIntervalMs;
+  /** See {@link LunoraClientOptions.authTokenOnUpgrade}. */
+  private readonly authTokenOnUpgrade;
   private readonly offlineQueue;
   /**
    * Durable outbox seam (the `@lunora/db` `createExecutorOutboxSink`). When
@@ -2075,6 +2095,8 @@ declare class LunoraClient {
    */
   private readonly connectionContextHolders;
   private authToken;
+  /** Hash of the current bearer, keyed on the token so a new token misses once. `setAuthToken` drops it on every change, so a replaced or signed-out bearer is not retained. */
+  private tokenFingerprint;
   /**
    * Optional STABLE identity subject (a user id), the basis of the offline-queue
    * identity stamp when supplied. Keeps a same-user token *refresh* from looking
@@ -2268,6 +2290,27 @@ declare class LunoraClient {
    *    racing write was never in the queue.
    */
   private readonly offlineFlushes;
+  /**
+   * Subscriptions a socket `open` un-answered that no value-bearing frame has
+   * answered since. What they hold is the previous socket's value, or a blank
+   * after a cold reconnect, and the server acks a `subscribe` before it seeds
+   * it, so neither `lastValue` nor `ack` says the value is current. A queued
+   * write whose snapshot precondition reads one of them is not evaluated yet:
+   * see {@link LunoraClient.snapshotAnswer}. On a follower the open is the
+   * leader's, see {@link LunoraClient.awaitLeaderAnswers}.
+   */
+  private readonly awaitingAnswer;
+  /**
+   * Subscriptions whose wait ended without a value to read: the seed was
+   * refused or undecodable, or the resubscribe was given up on. Still acked and
+   * blank after a cold reconnect, so a snapshot comparison would read the blank
+   * as a change; a guard over one of them is no evidence either way.
+   */
+  private readonly answeredUnreadable;
+  /** Connection keys whose last flush left a write waiting on {@link LunoraClient.awaitingAnswer}; an answer there flushes again. */
+  private readonly answerHeldShards;
+  /** Gives up on the leader relaying an answer, one per subscription, see {@link LunoraClient.awaitLeaderAnswer}. */
+  private readonly leaderAnswerTimers;
   /**
    * Per-shard replay backoff, keyed by {@link connectionKey} exactly as the
    * flushes and their timers are: `delayMs` is the longest hint the CURRENT
@@ -2323,7 +2366,10 @@ declare class LunoraClient {
    * Does NOT update the WebSocket auth — a socket keeps the session credential
    * it connected with for its life. To refresh live WS auth, call
    * {@link setWsToken} explicitly, which closes existing shard sockets to
-   * force a reconnect with the new credential.
+   * force a reconnect with the new credential. With
+   * {@link LunoraClientOptions.authTokenOnUpgrade} (React Native's
+   * `Authorization` header), a sign-in from signed-out (a token where there was
+   * none) reconnects the sockets, cold, so the upgrade presents it.
    */
   setAuthToken(token: string | null, subject?: string | null): void;
   getAuthToken(): string | null;
@@ -2844,6 +2890,25 @@ declare class LunoraClient {
    * `new globalThis.WebSocket(url)` would silently bypass.
    */
   getWebSocketImpl(): typeof WebSocket | undefined;
+  /**
+   * `true` while {@link LunoraClientOptions.crossTabSync} is on and this tab
+   * is not the elected leader, including the election window before it knows
+   * whether another tab leads. Such a tab holds no socket: its subscriptions
+   * see only the frames the leader relays for queries the leader holds too,
+   * so a read that must resolve goes over HTTP instead of waiting on a push.
+   */
+  isCrossTabFollower(): boolean;
+  /**
+   * Whether a live query on `shardKey` can expect its value to be pushed: by a
+   * socket that is open or still on its first connect attempt, or by the
+   * polling fallback. `false` once a connect attempt has failed to reach `open`
+   * since the socket last did and polling is not delivering instead, where a
+   * read that must resolve should go over HTTP rather than wait on a push. A
+   * shard with no connection yet expects one: subscribing opens it.
+   */
+  expectsPush(options?: {
+    shardKey?: string;
+  }): boolean;
   /**
    * Read the current value for a {@link ClientQueryRef}. Returns
    * `ref.defaultValue` when no value has been explicitly set.
@@ -2926,7 +2991,9 @@ declare class LunoraClient {
    * whether one exists at all rather than just its value. `present` is `false`
    * when no subscription is open for the given `(functionPath, args, shardKey)`;
    * `value` is the subscription's `lastValue`, which includes any optimistic
-   * overlay.
+   * overlay. `answered` is `false` while an open subscription holds no answer
+   * (never answered, or blanked by a cold reconnect), when `value` is absence
+   * rather than evidence.
    *
    * The two are separate because a caller like the snapshot precondition has to
    * tell "no subscription is active, so this read knows nothing" apart from
@@ -2939,6 +3006,7 @@ declare class LunoraClient {
    * in-memory state of an already-opened subscription.
    */
   peekActiveQuerySnapshot(functionPath: string, args: Record<string, unknown>, shardKey?: string): {
+    answered: boolean;
     present: boolean;
     value: unknown;
   };
@@ -3785,6 +3853,29 @@ declare class LunoraClient {
     signal?: AbortSignal;
   }): StreamIterable<HttpStreamChunkOf<Ref>>;
   close(): void;
+  /**
+   * A genuine credential change: reject the queued writes that can no longer
+   * replay as the incoming identity, and evict the session the previous one
+   * left live. `true` when it evicted, which reconnects every socket cold.
+   */
+  private retirePreviousIdentity;
+  /**
+   * How the open sockets must follow a bearer change when the transport
+   * presents the bearer on the upgrade (React Native's `Authorization`
+   * header). An open upgrade keeps the token it was made with for its whole
+   * life, and a browser socket never carries it, so without
+   * `authTokenOnUpgrade` nothing reconnects.
+   *
+   * A sign-in from signed-out is `"cold"`: the sockets upgraded anonymously,
+   * and no view may resume from an anonymous cursor. A refreshed bearer under
+   * an unchanged identity is `"warm"`: the subscriptions resume from their
+   * cursors.
+   *
+   * A sign-out or an account switch leaves a previous identity behind and is
+   * evicted by `setAuthToken` before this is asked.
+   */
+  private reconcileUpgradeBearer;
+  private applyUpgradeBearer;
   /** Guard shared by every public entry point: a closed client accepts no further calls. */
   private assertOpen;
   /**
@@ -4374,6 +4465,11 @@ declare class LunoraClient {
    * shard still waking, a swallowed message) would otherwise leave the
    * subscription un-acked on a perfectly live socket until the next reconnect.
    * One retry, not a loop: a query that is merely slow must not be re-run repeatedly.
+   *
+   * The retry gets one ack window of its own (`final`), after which the frame is
+   * stood down so a later `subscribe()` can send again; otherwise a lost retry
+   * refuses every send until the next reconnect. Kept in `unackedWatchdogs`, so
+   * an ack or a teardown cancels either phase.
    */
   private armUnackedWatchdog;
   private sendShapeSubscribeIfOpen;
@@ -4859,6 +4955,14 @@ declare class LunoraClient {
   private restartTabCoordinatorForIdentity;
   /** Drop every room send held before the socket opened: they were made under the identity that is now going away. */
   private resetRoomSends;
+  /**
+   * Blank every live subscription and shape, forget their resume cursors, and
+   * reconnect every socket, so each resubscribe is a cold one the server
+   * re-seeds for the identity the new socket carries. Used when the socket's
+   * credential changes: resuming from a cursor taken under the previous one
+   * would splice a diff onto rows that identity was never shown.
+   */
+  private reconnectCold;
   /**
    * Close every open shard socket so each reconnects carrying the credential
    * in effect now.
@@ -4889,6 +4993,47 @@ declare class LunoraClient {
    * flush AND every write waiting on the barrier.
    */
   private flushOfflineQueue;
+  /**
+   * Where a snapshot precondition's subscription stands on its socket, when
+   * comparing would mislead: `"awaiting"` while a reconnect has un-answered it
+   * and no value has answered since (the comparison would judge the previous
+   * socket's value, or a blank), `"unreadable"` once that wait ended with no
+   * value to read. `undefined` for any other precondition or subscription.
+   */
+  private snapshotAnswer;
+  /**
+   * The precondition a queued write carries. A snapshot precondition reads as
+   * holding while its subscription is awaited, so `drainConflict` keeps the
+   * write rather than drop it on a blank the server acked but has not seeded
+   * yet (the drain then holds it back, {@link drainOfflineQueue}), and once the
+   * wait ended unreadable, which is no evidence the value changed.
+   */
+  private holdWhileUnanswered;
+  /**
+   * A follower's counterpart of a socket open in {@link markShardPendingAck}: every
+   * subscription awaits the leader's next relay. A follower cannot ask the leader for
+   * one, and the leader relays only the queries it holds itself, so the wait is bounded
+   * by the leader's own (an ack window and one retry) and ends unreadable, as the
+   * leader's does when it gives up.
+   */
+  private awaitLeaderAnswers;
+  /**
+   * Holds `state` for the leader's next relay. Its timer is its own, so settling
+   * one subscription early never releases another.
+   */
+  private awaitLeaderAnswer;
+  /**
+   * `state` has been answered on its socket (`readable`), or will not be: release
+   * any write held for it. Not called for an `ack`, which the server sends
+   * before the seed.
+   */
+  private settleAwaitedAnswer;
+  /**
+   * Put back a drained write whose snapshot cannot be compared yet, and every
+   * write behind it (replaying those first would reorder the shard), recording
+   * the hold so the answer flushes again. Returns the writes that may go on.
+   */
+  private holdUndecidedWrites;
   private drainOfflineQueue;
   /**
    * Ask for another flush of this shard after a backoff, because every entry it

package/dist/packem_shared/{lunora-client.d-B_eWE1gD.d.mts → lunora-client.d-DtTKDhtw.d.mts}

@@ -1,4 +1,4 @@
-import { LunoraErrorCodeInput, LunoraErrorCode } from '@lunora/errors';
+import { LunoraErrorCodeInput, LunoraErrorCode, LunoraError } from '@lunora/errors';
 import { F as FunctionReference, A as ArgsOf, R as ReturnOf } from "./function-reference.d-Br_hsKje.mjs";
 import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, PipelineLogQuery, PipelineLogPage, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
 /**
@@ -382,6 +382,14 @@ interface LunoraClientOptions {
    * `/api/auth` (matching `@lunora/auth`'s `DEFAULT_AUTH_BASE_PATH`).
    */
   authBasePath?: string;
+  /**
+   * Whether the `WebSocket` transport sends the `setAuthToken` bearer on the
+   * upgrade, as `@lunora/react-native` does on native. Then a
+   * sign-in from signed-out reconnects the shard sockets so the server sees the
+   * bearer. A browser socket cannot carry it, so the default `false` leaves its
+   * sockets (and their live values) alone.
+   */
+  authTokenOnUpgrade?: boolean;
   bookmarkStorage?: BookmarkStorage;
   /**
    * Stable per-client id backing the custom-mutator watermark. Sent on the
@@ -1320,8 +1328,13 @@ interface OptimisticLayer {
   readonly transform: (current: unknown) => unknown;
 }
 interface SubscriptionState {
-  /** True once the server has acked the subscription on the current socket. */
-  acked: boolean;
+  /**
+   * Where this subscription's `subscribe` frame stands on the current socket:
+   * none outstanding (`"idle"`), sent and not yet answered (`"inflight"`, so a
+   * second subscriber joins it instead of sending another), or acknowledged by
+   * the server (`"acked"`). Written only through {@link setSubscriptionAck}.
+   */
+  ack: "acked" | "idle" | "inflight";
   readonly args: Record<string, unknown>;
   /**
    * Stable wire-key of `args` (`stableWireKey`), computed once at subscribe
@@ -1470,12 +1483,17 @@ type LunoraClientError = Error & {
   code?: LunoraErrorCode | (string & {});
   data?: unknown;
   docsUrl?: string;
+  /**
+   * The headers of the reply this error came from. Set by the RPC, batch and replay paths; absent on
+   * a failure with no reply (a `fetch` that rejected, a timeout) and on the admin and stream paths.
+   */
+  headers?: Readonly<Record<string, string>>;
   hint?: string | string[];
   why?: string;
 };
 /** One demuxed result slot of a `LunoraClient.batch` call. */
 type BatchSlot = {
-  error: LunoraClientError;
+  error: LunoraClientError | LunoraError;
   ok: false;
 } | {
   ok: true;
@@ -1924,6 +1942,8 @@ declare class LunoraClient {
   private readonly pollingFallbackAfterFailedAttempts;
   /** Polling-fallback cadence (ms); `0` disables it. See {@link LunoraClientOptions.pollingFallback}. */
   private readonly pollingFallbackIntervalMs;
+  /** See {@link LunoraClientOptions.authTokenOnUpgrade}. */
+  private readonly authTokenOnUpgrade;
   private readonly offlineQueue;
   /**
    * Durable outbox seam (the `@lunora/db` `createExecutorOutboxSink`). When
@@ -2075,6 +2095,8 @@ declare class LunoraClient {
    */
   private readonly connectionContextHolders;
   private authToken;
+  /** Hash of the current bearer, keyed on the token so a new token misses once. `setAuthToken` drops it on every change, so a replaced or signed-out bearer is not retained. */
+  private tokenFingerprint;
   /**
    * Optional STABLE identity subject (a user id), the basis of the offline-queue
    * identity stamp when supplied. Keeps a same-user token *refresh* from looking
@@ -2268,6 +2290,27 @@ declare class LunoraClient {
    *    racing write was never in the queue.
    */
   private readonly offlineFlushes;
+  /**
+   * Subscriptions a socket `open` un-answered that no value-bearing frame has
+   * answered since. What they hold is the previous socket's value, or a blank
+   * after a cold reconnect, and the server acks a `subscribe` before it seeds
+   * it, so neither `lastValue` nor `ack` says the value is current. A queued
+   * write whose snapshot precondition reads one of them is not evaluated yet:
+   * see {@link LunoraClient.snapshotAnswer}. On a follower the open is the
+   * leader's, see {@link LunoraClient.awaitLeaderAnswers}.
+   */
+  private readonly awaitingAnswer;
+  /**
+   * Subscriptions whose wait ended without a value to read: the seed was
+   * refused or undecodable, or the resubscribe was given up on. Still acked and
+   * blank after a cold reconnect, so a snapshot comparison would read the blank
+   * as a change; a guard over one of them is no evidence either way.
+   */
+  private readonly answeredUnreadable;
+  /** Connection keys whose last flush left a write waiting on {@link LunoraClient.awaitingAnswer}; an answer there flushes again. */
+  private readonly answerHeldShards;
+  /** Gives up on the leader relaying an answer, one per subscription, see {@link LunoraClient.awaitLeaderAnswer}. */
+  private readonly leaderAnswerTimers;
   /**
    * Per-shard replay backoff, keyed by {@link connectionKey} exactly as the
    * flushes and their timers are: `delayMs` is the longest hint the CURRENT
@@ -2323,7 +2366,10 @@ declare class LunoraClient {
    * Does NOT update the WebSocket auth — a socket keeps the session credential
    * it connected with for its life. To refresh live WS auth, call
    * {@link setWsToken} explicitly, which closes existing shard sockets to
-   * force a reconnect with the new credential.
+   * force a reconnect with the new credential. With
+   * {@link LunoraClientOptions.authTokenOnUpgrade} (React Native's
+   * `Authorization` header), a sign-in from signed-out (a token where there was
+   * none) reconnects the sockets, cold, so the upgrade presents it.
    */
   setAuthToken(token: string | null, subject?: string | null): void;
   getAuthToken(): string | null;
@@ -2844,6 +2890,25 @@ declare class LunoraClient {
    * `new globalThis.WebSocket(url)` would silently bypass.
    */
   getWebSocketImpl(): typeof WebSocket | undefined;
+  /**
+   * `true` while {@link LunoraClientOptions.crossTabSync} is on and this tab
+   * is not the elected leader, including the election window before it knows
+   * whether another tab leads. Such a tab holds no socket: its subscriptions
+   * see only the frames the leader relays for queries the leader holds too,
+   * so a read that must resolve goes over HTTP instead of waiting on a push.
+   */
+  isCrossTabFollower(): boolean;
+  /**
+   * Whether a live query on `shardKey` can expect its value to be pushed: by a
+   * socket that is open or still on its first connect attempt, or by the
+   * polling fallback. `false` once a connect attempt has failed to reach `open`
+   * since the socket last did and polling is not delivering instead, where a
+   * read that must resolve should go over HTTP rather than wait on a push. A
+   * shard with no connection yet expects one: subscribing opens it.
+   */
+  expectsPush(options?: {
+    shardKey?: string;
+  }): boolean;
   /**
    * Read the current value for a {@link ClientQueryRef}. Returns
    * `ref.defaultValue` when no value has been explicitly set.
@@ -2926,7 +2991,9 @@ declare class LunoraClient {
    * whether one exists at all rather than just its value. `present` is `false`
    * when no subscription is open for the given `(functionPath, args, shardKey)`;
    * `value` is the subscription's `lastValue`, which includes any optimistic
-   * overlay.
+   * overlay. `answered` is `false` while an open subscription holds no answer
+   * (never answered, or blanked by a cold reconnect), when `value` is absence
+   * rather than evidence.
    *
    * The two are separate because a caller like the snapshot precondition has to
    * tell "no subscription is active, so this read knows nothing" apart from
@@ -2939,6 +3006,7 @@ declare class LunoraClient {
    * in-memory state of an already-opened subscription.
    */
   peekActiveQuerySnapshot(functionPath: string, args: Record<string, unknown>, shardKey?: string): {
+    answered: boolean;
     present: boolean;
     value: unknown;
   };
@@ -3785,6 +3853,29 @@ declare class LunoraClient {
     signal?: AbortSignal;
   }): StreamIterable<HttpStreamChunkOf<Ref>>;
   close(): void;
+  /**
+   * A genuine credential change: reject the queued writes that can no longer
+   * replay as the incoming identity, and evict the session the previous one
+   * left live. `true` when it evicted, which reconnects every socket cold.
+   */
+  private retirePreviousIdentity;
+  /**
+   * How the open sockets must follow a bearer change when the transport
+   * presents the bearer on the upgrade (React Native's `Authorization`
+   * header). An open upgrade keeps the token it was made with for its whole
+   * life, and a browser socket never carries it, so without
+   * `authTokenOnUpgrade` nothing reconnects.
+   *
+   * A sign-in from signed-out is `"cold"`: the sockets upgraded anonymously,
+   * and no view may resume from an anonymous cursor. A refreshed bearer under
+   * an unchanged identity is `"warm"`: the subscriptions resume from their
+   * cursors.
+   *
+   * A sign-out or an account switch leaves a previous identity behind and is
+   * evicted by `setAuthToken` before this is asked.
+   */
+  private reconcileUpgradeBearer;
+  private applyUpgradeBearer;
   /** Guard shared by every public entry point: a closed client accepts no further calls. */
   private assertOpen;
   /**
@@ -4374,6 +4465,11 @@ declare class LunoraClient {
    * shard still waking, a swallowed message) would otherwise leave the
    * subscription un-acked on a perfectly live socket until the next reconnect.
    * One retry, not a loop: a query that is merely slow must not be re-run repeatedly.
+   *
+   * The retry gets one ack window of its own (`final`), after which the frame is
+   * stood down so a later `subscribe()` can send again; otherwise a lost retry
+   * refuses every send until the next reconnect. Kept in `unackedWatchdogs`, so
+   * an ack or a teardown cancels either phase.
    */
   private armUnackedWatchdog;
   private sendShapeSubscribeIfOpen;
@@ -4859,6 +4955,14 @@ declare class LunoraClient {
   private restartTabCoordinatorForIdentity;
   /** Drop every room send held before the socket opened: they were made under the identity that is now going away. */
   private resetRoomSends;
+  /**
+   * Blank every live subscription and shape, forget their resume cursors, and
+   * reconnect every socket, so each resubscribe is a cold one the server
+   * re-seeds for the identity the new socket carries. Used when the socket's
+   * credential changes: resuming from a cursor taken under the previous one
+   * would splice a diff onto rows that identity was never shown.
+   */
+  private reconnectCold;
   /**
    * Close every open shard socket so each reconnects carrying the credential
    * in effect now.
@@ -4889,6 +4993,47 @@ declare class LunoraClient {
    * flush AND every write waiting on the barrier.
    */
   private flushOfflineQueue;
+  /**
+   * Where a snapshot precondition's subscription stands on its socket, when
+   * comparing would mislead: `"awaiting"` while a reconnect has un-answered it
+   * and no value has answered since (the comparison would judge the previous
+   * socket's value, or a blank), `"unreadable"` once that wait ended with no
+   * value to read. `undefined` for any other precondition or subscription.
+   */
+  private snapshotAnswer;
+  /**
+   * The precondition a queued write carries. A snapshot precondition reads as
+   * holding while its subscription is awaited, so `drainConflict` keeps the
+   * write rather than drop it on a blank the server acked but has not seeded
+   * yet (the drain then holds it back, {@link drainOfflineQueue}), and once the
+   * wait ended unreadable, which is no evidence the value changed.
+   */
+  private holdWhileUnanswered;
+  /**
+   * A follower's counterpart of a socket open in {@link markShardPendingAck}: every
+   * subscription awaits the leader's next relay. A follower cannot ask the leader for
+   * one, and the leader relays only the queries it holds itself, so the wait is bounded
+   * by the leader's own (an ack window and one retry) and ends unreadable, as the
+   * leader's does when it gives up.
+   */
+  private awaitLeaderAnswers;
+  /**
+   * Holds `state` for the leader's next relay. Its timer is its own, so settling
+   * one subscription early never releases another.
+   */
+  private awaitLeaderAnswer;
+  /**
+   * `state` has been answered on its socket (`readable`), or will not be: release
+   * any write held for it. Not called for an `ack`, which the server sends
+   * before the seed.
+   */
+  private settleAwaitedAnswer;
+  /**
+   * Put back a drained write whose snapshot cannot be compared yet, and every
+   * write behind it (replaying those first would reorder the shard), recording
+   * the hold so the answer flushes again. Returns the writes that may go on.
+   */
+  private holdUndecidedWrites;
   private drainOfflineQueue;
   /**
    * Ask for another flush of this shard after a backoff, because every entry it

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

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

package/dist/packem_shared/{preload.d-BSeSh11b.d.ts → preload.d-B26QlpOB.d.ts}

@@ -1,4 +1,4 @@
-import { L as LunoraClient, P as Preloaded } from "./lunora-client.d-BGbRstqH.js";
+import { L as LunoraClient, P as Preloaded } from "./lunora-client.d-7WaMRZUK.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-6WDEiJO5.d.mts → preload.d-CT_9YaL9.d.mts}

@@ -1,4 +1,4 @@
-import { L as LunoraClient, P as Preloaded } from "./lunora-client.d-B_eWE1gD.mjs";
+import { L as LunoraClient, P as Preloaded } from "./lunora-client.d-DtTKDhtw.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/snapshot-precondition-BEtcSbWr.mjs

@@ -0,0 +1 @@
+import{stableWireKey as p}from"@lunora/wire";const u=new WeakMap,i=(e,t)=>{u.set(e,t)},d=e=>e===void 0?void 0:u.get(e),h=(e,t,s,n)=>{const o=e.peekActiveQuerySnapshot(t.__lunoraRef,s,n),a=o.present&&o.answered?p(o.value):void 0,c=()=>{const r=e.peekActiveQuerySnapshot(t.__lunoraRef,s,n);return!o.present||!o.answered||!r.present||!r.answered?!0:p(r.value)===a};return a!==void 0&&i(c,{args:s,functionPath:t.__lunoraRef,shardKey:n}),c};export{h as c,i as r,d as s};

package/dist/packem_shared/wire-errors-BgFi7ONA.mjs

@@ -0,0 +1 @@
+import{LunoraError as n}from"@lunora/errors";import{decodeWire as d}from"@lunora/wire";import{TransportError as u,getRetryAfterMs as f}from"./CONFLICT_ERROR_CODE-B7qNZMMk.mjs";const l=t=>{if(t===null)return;const e=Number(t);if(Number.isFinite(e))return e>0?e*1e3:void 0;const r=Date.parse(t);if(Number.isNaN(r))return;const o=r-Date.now();return o>0?o:void 0},v=(t,e)=>{const r=l(e);if(!(r===void 0||f(t)!==void 0))return t.data===void 0?{retryAfterMs:r}:typeof t.data=="object"&&t.data!==null&&!Array.isArray(t.data)?{...t.data,retryAfterMs:r}:void 0},p=t=>{const e=t?.error;if(typeof e!="object"||e===null||Array.isArray(e))return;const{why:r,...o}=e;return typeof r=="string"?{...o,why:r}:o},E=()=>new u("LunoraClient: batch slot carried no error envelope"),i=(t,e)=>{const r=t.error,o=typeof r?.code=="string"?r.code:void 0,s=typeof r?.message=="string"?r.message:void 0;return{code:o,messageText:(typeof t.message=="string"?t.message:void 0)??s??e}},A=t=>{const{code:e,messageText:r}=i(t,"stream error"),o=t.error?.why,s=e===void 0?new Error(r):new n(e,r);return typeof o=="string"&&(s.why=o),s},R=t=>{const{code:e,messageText:r}=i(t,"subscription error"),o=t.error?.why;return{message:r,...e===void 0?{}:{code:e},...typeof o=="string"?{why:o}:{}}},y=Symbol.for("lunora.serverVerdict"),a=t=>{const e=new Error(t.message??"request failed");if(e.code=t.code,e[y]=!0,t.data!==void 0)try{e.data=d(t.data)}catch{}return t.hint!==void 0&&(e.hint=t.hint),t.docsUrl!==void 0&&(e.docsUrl=t.docsUrl),typeof t.why=="string"&&(e.why=t.why),e},m=t=>Object.freeze(Object.fromEntries([...t].filter(([e])=>e!=="set-cookie"))),b=(t,e)=>Object.defineProperty(t,"headers",{value:m(e)}),S=(t,e)=>{const r=a(t),o=v(r,e.get("retry-after"));return o!==void 0&&(r.data=o),b(r,e)},D=t=>{const e=p(t);return e===void 0?E():a(e)},c=new WeakSet,j=t=>{const e=new n("WIRE_DECODE_FAILED",`LunoraClient: the call succeeded but its result could not be decoded (a mutation has still committed) — ${t instanceof Error?t.message:String(t)}`,{cause:t});return c.add(e),e},M=t=>t instanceof Error&&c.has(t);export{l as a,S as b,A as c,R as d,p as e,E as f,M as i,a as r,D as s,j as u,b as w};

package/dist/query/index.d.mts

@@ -1,4 +1,4 @@
-import { S as SubscriptionError, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-B_eWE1gD.mjs";
+import { S as SubscriptionError, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-DtTKDhtw.mjs";
 export type {
 /**
  * `@lunora/client/query` — the framework-neutral live-query state machine shared
@@ -10,7 +10,7 @@ export type {
  * framework — each adapter supplies thin sinks that write into its own ref /
  * store / signal / cache.
  */
-b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-B_eWE1gD.mjs";
+b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DtTKDhtw.mjs";
 import { F as FunctionReference, A as ArgsOf, R as ReturnOf } from "../packem_shared/function-reference.d-Br_hsKje.mjs";
 import '@lunora/errors';
 import '@lunora/runtime';

package/dist/query/index.d.ts

@@ -1,4 +1,4 @@
-import { S as SubscriptionError, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-BGbRstqH.js";
+import { S as SubscriptionError, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-7WaMRZUK.js";
 export type {
 /**
  * `@lunora/client/query` — the framework-neutral live-query state machine shared
@@ -10,7 +10,7 @@ export type {
  * framework — each adapter supplies thin sinks that write into its own ref /
  * store / signal / cache.
  */
-b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-BGbRstqH.js";
+b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-7WaMRZUK.js";
 import { F as FunctionReference, A as ArgsOf, R as ReturnOf } from "../packem_shared/function-reference.d-Br_hsKje.js";
 import '@lunora/errors';
 import '@lunora/runtime';

package/dist/service.mjs

@@ -1 +1 @@
-import{LunoraError as c}from"@lunora/errors";import{encodeArgsOrThrow as d,decodeWire as y}from"@lunora/wire";import{e as f,r as w}from"./packem_shared/wire-errors-u1qRPmDJ.mjs";const v="/_lunora/rpc",N="https://lunora.internal",i=async(n,t,r,o,u)=>{const a=r.__lunoraRef,p=JSON.stringify({args:d("@lunora/client/service",a,o??{}),functionPath:a,...u?.shardKey===void 0?{}:{shardKey:u.shardKey}}),e=await n.fetch(new Request(`${N}${v}`,{body:p,headers:{"content-type":"application/json"},method:"POST"}));let s;try{s=await e.json()}catch{throw new c("INTERNAL",`@lunora/client/service: ${t} "${a}" got a non-JSON response (status ${e.status.toString()}). Check the service binding points at the Lunora Worker that declares this function.`,{status:e.status})}if(s===null||typeof s!="object")throw new c("INTERNAL",`@lunora/client/service: ${t} "${a}" returned a JSON body that is not an object (status ${e.status.toString()}). Check the service binding points at the Lunora Worker that declares this function.`,{status:e.status});const h=s,l=f(h);if(l!==void 0)throw w(l);if(!e.ok)throw new c("INTERNAL",`@lunora/client/service: ${t} "${a}" failed with status ${e.status.toString()} and no error envelope.`,{status:e.status});return y(h.result)},R=n=>({action:async(t,r,o)=>await i(n,"action",t,r,o),mutation:async(t,r,o)=>await i(n,"mutation",t,r,o),query:async(t,r,o)=>await i(n,"query",t,r,o)});export{v as RPC_PATH,R as createServiceClient};
+import{LunoraError as c}from"@lunora/errors";import{encodeArgsOrThrow as d,decodeWire as y}from"@lunora/wire";import{e as f,r as w}from"./packem_shared/wire-errors-BgFi7ONA.mjs";const v="/_lunora/rpc",N="https://lunora.internal",i=async(n,t,r,o,u)=>{const a=r.__lunoraRef,p=JSON.stringify({args:d("@lunora/client/service",a,o??{}),functionPath:a,...u?.shardKey===void 0?{}:{shardKey:u.shardKey}}),e=await n.fetch(new Request(`${N}${v}`,{body:p,headers:{"content-type":"application/json"},method:"POST"}));let s;try{s=await e.json()}catch{throw new c("INTERNAL",`@lunora/client/service: ${t} "${a}" got a non-JSON response (status ${e.status.toString()}). Check the service binding points at the Lunora Worker that declares this function.`,{status:e.status})}if(s===null||typeof s!="object")throw new c("INTERNAL",`@lunora/client/service: ${t} "${a}" returned a JSON body that is not an object (status ${e.status.toString()}). Check the service binding points at the Lunora Worker that declares this function.`,{status:e.status});const h=s,l=f(h);if(l!==void 0)throw w(l);if(!e.ok)throw new c("INTERNAL",`@lunora/client/service: ${t} "${a}" failed with status ${e.status.toString()} and no error envelope.`,{status:e.status});return y(h.result)},R=n=>({action:async(t,r,o)=>await i(n,"action",t,r,o),mutation:async(t,r,o)=>await i(n,"mutation",t,r,o),query:async(t,r,o)=>await i(n,"query",t,r,o)});export{v as RPC_PATH,R as createServiceClient};

package/dist/ssr/index.d.mts

@@ -1,4 +1,4 @@
-import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-B_eWE1gD.mjs";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-DtTKDhtw.mjs";
 export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/function-reference.d-Br_hsKje.mjs";
 export {
 /**
@@ -20,7 +20,7 @@ p as preloadQuery,
  * WebSocket or touches a UI framework, so it is safe to import from any SSR
  * loader.
  */
-a as preloadedQueryResult } from "../packem_shared/preload.d-6WDEiJO5.mjs";
+a as preloadedQueryResult } from "../packem_shared/preload.d-CT_9YaL9.mjs";
 import '@lunora/errors';
 import '@lunora/runtime';
 /**

package/dist/ssr/index.d.ts

@@ -1,4 +1,4 @@
-import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-BGbRstqH.js";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-7WaMRZUK.js";
 export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/function-reference.d-Br_hsKje.js";
 export {
 /**
@@ -20,7 +20,7 @@ p as preloadQuery,
  * WebSocket or touches a UI framework, so it is safe to import from any SSR
  * loader.
  */
-a as preloadedQueryResult } from "../packem_shared/preload.d-BSeSh11b.js";
+a as preloadedQueryResult } from "../packem_shared/preload.d-B26QlpOB.js";
 import '@lunora/errors';
 import '@lunora/runtime';
 /**

package/dist/ssr/index.mjs

@@ -1 +1 @@
-import{getServerSession as o}from"../packem_shared/getServerSession-BaOoo1p6.mjs";import{deserializePreloaded as l,serializePreloaded as t}from"../packem_shared/deserializePreloaded-CyFK_cv6.mjs";import{createServerClient as i}from"../packem_shared/createServerClient-T1RiYjZx.mjs";import{preloadQuery as s,preloadedQueryResult as f}from"../packem_shared/preloadQuery-uFy24PCR.mjs";export{i as createServerClient,l as deserializePreloaded,o as getServerSession,s as preloadQuery,f as preloadedQueryResult,t as serializePreloaded};
+import{getServerSession as o}from"../packem_shared/getServerSession-BaOoo1p6.mjs";import{deserializePreloaded as l,serializePreloaded as t}from"../packem_shared/deserializePreloaded-CyFK_cv6.mjs";import{createServerClient as i}from"../packem_shared/createServerClient-kd9cUs8g.mjs";import{preloadQuery as s,preloadedQueryResult as f}from"../packem_shared/preloadQuery-uFy24PCR.mjs";export{i as createServerClient,l as deserializePreloaded,o as getServerSession,s as preloadQuery,f as preloadedQueryResult,t as serializePreloaded};

package/package.json

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