@lunora/client 1.0.0-alpha.35 → 1.0.0-alpha.36

package/dist/packem_shared/TabCoordinator-CMFYQCL-.mjs

@@ -0,0 +1 @@
+let d=0;const n="lunora-bridge",o=1e3,h=3e3;class c{bc;tabId;heartbeatInterval;leaderTimeout;knownLeader=void 0;leader=!1;running=!1;promotionPending=!1;lastHeartbeat=0;heartbeatTimer=void 0;leaderCheckTimer=void 0;onBecomeLeader;onStopBeingLeader;onConnectionStatus;onSubscriptionData;onSubscriptionError;onSubscriptionSettled;constructor(e={}){if(d+=1,this.tabId=`tab_${String(d)}_${crypto.randomUUID()}`,this.heartbeatInterval=e.heartbeatInterval??o,this.leaderTimeout=e.leaderTimeout??h,this.onBecomeLeader=e.onBecomeLeader,this.onStopBeingLeader=e.onStopBeingLeader,this.onConnectionStatus=e.onConnectionStatus,this.onSubscriptionData=e.onSubscriptionData,this.onSubscriptionError=e.onSubscriptionError,this.onSubscriptionSettled=e.onSubscriptionSettled,typeof BroadcastChannel>"u"){this.bc=void 0;return}this.bc=new BroadcastChannel(e.channelName??n),this.bc.addEventListener("message",t=>{this.handleMessage(t.data)})}start(){if(!this.running){if(this.running=!0,this.bc===void 0){this.becomeLeader();return}this.broadcast({type:"claim-leadership",tabId:this.tabId,ts:Date.now()}),setTimeout(()=>{this.running&&this.knownLeader===void 0&&this.becomeLeader()},this.leaderTimeout),this.leaderCheckTimer=setInterval(()=>{this.checkLeaderHealth()},this.leaderTimeout),this.heartbeatTimer=setInterval(()=>{this.sendHeartbeat()},this.heartbeatInterval)}}stop(){this.running=!1,this.leader&&(this.broadcast({type:"yield-leadership",tabId:this.tabId}),this.leader=!1,this.knownLeader=void 0,this.onStopBeingLeader?.()),this.heartbeatTimer!==void 0&&(clearInterval(this.heartbeatTimer),this.heartbeatTimer=void 0),this.leaderCheckTimer!==void 0&&(clearInterval(this.leaderCheckTimer),this.leaderCheckTimer=void 0),this.bc?.close()}isLeader(){return this.leader}promoteImmediately(){this.running&&this.becomeLeader()}get leaderTabId(){return this.knownLeader}get id(){return this.tabId}get isRunning(){return this.running}broadcastSubscriptionData(e,t,a,i,s){this.leader&&this.broadcast({type:"subscription-data",tabId:this.tabId,key:e,data:t,...a===void 0?{}:{cursor:a},...i===void 0?{}:{epoch:i},...s===void 0?{}:{identity:s}})}broadcastSubscriptionError(e,t){this.leader&&this.broadcast({type:"subscription-error",tabId:this.tabId,key:e,error:t})}broadcastSubscriptionSettled(e,t,a,i,s,r){this.leader&&this.broadcast({type:"subscription-settled",tabId:this.tabId,key:e,...t===void 0?{}:{cursor:t},...a===void 0?{}:{epoch:a},...i===void 0?{}:{lastMutationId:i},...s===void 0?{}:{clientId:s},...r===void 0?{}:{identity:r}})}broadcastConnectionStatus(e,t){this.leader&&this.broadcast({type:"connection-status",tabId:this.tabId,status:e,...t===void 0?{}:{identity:t}})}broadcast(e){this.bc?.postMessage(e)}handleMessage(e){switch(e.type){case"claim-leadership":{this.handleClaimLeadership(e);break}case"connection-status":{if(this.leader||e.tabId===this.tabId)break;this.onConnectionStatus?.(e.status,e.identity);break}case"heartbeat":{this.handleHeartbeat(e);break}case"subscription-data":{if(this.leader||e.tabId===this.tabId)break;this.onSubscriptionData?.(e.key,e.data,e.cursor,e.epoch,e.identity);break}case"subscription-error":{if(this.leader||e.tabId===this.tabId)break;this.onSubscriptionError?.(e.key,e.error);break}case"subscription-settled":{if(this.leader||e.tabId===this.tabId)break;this.onSubscriptionSettled?.(e.key,e.cursor,e.epoch,e.lastMutationId,e.clientId,e.identity);break}case"yield-leadership":{this.knownLeader===e.tabId&&(this.knownLeader=void 0,this.running&&!this.leader&&this.claimAndPromote());break}}}handleClaimLeadership(e){if(e.tabId!==this.tabId){if(this.leader){this.broadcast({type:"heartbeat",tabId:this.tabId,ts:Date.now()});return}this.knownLeader===void 0&&e.tabId<this.tabId&&(this.knownLeader=e.tabId,this.lastHeartbeat=e.ts)}}handleHeartbeat(e){if(e.tabId!==this.tabId){if(this.leader){this.resolveLeaderVsLeaderTieBreak(e);return}this.lastHeartbeat=e.ts,this.knownLeader=e.tabId}}resolveLeaderVsLeaderTieBreak(e){e.tabId<this.tabId?(this.leader=!1,this.knownLeader=e.tabId,this.lastHeartbeat=e.ts,this.onStopBeingLeader?.()):this.broadcast({type:"heartbeat",tabId:this.tabId,ts:Date.now()})}becomeLeader(){this.leader||(this.leader=!0,this.knownLeader=this.tabId,this.lastHeartbeat=Date.now(),this.onBecomeLeader?.(),this.broadcast({type:"heartbeat",tabId:this.tabId,ts:Date.now()}))}sendHeartbeat(){this.leader&&this.broadcast({type:"heartbeat",tabId:this.tabId,ts:Date.now()})}checkLeaderHealth(){if(!(!this.running||this.leader)){if(this.knownLeader===void 0){this.claimAndPromote();return}Date.now()-this.lastHeartbeat>this.leaderTimeout&&(this.knownLeader=void 0,this.claimAndPromote())}}claimAndPromote(){this.promotionPending||(this.promotionPending=!0,this.broadcast({type:"claim-leadership",tabId:this.tabId,ts:Date.now()}),setTimeout(()=>{this.promotionPending=!1,this.running&&this.knownLeader===void 0&&this.becomeLeader()},this.leaderTimeout))}}export{c as TabCoordinator};

