@bounded-sh/core 0.0.102 → 0.0.104

package/dist/client/realtime-store.d.ts

@@ -33,6 +33,8 @@ export declare class RealtimeStore {
     private reconnectTimer;
     private reconnectDelay;
     private maxReconnectDelay;
+    /** When the current socket finished connecting; decides whether a close resets the backoff. */
+    private connectedAtMs;
     private idbFlushTimer;
     private idbDirtyKeys;
     private closed;

package/dist/client/reconnect-backoff.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reconnect backoff for RealtimeStore's WebSocket.
+ *
+ * A server that sheds load closes many sockets at once (1013). Without jitter
+ * every client comes back at the same instant; without growth on quick closes a
+ * socket that is accepted and then immediately dropped retries at the floor
+ * forever. So: a connection that stayed up for STABLE_CONNECTION_MS resets the
+ * delay, a shorter one doubles it, and every scheduled wait is jittered.
+ */
+export declare const RECONNECT_BASE_DELAY_MS = 1000;
+export declare const RECONNECT_MAX_DELAY_MS = 30000;
+export declare const STABLE_CONNECTION_MS = 10000;
+/** Delay to use after a close, given how long the closed connection had been up (null: never connected). */
+export declare function reconnectDelayAfterClose(currentDelayMs: number, connectedForMs: number | null, maxDelayMs?: number): number;
+/** The wait actually scheduled: the delay scaled by a random factor in [0.5, 1.5). */
+export declare function jitteredReconnectDelayMs(delayMs: number, random?: () => number): number;

package/dist/client/socket-heartbeat.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Idle heartbeat for the realtime WebSocket connection (subscription-v2.ts).
+ *
+ * A socket whose server has stopped delivering frames looks exactly like a
+ * quiet one: the browser reports it open and nothing arrives. The client only
+ * learns the difference by asking. Once nothing has been received for
+ * HEARTBEAT_IDLE_MS the heartbeat asks the connection to send a ping; if
+ * nothing at all arrives within HEARTBEAT_TIMEOUT_MS after that, the socket is
+ * declared dead and the connection is reconnected. Any inbound frame counts as
+ * proof of life, so a busy socket is never pinged and a pong is just another
+ * frame. The connection may decline to ping (it already has a request in
+ * flight with its own timeout); the idle wait then simply starts over.
+ *
+ * The timeout sits above both budgets a pong can wait behind: the connection's
+ * own 30 s request budget (the server handles one frame per socket at a time)
+ * and the object's 30 s CPU slice, which another socket's handler can hold
+ * while every pong waits. A healthy socket must never be declared dead
+ * within either.
+ *
+ * Pure: timers come from the clock passed in, so tests can drive it.
+ */
+export declare const HEARTBEAT_IDLE_MS = 25000;
+export declare const HEARTBEAT_TIMEOUT_MS = 45000;
+export interface HeartbeatClock {
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export declare class SocketHeartbeat {
+    /** Send a ping now; return false to skip this round (the idle wait restarts). */
+    private readonly sendPing;
+    private readonly onDead;
+    private readonly clock;
+    private readonly idleMs;
+    private readonly timeoutMs;
+    private idleTimer;
+    private timeoutTimer;
+    private stopped;
+    constructor(
+    /** Send a ping now; return false to skip this round (the idle wait restarts). */
+    sendPing: () => boolean, onDead: () => void, clock?: HeartbeatClock, idleMs?: number, timeoutMs?: number);
+    start(): void;
+    /** An inbound frame arrived: the socket is alive, so the idle wait starts over. */
+    noteActivity(): void;
+    stop(): void;
+    private armIdle;
+    private clearTimers;
+}

package/dist/client/solana-operations.d.ts

@@ -121,6 +121,21 @@ export declare function validateServerTransactionSemantics(input: {
     instructions: ServerTransactionInstructionView[];
     PublicKeyCtor: PublicKeyClass;
 }): void;
+/**
+ * Poofnet lane of the onchain 202. Poofnet has no chain, so there is nothing to
+ * submit and no blockhash to refresh: the worker issued an unsendable message
+ * (off-curve fee payer) that only proves this wallet approved this write. It is
+ * validated exactly like a mainnet transaction before the wallet sees it, signed
+ * by the same provider method, and returned for the worker to verify and commit.
+ */
+/**
+ * The fee payer of every poofnet approval message (realtime's
+ * POOFNET_VOID_FEE_PAYER): an off-curve address with no private key, so a message
+ * it pays for can never land on any cluster. Pinned here so a 202 from anything
+ * else can never get a live, broadcastable transaction signed.
+ */
+export declare const POOFNET_VOID_FEE_PAYER = "CAXES7Tt3KGsSw4A5knQXKKUJZWsrguu6PC7SDBL4oq2";
+export declare function signPoofnetTransaction(serializedTransaction: string, authProvider: AuthProvider, options: SetOptions | undefined, expectedIntent: ExpectedWriteIntent): Promise<string>;
 export declare function handlePreBuiltTransaction(tx: {
     serializedTransaction: string;
     blockhash: string;

package/dist/client/subscription-v2.d.ts

@@ -28,6 +28,12 @@ export declare const SHARD_CAP = 45;
  * target, far beyond any legitimate UI.
  */
 export declare const MAX_SHARDS_PER_KEY = 8;
+/**
+ * Every idle client on a stalled object hits its dead timer at about the same
+ * moment, so the replacement waits out the wrapper's own first-attempt delay
+ * with the same jitter, instead of every client reopening in one instant.
+ */
+export declare const HEARTBEAT_RECONNECT_DELAY_MAX_MS: number;
 /**
  * Subscribe to data at a path using WebSocket v2.
  * Returns an unsubscribe function.

package/dist/{index-BEGeDFQI.js → index-62gjQH30.js}

@@ -4190,7 +4190,7 @@ class ServerSessionManager {
         const sessionConfig = (_a = this.sessionConfig) !== null && _a !== void 0 ? _a : undefined;
         /* fetch nonce from auth API (bound to the snapshotted app+issuer) */
         const nonce = await genAuthNonce(sessionConfig);
-        const { genSolanaMessage } = await Promise.resolve().then(function () { return require('./solana-message-CJTnYiJu.js'); });
+        const { genSolanaMessage } = await Promise.resolve().then(function () { return require('./solana-message-Bf2q_JO1.js'); });
         const message = await genSolanaMessage(address, nonce, sessionConfig === null || sessionConfig === void 0 ? void 0 : sessionConfig.appId);
         /* sign the message */
         const sigBytes = nacl.sign.detached(new TextEncoder().encode(message), kp.secretKey);
@@ -5231,6 +5231,83 @@ async function resolveClientTransactionVersions(authProvider) {
     return typeof authProvider.signTransactionV1 === 'function' ? ['legacy', 0, 1] : ['legacy', 0];
 }
 
+/**
+ * Idle heartbeat for the realtime WebSocket connection (subscription-v2.ts).
+ *
+ * A socket whose server has stopped delivering frames looks exactly like a
+ * quiet one: the browser reports it open and nothing arrives. The client only
+ * learns the difference by asking. Once nothing has been received for
+ * HEARTBEAT_IDLE_MS the heartbeat asks the connection to send a ping; if
+ * nothing at all arrives within HEARTBEAT_TIMEOUT_MS after that, the socket is
+ * declared dead and the connection is reconnected. Any inbound frame counts as
+ * proof of life, so a busy socket is never pinged and a pong is just another
+ * frame. The connection may decline to ping (it already has a request in
+ * flight with its own timeout); the idle wait then simply starts over.
+ *
+ * The timeout sits above both budgets a pong can wait behind: the connection's
+ * own 30 s request budget (the server handles one frame per socket at a time)
+ * and the object's 30 s CPU slice, which another socket's handler can hold
+ * while every pong waits. A healthy socket must never be declared dead
+ * within either.
+ *
+ * Pure: timers come from the clock passed in, so tests can drive it.
+ */
+const HEARTBEAT_IDLE_MS = 25000;
+const HEARTBEAT_TIMEOUT_MS = 45000;
+class SocketHeartbeat {
+    constructor(
+    /** Send a ping now; return false to skip this round (the idle wait restarts). */
+    sendPing, onDead, clock = globalThis, idleMs = HEARTBEAT_IDLE_MS, timeoutMs = HEARTBEAT_TIMEOUT_MS) {
+        this.sendPing = sendPing;
+        this.onDead = onDead;
+        this.clock = clock;
+        this.idleMs = idleMs;
+        this.timeoutMs = timeoutMs;
+        this.idleTimer = null;
+        this.timeoutTimer = null;
+        this.stopped = false;
+    }
+    start() {
+        if (this.stopped)
+            return;
+        this.armIdle();
+    }
+    /** An inbound frame arrived: the socket is alive, so the idle wait starts over. */
+    noteActivity() {
+        if (this.stopped)
+            return;
+        this.clearTimers();
+        this.armIdle();
+    }
+    stop() {
+        this.stopped = true;
+        this.clearTimers();
+    }
+    armIdle() {
+        this.idleTimer = this.clock.setTimeout(() => {
+            this.idleTimer = null;
+            if (!this.sendPing()) {
+                this.armIdle();
+                return;
+            }
+            this.timeoutTimer = this.clock.setTimeout(() => {
+                this.timeoutTimer = null;
+                this.onDead();
+            }, this.timeoutMs);
+        }, this.idleMs);
+    }
+    clearTimers() {
+        if (this.idleTimer !== null) {
+            this.clock.clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        if (this.timeoutTimer !== null) {
+            this.clock.clearTimeout(this.timeoutTimer);
+            this.timeoutTimer = null;
+        }
+    }
+}
+
 /**
  * WebSocket v2 Subscription Manager
  *
@@ -5325,6 +5402,81 @@ const WS_CONFIG = {
     // Give handshakes more time before considering the attempt failed.
     connectionTimeout: 10000,
 };
+/** Client-chosen close code for a socket the heartbeat declared dead (4000-4999 are application codes). */
+const HEARTBEAT_CLOSE_CODE = 4000;
+function heartbeatReconnectDelayMs() {
+    return BASE_MIN_RECONNECT_DELAY_MS + Math.floor(Math.random() * MIN_RECONNECT_DELAY_JITTER_MS);
+}
+/**
+ * Start the idle heartbeat for the native socket that just opened on `ws`.
+ * A ping goes out after HEARTBEAT_IDLE_MS of silence, and a socket that
+ * answers nothing for HEARTBEAT_TIMEOUT_MS more is reconnected through the
+ * wrapper after a jittered delay, the same path an auth change takes. A
+ * server that has stopped dispatching frames leaves the socket open and
+ * silent, so nothing else on the client would ever notice.
+ */
+function startHeartbeat(connection, ws) {
+    stopHeartbeat(connection);
+    const heartbeat = new SocketHeartbeat(() => {
+        // An outbound wait already has its own timeout, and the server
+        // answers one frame per socket at a time, so a ping behind it would
+        // only measure that wait. Let the idle wait start over instead.
+        if (hasOutboundWait(connection))
+            return false;
+        // The wrapper drops a send on a socket that is not open, and a send
+        // that throws is a socket that cannot carry a ping either way; the
+        // dead timer then reports it.
+        try {
+            ws.send(JSON.stringify({ type: 'ping' }));
+        }
+        catch (error) {
+            console.warn('[WS v2] Heartbeat ping could not be sent:', error);
+        }
+        return true;
+    }, () => {
+        // Only the socket this heartbeat was started for. A replaced or
+        // torn-down connection must never be resurrected by a late timer.
+        if (connection.heartbeat !== heartbeat || connection.ws !== ws)
+            return;
+        console.warn('[WS v2] No frames within the heartbeat window; reconnecting');
+        // The heartbeat stays installed through the delay: a frame that
+        // arrives meanwhile cancels the replacement (see the message
+        // listener) and starts a fresh idle window on the same socket.
+        connection.heartbeatReconnectTimer = setTimeout(() => {
+            connection.heartbeatReconnectTimer = null;
+            if (connection.heartbeat !== heartbeat || connection.ws !== ws)
+                return;
+            connection.heartbeat = null;
+            try {
+                ws.reconnect(HEARTBEAT_CLOSE_CODE, 'Heartbeat timeout');
+            }
+            catch (error) {
+                console.error('[WS v2] Error reconnecting after heartbeat timeout:', error);
+            }
+        }, heartbeatReconnectDelayMs());
+    });
+    connection.heartbeat = heartbeat;
+    heartbeat.start();
+}
+function stopHeartbeat(connection) {
+    var _a;
+    (_a = connection.heartbeat) === null || _a === void 0 ? void 0 : _a.stop();
+    connection.heartbeat = null;
+    if (connection.heartbeatReconnectTimer) {
+        clearTimeout(connection.heartbeatReconnectTimer);
+        connection.heartbeatReconnectTimer = null;
+    }
+}
+/** A frame of ours the server has not answered yet: a request, a subscription confirmation, or a snapshot refresh. */
+function hasOutboundWait(connection) {
+    if (connection.pendingRequests.size > 0 || connection.pendingSubscriptions.size > 0)
+        return true;
+    for (const subscription of connection.subscriptions.values()) {
+        if (subscription.refresh)
+            return true;
+    }
+    return false;
+}
 const WS_V2_PATH = '/ws/v2';
 let browserReconnectHooksAttached = false;
 let lastBrowserTriggeredReconnectAt = 0;
@@ -5793,6 +5945,7 @@ function closeConnectionNow(connection) {
         clearInterval(connection.tokenRefreshTimer);
         connection.tokenRefreshTimer = null;
     }
+    stopHeartbeat(connection);
     const ws = connection.ws;
     connection.ws = null;
     connection.isConnecting = false;
@@ -6077,6 +6230,8 @@ async function getOrCreateConnectionOnce(appId, isServer, routePath, authTokenPr
         authTokenValue: null,
         authPrincipal: null,
         socketGeneration: 0,
+        heartbeat: null,
+        heartbeatReconnectTimer: null,
         tokenRefreshTimer: null,
         idleCloseTimer: null,
         consecutiveAuthFailures: 0,
@@ -6151,6 +6306,7 @@ async function getOrCreateConnectionOnce(appId, isServer, routePath, authTokenPr
         connection.socketGeneration += 1;
         connection.isConnecting = false;
         connection.isConnected = true;
+        startHeartbeat(connection, ws);
         // NOTE: Do NOT reset consecutiveAuthFailures here. It is reset when a
         // fresh auth token is actually obtained or on an explicit auth change.
         // Schedule periodic token freshness checks. An anonymous (read-only
@@ -6185,6 +6341,13 @@ async function getOrCreateConnectionOnce(appId, isServer, routePath, authTokenPr
     });
     // Handle incoming messages
     ws.addEventListener('message', (event) => {
+        var _a;
+        if (connection.heartbeatReconnectTimer) {
+            // A frame inside the replacement delay: the socket is alive after all.
+            clearTimeout(connection.heartbeatReconnectTimer);
+            connection.heartbeatReconnectTimer = null;
+        }
+        (_a = connection.heartbeat) === null || _a === void 0 ? void 0 : _a.noteActivity();
         try {
             const message = JSON.parse(event.data);
             handleServerMessage(connection, message);
@@ -6206,6 +6369,7 @@ async function getOrCreateConnectionOnce(appId, isServer, routePath, authTokenPr
     });
     // Handle close
     ws.addEventListener('close', () => {
+        stopHeartbeat(connection);
         connection.isConnected = false;
         connection.isAuthenticating = false;
         const disconnectError = new Error('WebSocket disconnected');
@@ -7185,6 +7349,7 @@ async function closeAllSubscriptionsV2() {
             connection.tokenRefreshTimer = null;
         }
         if (connection.ws) {
+            stopHeartbeat(connection);
             const ws = connection.ws;
             connection.ws = null;
             connection.isConnected = false;
@@ -7304,7 +7469,7 @@ async function doReconnectWithNewAuth() {
         console.warn('[WS v2] Failed to clear HTTP read cache on auth change:', error);
     }
     try {
-        const { reconnectRealtimeStoreWithNewAuth } = await Promise.resolve().then(function () { return require('./realtime-store-DrtEj-bE.js'); });
+        const { reconnectRealtimeStoreWithNewAuth } = await Promise.resolve().then(function () { return require('./realtime-store-9SCt1RPf.js'); });
         await reconnectRealtimeStoreWithNewAuth();
     }
     catch (error) {
@@ -8647,7 +8812,7 @@ async function set(path, document, options) {
  * state appears only under `observation`/`mirrorSync` once actually observed.
  */
 async function setMany(many, options) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
     // Returns the data that was set, or undefined if the document was already set.
     try {
         // A server WalletClient threads its immutable config snapshot; the default
@@ -8752,13 +8917,35 @@ async function setMany(many, options) {
                 throw new Error('The write response carried no execution-chain tag, so this receipt could not state where the write ran. ' +
                     'Nothing was signed or submitted.');
             }
+            if (workerChain === 'realtime_offchain') {
+                // Poofnet: the wallet signs the worker's unsendable approval message and
+                // the worker verifies and commits it. Nothing is submitted to any chain.
+                if (typeof curTx.serializedTransaction !== 'string' || typeof curTx.poofnetIntentId !== 'string') {
+                    throw new Error('Unsupported 202 transaction shape: a poofnet write needs serializedTransaction and poofnetIntentId');
+                }
+                const { signPoofnetTransaction, buildExpectedWriteIntent } = await Promise.resolve().then(function () { return require('./solana-operations-eTiLgak2.js'); });
+                const signedTransaction = await signPoofnetTransaction(curTx.serializedTransaction, authProvider, options, buildExpectedWriteIntent(documents));
+                // Signing-only, exactly as on a real chain: signed and NOT committed.
+                if ((options === null || options === void 0 ? void 0 : options.shouldSubmitTx) === false) {
+                    return {
+                        status: 'signed', appId, requestedDocuments: buildRequestedDocuments(documents),
+                        chain: 'realtime_offchain', transactionId: null, signedTransaction,
+                        poofnetIntentId: curTx.poofnetIntentId,
+                    };
+                }
+                const commitResponse = await makeApiRequest('PUT', 'items/signed', { intentId: curTx.poofnetIntentId, signedTransaction }, options === null || options === void 0 ? void 0 : options._overrides);
+                if (commitResponse.status !== 200) {
+                    throw new Error(`Poofnet signed write was not committed (status ${commitResponse.status})`);
+                }
+                return directCommitResult(commitResponse, documents);
+            }
             if (curTx.serializedTransaction) {
                 if (!SOLANA_CHAIN_TAGS.has(workerChain)) {
                     throw new Error(`The write response reported execution chain "${workerChain}" for a Solana transaction. ` +
                         'Nothing was signed or submitted.');
                 }
                 const solanaChain = workerChain;
-                const { handlePreBuiltTransaction, buildExpectedWriteIntent } = await Promise.resolve().then(function () { return require('./solana-operations-CU0YbiMu.js'); });
+                const { handlePreBuiltTransaction, buildExpectedWriteIntent } = await Promise.resolve().then(function () { return require('./solana-operations-eTiLgak2.js'); });
                 // OA-0001: derive the expected intent from OUR OWN request (the one
                 // ground truth a tampered builder response cannot change) so the
                 // validator can reject any transaction whose operation semantics
@@ -8801,26 +8988,7 @@ async function setMany(many, options) {
             }
         }
         else if (setResponse.status === 200) {
-            // Direct commit: the worker applied the batch itself. The receipt is
-            // batch-level — `transactionId` comes from the worker's own receipt and is
-            // NEVER lifted out of a result document (a delete returns the PREVIOUS
-            // document, so its stale `_transaction_hash` would misreport the delete).
-            const body = (setResponse.data && typeof setResponse.data === 'object' && !Array.isArray(setResponse.data))
-                ? setResponse.data
-                : null;
-            const receipt = ((body === null || body === void 0 ? void 0 : body.receipt) && typeof body.receipt === 'object' && !Array.isArray(body.receipt))
-                ? body.receipt
-                : null;
-            const rawTransactionId = receipt === null || receipt === void 0 ? void 0 : receipt.transactionId;
-            return {
-                status: 'committed',
-                requestedDocuments: buildRequestedDocuments(documents),
-                observation: observationFromDirectCommit(documents.map(d => d.destinationPath), receipt === null || receipt === void 0 ? void 0 : receipt.observation),
-                // A worker predating the batch receipt reports no lane. Say so rather
-                // than inventing one — and never discard a committed write's receipt.
-                chain: ((_l = readWorkerChainTag(receipt)) !== null && _l !== void 0 ? _l : 'unknown'),
-                transactionId: typeof rawTransactionId === 'string' && rawTransactionId.length > 0 ? rawTransactionId : null,
-            };
+            return directCommitResult(setResponse, documents);
         }
         else {
             throw new Error(`Failed to set document: ${setResponse}`);
@@ -8830,6 +8998,32 @@ async function setMany(many, options) {
         throw error;
     }
 }
+/**
+ * Direct commit: the worker applied the batch itself (an offchain write, or a
+ * poofnet onchain write after its signature verified). The receipt is batch-level
+ * - `transactionId` comes from the worker's own receipt and is NEVER lifted out
+ * of a result document (a delete returns the PREVIOUS document, so its stale
+ * `_transaction_hash` would misreport the delete).
+ */
+function directCommitResult(response, documents) {
+    var _a;
+    const body = (response.data && typeof response.data === 'object' && !Array.isArray(response.data))
+        ? response.data
+        : null;
+    const receipt = ((body === null || body === void 0 ? void 0 : body.receipt) && typeof body.receipt === 'object' && !Array.isArray(body.receipt))
+        ? body.receipt
+        : null;
+    const rawTransactionId = receipt === null || receipt === void 0 ? void 0 : receipt.transactionId;
+    return {
+        status: 'committed',
+        requestedDocuments: buildRequestedDocuments(documents),
+        observation: observationFromDirectCommit(documents.map(d => d.destinationPath), receipt === null || receipt === void 0 ? void 0 : receipt.observation),
+        // A worker predating the batch receipt reports no lane. Say so rather
+        // than inventing one - and never discard a committed write's receipt.
+        chain: ((_a = readWorkerChainTag(receipt)) !== null && _a !== void 0 ? _a : 'unknown'),
+        transactionId: typeof rawTransactionId === 'string' && rawTransactionId.length > 0 ? rawTransactionId : null,
+    };
+}
 /**
  * Extract the document/collection path from a cache key. Keys are
  * `<appId:principal>|<path>:<...>` (H1 principal-scoped) — strip the principal
@@ -10533,7 +10727,7 @@ function toMillis(seconds) {
 
 /** SIWS message creation is async already, so its onchain module can be lazy. */
 async function genSolanaMessage(address, nonce) {
-    const implementation = await Promise.resolve().then(function () { return require('./solana-message-CJTnYiJu.js'); });
+    const implementation = await Promise.resolve().then(function () { return require('./solana-message-Bf2q_JO1.js'); });
     return implementation.genSolanaMessage(address, nonce);
 }
 
@@ -11180,4 +11374,4 @@ exports.toMillis = toMillis;
 exports.toSeconds = toSeconds;
 exports.waitForSetResult = waitForSetResult;
 exports.withEffects = withEffects;
-//# sourceMappingURL=index-BEGeDFQI.js.map
+//# sourceMappingURL=index-62gjQH30.js.map