@lunora/client 1.0.0-alpha.194 → 1.0.0-alpha.196

package/dist/packem_shared/{lunora-client.d-DDVPWV7D.d.mts → lunora-client.d-BZq8UjLD.d.mts}

@@ -1,41 +1,6 @@
 import { LunoraErrorCodeInput, LunoraErrorCode } 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';
-/**
- * Reactive key-value store for local-only client state.
- *
- * Unlike a server {@link SubscriptionState} (which tracks a live WS connection,
- * an `acked` flag, `serverBase`, optimistic layers, and the full subscription
- * machinery), a `ClientQueryRef` is purely local — no server round-trip, no
- * WebSocket, no persistence. It exists so framework adapters can offer a
- * `useClientQuery` hook whose values survive component remounts and are shared
- * across every consumer of the same ref, with none of the ceremony or coupling
- * of a dedicated context provider.
- *
- * The store lives inside `LunoraClient` (a private field) and is surfaced through
- * `client.getClientQuery(ref)` / `setClientQuery(ref, value)` /
- * `subscribeClientQuery(ref, callback)`.
- */
-/** Opaque handle for a typed client-local query slot. */
-interface ClientQueryRef<T = unknown> {
-  /** Default value when no value has been set explicitly. */
-  readonly defaultValue: T;
-  /** Stable identity for the slot. Must be unique within a client instance. */
-  readonly key: string;
-}
-/**
- * Create a typed {@link ClientQueryRef}. Call once per slot at module scope
- * (or inside a component module) — the ref object is the stable identity.
- * @example
- * ```ts
- * // lunora/client-queries.ts
- * import { createClientQuery } from "@lunora/client";
- *
- * export const sidebarOpen = createClientQuery("sidebarOpen", true);
- * export const selectedMessageId = createClientQuery("selectedMessageId", undefined as string | undefined);
- * ```
- */
-declare const createClientQuery: <T>(key: string, defaultValue: T) => ClientQueryRef<T>;
 /**
  * Typed reference to an HTTP-SSE stream route (`httpRoute.<verb>(path).stream()`)
  * emitted by `@lunora/codegen` as `httpStreams.<namespace>.<name>`.
@@ -1397,6 +1362,80 @@ declare class SubscriptionRegistry {
    */
   clear(): void;
 }