package/dist/packem_shared/{createServerClient-DX7Dk2w2.mjs → createServerClient-Bc6O-zYd.mjs}

@@ -1 +1 @@
-import{LunoraClient as r}from"./LunoraClient-DRo2LNe9.mjs";const o=t=>{const e=new r({fetch:t.fetch,url:t.url});return t.token!==void 0&&e.setAuthToken(t.token),e};export{o as createServerClient};
+import{LunoraClient as r}from"./LunoraClient-NUIJBf6Z.mjs";const o=t=>{const e=new r({fetch:t.fetch,url:t.url});return t.token!==void 0&&e.setAuthToken(t.token),e};export{o as createServerClient};

package/dist/packem_shared/{lunora-client.d-DLcz4GRz.d.mts → lunora-client.d-CQ4K1Ls8.d.mts}

@@ -1492,6 +1492,24 @@ declare class LunoraClient {
    * Not `readonly` — `close()` clears it (mirrors `outboxLeaderRelease`).
    */
   private tabCoordinator;
+  /**
+   * The leader's last-broadcast aggregate {@link ConnectionStatus}, mirrored
+   * on a follower tab — which owns no `ShardConnection` of its own to
+   * compute a status from (see `computeStatus`). `undefined` until the
+   * leader's first broadcast (falls back to `"idle"`), and reset back to
+   * `undefined` whenever this tab stops being a follower of the CURRENT
+   * leader (becomes leader itself, or the leader changes), so a stale
+   * mirror from a previous leader never survives a leadership change.
+   */
+  private leaderStatus;
+  /**
+   * Sticky "has the mirrored leader status ever reported `connected`" flag —
+   * the follower's counterpart to {@link ShardConnection.wasEverConnected},
+   * since a follower has no `ShardConnection` of its own. Feeds the
+   * offline-queue gate (see `mutation`) exactly like the real per-shard flag
+   * does on the leader/single-tab path.
+   */
+  private leaderWasEverConnected;
   /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
   private readonly connections;
   /** Default `connect`-envelope context applied to a shard with no explicit override. */
@@ -1534,6 +1552,17 @@ declare class LunoraClient {
    * See `identityFingerprint` for the fingerprint shape.
    */
   private readonly queuedIdentities;
+  /**
+   * Distinct shard keys with a mutation currently sitting in `offlineQueue`
+   * — fresh writes queued this session (`enqueueOfflineMutation`) or writes
+   * restored from durable storage (`hydratePersistedQueue`). A follower tab
+   * has no per-shard `ShardConnection` to iterate when its mirrored leader
+   * status turns `"connected"` (see the `onConnectionStatus` coordinator
+   * option), so this is what that flush walks instead. Entries are never
+   * removed — flushing an already-empty shard is a cheap no-op, and the set
+   * is bounded by the app's own distinct shard-key cardinality.
+   */
+  private readonly queuedOfflineShardKeys;
   private closed;
   /** Subscribers to auth-token changes (see `onAuthTokenChange`). */
   private readonly authTokenListeners;
@@ -2624,6 +2653,25 @@ declare class LunoraClient {
     signal?: AbortSignal;
   }): StreamIterable<HttpStreamChunkOf<Ref>>;
   close(): void;
+  /**
+   * Tear down one {@link ShardConnection}'s live state: clear its reconnect/
+   * connect timers, stop its heartbeat, and close its socket (if any).
+   * Shared by `close()` (terminal) and the cross-tab `onStopBeingLeader`
+   * handler (demoted, but still alive) so a demoted leader can't leak a
+   * pending `reconnectTimer` or an open socket's `heartbeatTimer` the way
+   * an inline `conn.socket?.close()` — which skips both — used to.
+   */
+  private teardownConnection;
+  /**
+   * Build (but do not start) this client's `TabCoordinator`. Extracted out of
+   * the constructor so `setAuthToken` can rebuild it on an identity change —
+   * the default channel name embeds the identity fingerprint (see below), so
+   * a new identity needs a new coordinator on a new channel. The callback
+   * bodies are the drift-sensitive region (a hand-merged identity guard on
+   * the shard message listener sits ahead of an extracted `lastFrameAt`
+   * stamp elsewhere in this file) — moved verbatim, not reflowed.
+   */
+  private createTabCoordinator;
   /**
    * 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
@@ -2717,6 +2765,19 @@ declare class LunoraClient {
    */
   private applyOptimisticUpdate;
   private getConnection;
+  /**
+   * The `(wsState, hasSocket, wasEverConnected)` triple `mutation()`'s
+   * offline-queue gate reads. On the leader/single-tab path this is exactly
+   * the real `ShardConnection`'s state (byte-identical to the pre-cross-tab
+   * behavior). A follower has no `ShardConnection` of its own (see
+   * `ensureSocket`), so it derives the same triple from the mirrored
+   * `leaderStatus`/`leaderWasEverConnected` instead: `"connected"` maps to
+   * `"open"` (queue-eligible once `wasEverConnected`), `"connecting"` stays
+   * `"connecting"` (the mid-reconnect queue branch), anything else is
+   * `"idle"`. `hasSocket` is always `false` for a follower — it never has
+   * one.
+   */
+  private connectionGateState;
   private getOrCreateConnection;
   private wsUrlFor;
   /**
@@ -2778,15 +2839,46 @@ declare class LunoraClient {
    * a silent tokenless socket the admin gate would reject.
    */
   private openSocketWithProvidedToken;
+  /**
+   * Construct one WebSocket connection attempt and wire the shared
+   * lifecycle guarantees around it — the fail-fast connect-timeout, the
+   * identity guard that stops a superseded attempt's late `open`/`message`/
+   * `close`/`error` from touching a connection a newer attempt already
+   * owns, and (once open) the keepalive heartbeat with its half-open
+   * watchdog (plan 217). One call opens ONE attempt; the caller owns
+   * reconnect scheduling from `onClose` — mirrors the shard's existing
+   * `ensureSocket` / `handleDisconnect` split, now shared with
+   * `subscribeScheduledJobs` so it stops re-living the bug that split
+   * already fixed once (CLIENT-05).
+   *
+   * The identity guard is `conn.socket !== socket`, re-checked before every
+   * action below. `conn.socket` is reassigned to a new attempt's socket
+   * synchronously — right here, before `open` ever fires — so an older
+   * attempt's guard trips the instant it's superseded, even if its
+   * underlying socket only fires its real `close`/`error` much later. This
+   * ordering is load-bearing: preserve it exactly.
+   */
+  private openManagedSocket;
   /** Construct the shard socket and wire its lifecycle handlers. The connection must already be in the `connecting` state. */
   private openSocket;
   private handleDisconnect;
   /**
-   * Begin the keepalive heartbeat on an open connection. Each tick sends a
-   * {@link WS_KEEPALIVE_PING} text frame the server answers from its
-   * hibernation auto-response without waking the DO. A no-op when the
-   * heartbeat is disabled (an interval of zero or less); idempotent — any
-   * existing timer is cleared first so a reconnect can't leak intervals.
+   * Begin the keepalive heartbeat on an open connection attempt — the only
+   * caller is {@link openManagedSocket}'s own `open` handler, so both the
+   * shard socket and `subscribeScheduledJobs` share this one implementation
+   * instead of each hand-rolling their own (plan 217, generalized).
+   *
+   * Each tick first checks the half-open watchdog (see
+   * {@link ManagedSocketState.lastFrameAt}): if no frame at all has arrived
+   * within `heartbeatIntervalMs * 2.5`, the far end has gone quiet without
+   * the socket ever firing `close` — force it closed and report it through
+   * `onWatchdogTrip` (the caller's `onClose`) so the normal reconnect/backoff
+   * takes over instead of every live query on it silently staling forever.
+   * Otherwise it sends a {@link WS_KEEPALIVE_PING} text frame the server
+   * answers from its hibernation auto-response without waking the DO. A
+   * no-op when the heartbeat is disabled (an interval of zero or less);
+   * idempotent — any existing timer is cleared first so a reconnect can't
+   * leak intervals.
    */
   private startHeartbeat;
   /** Clear a connection's keepalive timer, if any. Safe to call repeatedly. */
@@ -2848,6 +2940,23 @@ declare class LunoraClient {
   private dispatchWhisper;
   /** Notify every {@link onTokenExpired} listener (best-effort, listener throws swallowed). */
   private notifyTokenExpired;
+  /**
+   * CLIENT-04: `type: "complete"` today is sent ONLY by `@lunora/do`'s
+   * `handleStream` (see `shard-do.ts`), gated to the `stream` envelope type
+   * and minting only `stream_*` ids — the `subscribe` path never sends it, so
+   * a live SUBSCRIPTION provably never receives `complete` from the current
+   * server. But `ServerCompleteMessage` is a generic `id`-keyed frame and
+   * `ShardDO` is user-subclassable, so this stays defensive rather than
+   * assuming a `sub_*` id can never reach here: unlike the historical
+   * `subscriptions.remove(state)`, which dropped the state out of
+   * `subscriptions.all()` — the set the reconnect resubscribe loop walks
+   * (`ensureSocket`'s `open` handler) — and so froze the query forever across
+   * every future reconnect, this fans a cancellation error to any listener
+   * and marks the registration un-acked instead. Non-destructive: the state
+   * stays in the registry, so the very next reconnect resubscribes it. The
+   * two id-spaces don't overlap (`sub_*` vs `stream_*`), so the stream and
+   * subscription lookups below are mutually exclusive.
+   */
   private handleCompleteMessage;
   private unpersist;
   /**
@@ -2910,6 +3019,18 @@ declare class LunoraClient {
    * the durable `clear()` is best-effort.
    */
   private clearQueryCacheForIdentityChange;
+  /**
+   * Flush every shard with a mutation currently queued in `offlineQueue`
+   * (see `queuedOfflineShardKeys`). Used on a FOLLOWER tab when the
+   * mirrored leader status transitions to `"connected"` — a follower has no
+   * per-shard `ShardConnection` reconnect event to hang the usual
+   * single-shard `flushOfflineQueue(shardKey)` call off of (see the
+   * `handleConnect` call site), so this walks every shard that might have
+   * something queued instead. Flushing an already-empty shard is a cheap
+   * no-op (`flushOfflineQueue` returns immediately once `drain` yields
+   * nothing), so over-inclusion here is harmless.
+   */
+  private flushAllOfflineQueues;
   private flushOfflineQueue;
   /**
    * Partition already-gated writes into the encodable ones (returned) and reject
@@ -2984,4 +3105,4 @@ declare class LunoraClient {
    */
   private settleReplayBatchSlots;
 }
-export { SchedulerStatus as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, LunoraErrorCode as E, FunctionReference as F, GlobalFacetResult as G, HttpStreamRef as H, MutationSettledEvent as I, OptimisticLocalStore as J, OptimisticUpdate as K, LunoraClient as L, MutationCallOptions as M, OutboxMutation as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, OutboxSink as T, User as U, PersistedMutation as V, RowOp as W, RpcEnvelope as X, RpcResponseBody as Y, ScheduleRecord as Z, SchedulerPoolStatus as _, Unsubscribe as a, ServerMessage as a0, ServerPokeEndMessage as a1, ServerPokePartMessage as a2, ServerPokeStartMessage as a3, ShardTrafficEntry as a4, ShardTrafficResult as a5, StorageListPage as a6, StorageObject as a7, StreamHandle as a8, SubscriptionCallback as a9, SubscriptionRegistry as aa, SubscriptionState as ab, SyncWatermark as ac, WorkflowInstanceAction as ad, WorkflowInstanceDetail as ae, WorkflowInstancePage as af, WorkflowInstanceStatus as ag, WorkflowInstanceSummary as ah, WorkflowStepDetail as ai, WsTokenProvider as aj, createClientQuery as ak, createLocalStore as al, createStream as am, getErrorCode as an, getRetryAfterMs as ao, isConflictError as ap, isForbiddenError as aq, isRateLimitedError as ar, isUnauthorizedError as as, SubscriptionErrorCallback as b, PersistenceAdapter as c, HttpStreamArgsOf as d, HttpStreamChunkOf as e, StreamIterable as f, ReconnectOptions as g, BatchSlot as h, CachedQuery as i, ClientDebugShard as j, ClientDebugSnapshot as k, ClientDebugSubscription as l, ClientMessage as m, ClientQueryRef as n, ClientShapeSubscribeMessage as o, ClientShapeUnsubscribeMessage as p, ConnectionStatus as q, FunctionArgumentDescriptor as r, FunctionDescriptor as s, GlobalFacetValue as t, GlobalFilterClause as u, GlobalTableInfo as v, GlobalTablePage as w, HttpStreamCallArgs as x, LunoraClientError as y, LunoraClientOptions as z };
+export { SchedulerStatus as $, ArgsOf as A, BookmarkStorage as B, ConnectionStatus as C, DEFAULT_MAX_BUFFER as D, LunoraErrorCode as E, FunctionReference as F, GlobalFacetResult as G, HttpStreamRef as H, MutationSettledEvent as I, OptimisticLocalStore as J, OptimisticUpdate as K, LunoraClient as L, MutationCallOptions as M, OutboxMutation as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, OutboxSink as T, User as U, PersistedMutation as V, RowOp as W, RpcEnvelope as X, RpcResponseBody as Y, ScheduleRecord as Z, SchedulerPoolStatus as _, Unsubscribe as a, ServerMessage as a0, ServerPokeEndMessage as a1, ServerPokePartMessage as a2, ServerPokeStartMessage as a3, ShardTrafficEntry as a4, ShardTrafficResult as a5, StorageListPage as a6, StorageObject as a7, StreamHandle as a8, SubscriptionCallback as a9, SubscriptionRegistry as aa, SubscriptionState as ab, SyncWatermark as ac, WorkflowInstanceAction as ad, WorkflowInstanceDetail as ae, WorkflowInstancePage as af, WorkflowInstanceStatus as ag, WorkflowInstanceSummary as ah, WorkflowStepDetail as ai, WsTokenProvider as aj, createClientQuery as ak, createLocalStore as al, createStream as am, getErrorCode as an, getRetryAfterMs as ao, isConflictError as ap, isForbiddenError as aq, isRateLimitedError as ar, isUnauthorizedError as as, SubscriptionErrorCallback as b, PersistenceAdapter as c, HttpStreamArgsOf as d, HttpStreamChunkOf as e, StreamIterable as f, ReconnectOptions as g, BatchSlot as h, CONFLICT_ERROR_CODE as i, CachedQuery as j, ClientDebugShard as k, ClientDebugSnapshot as l, ClientDebugSubscription as m, ClientMessage as n, ClientQueryRef as o, ClientShapeSubscribeMessage as p, ClientShapeUnsubscribeMessage as q, FunctionArgumentDescriptor as r, FunctionDescriptor as s, GlobalFacetValue as t, GlobalFilterClause as u, GlobalTableInfo as v, GlobalTablePage as w, HttpStreamCallArgs as x, LunoraClientError as y, LunoraClientOptions as z };

package/dist/packem_shared/{lunora-client.d-DLcz4GRz.d.ts → lunora-client.d-CQ4K1Ls8.d.ts}

@@ -1492,6 +1492,24 @@ declare class LunoraClient {
    * Not `readonly` — `close()` clears it (mirrors `outboxLeaderRelease`).
    */
   private tabCoordinator;
+  /**
+   * The leader's last-broadcast aggregate {@link ConnectionStatus}, mirrored
+   * on a follower tab — which owns no `ShardConnection` of its own to
+   * compute a status from (see `computeStatus`). `undefined` until the
+   * leader's first broadcast (falls back to `"idle"`), and reset back to
+   * `undefined` whenever this tab stops being a follower of the CURRENT
+   * leader (becomes leader itself, or the leader changes), so a stale
+   * mirror from a previous leader never survives a leadership change.
+   */
+  private leaderStatus;
+  /**
+   * Sticky "has the mirrored leader status ever reported `connected`" flag —
+   * the follower's counterpart to {@link ShardConnection.wasEverConnected},
+   * since a follower has no `ShardConnection` of its own. Feeds the
+   * offline-queue gate (see `mutation`) exactly like the real per-shard flag
+   * does on the leader/single-tab path.
+   */
+  private leaderWasEverConnected;
   /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
   private readonly connections;
   /** Default `connect`-envelope context applied to a shard with no explicit override. */
@@ -1534,6 +1552,17 @@ declare class LunoraClient {
    * See `identityFingerprint` for the fingerprint shape.
    */
   private readonly queuedIdentities;
+  /**
+   * Distinct shard keys with a mutation currently sitting in `offlineQueue`
+   * — fresh writes queued this session (`enqueueOfflineMutation`) or writes
+   * restored from durable storage (`hydratePersistedQueue`). A follower tab
+   * has no per-shard `ShardConnection` to iterate when its mirrored leader
+   * status turns `"connected"` (see the `onConnectionStatus` coordinator
+   * option), so this is what that flush walks instead. Entries are never
+   * removed — flushing an already-empty shard is a cheap no-op, and the set
+   * is bounded by the app's own distinct shard-key cardinality.
+   */
+  private readonly queuedOfflineShardKeys;
   private closed;
   /** Subscribers to auth-token changes (see `onAuthTokenChange`). */
   private readonly authTokenListeners;
@@ -2624,6 +2653,25 @@ declare class LunoraClient {
     signal?: AbortSignal;
   }): StreamIterable<HttpStreamChunkOf<Ref>>;
   close(): void;
+  /**
+   * Tear down one {@link ShardConnection}'s live state: clear its reconnect/
+   * connect timers, stop its heartbeat, and close its socket (if any).
+   * Shared by `close()` (terminal) and the cross-tab `onStopBeingLeader`
+   * handler (demoted, but still alive) so a demoted leader can't leak a
+   * pending `reconnectTimer` or an open socket's `heartbeatTimer` the way
+   * an inline `conn.socket?.close()` — which skips both — used to.
+   */
+  private teardownConnection;
+  /**
+   * Build (but do not start) this client's `TabCoordinator`. Extracted out of
+   * the constructor so `setAuthToken` can rebuild it on an identity change —
+   * the default channel name embeds the identity fingerprint (see below), so
+   * a new identity needs a new coordinator on a new channel. The callback
+   * bodies are the drift-sensitive region (a hand-merged identity guard on
+   * the shard message listener sits ahead of an extracted `lastFrameAt`
+   * stamp elsewhere in this file) — moved verbatim, not reflowed.
+   */
+  private createTabCoordinator;
   /**
    * 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
@@ -2717,6 +2765,19 @@ declare class LunoraClient {
    */
   private applyOptimisticUpdate;
   private getConnection;
+  /**
+   * The `(wsState, hasSocket, wasEverConnected)` triple `mutation()`'s
+   * offline-queue gate reads. On the leader/single-tab path this is exactly
+   * the real `ShardConnection`'s state (byte-identical to the pre-cross-tab
+   * behavior). A follower has no `ShardConnection` of its own (see
+   * `ensureSocket`), so it derives the same triple from the mirrored
+   * `leaderStatus`/`leaderWasEverConnected` instead: `"connected"` maps to
+   * `"open"` (queue-eligible once `wasEverConnected`), `"connecting"` stays
+   * `"connecting"` (the mid-reconnect queue branch), anything else is
+   * `"idle"`. `hasSocket` is always `false` for a follower — it never has
+   * one.
+   */
+  private connectionGateState;
   private getOrCreateConnection;
   private wsUrlFor;
   /**
@@ -2778,15 +2839,46 @@ declare class LunoraClient {
    * a silent tokenless socket the admin gate would reject.
    */
   private openSocketWithProvidedToken;
+  /**
+   * Construct one WebSocket connection attempt and wire the shared
+   * lifecycle guarantees around it — the fail-fast connect-timeout, the
+   * identity guard that stops a superseded attempt's late `open`/`message`/
+   * `close`/`error` from touching a connection a newer attempt already
+   * owns, and (once open) the keepalive heartbeat with its half-open
+   * watchdog (plan 217). One call opens ONE attempt; the caller owns
+   * reconnect scheduling from `onClose` — mirrors the shard's existing
+   * `ensureSocket` / `handleDisconnect` split, now shared with
+   * `subscribeScheduledJobs` so it stops re-living the bug that split
+   * already fixed once (CLIENT-05).
+   *
+   * The identity guard is `conn.socket !== socket`, re-checked before every
+   * action below. `conn.socket` is reassigned to a new attempt's socket
+   * synchronously — right here, before `open` ever fires — so an older
+   * attempt's guard trips the instant it's superseded, even if its
+   * underlying socket only fires its real `close`/`error` much later. This
+   * ordering is load-bearing: preserve it exactly.
+   */
+  private openManagedSocket;
   /** Construct the shard socket and wire its lifecycle handlers. The connection must already be in the `connecting` state. */
   private openSocket;
   private handleDisconnect;
   /**
-   * Begin the keepalive heartbeat on an open connection. Each tick sends a
-   * {@link WS_KEEPALIVE_PING} text frame the server answers from its
-   * hibernation auto-response without waking the DO. A no-op when the
-   * heartbeat is disabled (an interval of zero or less); idempotent — any
-   * existing timer is cleared first so a reconnect can't leak intervals.
+   * Begin the keepalive heartbeat on an open connection attempt — the only
+   * caller is {@link openManagedSocket}'s own `open` handler, so both the
+   * shard socket and `subscribeScheduledJobs` share this one implementation
+   * instead of each hand-rolling their own (plan 217, generalized).
+   *
+   * Each tick first checks the half-open watchdog (see
+   * {@link ManagedSocketState.lastFrameAt}): if no frame at all has arrived
+   * within `heartbeatIntervalMs * 2.5`, the far end has gone quiet without
+   * the socket ever firing `close` — force it closed and report it through
+   * `onWatchdogTrip` (the caller's `onClose`) so the normal reconnect/backoff
+   * takes over instead of every live query on it silently staling forever.
+   * Otherwise it sends a {@link WS_KEEPALIVE_PING} text frame the server
+   * answers from its hibernation auto-response without waking the DO. A
+   * no-op when the heartbeat is disabled (an interval of zero or less);
+   * idempotent — any existing timer is cleared first so a reconnect can't
+   * leak intervals.
    */
   private startHeartbeat;
   /** Clear a connection's keepalive timer, if any. Safe to call repeatedly. */
@@ -2848,6 +2940,23 @@ declare class LunoraClient {
   private dispatchWhisper;
   /** Notify every {@link onTokenExpired} listener (best-effort, listener throws swallowed). */
   private notifyTokenExpired;
+  /**
+   * CLIENT-04: `type: "complete"` today is sent ONLY by `@lunora/do`'s
+   * `handleStream` (see `shard-do.ts`), gated to the `stream` envelope type
+   * and minting only `stream_*` ids — the `subscribe` path never sends it, so
+   * a live SUBSCRIPTION provably never receives `complete` from the current
+   * server. But `ServerCompleteMessage` is a generic `id`-keyed frame and
+   * `ShardDO` is user-subclassable, so this stays defensive rather than
+   * assuming a `sub_*` id can never reach here: unlike the historical
+   * `subscriptions.remove(state)`, which dropped the state out of
+   * `subscriptions.all()` — the set the reconnect resubscribe loop walks
+   * (`ensureSocket`'s `open` handler) — and so froze the query forever across
+   * every future reconnect, this fans a cancellation error to any listener
+   * and marks the registration un-acked instead. Non-destructive: the state
+   * stays in the registry, so the very next reconnect resubscribes it. The
+   * two id-spaces don't overlap (`sub_*` vs `stream_*`), so the stream and
+   * subscription lookups below are mutually exclusive.
+   */
   private handleCompleteMessage;
   private unpersist;
   /**
@@ -2910,6 +3019,18 @@ declare class LunoraClient {
    * the durable `clear()` is best-effort.
    */
   private clearQueryCacheForIdentityChange;
+  /**
+   * Flush every shard with a mutation currently queued in `offlineQueue`
+   * (see `queuedOfflineShardKeys`). Used on a FOLLOWER tab when the
+   * mirrored leader status transitions to `"connected"` — a follower has no
+   * per-shard `ShardConnection` reconnect event to hang the usual
+   * single-shard `flushOfflineQueue(shardKey)` call off of (see the
+   * `handleConnect` call site), so this walks every shard that might have
+   * something queued instead. Flushing an already-empty shard is a cheap
+   * no-op (`flushOfflineQueue` returns immediately once `drain` yields
+   * nothing), so over-inclusion here is harmless.
+   */
+  private flushAllOfflineQueues;
   private flushOfflineQueue;
   /**
    * Partition already-gated writes into the encodable ones (returned) and reject
@@ -2984,4 +3105,4 @@ declare class LunoraClient {
    */
   private settleReplayBatchSlots;
 }
-export { SchedulerStatus as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, LunoraErrorCode as E, FunctionReference as F, GlobalFacetResult as G, HttpStreamRef as H, MutationSettledEvent as I, OptimisticLocalStore as J, OptimisticUpdate as K, LunoraClient as L, MutationCallOptions as M, OutboxMutation as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, OutboxSink as T, User as U, PersistedMutation as V, RowOp as W, RpcEnvelope as X, RpcResponseBody as Y, ScheduleRecord as Z, SchedulerPoolStatus as _, Unsubscribe as a, ServerMessage as a0, ServerPokeEndMessage as a1, ServerPokePartMessage as a2, ServerPokeStartMessage as a3, ShardTrafficEntry as a4, ShardTrafficResult as a5, StorageListPage as a6, StorageObject as a7, StreamHandle as a8, SubscriptionCallback as a9, SubscriptionRegistry as aa, SubscriptionState as ab, SyncWatermark as ac, WorkflowInstanceAction as ad, WorkflowInstanceDetail as ae, WorkflowInstancePage as af, WorkflowInstanceStatus as ag, WorkflowInstanceSummary as ah, WorkflowStepDetail as ai, WsTokenProvider as aj, createClientQuery as ak, createLocalStore as al, createStream as am, getErrorCode as an, getRetryAfterMs as ao, isConflictError as ap, isForbiddenError as aq, isRateLimitedError as ar, isUnauthorizedError as as, SubscriptionErrorCallback as b, PersistenceAdapter as c, HttpStreamArgsOf as d, HttpStreamChunkOf as e, StreamIterable as f, ReconnectOptions as g, BatchSlot as h, CachedQuery as i, ClientDebugShard as j, ClientDebugSnapshot as k, ClientDebugSubscription as l, ClientMessage as m, ClientQueryRef as n, ClientShapeSubscribeMessage as o, ClientShapeUnsubscribeMessage as p, ConnectionStatus as q, FunctionArgumentDescriptor as r, FunctionDescriptor as s, GlobalFacetValue as t, GlobalFilterClause as u, GlobalTableInfo as v, GlobalTablePage as w, HttpStreamCallArgs as x, LunoraClientError as y, LunoraClientOptions as z };
+export { SchedulerStatus as $, ArgsOf as A, BookmarkStorage as B, ConnectionStatus as C, DEFAULT_MAX_BUFFER as D, LunoraErrorCode as E, FunctionReference as F, GlobalFacetResult as G, HttpStreamRef as H, MutationSettledEvent as I, OptimisticLocalStore as J, OptimisticUpdate as K, LunoraClient as L, MutationCallOptions as M, OutboxMutation as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, OutboxSink as T, User as U, PersistedMutation as V, RowOp as W, RpcEnvelope as X, RpcResponseBody as Y, ScheduleRecord as Z, SchedulerPoolStatus as _, Unsubscribe as a, ServerMessage as a0, ServerPokeEndMessage as a1, ServerPokePartMessage as a2, ServerPokeStartMessage as a3, ShardTrafficEntry as a4, ShardTrafficResult as a5, StorageListPage as a6, StorageObject as a7, StreamHandle as a8, SubscriptionCallback as a9, SubscriptionRegistry as aa, SubscriptionState as ab, SyncWatermark as ac, WorkflowInstanceAction as ad, WorkflowInstanceDetail as ae, WorkflowInstancePage as af, WorkflowInstanceStatus as ag, WorkflowInstanceSummary as ah, WorkflowStepDetail as ai, WsTokenProvider as aj, createClientQuery as ak, createLocalStore as al, createStream as am, getErrorCode as an, getRetryAfterMs as ao, isConflictError as ap, isForbiddenError as aq, isRateLimitedError as ar, isUnauthorizedError as as, SubscriptionErrorCallback as b, PersistenceAdapter as c, HttpStreamArgsOf as d, HttpStreamChunkOf as e, StreamIterable as f, ReconnectOptions as g, BatchSlot as h, CONFLICT_ERROR_CODE as i, CachedQuery as j, ClientDebugShard as k, ClientDebugSnapshot as l, ClientDebugSubscription as m, ClientMessage as n, ClientQueryRef as o, ClientShapeSubscribeMessage as p, ClientShapeUnsubscribeMessage as q, FunctionArgumentDescriptor as r, FunctionDescriptor as s, GlobalFacetValue as t, GlobalFilterClause as u, GlobalTableInfo as v, GlobalTablePage as w, HttpStreamCallArgs as x, LunoraClientError as y, LunoraClientOptions as z };

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

@@ -0,0 +1 @@
+let c=0;const a=()=>{if(typeof crypto<"u"&&typeof crypto.randomUUID=="function")return crypto.randomUUID();c+=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)}_${c.toString(36)}_${r}`},f=(r,t)=>r!==void 0&&t!==r,d=a,h=(r,t,e,i)=>{if(r){r({error:e,mutationId:i,operation:t});return}console.warn(`[lunora] offline-queue persistence ${t} failed`,e)};class u{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??=d(),this.items.push(e),this.persistence?.append({args:e.args,functionPath:e.functionPath,id:e.id,identity:e.identity,shardKey:e.shardKey,...this.version===void 0?{}:{version:this.version}}).catch(i=>{h(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 h(this.onPersistenceError,"load",s),s}const e=[];for(const s of t)if(!(this.items.some(o=>o.id===s.id)||e.some(o=>o.id===s.id))){if(f(this.version,s.version)){this.persistence.remove(s.id).catch(o=>{h(this.onPersistenceError,"remove",o,s.id)});continue}e.push({args:s.args,functionPath:s.functionPath,id:s.id,identity:s.identity,reject:()=>{},resolve:()=>{},shardKey:s.shardKey})}this.items.unshift(...e),this.evictOverflow(),this.notifySize();const i=new Set(this.items),n=new Set;for(const s of e)i.has(s)&&n.add(s.shardKey);return[...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()}evictOverflow(){for(;this.items.length>this.maxItems;){const t=this.items.shift();if(t){t.id&&this.persistence?.remove(t.id).catch(i=>{h(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{f as d,u as h,h as s,d as u};

package/dist/packem_shared/{preload.d-C1M_N5mE.d.mts → preload.d-CrqgaKH9.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-DLcz4GRz.mjs";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CQ4K1Ls8.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/{preload.d-hkFC0Uno.d.ts → preload.d-DZf_x6mY.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-DLcz4GRz.js";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CQ4K1Ls8.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/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-DLcz4GRz.mjs";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DLcz4GRz.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-CQ4K1Ls8.mjs";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CQ4K1Ls8.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-DLcz4GRz.js";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DLcz4GRz.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-CQ4K1Ls8.js";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CQ4K1Ls8.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-DLcz4GRz.mjs";
-export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DLcz4GRz.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-C1M_N5mE.mjs";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-CQ4K1Ls8.mjs";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-CQ4K1Ls8.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-CrqgaKH9.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-DLcz4GRz.js";
-export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DLcz4GRz.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-hkFC0Uno.js";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-CQ4K1Ls8.js";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-CQ4K1Ls8.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-DZf_x6mY.js";
 import '@lunora/runtime';
 /**
  * Structural shape of a better-auth `getSession` call's resolved value.

package/dist/ssr/index.mjs

@@ -1 +1 @@
-import{getServerSession as o}from"../packem_shared/getServerSession-CGjgRBAE.mjs";import{deserializePreloaded as l,serializePreloaded as t}from"../packem_shared/deserializePreloaded-CHfOFpka.mjs";import{createServerClient as i}from"../packem_shared/createServerClient-DX7Dk2w2.mjs";import{preloadQuery as s,preloadedQueryResult as f}from"../packem_shared/preloadQuery-DjwSjFwt.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-CGjgRBAE.mjs";import{deserializePreloaded as l,serializePreloaded as t}from"../packem_shared/deserializePreloaded-CHfOFpka.mjs";import{createServerClient as i}from"../packem_shared/createServerClient-Bc6O-zYd.mjs";import{preloadQuery as s,preloadedQueryResult as f}from"../packem_shared/preloadQuery-DjwSjFwt.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.35",
+  "version": "1.0.0-alpha.36",
   "description": "Lunora browser SDK: WebSocket transport, optimistic updates, and an offline mutation queue",
   "keywords": [
     "cloudflare",
@@ -66,7 +66,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.10",
+    "@lunora/errors": "1.0.0-alpha.12",
     "@visulima/storage-client": "1.0.0"
   },
   "engines": {