@novasamatech/statement-store 0.8.6 → 0.8.7-1

package/dist/session/session.js

@@ -1,38 +1,124 @@
-import { createExpiryFromDuration } from '@novasamatech/sdk-statement';
 import { nanoid } from 'nanoid';
 import { ResultAsync, err, errAsync, fromPromise, fromThrowable, ok, okAsync } from 'neverthrow';
 import { toHex } from 'polkadot-api/utils';
+import { Struct, str } from 'scale-ts';
+import { ExpiryTooLowError } from '../adapter/types.js';
 import { khash, stringToBytes } from '../crypto.js';
 import { nonNullable, toError } from '../helpers.js';
 import { createSessionId } from '../model/session.js';
 import { DecodingError, DecryptionError, UnknownError } from './error.js';
 import { toMessage } from './messageMapper.js';
 import { StatementData } from './scale/statementData.js';
-const DEFAULT_EXPIRY_DURATION_SECS = 7 * 24 * 60 * 60; // 7 days
 const DEFAULT_MAX_REQUEST_SIZE = 4096;
+// Bounded retry for transient transport failures (the spec mandates retrying queries
+// and submit_statement on connection failure). The TS adapter doesn't expose connection
+// state, so we approximate with a short fixed backoff and an attempt cap.
+const MAX_INIT_RETRIES = 3;
+const MAX_SUBMIT_RETRIES = 3;
+const RETRY_DELAY_MS = 25;
+/**
+ * Fixed per-statement wire overhead reserved before sizing the request payload:
+ * topic (32) + channel (32) + expiry (8) + proof signature (64) + signer (32).
+ * Mirrors the Android/iOS sessions, which size message batches against
+ * `maxStatementSize - overhead` rather than the raw statement limit.
+ */
+export const STATEMENT_OVERHEAD = 32 + 32 + 8 + 64 + 32; // 168 bytes
+/**
+ * Statement expiry/priority, u64 = (expiration_epoch << 32) | priority (spec layout).
+ * We pin the high word to 0xFFFFFFFF (max → effectively non-expiring, matching iOS &
+ * Android) and use the low word as a wall-clock-floored monotonic priority, so channel
+ * supersession is driven by the priority regardless of how the store compares the field.
+ * Returns a value strictly greater than `current` (i.e. `max(current + 1, now-priority)`).
+ */
+const NEVER_EXPIRE_HIGH = 0xffffffffn;
 export function nextExpiry(current) {
-    const fresh = createExpiryFromDuration(DEFAULT_EXPIRY_DURATION_SECS);
-    return fresh > current ? fresh : current + 1n;
+    const nowSecs = BigInt(Math.floor(Date.now() / 1000));
+    const timestampPriority = (NEVER_EXPIRE_HIGH << 32n) | nowSecs;
+    return timestampPriority > current ? timestampPriority : current + 1n;
+}
+// Encode/decode a StatementData envelope, surfacing scale-ts throws as a Result.
+const encodeStatementData = fromThrowable(StatementData.enc, toError);
+const decodeStatementData = fromThrowable(StatementData.dec, toError);
+// Best-effort recovery of the requestId from a decrypted-but-undecodable payload. The requestId
+// is the first field after the enum tag, so it usually survives a corrupt message body. Only
+// requests (tag 0) carry an id we should answer; responses (tag 1) and unrecoverable payloads
+// return null and are dropped rather than NACKed.
+const RequestIdPrefix = Struct({ requestId: str });
+const decodeRequestIdPrefix = fromThrowable(
+// slice (a copy), not subarray: scale-ts decodes from the backing buffer start and ignores
+// a view's byteOffset, so a subarray would be read from the wrong position.
+(decrypted) => RequestIdPrefix.dec(decrypted.slice(1)).requestId, () => null);
+function recoverRequestId(decrypted) {
+    if (decrypted.length < 1 || decrypted[0] !== 0)
+        return null;
+    return decodeRequestIdPrefix(decrypted).unwrapOr(null);
+}
+// nanoid() is fixed-length, so the requestId contributes a constant size; any
+// placeholder of that length yields the real encoded size.
+const SIZING_REQUEST_ID = 'x'.repeat(21);
+// Encoded size of the request payload these messages would occupy in a statement's `data`
+// field — the full SCALE envelope (requestId + vector framing), not just the raw bytes. This
+// is what must fit the per-statement budget, matching iOS/Android (which size the full payload).
+function requestPayloadSize(messages) {
+    return encodeStatementData({ tag: 'request', value: { requestId: SIZING_REQUEST_ID, data: messages } })
+        .map(d => d.length)
+        .unwrapOr(Number.MAX_SAFE_INTEGER); // unencodable → treat as "doesn't fit"
+}
+// A response promise paired with its resolver/rejecter. The pre-attached catch
+// keeps a clearOutgoingStatement()/dispose() rejection from surfacing as an
+// unhandled rejection when no caller awaited it via waitForResponseMessage().
+function makeDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    promise.catch(() => undefined);
+    return { resolve, reject, promise };
+}
+// Retry a submit on failure with a short backoff, up to `attemptsLeft` extra attempts.
+// A successful submit returns immediately (no delay on the happy path). `shouldRetry` is
+// re-checked before each retry: once the submission is superseded, aborted, or the session
+// is disposed it returns false, so a stale retry can never resurrect an old statement.
+function submitWithRetry(submit, attemptsLeft, shouldRetry) {
+    return submit().orElse(error => {
+        if (attemptsLeft <= 0 || !shouldRetry())
+            return errAsync(error);
+        return ResultAsync.fromSafePromise(new Promise(resolve => setTimeout(resolve, RETRY_DELAY_MS))).andThen(() => !shouldRetry() ? errAsync(error) : submitWithRetry(submit, attemptsLeft - 1, shouldRetry));
+    });
 }
 export function createSession({ localAccount, remoteAccount, statementStore, encryption, prover, sessionKey, maxRequestSize = DEFAULT_MAX_REQUEST_SIZE, }) {
     const outgoingSessionId = createSessionId(sessionKey, localAccount, remoteAccount);
     const incomingSessionId = createSessionId(sessionKey, remoteAccount, localAccount);
+    // Message bytes must fit within the statement limit minus the fixed wire overhead.
+    const maxPayloadSize = Math.max(0, maxRequestSize - STATEMENT_OVERHEAD);
     const state = {
         phase: 'initialization',
         initError: null,
         expiry: 0n,
         outgoingRequest: null,
-        incomingRequest: null,
-        respondedIncomingRequest: false,
+        incomingRequests: new Map(),
         messageQueue: [],
         pendingDelivery: new Map(),
         seenStatements: new Set(),
     };
     let subscribers = [];
+    // Reject callbacks for in-flight waitForRequestMessage() promises, so dispose()
+    // can settle them instead of leaving them to hang forever.
+    const requestWaiters = new Set();
     const bufferedMessages = [];
     let storeUnsub = null;
-    let responseStoreUnsub = null;
-    function submitStatementAt(expiry, channel, topicSessionId, data) {
+    let initRetries = 0;
+    let initRetryTimer = null;
+    let disposed = false;
+    // Id of the most recent response we initiated (responses share one channel, so only the
+    // latest is live — a retry for an older one must not resurrect it).
+    let lastResponseRequestId = null;
+    // Submit on `channel`/`topicSessionId` at the next (strictly increasing) expiry.
+    function submitStatementData(channel, topicSessionId, data) {
+        state.expiry = nextExpiry(state.expiry);
+        const expiry = state.expiry;
         return encryption
             .encrypt(data)
             .map(encrypted => ({
@@ -42,18 +128,46 @@ export function createSession({ localAccount, remoteAccount, statementStore, enc
             data: encrypted,
         }))
             .asyncAndThen(prover.generateMessageProof)
-            .andThen(statementStore.submitStatement);
+            .andThen(statementStore.submitStatement)
+            .orElse(error => {
+            // The chain is the source of truth for a channel's priority. If our in-memory counter
+            // drifted behind it (a prior run, another writer, or propagation lag), resync to the
+            // reported minimum so the retry — and every later submit — clears it.
+            if (error instanceof ExpiryTooLowError && error.min > state.expiry)
+                state.expiry = error.min;
+            return errAsync(error);
+        });
     }
-    function submitStatementData(channel, topicSessionId, data) {
-        state.expiry = nextExpiry(state.expiry);
-        return submitStatementAt(state.expiry, channel, topicSessionId, data);
+    // Settle and remove the pending-delivery entries for the given tokens.
+    function settleTokens(tokens, settle) {
+        for (const token of tokens) {
+            const deferred = state.pendingDelivery.get(token);
+            if (deferred) {
+                settle(deferred);
+                state.pendingDelivery.delete(token);
+            }
+        }
     }
     function encodeAndSubmitRequest(requestId, messages) {
-        const encode = fromThrowable(StatementData.enc, toError);
-        encode({ tag: 'request', value: { requestId, data: messages } })
-            .asyncAndThen(data => submitStatementData(createRequestChannel(outgoingSessionId), outgoingSessionId, data))
+        encodeStatementData({ tag: 'request', value: { requestId, data: messages } })
+            .asyncAndThen(data => submitWithRetry(() => submitStatementData(createRequestChannel(outgoingSessionId), outgoingSessionId, data), MAX_SUBMIT_RETRIES, 
+        // Only keep retrying while this is still the live submission (not superseded by a
+        // newer retransmit, aborted via clearOutgoingStatement, or disposed).
+        () => !disposed && state.outgoingRequest?.requestIds.at(-1) === requestId))
             .mapErr(e => {
+            if (disposed)
+                return;
             console.error('submitRequest failed:', e);
+            // Retries are exhausted. If this is still the live submission (not already
+            // superseded by a newer retransmit), the request never landed — fail its
+            // waiters rather than let them hang. A superseded older submission failing
+            // is expected and must NOT reject, since the newer one carries the same tokens.
+            const outgoing = state.outgoingRequest;
+            if (outgoing && outgoing.requestIds[outgoing.requestIds.length - 1] === requestId) {
+                settleTokens(outgoing.tokens, deferred => deferred.reject(e));
+                state.outgoingRequest = null;
+                processMessageQueue();
+            }
         });
     }
     function deliverStatementData(statementData) {
@@ -73,36 +187,58 @@ export function createSession({ localAccount, remoteAccount, statementStore, enc
     }
     function tryDecodeStatement(statement) {
         if (!statement.data)
-            return okAsync(null);
+            return okAsync({ kind: 'undecodable', requestId: null });
         const data = statement.data;
-        return prover
+        return (prover
             .verifyMessageProof(statement)
             .andThen(verified => (verified ? ok() : err(new Error('Invalid proof'))))
             .andThen(() => encryption.decrypt(data))
-            .map(decrypted => StatementData.dec(decrypted))
-            .orElse(() => ok(null));
+            .map(decrypted => {
+            const decoded = decodeStatementData(decrypted);
+            return decoded.isOk()
+                ? { kind: 'decoded', data: decoded.value }
+                : { kind: 'undecodable', requestId: recoverRequestId(decrypted) };
+        })
+            // Proof or decryption failure: the payload (incl. the requestId) is unreadable → drop.
+            .orElse(() => okAsync({ kind: 'undecodable', requestId: null })));
     }
-    function processIncomingStatement(statement, responsesOnly = false) {
+    function processIncomingStatement(statement) {
         if (!statement.data)
             return;
         const key = toHex(statement.data);
         if (state.seenStatements.has(key))
             return;
         state.seenStatements.add(key);
-        tryDecodeStatement(statement).andTee(statementData => {
-            if (!statementData)
+        void tryDecodeStatement(statement).andTee(outcome => {
+            if (outcome.kind === 'undecodable') {
+                if (outcome.requestId === null) {
+                    // Proof/decryption failed, or no requestId was recoverable — nothing to NACK.
+                    console.warn('statement-store: dropping an undecodable incoming statement (no recoverable requestId)');
+                    return;
+                }
+                // Only NACK a genuinely new id. If we already know this request, a valid copy is being
+                // handled (or was already answered) — NACKing now would mask the real response, since the
+                // `responded` flag is sticky.
+                if (state.incomingRequests.has(outcome.requestId))
+                    return;
+                // Decrypted but the message body is malformed — NACK so the sender stops waiting.
+                state.incomingRequests.set(outcome.requestId, { responded: false });
+                void session
+                    .submitResponseMessage(outcome.requestId, 'decodingFailed')
+                    .mapErr(e => console.error('statement-store: failed to NACK an undecodable request:', e));
                 return;
+            }
+            const statementData = outcome.data;
             if (statementData.tag === 'request') {
-                if (responsesOnly)
+                const requestId = statementData.value.requestId;
+                if (state.incomingRequests.has(requestId))
                     return;
-                if (statementData.value.requestId === state.incomingRequest?.requestId)
-                    return;
-                state.incomingRequest = { requestId: statementData.value.requestId };
-                state.respondedIncomingRequest = false;
+                state.incomingRequests.set(requestId, { responded: false });
                 deliverStatementData(statementData);
             }
             else if (statementData.tag === 'response') {
-                if (!state.outgoingRequest?.requestIds.includes(statementData.value.requestId))
+                const outgoing = state.outgoingRequest;
+                if (!outgoing?.requestIds.includes(statementData.value.requestId))
                     return;
                 const responseMessage = {
                     type: 'response',
@@ -110,66 +246,82 @@ export function createSession({ localAccount, remoteAccount, statementStore, enc
                     requestId: statementData.value.requestId,
                     responseCode: statementData.value.responseCode,
                 };
-                for (const token of state.outgoingRequest.tokens) {
-                    const deferred = state.pendingDelivery.get(token);
-                    if (deferred) {
-                        deferred.resolve(responseMessage);
-                        state.pendingDelivery.delete(token);
-                    }
-                }
+                settleTokens(outgoing.tokens, deferred => deferred.resolve(responseMessage));
                 state.outgoingRequest = null;
                 deliverStatementData(statementData);
                 processMessageQueue();
             }
         });
     }
-    function processNewMessage(encoded, token) {
+    // Returns true if `encoded` matches a message already in flight or queued, after
+    // attaching `token` to it so the caller resolves on that message's response
+    // instead of the bytes being submitted a second time.
+    function attachToDuplicate(encoded, token) {
+        const encodedHex = toHex(encoded);
+        const sameBytes = (m) => m.length === encoded.length && toHex(m) === encodedHex;
+        const outgoing = state.outgoingRequest;
+        if (outgoing && outgoing.messages.some(sameBytes)) {
+            outgoing.tokens.push(token);
+            return true;
+        }
+        const queued = state.messageQueue.find(entry => sameBytes(entry.encoded));
+        if (queued) {
+            queued.tokens.push(token);
+            return true;
+        }
+        return false;
+    }
+    function processNewMessage(encoded, tokens) {
         if (state.outgoingRequest === null) {
             const requestId = nanoid();
-            state.outgoingRequest = { requestIds: [requestId], messages: [encoded], tokens: [token] };
+            state.outgoingRequest = { requestIds: [requestId], messages: [encoded], tokens: [...tokens] };
             encodeAndSubmitRequest(requestId, state.outgoingRequest.messages);
         }
+        else if (requestPayloadSize([...state.outgoingRequest.messages, encoded]) <= maxPayloadSize) {
+            state.outgoingRequest.messages.push(encoded);
+            state.outgoingRequest.tokens.push(...tokens);
+            const newRequestId = nanoid();
+            state.outgoingRequest.requestIds.push(newRequestId);
+            encodeAndSubmitRequest(newRequestId, state.outgoingRequest.messages);
+        }
         else {
-            const currentTotal = state.outgoingRequest.messages.reduce((s, m) => s + m.length, 0);
-            if (currentTotal + encoded.length <= maxRequestSize) {
-                state.outgoingRequest.messages.push(encoded);
-                state.outgoingRequest.tokens.push(token);
-                const newRequestId = nanoid();
-                state.outgoingRequest.requestIds.push(newRequestId);
-                encodeAndSubmitRequest(newRequestId, state.outgoingRequest.messages);
-            }
-            else {
-                state.messageQueue.push({ encoded, token });
-            }
+            state.messageQueue.push({ encoded, tokens });
         }
     }
     function processMessageQueue() {
         while (state.messageQueue.length > 0) {
             const head = state.messageQueue[0];
             // Recompute per iteration; `processNewMessage` mutates outgoingRequest.messages in place.
-            const currentTotal = state.outgoingRequest?.messages.reduce((s, m) => s + m.length, 0) ?? 0;
-            if (state.outgoingRequest !== null && currentTotal + head.encoded.length > maxRequestSize)
+            if (state.outgoingRequest !== null &&
+                requestPayloadSize([...state.outgoingRequest.messages, head.encoded]) > maxPayloadSize) {
                 break;
+            }
             state.messageQueue.shift();
-            processNewMessage(head.encoded, head.token);
+            processNewMessage(head.encoded, head.tokens);
         }
     }
     function ensureStoreSubscription() {
         if (storeUnsub)
             return;
+        // A single subscription on the incoming topic carries BOTH the peer's requests
+        // and the peer's responses to our requests (the peer publishes everything on its
+        // outgoing topic = our incoming topic). We publish on the outgoing topic, which
+        // we don't subscribe to, so our own statements are never echoed back.
         storeUnsub = statementStore.subscribeStatements({ matchAll: [incomingSessionId] }, page => {
             for (const statement of page.statements) {
                 processIncomingStatement(statement);
             }
         });
-        // Subscribe to outgoing topic to receive peer ACK responses.
-        // Only process response-type statements — request-type statements on this topic
-        // are our own submissions echoed back and must be ignored.
-        responseStoreUnsub = statementStore.subscribeStatements({ matchAll: [outgoingSessionId] }, ({ statements }) => {
-            for (const statement of statements) {
-                processIncomingStatement(statement, true);
-            }
-        });
+    }
+    // Once a request is answered it no longer needs to be replayed to future subscribers (and a
+    // late waitForRequestMessage must not re-receive an already-handled request). Dropping it also
+    // keeps bufferedMessages from growing unboundedly with every incoming request.
+    function pruneBufferedRequest(requestId) {
+        for (let i = bufferedMessages.length - 1; i >= 0; i--) {
+            const sd = bufferedMessages[i];
+            if (sd && sd.tag === 'request' && sd.value.requestId === requestId)
+                bufferedMessages.splice(i, 1);
+        }
     }
     function rejectAllPending(error) {
         for (const [, deferred] of state.pendingDelivery) {
@@ -184,38 +336,59 @@ export function createSession({ localAccount, remoteAccount, statementStore, enc
         rejectAllPending(error);
     }
     async function init() {
-        const [ownResult, peerResult] = await Promise.all([
+        const result = await ResultAsync.combine([
             statementStore.queryStatements({ matchAll: [outgoingSessionId] }),
             statementStore.queryStatements({ matchAll: [incomingSessionId] }),
         ]);
-        if (ownResult.isErr()) {
-            failInit(ownResult.error);
-            return;
-        }
-        if (peerResult.isErr()) {
-            failInit(peerResult.error);
+        if (result.isErr()) {
+            if (disposed)
+                return;
+            // Transient transport failure: retry init (preserving the message queue) before
+            // giving up. Only after the cap is reached do we fail terminally.
+            if (initRetries < MAX_INIT_RETRIES) {
+                initRetries++;
+                // Store the handle so dispose() can cancel it — otherwise a disposed session keeps
+                // querying and can re-activate itself if a late retry succeeds.
+                initRetryTimer = setTimeout(() => {
+                    initRetryTimer = null;
+                    void init();
+                }, RETRY_DELAY_MS);
+                return;
+            }
+            failInit(result.error);
             return;
         }
-        const ownStatements = ownResult.value;
-        const peerStatements = peerResult.value;
+        initRetries = 0;
+        const [ownStatements, peerStatements] = result.value;
         let maxExpiry = 0n;
         for (const s of ownStatements) {
             if (s.expiry !== undefined && s.expiry > maxExpiry)
                 maxExpiry = s.expiry;
         }
-        state.expiry = nextExpiry(maxExpiry);
+        // Never regress the counter. The query is a snapshot taken when init() began; a statement
+        // submitted while init was in flight (e.g. an auto-ACK for a peer request that arrived during
+        // the query) has already advanced both state.expiry and the on-chain channel past that
+        // snapshot. Overwriting unconditionally would drop the counter below the on-chain priority,
+        // making the next submit collide at an equal expiry.
+        const seeded = nextExpiry(maxExpiry);
+        if (seeded > state.expiry)
+            state.expiry = seeded;
         for (const s of [...ownStatements, ...peerStatements]) {
             if (s.data)
                 state.seenStatements.add(toHex(s.data));
         }
-        const decodeAll = (statements) => Promise.all(statements.map(s => tryDecodeStatement(s).match(v => v, () => null))).then(r => r.filter(nonNullable));
+        const decodeAll = (statements) => Promise.all(statements.map(s => tryDecodeStatement(s).unwrapOr({ kind: 'undecodable', requestId: null }))).then(outcomes => outcomes.map(o => (o.kind === 'decoded' ? o.data : null)).filter(nonNullable));
         const [ownDecoded, peerDecoded] = await Promise.all([decodeAll(ownStatements), decodeAll(peerStatements)]);
+        // Both parties publish on their own outgoing topic, so the OUTGOING query returns our
+        // requests + OUR responses, and the INCOMING query returns the peer's requests + the
+        // PEER's responses. Hence: our request is answered by a PEER response (incoming), and we
+        // have answered a peer request iff OUR response (outgoing) carries its id.
         const ownRequest = ownDecoded.find(d => d.tag === 'request');
         const ownResponse = ownDecoded.find(d => d.tag === 'response');
         const peerRequest = peerDecoded.find(d => d.tag === 'request');
         const peerResponse = peerDecoded.find(d => d.tag === 'response');
         if (ownRequest?.tag === 'request') {
-            const hasResponse = ownResponse?.tag === 'response' && ownResponse.value.requestId === ownRequest.value.requestId;
+            const hasResponse = peerResponse?.tag === 'response' && peerResponse.value.requestId === ownRequest.value.requestId;
             if (!hasResponse) {
                 state.outgoingRequest = {
                     requestIds: [ownRequest.value.requestId],
@@ -225,15 +398,18 @@ export function createSession({ localAccount, remoteAccount, statementStore, enc
             }
         }
         if (peerRequest?.tag === 'request') {
-            state.incomingRequest = { requestId: peerRequest.value.requestId };
-            state.respondedIncomingRequest =
-                peerResponse?.tag === 'response' && peerResponse.value.requestId === peerRequest.value.requestId;
-        }
-        // Notify app of any unresponded incoming request.
-        // Delivered while phase is still 'initialization' so that deliverStatementData
-        // buffers the message for replay if no subscriber is registered yet.
-        if (peerRequest && state.incomingRequest && !state.respondedIncomingRequest) {
-            deliverStatementData(peerRequest);
+            const requestId = peerRequest.value.requestId;
+            // Don't clobber an entry a live delivery may have created during the awaits
+            // above (the live one is newer/authoritative).
+            if (!state.incomingRequests.has(requestId)) {
+                const responded = ownResponse?.tag === 'response' && ownResponse.value.requestId === requestId;
+                state.incomingRequests.set(requestId, { responded });
+                // Notify app of an unresponded incoming request. Delivered while phase is
+                // still 'initialization' so deliverStatementData buffers it for replay if
+                // no subscriber is registered yet.
+                if (!responded)
+                    deliverStatementData(peerRequest);
+            }
         }
         state.phase = 'active';
         processMessageQueue();
@@ -250,61 +426,108 @@ export function createSession({ localAccount, remoteAccount, statementStore, enc
             if (encodedResult.isErr())
                 return errAsync(encodedResult.error);
             const encoded = encodedResult.value;
-            if (encoded.length > maxRequestSize)
+            if (requestPayloadSize([encoded]) > maxPayloadSize)
                 return errAsync(new Error('message too big'));
             if (state.phase === 'failed') {
                 return errAsync(state.initError ?? new Error('Session initialization failed'));
             }
             const token = nanoid();
-            let resolveFn;
-            let rejectFn;
-            const promise = new Promise((res, rej) => {
-                resolveFn = res;
-                rejectFn = rej;
-            });
-            state.pendingDelivery.set(token, { resolve: resolveFn, reject: rejectFn, promise });
-            // Ensure a rejection from clearOutgoingStatement()/dispose() is always handled,
-            // even when no caller attached via waitForResponseMessage(); the real waiter
-            // still receives the rejection through its own handler.
-            promise.catch(() => undefined);
-            if (state.phase === 'initialization') {
-                state.messageQueue.push({ encoded, token });
-            }
-            else {
-                processNewMessage(encoded, token);
+            state.pendingDelivery.set(token, makeDeferred());
+            // Dedup: an identical message already in flight or queued is not re-sent — the
+            // new caller is attached to it and resolves on the same response.
+            if (!attachToDuplicate(encoded, token)) {
+                // FIFO: never let a later (fitting) message overtake queued ones; only append
+                // to the live batch when nothing is waiting behind it.
+                if (state.phase === 'initialization' || state.messageQueue.length > 0) {
+                    state.messageQueue.push({ encoded, tokens: [token] });
+                }
+                else {
+                    processNewMessage(encoded, [token]);
+                }
             }
             return okAsync({ requestId: token });
         },
         submitResponseMessage(requestId, responseCode) {
-            if (state.respondedIncomingRequest)
-                return okAsync(undefined);
-            if (state.incomingRequest?.requestId !== requestId) {
+            const incoming = state.incomingRequests.get(requestId);
+            if (!incoming)
                 return errAsync(new Error(`No incoming request with id ${requestId}`));
+            if (incoming.responded) {
+                pruneBufferedRequest(requestId);
+                return okAsync(undefined);
             }
-            state.respondedIncomingRequest = true;
-            const encode = fromThrowable(StatementData.enc, toError);
-            return encode({ tag: 'response', value: { requestId, responseCode } }).asyncAndThen(data => submitStatementData(createResponseChannel(incomingSessionId), incomingSessionId, data));
+            const encoded = encodeStatementData({ tag: 'response', value: { requestId, responseCode } });
+            if (encoded.isErr())
+                return errAsync(encoded.error);
+            // Mark responded up-front so concurrent callers dedupe, but roll back if the
+            // submission fails — otherwise the ACK is lost forever (and a peer retransmit
+            // with a fresh id could never be answered either).
+            incoming.responded = true;
+            lastResponseRequestId = requestId;
+            // Responses go on OUR outgoing topic/response-channel (per spec: the responder
+            // publishes on SessionId(self, peer)); the requester reads them from its incoming topic.
+            return (submitWithRetry(() => submitStatementData(createResponseChannel(outgoingSessionId), outgoingSessionId, encoded.value), MAX_SUBMIT_RETRIES, 
+            // Stop retrying once a newer response supersedes this one (shared response channel) or disposed.
+            () => !disposed && lastResponseRequestId === requestId)
+                // Answered: it no longer needs replaying to future subscribers.
+                .andTee(() => pruneBufferedRequest(requestId))
+                .orElse(error => {
+                incoming.responded = false;
+                return errAsync(error);
+            }));
         },
         waitForRequestMessage(codec, filter) {
-            const promise = new Promise(resolve => {
-                const unsubscribe = session.subscribe(codec, messages => {
+            const promise = new Promise((resolve, reject) => {
+                let settled = false;
+                // Initialised to a no-op so a synchronous buffered-replay match during
+                // subscribe() can call it without hitting the temporal dead zone; the
+                // real unsubscribe is wired in once subscribe() returns.
+                let unsubscribe = () => undefined;
+                const finish = (run) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    requestWaiters.delete(rejectWaiter);
+                    unsubscribe();
+                    run();
+                };
+                const rejectWaiter = (error) => finish(() => reject(error));
+                requestWaiters.add(rejectWaiter);
+                unsubscribe = session.subscribe(codec, messages => {
                     for (const message of messages) {
                         if (message.type !== 'request')
                             continue;
-                        const payload = message.payload;
-                        if (payload.status !== 'parsed')
+                        if (message.payload.status !== 'parsed')
                             continue;
-                        const filtered = filter(payload.value);
-                        if (filtered) {
-                            unsubscribe();
-                            resolve(filtered);
-                            break;
+                        const filtered = filter(message.payload.value);
+                        if (filtered !== undefined) {
+                            finish(() => resolve(filtered));
+                            return;
                         }
                     }
                 });
+                // subscribe() may have matched synchronously (buffered replay) while
+                // `unsubscribe` was still the no-op above — tear down the real one now.
+                if (settled)
+                    unsubscribe();
             });
             return fromPromise(promise, toError);
         },
+        respondToRequests(codec, handler) {
+            return session.subscribe(codec, messages => {
+                for (const message of messages) {
+                    if (message.type !== 'request')
+                        continue;
+                    const handled = handler(message);
+                    const statusResult = handled instanceof ResultAsync ? handled : okAsync(handled);
+                    void statusResult
+                        .orElse(() => okAsync('unknown'))
+                        .andThen(code => session.submitResponseMessage(message.requestId, code))
+                        .mapErr(e => {
+                        console.error('respondToRequests: failed to submit response:', e);
+                    });
+                }
+            });
+        },
         waitForResponseMessage(token) {
             const deferred = state.pendingDelivery.get(token);
             if (!deferred)
@@ -326,24 +549,14 @@ export function createSession({ localAccount, remoteAccount, statementStore, enc
             }
             return () => {
                 subscribers = subscribers.filter(s => s !== sub);
-                if (subscribers.length === 0) {
-                    if (storeUnsub) {
-                        storeUnsub();
-                        storeUnsub = null;
-                    }
-                    if (responseStoreUnsub) {
-                        responseStoreUnsub();
-                        responseStoreUnsub = null;
-                    }
+                if (subscribers.length === 0 && storeUnsub) {
+                    storeUnsub();
+                    storeUnsub = null;
                 }
             };
         },
         clearOutgoingStatement() {
             const outgoing = state.outgoingRequest;
-            // Reuse the current expiry (do NOT call nextExpiry): the live batch was last
-            // submitted at state.expiry, so an empty statement at the same expiry on the
-            // same channel supersedes it. The store rejects only a strictly lower expiry.
-            const expiry = state.expiry;
             // Always drop local outgoing state and reject pending waiters up-front,
             // regardless of which path follows. This covers messages queued before the
             // batch went out (e.g. during init, while outgoingRequest is still null) and
@@ -355,20 +568,32 @@ export function createSession({ localAccount, remoteAccount, statementStore, enc
             if (outgoing === null)
                 return okAsync(undefined);
             const requestId = outgoing.requestIds[outgoing.requestIds.length - 1];
-            const encoded = fromThrowable(StatementData.enc, toError)({
-                tag: 'request',
-                value: { requestId, data: [] },
-            });
+            const encoded = encodeStatementData({ tag: 'request', value: { requestId, data: [] } });
             if (encoded.isErr())
                 return errAsync(encoded.error);
-            return submitStatementAt(expiry, createRequestChannel(outgoingSessionId), outgoingSessionId, encoded.value);
+            // Supersede the live batch with an empty one. Use submitStatementData so the
+            // empty statement goes out at a STRICTLY higher expiry — the store rejects an
+            // equal-or-lower expiry on the same channel, so reusing state.expiry would
+            // leave the original request live on-chain.
+            return submitStatementData(createRequestChannel(outgoingSessionId), outgoingSessionId, encoded.value);
         },
         dispose() {
+            disposed = true;
+            if (initRetryTimer) {
+                clearTimeout(initRetryTimer);
+                initRetryTimer = null;
+            }
             storeUnsub?.();
             storeUnsub = null;
-            responseStoreUnsub?.();
-            responseStoreUnsub = null;
             subscribers = [];
+            // Drop pending work so no in-flight retry or queue drain acts on a disposed session.
+            state.outgoingRequest = null;
+            state.messageQueue = [];
+            // Settle any waitForRequestMessage() promises so callers unwind instead of
+            // hanging forever. Snapshot first — rejecting mutates the set.
+            for (const rejectWaiter of [...requestWaiters])
+                rejectWaiter(new Error('Session disposed'));
+            requestWaiters.clear();
             rejectAllPending(new Error('Session disposed'));
         },
     };