+/**
+ * An `Error` carrying the server's machine-readable `code` and (for a
+ * `LunoraError`) structured `data`, plus an optional actionable `hint` (Markdown)
+ * and `docsUrl` resolved from the central error catalog. The client's public
+ * error contract for RPC/batch failures — a UI can render `hint`/`docsUrl` to
+ * tell the user how to fix the error. The `(string & {})` arm keeps
+ * forward-compat/unknown server codes assignable without losing autocomplete on
+ * the known `LunoraErrorCode` union.
+ */
+type LunoraClientError = Error & {
+  code?: LunoraErrorCode | (string & {});
+  data?: unknown;
+  docsUrl?: string;
+  hint?: string | string[];
+};
+/** One demuxed result slot of a `LunoraClient.batch` call. */
+type BatchSlot = {
+  error: LunoraClientError;
+  ok: false;
+} | {
+  ok: true;
+  value: unknown;
+};
+/**
+ * Reactive key-value store for local-only client state.
+ *
+ * Unlike a server {@link SubscriptionState} (which tracks a live WS connection,
+ * an `acked` flag, `serverBase`, optimistic layers, and the full subscription
+ * machinery), a `ClientQueryRef` is purely local — no server round-trip, no
+ * WebSocket, no persistence. It exists so framework adapters can offer a
+ * `useClientQuery` hook whose values survive component remounts and are shared
+ * across every consumer of the same ref, with none of the ceremony or coupling
+ * of a dedicated context provider.
+ *
+ * The store lives inside `LunoraClient` (a private field) and is surfaced through
+ * `client.getClientQuery(ref)` / `setClientQuery(ref, value)` /
+ * `subscribeClientQuery(ref, callback)`.
+ */
+/** Opaque handle for a typed client-local query slot. */
+interface ClientQueryRef<T = unknown> {
+  /** Default value when no value has been set explicitly. */
+  readonly defaultValue: T;
+  /** Stable identity for the slot. Must be unique within a client instance. */
+  readonly key: string;
+}
+/**
+ * Create a typed {@link ClientQueryRef}. Call once per slot at module scope
+ * (or inside a component module) — the ref object is the stable identity.
+ * @example
+ * ```ts
+ * // lunora/client-queries.ts
+ * import { createClientQuery } from "@lunora/client";
+ *
+ * export const sidebarOpen = createClientQuery("sidebarOpen", true);
+ * export const selectedMessageId = createClientQuery("selectedMessageId", undefined as string | undefined);
+ * ```
+ */
+declare const createClientQuery: <T>(key: string, defaultValue: T) => ClientQueryRef<T>;
+type WSState = "idle" | "connecting" | "open" | "closed";
+/**
+ * Aggregate live-socket health across every shard connection, for a UI status
+ * indicator. `idle` = no socket opened yet; `connecting` = at least one socket
+ * is (re)connecting and none is open; `connected` = at least one socket is open;
+ * `polling` = no socket would open, so live queries are being refreshed over HTTP
+ * instead (see `polling-fallback.ts` — live but slower, and shapes
+ * / streams / whispers are dark; mutations go over HTTP as they do while
+ * connected); `offline` = sockets exist but all are down (between reconnect
+ * attempts), and a poll could not reach the origin either.
+ *
+ * `polling` outranks `connecting`: while the fallback is running a reconnect is
+ * still armed in the background, and reporting that attempt would flicker the
+ * indicator between two states while data is in fact arriving on the slow path.
+ */
+type ConnectionStatus = "connected" | "connecting" | "idle" | "offline" | "polling";
 /**
  * Read/write handle over the client's live query cache, handed to a mutation's
  * `withOptimisticUpdate` callback so a single mutation can optimistically patch
@@ -1450,6 +1489,8 @@ declare const createLocalStore: (subscriptions: SubscriptionRegistry, shardKey:
   rollbacks: (() => void)[];
   store: OptimisticLocalStore;
 };
+/** Callback a shape subscription invokes with its materialized rowset on every applied poke. */
+type ShapeCallback = (rows: Record<string, unknown>[]) => void;
 declare const DEFAULT_MAX_BUFFER = 1024;
 interface StreamHandle<T = unknown> {
   /** Mark the stream complete (no more chunks); resolves any pending consumer to `done:true`. */
@@ -1482,22 +1523,6 @@ declare const createStream: <T>(options: {
   handle: StreamHandle<T>;
   iterable: StreamIterable<T>;
 };
-type WSState = "idle" | "connecting" | "open" | "closed";
-/**
- * Aggregate live-socket health across every shard connection, for a UI status
- * indicator. `idle` = no socket opened yet; `connecting` = at least one socket
- * is (re)connecting and none is open; `connected` = at least one socket is open;
- * `polling` = no socket would open, so live queries are being refreshed over HTTP
- * instead (see {@link file://./polling-fallback.ts} — live but slower, and shapes
- * / streams / whispers are dark; mutations go over HTTP as they do while
- * connected); `offline` = sockets exist but all are down (between reconnect
- * attempts), and a poll could not reach the origin either.
- *
- * `polling` outranks `connecting`: while the fallback is running a reconnect is
- * still armed in the background, and reporting that attempt would flicker the
- * indicator between two states while data is in fact arriving on the slow path.
- */
-type ConnectionStatus = "connected" | "connecting" | "idle" | "offline" | "polling";
 /** One shard's socket + watermark state in a {@link LunoraClient.debug} snapshot. */
 interface ClientDebugShard {
   /**
@@ -1702,31 +1727,6 @@ type ReplayIdentityVerdict = {
 } | {
   verdict: "unknown";
 };
-/** Callback a shape subscription invokes with its materialized rowset on every applied poke. */
-type ShapeCallback = (rows: Record<string, unknown>[]) => void;
-/**
- * An `Error` carrying the server's machine-readable `code` and (for a
- * `LunoraError`) structured `data`, plus an optional actionable `hint` (Markdown)
- * and `docsUrl` resolved from the central error catalog. The client's public
- * error contract for RPC/batch failures — a UI can render `hint`/`docsUrl` to
- * tell the user how to fix the error. The `(string & {})` arm keeps
- * forward-compat/unknown server codes assignable without losing autocomplete on
- * the known {@link LunoraErrorCode} union.
- */
-type LunoraClientError = Error & {
-  code?: LunoraErrorCode | (string & {});
-  data?: unknown;
-  docsUrl?: string;
-  hint?: string | string[];
-};
-/** One demuxed result slot of a {@link LunoraClient.batch} call (plan 088). */
-type BatchSlot = {
-  error: LunoraClientError;
-  ok: false;
-} | {
-  ok: true;
-  value: unknown;
-};
 /**
  * Lunora browser/edge client. Talks RPC over HTTP and real-time deltas over
  * a single multiplexed WebSocket.
@@ -1748,6 +1748,8 @@ declare class LunoraClient {
   static createClientQuery<T>(key: string, defaultValue: T): ClientQueryRef<T>;
   readonly url: string;
   readonly wsUrl: string;
+  /** The admin modules reach the client only through this host. The arrows read `this` when called, so spies and overrides installed after construction still take effect. */
+  private readonly adminHost;
   /** Local reactive store for {@link ClientQueryRef} values — no server round-trip. Private; reach it via `getClientQuery` / `setClientQuery` / `subscribeClientQuery`. */
   private readonly clientQueryStore;
   private wsToken;
@@ -1761,6 +1763,8 @@ declare class LunoraClient {
   private readonly connectTimeoutMs;
   /** Keepalive cadence (ms); `0` disables the heartbeat. See {@link LunoraClientOptions.heartbeatIntervalMs}. */
   private readonly heartbeatIntervalMs;
+  /** The socket-lifecycle inputs, built once after the constructor assigns them (none is reassigned later). */
+  private readonly managedSocketOptions;
   /** Failed-open run that engages the HTTP polling fallback; `0` disables it. */
   private readonly pollingFallbackAfterFailedAttempts;
   /** Polling-fallback cadence (ms); `0` disables it. See {@link LunoraClientOptions.pollingFallback}. */
@@ -1879,15 +1883,7 @@ declare class LunoraClient {
    * 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;
+  private readonly leader;
   /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
   private readonly connections;
   /**
@@ -2112,18 +2108,8 @@ declare class LunoraClient {
   /** 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
-   * `<connectionKey>\u0000<pokeId>`.
-   *
-   * The connection has to be in the key: `pokeId` is a per-DO counter that also
-   * resets on eviction, so a multi-shard client — one socket per shard, one map
-   * here — sees two shards mint `poke-1` concurrently. Keyed by `pokeId` alone
-   * their frames interleave into a single buffer: one shard applies the other's
-   * epoch (spurious fork → view wiped) and the other finds no buffer for its
-   * parts at all, silently dropping rows while the server's memo advances.
-   */
-  private readonly pokeBuffers;
+  /** In-flight pokes, keyed by connection and `pokeId`. The key rule is in shape-state.ts. */
+  private readonly pokeAssembler;
   private nextShapeId;
   constructor(options: LunoraClientOptions);
   /**
@@ -3841,7 +3827,7 @@ declare class LunoraClient {
    * 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
+   * `leader.status`/`leader.wasEverConnected` 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
@@ -3921,26 +3907,6 @@ 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;
   /**
@@ -3949,27 +3915,6 @@ declare class LunoraClient {
    */
   private cancelStream;
   private handleDisconnect;
-  /**
-   * 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. */
-  private stopHeartbeat;
   /** Mark every subscription bound to `shardKey` as needing a fresh ack. */
   private markShardPendingAck;
   /**
@@ -4006,17 +3951,10 @@ declare class LunoraClient {
   private sendShapeSubscribeIfOpen;
   private handleServerMessage;
   private handleErrorMessage;
-  /** Buffer key for an in-flight poke: `pokeId` is only unique per shard socket, so it is scoped by connection. */
-  private pokeBufferKey;
-  private handlePokeStart;
-  private handlePokePart;
   private handlePokeEnd;
   /**
-   * Commit one shape's slice of a poke, or refuse it and re-seed.
-   *
-   * Split out of {@link handlePokeEnd} because every decision here is PER SHAPE
-   * — the reset flag, the base checkpoint, the watermark — while the poke
-   * envelope around it is not.
+   * Commit one shape's slice of a poke. The decision and the state change live in
+   * `commitPokeSlice`; this method only performs the I/O that follows it.
    */
   private applyPokePart;
   /**
@@ -4028,8 +3966,6 @@ declare class LunoraClient {
    * path's re-seed on a diverged base.
    */
   private resnapshotSubscription;
-  /** Materialize a shape's keyed view to an array and invoke its callbacks. */
-  private emitShapeRows;
   /**
    * Apply one `data` frame. `snapshotMark` is set only for a frame synthesized
    * by a poll, which carries no cursor: see {@link pollSubscriptions}.
@@ -4063,19 +3999,6 @@ declare class LunoraClient {
    * client must re-render changed, but the resume position may have moved".
    */
   private ackAndAdvanceCursor;
-  /**
-   * Resolve the value to publish for a `data`/`delta` frame.
-   *
-   * A `data` frame is an authoritative snapshot (the server re-execution path)
-   * and always replaces the cached value wholesale. A `delta` frame carrying a
-   * structured `MutationDelta` (the `broadcastDelta` row-change path) is
-   * merged incrementally into the cached list — preserving order, no dup/loss —
-   * so each subscription (including every paginated page) updates by delta
-   * rather than a full re-send. We fall back to full replacement when the
-   * delta isn't a recognisable row change, when there's no cached value yet,
-   * or when it can't be applied cleanly against the current cached shape.
-   */
-  private resolveDataPayload;
   /** Route an inbound whisper to the topic's handlers on the originating shard. */
   private dispatchWhisper;
   /** Notify every {@link onTokenExpired} listener (best-effort, listener throws swallowed). */
@@ -4715,12 +4638,5 @@ declare class LunoraClient {
    * @returns the writes that must be re-queued (kept slots), in input order
    */
   private settleReplayBatchSlots;
-  /**
-   * Settle one batch slot that answered with a result. Decoded per slot: one
-   * result the codec refuses must not abandon the slots after it (committed
-   * writes left pending and unsettled for the rest of the session), and its
-   * own write DID commit.
-   */
-  private settleReplayBatchResult;
 }
 export { ServerMessage as $, ActionCallOptions as A, BookmarkStorage as B, ConnectionStatus as C, DEFAULT_MAX_BUFFER as D, OutboxMutation as E, FunctionArgumentDescriptor as F, GlobalFacetResult as G, HttpStreamRef as H, OutboxSink as I, PersistedMutation as J, ReplayCredential as K, LunoraClient as L, MutationCallOptions as M, ReplayIdentityVerdict as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReconnectOptions as R, SubscriptionError as S, RowOp as T, User as U, RpcEnvelope as V, RpcResponseBody as W, ScheduleRecord as X, ScheduleRetryPolicy as Y, SchedulerPoolStatus as Z, SchedulerStatus as _, Unsubscribe as a, ServerPokeEndMessage as a0, ServerPokePartMessage as a1, ServerPokeStartMessage as a2, ShardTrafficEntry as a3, ShardTrafficResult as a4, StorageListPage as a5, StorageObject as a6, StoredQuery 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, SubscriptionErrorCallback as b, PersistenceAdapter as c, HttpStreamArgsOf as d, HttpStreamChunkOf as e, StreamIterable as f, BatchSlot as g, CachedQuery as h, ClientDebugShard as i, ClientDebugSnapshot as j, ClientDebugSubscription as k, ClientMessage as l, ClientQueryRef as m, ClientShapeSubscribeMessage as n, ClientShapeUnsubscribeMessage as o, FunctionDescriptor as p, GlobalFacetValue as q, GlobalFilterClause as r, GlobalTableInfo as s, GlobalTablePage as t, HttpStreamCallArgs as u, LunoraClientError as v, LunoraClientOptions as w, MutationSettledEvent as x, OptimisticLocalStore as y, OptimisticUpdate as z };