@novasamatech/statement-store 0.8.7-0 → 0.8.7-1

package/dist/session/session.spec.js

@@ -1,10 +1,13 @@
 import { createExpiryFromDuration } from '@novasamatech/sdk-statement';
 import { ResultAsync, errAsync, ok, okAsync } from 'neverthrow';
-import { Bytes, str } from 'scale-ts';
+import { Bytes, Struct, str } from 'scale-ts';
 import { describe, expect, it, vi } from 'vitest';
+import { createInMemoryStatementStore } from '../adapter/inMemory.js';
+import { ExpiryTooLowError } from '../adapter/types.js';
 import { createAccountId, createLocalSessionAccount, createRemoteSessionAccount } from '../model/sessionAccount.js';
+import { DecodingError, UnknownError } from './error.js';
 import { StatementData } from './scale/statementData.js';
-import { createSession, nextExpiry } from './session.js';
+import { STATEMENT_OVERHEAD, createSession, nextExpiry } from './session.js';
 // Real signature work belongs in statementProver tests; this stub stamps a
 // non-empty proof so submitted statements are well-formed.
 const mockProver = {
@@ -47,10 +50,16 @@ function makeStatement(statementData, expiry) {
         channel: `0x${'00'.repeat(32)}`,
     };
 }
-function makeSession(overrides) {
+function makeSession(opts = {}) {
     const { localAccount, remoteAccount } = makeAccounts();
-    const { maxRequestSize, ...adapterOverrides } = overrides ?? {};
-    const adapter = { ...makeAdapter(), ...adapterOverrides };
+    const { own = [], peer = [], maxRequestSize, ...adapterOverrides } = opts;
+    const adapter = makeAdapter();
+    // init() queries the outgoing (own) topic first, then the incoming (peer) topic.
+    let queryCall = 0;
+    adapter.queryStatements.mockImplementation(() => okAsync(queryCall++ === 0 ? own : peer));
+    // Explicit adapter mocks (e.g. a capturing subscribeStatements, or a custom
+    // queryStatements) take precedence over the own/peer defaults.
+    Object.assign(adapter, adapterOverrides);
     const session = createSession({
         localAccount,
         remoteAccount,
@@ -64,27 +73,88 @@ function makeSession(overrides) {
     });
     return { session, adapter };
 }
+// Capture the callbacks the session registers via subscribeStatements so a test can
+// push statement pages itself. The session subscribes once, to the incoming topic
+// (callbacks[0]), which carries both peer requests and peer responses.
+function capturingSubscribe() {
+    const callbacks = [];
+    const subscribeStatements = vi.fn((_filter, cb) => {
+        callbacks.push(cb);
+        return vi.fn();
+    });
+    return { subscribeStatements, callbacks };
+}
+function lastSubmitted(adapter) {
+    return adapter.submitStatement.mock.calls.at(-1)[0];
+}
+function lastSubmittedRequestId(adapter) {
+    const decoded = StatementData.dec(lastSubmitted(adapter).data);
+    return decoded.tag === 'request' ? decoded.value.requestId : '';
+}
+// Encoded size of the request payload (the statement `data` field) for these messages —
+// what the session sizes batches against. Includes the requestId (a fixed-length nanoid)
+// and the SCALE vector framing, so it is larger than the raw message bytes alone.
+function reqPayloadSize(...messages) {
+    return StatementData.enc({ tag: 'request', value: { requestId: 'x'.repeat(21), data: messages } }).length;
+}
 async function delay(ttl = 0) {
     await new Promise(resolve => setTimeout(resolve, ttl));
 }
+// Drain microtasks + macrotasks repeatedly so a multi-hop cross-session
+// exchange (submit → deliver → process → submit → …) fully settles.
+async function settle() {
+    for (let i = 0; i < 12; i++)
+        await delay();
+}
+// Two mirrored sessions sharing one in-memory store. A SHARED session key makes
+// them derive the same SessionId pair (host.outgoing === peer.incoming, and vice
+// versa) — a real host/papp pairing. With identity encryption/prover, each side
+// decrypts and verifies the other's statements.
+const SHARED_KEY = new Uint8Array(32).fill(7);
+const localA = createLocalSessionAccount(createAccountId(new Uint8Array(32).fill(1)));
+const remoteA = createRemoteSessionAccount(createAccountId(new Uint8Array(32).fill(1)), new Uint8Array(32).fill(11));
+const localB = createLocalSessionAccount(createAccountId(new Uint8Array(32).fill(2)));
+const remoteB = createRemoteSessionAccount(createAccountId(new Uint8Array(32).fill(2)), new Uint8Array(32).fill(22));
+const RemoteMsg = Struct({ id: str, kind: str, respondingTo: str, body: str });
+const requestMsg = (id) => ({ id, kind: 'request', respondingTo: '', body: id });
+function makeHost(adapter) {
+    return createSession({
+        localAccount: localA,
+        remoteAccount: remoteB,
+        statementStore: adapter,
+        encryption: mockEncryption(),
+        prover: mockProver,
+        sessionKey: SHARED_KEY,
+    });
+}
+function makeMobile(adapter) {
+    return createSession({
+        localAccount: localB,
+        remoteAccount: remoteA,
+        statementStore: adapter,
+        encryption: mockEncryption(),
+        prover: mockProver,
+        sessionKey: SHARED_KEY,
+    });
+}
 describe('session', () => {
-    describe('nextExpiry', () => {
-        it('returns fresh expiry when current is 0', () => {
-            const result = nextExpiry(0n);
-            expect(result).toBeGreaterThan(0n);
+    const rawCodec = Bytes();
+    // Statement expiry/priority: u64 = (expiration_epoch << 32) | priority. The high word is pinned
+    // to 0xFFFFFFFF (non-expiring) and the low word is a wall-clock-floored monotonic priority that
+    // drives channel supersession. (Spec §1; matches iOS/Android.)
+    describe('expiry priority', () => {
+        it('encodes a non-expiring statement (high word pinned to 0xFFFFFFFF)', () => {
+            expect(nextExpiry(0n) >> 32n).toBe(0xffffffffn);
         });
-        it('returns fresh expiry when current is less than fresh', () => {
-            const stale = createExpiryFromDuration(1); // 1 second from now, will be smaller than 7-day
-            const result = nextExpiry(stale);
-            const fresh = createExpiryFromDuration(7 * 24 * 60 * 60);
-            expect(result).toBeGreaterThanOrEqual(fresh);
+        it('carries a wall-clock priority in the low word', () => {
+            const result = nextExpiry(0n);
+            expect(result & 0xffffffffn).toBeGreaterThan(0n);
         });
-        it('returns current + 1n when current is already at or above fresh', () => {
-            const high = createExpiryFromDuration(7 * 24 * 60 * 60 + 999999);
-            const result = nextExpiry(high);
-            expect(result).toBe(high + 1n);
+        it('increments by one when the current value already exceeds the wall-clock priority', () => {
+            const high = (0xffffffffn << 32n) | 0xffffffffn; // max u64
+            expect(nextExpiry(high)).toBe(high + 1n);
         });
-        it('is monotonically increasing across repeated calls', () => {
+        it('is strictly monotonic across repeated calls', () => {
             let expiry = 0n;
             for (let i = 0; i < 5; i++) {
                 const next = nextExpiry(expiry);
@@ -93,163 +163,291 @@ describe('session', () => {
             }
         });
     });
-    describe('createSession initialization', () => {
-        it('queries own and peer statements on creation', async () => {
+    // On creation a session queries both of its topics, derives the starting expiry, and buffers
+    // anything it finds until it goes active. (Spec §5 initialization.)
+    describe('initialization', () => {
+        it('queries the outgoing and incoming topics on creation', async () => {
             const { adapter } = makeSession();
             await delay();
-            // Two single-topic matchAll queries — one per channel (outgoing/incoming).
-            // The topics must differ; otherwise both queries would target the same channel.
+            // Two single-topic matchAll queries — one per topic (outgoing/incoming); they must differ.
             const topics = adapter.queryStatements.mock.calls.map(([f]) => f.matchAll);
             expect(topics).toHaveLength(2);
             expect(topics.map(t => t.length)).toEqual([1, 1]);
             expect(topics[0]).not.toEqual(topics[1]);
         });
-        it('expiry is initialized from max own statement expiry', async () => {
+        it('seeds the expiry from the highest own statement expiry', async () => {
             const highExpiry = createExpiryFromDuration(7 * 24 * 60 * 60) + 9999n;
             const ownRequest = makeStatement({ tag: 'request', value: { requestId: 'r1', data: [] } }, highExpiry);
-            const adapter = makeAdapter();
-            let firstCall = true;
-            adapter.queryStatements.mockImplementation(() => {
-                if (firstCall) {
-                    firstCall = false;
-                    return okAsync([ownRequest]);
-                }
-                return okAsync([]);
-            });
-            const { session } = makeSession(adapter);
+            const { session, adapter } = makeSession({ own: [ownRequest] });
             await delay();
-            // Submit a message to trigger a statement — its expiry must be greater than highExpiry
-            const rawCodec = Bytes();
+            // The next submitted statement must carry an expiry greater than the highest seen.
             void session.submitRequestMessage(rawCodec, new Uint8Array([1]));
             await delay();
-            const submittedStatement = adapter.submitStatement.mock.calls[0]?.[0];
-            if (submittedStatement) {
-                expect(submittedStatement.expiry).toBeGreaterThan(highExpiry);
-            }
+            expect(lastSubmitted(adapter).expiry).toBeGreaterThan(highExpiry);
         });
-        it('marks own and peer statement data as seen during init', async () => {
+        it('buffers an incoming request found during init for a subscriber that registers later', async () => {
             const peerRequest = makeStatement({ tag: 'request', value: { requestId: 'r2', data: [new Uint8Array([1])] } });
-            const adapter = makeAdapter();
-            let callCount = 0;
-            adapter.queryStatements.mockImplementation(() => {
-                callCount++;
-                if (callCount === 2)
-                    return okAsync([peerRequest]);
-                return okAsync([]);
-            });
-            const { session } = makeSession(adapter);
+            const { session } = makeSession({ peer: [peerRequest] });
             await delay();
-            // Register subscriber AFTER init — buffered incoming request should be delivered
             const callback = vi.fn();
-            session.subscribe(Bytes(), callback);
+            session.subscribe(rawCodec, callback);
             expect(callback).toHaveBeenCalled();
         });
-        it('transitions to active phase after queries complete', async () => {
+        it('queues messages submitted before init completes and sends them once active', async () => {
             const { session, adapter } = makeSession();
-            // Before init completes, submitRequestMessage queues the message
+            // Submitted while still initializing → queued, not sent yet.
             void session.submitRequestMessage(str, 'hello');
-            // Statement should NOT be submitted yet (still initializing)
             expect(adapter.submitStatement).not.toHaveBeenCalled();
             await delay();
-            // After init, queued messages are processed → submitStatement called
+            // After init the queue is drained.
             expect(adapter.submitStatement).toHaveBeenCalled();
         });
-    });
-    describe('session state restoration', () => {
-        it('restores outgoingRequest when own has request with no peer response', async () => {
-            const requestId = 'saved-request-id';
-            const ownRequest = makeStatement({ tag: 'request', value: { requestId, data: [] } });
-            const adapter = makeAdapter();
-            let callCount = 0;
-            adapter.queryStatements.mockImplementation(() => {
-                callCount++;
-                if (callCount === 1)
-                    return okAsync([ownRequest]);
-                return okAsync([]); // no peer response
+        it('does not regress its expiry counter when a response is submitted during init', async () => {
+            // A peer request auto-ACKed while init() is still in flight advances both state.expiry and
+            // the on-chain channel past the init query snapshot. init() must not reset the counter below
+            // that, or the next submit collides at an equal expiry (the single-writer drift).
+            let releaseInit;
+            const initBarrier = new Promise(resolve => {
+                releaseInit = resolve;
+            });
+            const queryStatements = vi.fn(() => ResultAsync.fromSafePromise(initBarrier.then(() => [])));
+            const { subscribeStatements, callbacks } = capturingSubscribe();
+            const { session, adapter } = makeSession({ queryStatements, subscribeStatements });
+            session.respondToRequests(rawCodec, () => 'success'); // activates the subscription + auto-ACK
+            // Two peer requests answered while init() is still pending → two response submits.
+            callbacks[0]({
+                statements: [makeStatement({ tag: 'request', value: { requestId: 'a', data: [new Uint8Array([1])] } })],
+                isComplete: true,
+            });
+            callbacks[0]({
+                statements: [makeStatement({ tag: 'request', value: { requestId: 'b', data: [new Uint8Array([2])] } })],
+                isComplete: true,
             });
-            const { session } = makeSession(adapter);
             await delay();
-            // If outgoingRequest was restored, a new message appends to it
-            const codec = str;
-            void session.submitRequestMessage(codec, 'hello');
+            const inInitMax = adapter.submitStatement.mock.calls
+                .map(c => c[0].expiry ?? 0n)
+                .reduce((m, e) => (e > m ? e : m), 0n);
+            expect(inInitMax).toBeGreaterThan(0n); // sanity: responses really went out during init
+            releaseInit();
+            await delay();
+            // A response after init completes must use an expiry strictly above the in-init submits.
+            callbacks[0]({
+                statements: [makeStatement({ tag: 'request', value: { requestId: 'c', data: [new Uint8Array([3])] } })],
+                isComplete: true,
+            });
+            await delay();
+            const afterInit = (adapter.submitStatement.mock.calls.at(-1)?.[0]).expiry ?? 0n;
+            expect(afterInit).toBeGreaterThan(inInitMax);
+            session.dispose();
+        });
+    });
+    // On restart a session rebuilds its in-flight state from the on-chain statements. A request is
+    // answered by the PEER's response (read from our incoming topic); we have answered a peer request
+    // iff OUR response (on our outgoing topic) carries its id. (Spec §4 response placement + §5.)
+    describe('state restoration on restart', () => {
+        it('restores the outgoing request when it has no response yet', async () => {
+            const ownRequest = makeStatement({ tag: 'request', value: { requestId: 'saved-request-id', data: [] } });
+            const { session, adapter } = makeSession({ own: [ownRequest] }); // no peer response
+            await delay();
+            // If outgoingRequest was restored, a new message appends to it.
+            void session.submitRequestMessage(str, 'hello');
             await delay();
             expect(adapter.submitStatement).toHaveBeenCalled();
         });
-        it('clears outgoingRequest when peer has a matching response', async () => {
-            const requestId = 'acked-request';
-            const ownRequest = makeStatement({ tag: 'request', value: { requestId, data: [] } });
-            const peerResponse = makeStatement({ tag: 'response', value: { requestId, responseCode: 'success' } });
-            const adapter = makeAdapter();
-            let callCount = 0;
-            adapter.queryStatements.mockImplementation(() => {
-                callCount++;
-                // Outgoing topic contains both our request AND the peer's response
-                if (callCount === 1)
-                    return okAsync([ownRequest, peerResponse]);
-                return okAsync([]);
-            });
-            const { session } = makeSession(adapter);
+        it('does not restore the outgoing request once the peer has responded', async () => {
+            // Our request is on our outgoing topic; the peer's response to it is on our incoming topic.
+            const ownRequest = makeStatement({ tag: 'request', value: { requestId: 'or', data: [new Uint8Array([1])] } });
+            const peerResponse = makeStatement({ tag: 'response', value: { requestId: 'or', responseCode: 'success' } });
+            const { session, adapter } = makeSession({ own: [ownRequest], peer: [peerResponse] });
             await delay();
-            // No pending outgoing request — new message creates a brand new request
-            const codec = str;
-            void session.submitRequestMessage(codec, 'hi');
+            // Answered → not restored as pending → a new message starts a fresh batch (data length 1, not 2).
+            void session.submitRequestMessage(rawCodec, new Uint8Array([9]));
             await delay();
-            // submitStatement called exactly once (for the new message only)
-            expect(adapter.submitStatement).toHaveBeenCalledTimes(1);
+            const decoded = StatementData.dec(lastSubmitted(adapter).data);
+            expect(decoded.tag === 'request' && decoded.value.data.length).toBe(1);
+            session.dispose();
         });
-        it('restores incomingRequest from peer statements', async () => {
+        it('restores an unanswered incoming request so it can still be answered', async () => {
             const requestId = 'peer-request-id';
             const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [] } });
-            const adapter = makeAdapter();
-            let callCount = 0;
-            adapter.queryStatements.mockImplementation(() => {
-                callCount++;
-                if (callCount === 2)
-                    return okAsync([peerRequest]);
-                return okAsync([]);
-            });
-            const { session } = makeSession(adapter);
+            const { session } = makeSession({ peer: [peerRequest] });
             await delay();
-            // Calling submitResponseMessage with restored requestId should succeed
             const result = await session.submitResponseMessage(requestId, 'success');
             expect(result.isOk()).toBe(true);
         });
-        it('sets respondedIncomingRequest=true when own has a response for the peer request', async () => {
+        it('treats an incoming request as already answered when our response is present (no resubmit)', async () => {
             const requestId = 'peer-request-id';
             const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [] } });
             const ownResponse = makeStatement({ tag: 'response', value: { requestId, responseCode: 'success' } });
-            const adapter = makeAdapter();
-            let callCount = 0;
-            adapter.queryStatements.mockImplementation(() => {
-                callCount++;
-                if (callCount === 1)
-                    return okAsync([]);
-                // Incoming topic contains both the peer's request AND our response
-                return okAsync([peerRequest, ownResponse]);
-            });
-            const { session } = makeSession(adapter);
+            // The peer's request is on our incoming topic; OUR response to it is on our outgoing topic.
+            const { session, adapter } = makeSession({ own: [ownResponse], peer: [peerRequest] });
             await delay();
-            // Already responded — submitResponseMessage should return ok without submitting again
             const submitsBefore = adapter.submitStatement.mock.calls.length;
             const result = await session.submitResponseMessage(requestId, 'success');
             expect(result.isOk()).toBe(true);
             expect(adapter.submitStatement.mock.calls.length).toBe(submitsBefore); // no new submit
         });
+        it('does not re-deliver an incoming request we already answered', async () => {
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId: 'pr', data: [new Uint8Array([1])] } });
+            const ownResponse = makeStatement({ tag: 'response', value: { requestId: 'pr', responseCode: 'success' } });
+            const { session } = makeSession({ own: [ownResponse], peer: [peerRequest] });
+            await delay();
+            const cb = vi.fn();
+            session.subscribe(rawCodec, cb);
+            expect(cb).not.toHaveBeenCalled(); // already responded → not re-delivered for re-processing
+            session.dispose();
+        });
     });
-    describe('subscribe', () => {
-        const rawCodec = Bytes();
-        it('delivers buffered init messages when subscriber registers after init', async () => {
+    // Outgoing messages are batched into one in-flight request; overflow is queued and sent only once
+    // the live request is answered. Identical messages are de-duplicated, order is preserved, and the
+    // batch is sized against the statement limit minus the fixed wire overhead. (Spec §6.)
+    describe('sending requests', () => {
+        it('sends a single statement for the first message', async () => {
+            const { session, adapter } = makeSession();
+            await delay();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3]));
+            await delay();
+            expect(adapter.submitStatement).toHaveBeenCalledTimes(1);
+        });
+        it('appends a second message to the in-flight batch and resubmits', async () => {
+            const { session, adapter } = makeSession();
+            await delay();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1]));
+            void session.submitRequestMessage(rawCodec, new Uint8Array([2]));
+            await delay();
+            // Two submits: first for msg1, second for the msg1+msg2 batch.
+            expect(adapter.submitStatement).toHaveBeenCalledTimes(2);
+        });
+        it('sizes a batch by its full encoded payload, not the raw message bytes', async () => {
+            const m1 = rawCodec.enc(new Uint8Array([1, 2, 3]));
+            const m2 = rawCodec.enc(new Uint8Array([4, 5, 6]));
+            // Budget fits a one-message request but not a two-message one — even though the raw
+            // message bytes are tiny, the requestId + SCALE framing tip the second over the limit.
+            const maxRequestSize = STATEMENT_OVERHEAD + reqPayloadSize(m1, m2) - 1;
+            expect(m1.length + m2.length).toBeLessThan(reqPayloadSize(m1)); // raw sum < a single-message payload
+            const { session, adapter } = makeSession({ maxRequestSize });
+            await delay();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3]));
+            void session.submitRequestMessage(rawCodec, new Uint8Array([4, 5, 6])); // raw sum fits, full payload doesn't
+            await delay();
+            // The second message is queued, not appended → only the first batch was submitted.
+            expect(adapter.submitStatement).toHaveBeenCalledTimes(1);
+        });
+        it('drains the queue after the in-flight batch is answered', async () => {
+            const { subscribeStatements, callbacks } = capturingSubscribe();
+            const m1 = rawCodec.enc(new Uint8Array([1, 2, 3]));
+            const m2 = rawCodec.enc(new Uint8Array([4, 5, 6]));
+            const maxRequestSize = STATEMENT_OVERHEAD + reqPayloadSize(m1, m2) - 1; // m1 fits, m1+m2 doesn't
+            const { session, adapter } = makeSession({ maxRequestSize, subscribeStatements });
+            await delay();
+            session.subscribe(Bytes(), vi.fn()); // ensure the store subscription is active
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3])); // sent
+            void session.submitRequestMessage(rawCodec, new Uint8Array([4, 5, 6])); // queued (doesn't fit)
+            await delay();
+            const submitCountBefore = adapter.submitStatement.mock.calls.length;
+            // Peer responds to the live request (responses arrive on our incoming topic).
+            const responseStatement = makeStatement({
+                tag: 'response',
+                value: { requestId: lastSubmittedRequestId(adapter), responseCode: 'success' },
+            });
+            callbacks[0]({ statements: [responseStatement], isComplete: true });
+            await delay();
+            // The queued message is now submitted.
+            expect(adapter.submitStatement.mock.calls.length).toBeGreaterThan(submitCountBefore);
+        });
+        it('resolves waitForResponseMessage when the batch is answered', async () => {
+            const { subscribeStatements, callbacks } = capturingSubscribe();
+            const { session, adapter } = makeSession({ subscribeStatements });
+            await delay();
+            session.subscribe(Bytes(), vi.fn()); // ensure the store subscription is active
+            const submitResult = await session.submitRequestMessage(rawCodec, new Uint8Array([1]));
+            const token = submitResult.unwrapOr({ requestId: '' }).requestId;
+            await delay();
+            const responsePromise = session.waitForResponseMessage(token);
+            callbacks[0]({
+                statements: [
+                    makeStatement({
+                        tag: 'response',
+                        value: { requestId: lastSubmittedRequestId(adapter), responseCode: 'success' },
+                    }),
+                ],
+                isComplete: true,
+            });
+            await delay();
+            const result = await responsePromise;
+            expect(result.isOk()).toBe(true);
+            expect(result.unwrapOr({ responseCode: 'unknown' }).responseCode).toBe('success');
+        });
+        it('does not resend a message that is already in flight (dedup)', async () => {
+            const store = createInMemoryStatementStore();
+            const session = makeHost(store);
+            await settle();
+            const msg = new Uint8Array([1, 2, 3]);
+            void session.submitRequestMessage(rawCodec, msg);
+            await settle();
+            const acceptedAfterFirst = store.acceptedStatements().length;
+            void session.submitRequestMessage(rawCodec, msg); // identical → must not resubmit
+            await settle();
+            expect(store.acceptedStatements().length).toBe(acceptedAfterFirst);
+            session.dispose();
+        });
+        it('resolves every caller of a deduplicated message on the single response', async () => {
+            const { subscribeStatements, callbacks } = capturingSubscribe();
+            const { session, adapter } = makeSession({ subscribeStatements });
+            await delay();
+            session.subscribe(rawCodec, vi.fn());
+            const r1 = await session.submitRequestMessage(rawCodec, new Uint8Array([7, 7]));
+            const r2 = await session.submitRequestMessage(rawCodec, new Uint8Array([7, 7])); // duplicate
+            const w1 = session.waitForResponseMessage(r1._unsafeUnwrap().requestId);
+            const w2 = session.waitForResponseMessage(r2._unsafeUnwrap().requestId);
+            await delay();
+            callbacks[0]({
+                statements: [
+                    makeStatement({
+                        tag: 'response',
+                        value: { requestId: lastSubmittedRequestId(adapter), responseCode: 'success' },
+                    }),
+                ],
+                isComplete: true,
+            });
+            await delay();
+            expect((await w1).isOk()).toBe(true);
+            expect((await w2).isOk()).toBe(true);
+        });
+        it('preserves FIFO order: a later fitting message does not overtake queued ones', async () => {
+            const m1 = rawCodec.enc(new Uint8Array([1, 2, 3])); // first → in-flight batch
+            const mBig = rawCodec.enc(new Uint8Array([4, 5, 6, 7, 8, 9, 10])); // does not fit alongside m1 → queued
+            const mSmall = rawCodec.enc(new Uint8Array([9])); // would fit alongside m1, but must queue behind mBig
+            const maxRequestSize = STATEMENT_OVERHEAD + reqPayloadSize(m1, mBig) - 1;
+            expect(reqPayloadSize(m1, mSmall)).toBeLessThanOrEqual(reqPayloadSize(m1, mBig) - 1); // mSmall alone could fit
+            const { session, adapter } = makeSession({ maxRequestSize });
+            await delay();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3]));
+            void session.submitRequestMessage(rawCodec, new Uint8Array([4, 5, 6, 7, 8, 9, 10]));
+            void session.submitRequestMessage(rawCodec, new Uint8Array([9]));
+            await delay();
+            const decoded = StatementData.dec(lastSubmitted(adapter).data);
+            expect(decoded.tag === 'request' && decoded.value.data.length).toBe(1); // still only the first message
+        });
+        it('rejects a message whose full request payload exceeds the limit', async () => {
+            const m = rawCodec.enc(new Uint8Array([1, 2, 3, 4]));
+            // The single-message request payload (requestId + framing + the message) is over budget.
+            const { session, adapter } = makeSession({ maxRequestSize: STATEMENT_OVERHEAD + reqPayloadSize(m) - 1 });
+            await delay();
+            adapter.submitStatement.mockClear();
+            const result = await session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3, 4]));
+            expect(result.isErr()).toBe(true);
+            expect(adapter.submitStatement).not.toHaveBeenCalled();
+        });
+    });
+    // A single subscription on the incoming topic carries both peer requests and peer responses.
+    // Requests are buffered so a subscriber registering after delivery still receives them; already
+    // seen statements are dropped. (Spec §4 reading + §6 dedup.)
+    describe('receiving statements', () => {
+        it('delivers a buffered incoming request to a subscriber that registers after init', async () => {
             const requestId = 'incoming-req';
             const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [new Uint8Array([1, 2, 3])] } });
-            const adapter = makeAdapter();
-            let callCount = 0;
-            adapter.queryStatements.mockImplementation(() => {
-                callCount++;
-                if (callCount === 2)
-                    return okAsync([peerRequest]);
-                return okAsync([]);
-            });
-            const { session } = makeSession(adapter);
+            const { session } = makeSession({ peer: [peerRequest] });
             await delay(); // init completes
             const callback = vi.fn();
             session.subscribe(rawCodec, callback);
@@ -258,18 +456,10 @@ describe('session', () => {
             expect(messages[0]?.type).toBe('request');
             expect(messages[0]?.requestId).toBe(requestId);
         });
-        it('delivers init messages via subscribe when subscriber is registered before init completes', async () => {
+        it('delivers a buffered incoming request to a subscriber that registers before init completes', async () => {
             const requestId = 'early-subscribe';
             const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [new Uint8Array([1])] } });
-            const adapter = makeAdapter();
-            let callCount = 0;
-            adapter.queryStatements.mockImplementation(() => {
-                callCount++;
-                if (callCount === 2)
-                    return okAsync([peerRequest]);
-                return okAsync([]);
-            });
-            const { session } = makeSession(adapter);
+            const { session } = makeSession({ peer: [peerRequest] });
             const callback = vi.fn();
             session.subscribe(rawCodec, callback); // before init completes
             await delay();
@@ -277,278 +467,300 @@ describe('session', () => {
             const messages2 = callback.mock.calls[0][0];
             expect(messages2[0]?.requestId).toBe(requestId);
         });
-        it('does NOT deliver already-seen statements from subscription', async () => {
+        it('does not redeliver an already-seen statement', async () => {
             const requestId = 'seen-req';
             const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [new Uint8Array([1])] } });
-            const adapter = makeAdapter();
-            let queryCallCount = 0;
-            adapter.queryStatements.mockImplementation(() => {
-                queryCallCount++;
-                if (queryCallCount === 2)
-                    return okAsync([peerRequest]);
-                return okAsync([]);
-            });
-            let subscribeCallback;
-            adapter.subscribeStatements.mockImplementation((_filter, cb) => {
-                subscribeCallback = cb;
-                return vi.fn();
-            });
-            const { session } = makeSession(adapter);
-            await delay(); // init sees peerRequest, adds to seenStatements
+            const { subscribeStatements, callbacks } = capturingSubscribe();
+            const { session } = makeSession({ peer: [peerRequest], subscribeStatements });
+            await delay(); // init sees peerRequest, adds it to seenStatements
             const appCallback = vi.fn();
             session.subscribe(rawCodec, appCallback);
-            // Simulate subscription delivering the same statement again
-            subscribeCallback({ statements: [peerRequest], isComplete: true });
+            // The store redelivers the same statement on the incoming topic — dedup must drop it.
+            callbacks[0]({ statements: [peerRequest], isComplete: true });
             await delay();
-            // Should only be called once (from buffered init message), not again from subscription
+            // Called only once (from the buffered init message), not again from the subscription.
             expect(appCallback).toHaveBeenCalledTimes(1);
         });
-        it('does NOT auto-send a response when an incoming request arrives', async () => {
-            const requestId = 'no-auto-resp';
-            const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [new Uint8Array([1])] } });
-            const adapter = makeAdapter();
-            const subscribeCallbacks = [];
-            adapter.subscribeStatements.mockImplementation((_filter, cb) => {
-                subscribeCallbacks.push(cb);
-                return vi.fn();
+        it('does not auto-respond when an incoming request arrives', async () => {
+            const peerRequest = makeStatement({
+                tag: 'request',
+                value: { requestId: 'no-auto-resp', data: [new Uint8Array([1])] },
             });
-            adapter.queryStatements.mockReturnValue(okAsync([]));
-            const { session } = makeSession(adapter);
+            const { subscribeStatements, callbacks } = capturingSubscribe();
+            const { session, adapter } = makeSession({ subscribeStatements });
             await delay();
             const callback = vi.fn();
             session.subscribe(rawCodec, callback);
             adapter.submitStatement.mockClear();
-            // Fire on the incoming topic callback (first subscription)
-            subscribeCallbacks[0]({ statements: [peerRequest], isComplete: true });
+            callbacks[0]({ statements: [peerRequest], isComplete: true });
             await delay();
-            // Message delivered to app callback but no automatic response submitted
+            // Delivered to the app, but no response is submitted automatically.
             expect(callback).toHaveBeenCalled();
             expect(adapter.submitStatement).not.toHaveBeenCalled();
         });
-        it('delivers peer request to a subscriber that registers after the batch notification (race condition)', async () => {
-            // Regression test for PB-439: when peer's request and the ACK response arrive in the
-            // same subscribeStatements batch, the request is processed before waitForRequestMessage
-            // has a chance to register its subscriber. The fix ensures request statements are always
-            // buffered so late subscribers (simulating waitForRequestMessage called in .andThen()
-            // after waitForResponseMessage resolves) still receive them.
-            const subscribeCallbacks = [];
-            const subscribeStatements = vi.fn().mockImplementation((_filter, cb) => {
-                subscribeCallbacks.push(cb);
-                return vi.fn();
-            });
+        it('delivers a buffered request to a subscriber that registers after the batch notification', async () => {
+            // When a request and an ACK arrive in the same batch, the request is processed before a later
+            // waitForRequestMessage registers its subscriber. Requests are buffered so the late subscriber
+            // still receives them (otherwise waitForRequestMessage would hang).
+            const { subscribeStatements, callbacks } = capturingSubscribe();
             const { session } = makeSession({ subscribeStatements });
             await delay();
-            // Register a dummy subscriber to activate the store subscription (simulates
-            // any pre-existing subscriber in the session, e.g. the app listening for messages).
+            // A pre-existing subscriber activates the store subscription.
             const dummyUnsub = session.subscribe(rawCodec, vi.fn());
             const peerRequestId = 'race-condition-request';
             const peerRequest = makeStatement({
                 tag: 'request',
                 value: { requestId: peerRequestId, data: [new Uint8Array([42])] },
             });
-            // Peer request arrives on the incoming topic (first subscription) while the
-            // dummy subscriber is active but waitForRequestMessage hasn't registered its
-            // subscriber yet (the race condition scenario).
-            subscribeCallbacks[0]({ statements: [peerRequest], isComplete: true });
+            // The request arrives before the late subscriber registers.
+            callbacks[0]({ statements: [peerRequest], isComplete: true });
             await delay();
-            // Now the late subscriber registers (simulates waitForRequestMessage being called
-            // in the .andThen() chain after waitForResponseMessage resolves).
             const lateCallback = vi.fn();
             session.subscribe(rawCodec, lateCallback);
-            // The late subscriber must receive the buffered peer request, otherwise
-            // waitForRequestMessage would hang indefinitely.
             expect(lateCallback).toHaveBeenCalledTimes(1);
             const messages = lateCallback.mock.calls[0][0];
             expect(messages[0]?.type).toBe('request');
             expect(messages[0]?.requestId).toBe(peerRequestId);
             dummyUnsub();
         });
-        it('unsubscribing last subscriber tears down the store subscription', () => {
-            const { session, adapter } = makeSession();
-            const unsub = session.subscribe(rawCodec, vi.fn());
-            expect(adapter.subscribeStatements).toHaveBeenCalledTimes(2);
-            unsub();
-            // subscribeStatements returns a mock unsubscribe fn — verify it was called
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            const storeMockUnsub = adapter.subscribeStatements.mock.results[0].value;
-            expect(storeMockUnsub).toHaveBeenCalled();
-        });
-        it('subscribes to outgoing topic for peer responses alongside incoming topic', () => {
-            const { session, adapter } = makeSession();
+        it('resolves waitForRequestMessage from a request already buffered at subscribe time', async () => {
+            // The subscribe() replay can invoke the filter synchronously during registration; the
+            // unsubscribe handle must already be usable at that point.
+            // The inner payload must decode cleanly with rawCodec so the filter actually runs.
+            const peerRequest = makeStatement({
+                tag: 'request',
+                value: { requestId: 'buf', data: [rawCodec.enc(new Uint8Array([7]))] },
+            });
+            const { session } = makeSession({ peer: [peerRequest] });
+            await delay(); // init buffers the peer request
+            const result = await session.waitForRequestMessage(rawCodec, () => 'matched');
+            expect(result._unsafeUnwrap()).toBe('matched');
+        }, 2000);
+        it('opens a single subscription on the incoming topic', () => {
+            const store = createInMemoryStatementStore();
+            const session = makeHost(store);
             session.subscribe(rawCodec, vi.fn());
-            // Two subscriptions: one for incoming (peer requests), one for outgoing (peer responses)
-            expect(adapter.subscribeStatements).toHaveBeenCalledTimes(2);
+            // One subscription: the incoming topic carries both peer requests and peer responses.
+            expect(store.activeSubscriptions()).toBe(1);
         });
-        it('tears down outgoing subscription when last subscriber leaves', () => {
-            const { session, adapter } = makeSession();
+        it('tears down the subscription when the last subscriber leaves', () => {
+            const store = createInMemoryStatementStore();
+            const session = makeHost(store);
             const unsub = session.subscribe(rawCodec, vi.fn());
+            expect(store.activeSubscriptions()).toBe(1);
             unsub();
-            // Both unsubscribe functions should be called
-            for (const result of adapter.subscribeStatements.mock.results) {
-                const mockUnsub = result.value;
-                expect(mockUnsub).toHaveBeenCalled();
-            }
+            expect(store.activeSubscriptions()).toBe(0);
         });
-        it('delivers peer response from outgoing topic subscription to subscribers', async () => {
-            const subscribeCallbacks = [];
-            const subscribeStatements = vi.fn().mockImplementation((_topics, cb) => {
-                subscribeCallbacks.push(cb);
-                return vi.fn();
-            });
+        it('delivers a peer response to subscribers', async () => {
+            const { subscribeStatements, callbacks } = capturingSubscribe();
             const { session, adapter } = makeSession({ subscribeStatements });
             await delay();
-            // Submit a request so the session has an outgoingRequest
-            void session.submitRequestMessage(rawCodec, new Uint8Array([1]));
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1])); // creates an outgoing request
             await delay();
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            const submitted = adapter.submitStatement.mock.calls[0][0];
-            const decoded = StatementData.dec(submitted.data);
-            const requestId = decoded.tag === 'request' ? decoded.value.requestId : '';
+            const requestId = lastSubmittedRequestId(adapter);
             const callback = vi.fn();
             session.subscribe(rawCodec, callback);
-            // Deliver the response via the SECOND subscription callback (outgoing topic)
-            // subscribeCallbacks[0] = incoming topic, subscribeCallbacks[1] = outgoing topic
             const responseStatement = makeStatement({
                 tag: 'response',
                 value: { requestId, responseCode: 'success' },
             });
-            subscribeCallbacks[1]({ statements: [responseStatement], isComplete: true });
+            callbacks[0]({ statements: [responseStatement], isComplete: true });
             await delay();
-            // Subscriber should receive the response
             const allCalls = callback.mock.calls.flat();
             const responseMessages = allCalls.flat().filter((m) => m.type === 'response');
             expect(responseMessages.length).toBeGreaterThan(0);
         });
-        it('ignores request-type statements from outgoing topic subscription', async () => {
-            const subscribeCallbacks = [];
-            const subscribeStatements = vi.fn().mockImplementation((_topics, cb) => {
-                subscribeCallbacks.push(cb);
-                return vi.fn();
-            });
-            const { session } = makeSession({ subscribeStatements });
-            await delay();
-            const callback = vi.fn();
-            session.subscribe(rawCodec, callback);
-            callback.mockClear(); // clear any buffered init messages
-            // Deliver a request via the outgoing topic subscription (would be our own echoed back)
-            const ownRequest = makeStatement({
-                tag: 'request',
-                value: { requestId: 'own-req', data: [new Uint8Array([1])] },
-            });
-            subscribeCallbacks[1]({ statements: [ownRequest], isComplete: true });
-            await delay();
-            // Should NOT be delivered to subscriber (filtered by responsesOnly flag)
-            expect(callback).not.toHaveBeenCalled();
+        it('stops replaying a buffered request to new subscribers once it has been answered', async () => {
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId: 'q', data: [new Uint8Array([1])] } });
+            const { session } = makeSession({ peer: [peerRequest] });
+            await delay(); // init buffers the unanswered request for replay
+            await session.submitResponseMessage('q', 'success'); // answer it
+            // A subscriber registering afterwards must not be handed the already-answered request
+            // (and the buffer must not retain it forever).
+            const late = vi.fn();
+            session.subscribe(rawCodec, late);
+            expect(late).not.toHaveBeenCalled();
+            session.dispose();
         });
     });
-    describe('submitResponseMessage', () => {
-        it('is idempotent — second call does not submit again', async () => {
+    // We answer the peer's requests by publishing a response on OUR outgoing topic/response-channel.
+    // submitResponseMessage is the low-level primitive; respondToRequests auto-answers from a handler.
+    // (Spec §4 response placement.)
+    describe('responding to incoming requests', () => {
+        it('is idempotent — a second response does not submit again', async () => {
             const requestId = 'req-to-respond';
             const peerRequest = makeStatement({ tag: 'request', value: { requestId, data: [] } });
-            const adapter = makeAdapter();
-            let callCount = 0;
-            adapter.queryStatements.mockImplementation(() => {
-                callCount++;
-                if (callCount === 2)
-                    return okAsync([peerRequest]);
-                return okAsync([]);
-            });
-            const { session } = makeSession(adapter);
+            const { session, adapter } = makeSession({ peer: [peerRequest] });
             await delay();
             await session.submitResponseMessage(requestId, 'success');
             const submitsAfterFirst = adapter.submitStatement.mock.calls.length;
             await session.submitResponseMessage(requestId, 'success'); // second call
             expect(adapter.submitStatement.mock.calls.length).toBe(submitsAfterFirst);
         });
-        it('returns error when requestId does not match incomingRequest', async () => {
+        it('errors when the requestId is unknown', async () => {
             const { session } = makeSession();
             await delay();
             const result = await session.submitResponseMessage('wrong-id', 'success');
             expect(result.isErr()).toBe(true);
         });
-    });
-    describe('message batching', () => {
-        const rawCodec = Bytes();
-        it('sends a single statement for the first message', async () => {
-            const { session, adapter } = makeSession();
+        it('NACKs an undecodable incoming request with decodingFailed', async () => {
+            // A request (enum tag 0) whose requestId decodes but whose data vector claims more
+            // elements than present → the body decode throws, the requestId is still recoverable.
+            const idBytes = new TextEncoder().encode('corrupt-rid');
+            const corrupted = new Uint8Array([0x00, idBytes.length << 2, ...idBytes, 0xfe, 0xff, 0xff, 0xff]);
+            const statement = { ...makeStatement({ tag: 'request', value: { requestId: 'x', data: [] } }), data: corrupted };
+            const { subscribeStatements, callbacks } = capturingSubscribe();
+            const { session, adapter } = makeSession({ subscribeStatements });
             await delay();
-            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3]));
+            session.subscribe(rawCodec, vi.fn()); // activate the subscription
+            adapter.submitStatement.mockClear();
+            callbacks[0]({ statements: [statement], isComplete: true });
             await delay();
             expect(adapter.submitStatement).toHaveBeenCalledTimes(1);
+            const decoded = StatementData.dec(lastSubmitted(adapter).data);
+            expect(decoded.tag).toBe('response');
+            if (decoded.tag === 'response') {
+                expect(decoded.value.requestId).toBe('corrupt-rid');
+                expect(decoded.value.responseCode).toBe('decodingFailed');
+            }
         });
-        it('appends second message to existing request (resubmits with new requestId)', async () => {
-            const { session, adapter } = makeSession();
+        it('drops an undecodable incoming statement with no recoverable request id', async () => {
+            // An invalid enum tag — nothing decodes, so there is no id to NACK.
+            const corrupted = new Uint8Array([0x05, 0x2c, 1, 2, 3]);
+            const statement = { ...makeStatement({ tag: 'request', value: { requestId: 'x', data: [] } }), data: corrupted };
+            const { subscribeStatements, callbacks } = capturingSubscribe();
+            const { session, adapter } = makeSession({ subscribeStatements });
             await delay();
-            void session.submitRequestMessage(rawCodec, new Uint8Array([1]));
-            void session.submitRequestMessage(rawCodec, new Uint8Array([2]));
+            session.subscribe(rawCodec, vi.fn());
+            adapter.submitStatement.mockClear();
+            callbacks[0]({ statements: [statement], isComplete: true });
             await delay();
-            // Two submits: first for msg1, second for msg1+msg2 batched
-            expect(adapter.submitStatement).toHaveBeenCalledTimes(2);
+            expect(adapter.submitStatement).not.toHaveBeenCalled();
         });
-        it('queues message that exceeds maxRequestSize', async () => {
-            const { session, adapter } = makeSession({ maxRequestSize: 5 });
+        it('does not NACK an undecodable copy of a request it already knows', async () => {
+            // A valid request is being handled; a corrupt copy of it must not trigger a premature
+            // decodingFailed that would mask the real response (the `responded` flag is sticky).
+            const reqId = 'known-req';
+            const valid = makeStatement({ tag: 'request', value: { requestId: reqId, data: [new Uint8Array([1])] } });
+            const idBytes = new TextEncoder().encode(reqId);
+            const corrupt = new Uint8Array([0x00, idBytes.length << 2, ...idBytes, 0xfe, 0xff, 0xff, 0xff]);
+            const corruptStatement = {
+                ...makeStatement({ tag: 'request', value: { requestId: 'x', data: [] } }),
+                data: corrupt,
+            };
+            const { subscribeStatements, callbacks } = capturingSubscribe();
+            const { session, adapter } = makeSession({ subscribeStatements });
             await delay();
-            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3])); // 3 bytes — fits
-            void session.submitRequestMessage(rawCodec, new Uint8Array([4, 5, 6, 7])); // 4 bytes — doesn't fit with existing
+            session.subscribe(rawCodec, vi.fn()); // activate the subscription
+            callbacks[0]({ statements: [valid], isComplete: true }); // reqId is now a known incoming request
             await delay();
-            // Only first message sent; second is queued
-            expect(adapter.submitStatement).toHaveBeenCalledTimes(1);
-        });
-        it('drains message queue after response received', async () => {
-            let subscribeCallback;
-            const subscribeStatements = vi.fn().mockImplementation((_filter, cb) => {
-                subscribeCallback = cb;
-                return vi.fn();
-            });
-            const { session, adapter } = makeSession({ maxRequestSize: 5, subscribeStatements });
+            adapter.submitStatement.mockClear();
+            callbacks[0]({ statements: [corruptStatement], isComplete: true }); // corrupt copy of the same id
             await delay();
-            session.subscribe(Bytes(), vi.fn()); // ensure store subscription is active
-            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3])); // sent
-            void session.submitRequestMessage(rawCodec, new Uint8Array([4, 5, 6])); // queued (doesn't fit)
+            expect(adapter.submitStatement).not.toHaveBeenCalled(); // no premature NACK
+            // The legitimate response still goes through.
+            const res = await session.submitResponseMessage(reqId, 'success');
+            expect(res.isOk()).toBe(true);
+            const decoded = StatementData.dec(lastSubmitted(adapter).data);
+            expect(decoded.tag === 'response' && decoded.value.responseCode).toBe('success');
+        });
+        it('publishes the response on the outgoing topic (same topic as our requests)', async () => {
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId: 'rid', data: [] } });
+            const { session, adapter } = makeSession({ peer: [peerRequest] });
             await delay();
-            const submitCountBefore = adapter.submitStatement.mock.calls.length;
-            // Simulate peer responding to the first request
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            const lastSubmittedStatement = adapter.submitStatement.mock.calls[adapter.submitStatement.mock.calls.length - 1][0];
-            const decoded = StatementData.dec(lastSubmittedStatement.data);
-            const respondingRequestId = decoded.tag === 'request' ? decoded.value.requestId : '';
-            const responseStatement = makeStatement({
-                tag: 'response',
-                value: { requestId: respondingRequestId, responseCode: 'success' },
-            });
-            subscribeCallback({ statements: [responseStatement], isComplete: true });
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1])); // → outgoing topic
             await delay();
-            // Queued message should now be submitted
-            expect(adapter.submitStatement.mock.calls.length).toBeGreaterThan(submitCountBefore);
+            const requestTopics = lastSubmitted(adapter).topics;
+            adapter.submitStatement.mockClear();
+            await session.submitResponseMessage('rid', 'success'); // must also go on the outgoing topic
+            const responseTopics = lastSubmitted(adapter).topics;
+            expect(responseTopics).toEqual(requestTopics);
         });
-        it('waitForResponseMessage resolves when response arrives for batch', async () => {
-            let subscribeCallback;
-            const subscribeStatements = vi.fn().mockImplementation((_filter, cb) => {
-                subscribeCallback = cb;
-                return vi.fn();
-            });
-            const { session, adapter } = makeSession({ subscribeStatements });
-            await delay();
-            session.subscribe(Bytes(), vi.fn()); // ensure store subscription is active
-            const submitResult = await session.submitRequestMessage(rawCodec, new Uint8Array([1]));
-            const token = submitResult.unwrapOr({ requestId: '' }).requestId;
+        // respondToRequests is exercised end-to-end over a shared in-memory store: a peer issues a real
+        // request and the handler's status flows all the way back through request()/mapResponseCode.
+        it('acknowledges an incoming request with the status the handler returns', async () => {
+            const store = createInMemoryStatementStore();
+            const host = makeHost(store);
+            const peer = makeMobile(store);
+            peer.subscribe(RemoteMsg, () => undefined); // peer must listen to receive the ACK
+            host.respondToRequests(RemoteMsg, () => 'success');
+            await settle();
+            const ack = await peer.request(RemoteMsg, requestMsg('p1'));
+            expect(ack.isOk()).toBe(true);
+            host.dispose();
+            peer.dispose();
+        });
+        it('maps a decodingFailed status back to the requester', async () => {
+            const store = createInMemoryStatementStore();
+            const host = makeHost(store);
+            const peer = makeMobile(store);
+            peer.subscribe(RemoteMsg, () => undefined);
+            host.respondToRequests(RemoteMsg, () => okAsync('decodingFailed'));
+            await settle();
+            const ack = await peer.request(RemoteMsg, requestMsg('p1'));
+            expect(ack.isErr()).toBe(true);
+            expect(ack._unsafeUnwrapErr()).toBeInstanceOf(DecodingError);
+            host.dispose();
+            peer.dispose();
+        });
+        it('answers with unknown when the handler errors', async () => {
+            const store = createInMemoryStatementStore();
+            const host = makeHost(store);
+            const peer = makeMobile(store);
+            peer.subscribe(RemoteMsg, () => undefined);
+            host.respondToRequests(RemoteMsg, () => errAsync(new Error('handler boom')));
+            await settle();
+            const ack = await peer.request(RemoteMsg, requestMsg('p1'));
+            expect(ack.isErr()).toBe(true);
+            expect(ack._unsafeUnwrapErr()).toBeInstanceOf(UnknownError);
+            host.dispose();
+            peer.dispose();
+        });
+        it('invokes the handler once per request and never for peer responses', async () => {
+            const store = createInMemoryStatementStore();
+            const host = makeHost(store);
+            const peer = makeMobile(store);
+            peer.subscribe(RemoteMsg, () => undefined);
+            const handler = vi.fn(() => 'success');
+            host.respondToRequests(RemoteMsg, handler);
+            await settle();
+            await peer.request(RemoteMsg, requestMsg('p1'));
+            // The host's own ACK (echoed back on its incoming topic) must not re-trigger the handler.
+            expect(handler).toHaveBeenCalledTimes(1);
+            host.dispose();
+            peer.dispose();
+        });
+        it('can answer an earlier incoming request after a newer one arrives', async () => {
+            const reqA = makeStatement({ tag: 'request', value: { requestId: 'A', data: [] } });
+            const { subscribeStatements, callbacks } = capturingSubscribe();
+            const { session } = makeSession({ peer: [reqA], subscribeStatements });
             await delay();
-            const responsePromise = session.waitForResponseMessage(token);
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            const lastStatement = adapter.submitStatement.mock.calls[adapter.submitStatement.mock.calls.length - 1][0];
-            const decoded = StatementData.dec(lastStatement.data);
-            const respondingId = decoded.tag === 'request' ? decoded.value.requestId : '';
-            subscribeCallback({
-                statements: [makeStatement({ tag: 'response', value: { requestId: respondingId, responseCode: 'success' } })],
-                isComplete: true,
-            });
+            session.subscribe(rawCodec, vi.fn()); // activate the store subscription
+            const reqB = makeStatement({ tag: 'request', value: { requestId: 'B', data: [] } });
+            callbacks[0]({ statements: [reqB], isComplete: true });
             await delay();
-            const result = await responsePromise;
-            expect(result.isOk()).toBe(true);
-            expect(result.unwrapOr({ responseCode: 'unknown' }).responseCode).toBe('success');
+            const resA = await session.submitResponseMessage('A', 'success');
+            const resB = await session.submitResponseMessage('B', 'success');
+            expect(resA.isOk()).toBe(true);
+            expect(resB.isOk()).toBe(true);
         });
+        it('remains answerable after response submission retries are exhausted', async () => {
+            const peerRequest = makeStatement({ tag: 'request', value: { requestId: 'rid', data: [] } });
+            const { session, adapter } = makeSession({ peer: [peerRequest] });
+            await delay();
+            adapter.submitStatement.mockReturnValue(errAsync(new Error('store rejected')));
+            const first = await session.submitResponseMessage('rid', 'success'); // all retries fail → err + rollback
+            expect(first.isErr()).toBe(true);
+            adapter.submitStatement.mockReturnValue(okAsync(undefined)); // store recovers
+            const submitsBefore = adapter.submitStatement.mock.calls.length;
+            const second = await session.submitResponseMessage('rid', 'success'); // retryable → submits and succeeds
+            expect(second.isOk()).toBe(true);
+            expect(adapter.submitStatement.mock.calls.length).toBeGreaterThan(submitsBefore);
+        }, 3000);
     });
-    describe('clearOutgoingStatement', () => {
+    // clearOutgoingStatement aborts the in-flight request: it drops local state, rejects waiters, and
+    // supersedes the on-chain request with an empty batch at a strictly higher expiry.
+    describe('aborting the outgoing request', () => {
         it('is a no-op when there is no outgoing request', async () => {
             const { session, adapter } = makeSession();
             await delay();
@@ -557,10 +769,9 @@ describe('session', () => {
             expect(result.isOk()).toBe(true);
             expect(adapter.submitStatement.mock.calls.length).toBe(before);
         });
-        it('submits an empty request batch on the same channel at >= the live expiry and clears state', async () => {
+        it('submits an empty batch on the same channel at a higher expiry and clears local state', async () => {
             const { session, adapter } = makeSession();
             await delay();
-            const rawCodec = Bytes();
             void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3]));
             await delay();
             const liveCall = adapter.submitStatement.mock.calls.at(-1)?.[0];
@@ -577,7 +788,7 @@ describe('session', () => {
                 expect(clearDecoded.value.data).toEqual([]);
             expect(clearCall.channel).toBe(liveCall.channel);
             expect(clearCall.expiry).toBeGreaterThanOrEqual(liveCall.expiry);
-            // Outgoing state is cleared: the next message starts a brand-new batch (data length 1, not 2).
+            // State is cleared: the next message starts a brand-new batch (data length 1, not 2).
             void session.submitRequestMessage(rawCodec, new Uint8Array([4]));
             await delay();
             const afterClear = adapter.submitStatement.mock.calls.at(-1)?.[0];
@@ -585,10 +796,29 @@ describe('session', () => {
             if (afterDecoded.tag === 'request')
                 expect(afterDecoded.value.data.length).toBe(1);
         });
+        it('evicts the live on-chain request by superseding it at a strictly higher expiry', async () => {
+            // The store rejects an equal-expiry write on the same channel, so the empty batch must go out
+            // at a strictly higher expiry to actually evict the live request.
+            const store = createInMemoryStatementStore();
+            const session = makeHost(store);
+            await settle();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3]));
+            await settle();
+            const result = await session.clearOutgoingStatement();
+            expect(result.isOk()).toBe(true);
+            await settle();
+            const requests = store
+                .currentStatements()
+                .map(s => StatementData.dec(s.data))
+                .filter(d => d.tag === 'request');
+            expect(requests.some(d => d.tag === 'request' && d.value.data.length > 0)).toBe(false);
+            expect(requests.some(d => d.tag === 'request' && d.value.data.length === 0)).toBe(true);
+            session.dispose();
+        });
         it('rejects the pending response waiter so callers unwind', async () => {
             const { session } = makeSession();
             await delay();
-            const submit = await session.submitRequestMessage(Bytes(), new Uint8Array([9]));
+            const submit = await session.submitRequestMessage(rawCodec, new Uint8Array([9]));
             expect(submit.isOk()).toBe(true);
             const requestId = submit._unsafeUnwrap().requestId;
             const waiter = session.waitForResponseMessage(requestId);
@@ -596,10 +826,9 @@ describe('session', () => {
             const waited = await waiter;
             expect(waited.isErr()).toBe(true);
         });
-        it('clears local state and rejects waiters even when the superseding submission fails', async () => {
+        it('clears local state and rejects waiters even when the supersede submission fails', async () => {
             const { session, adapter } = makeSession();
             await delay();
-            const rawCodec = Bytes();
             const submit = await session.submitRequestMessage(rawCodec, new Uint8Array([1, 2, 3]));
             const requestId = submit._unsafeUnwrap().requestId;
             const waiter = session.waitForResponseMessage(requestId);
@@ -609,7 +838,7 @@ describe('session', () => {
             // The pending waiter is rejected despite the failed submission.
             const waited = await waiter;
             expect(waited.isErr()).toBe(true);
-            // Local state is cleared: the next message starts a brand-new batch (data length 1, not 2).
+            // State is cleared: the next message starts a brand-new batch (data length 1, not 2).
             adapter.submitStatement.mockReturnValue(okAsync(undefined));
             void session.submitRequestMessage(rawCodec, new Uint8Array([4]));
             await delay();
@@ -618,14 +847,14 @@ describe('session', () => {
             if (afterDecoded.tag === 'request')
                 expect(afterDecoded.value.data.length).toBe(1);
         });
-        it('cancels messages queued before the batch is submitted (init still pending)', async () => {
-            // queryStatements never resolves, so init() stays pending and the message
-            // sits in the queue with outgoingRequest still null.
+        it('cancels messages queued before the batch was submitted (init still pending)', async () => {
+            // queryStatements never resolves, so init() stays pending and the message sits in the queue
+            // with outgoingRequest still null.
             const neverResolves = vi
                 .fn()
                 .mockReturnValue(new ResultAsync(new Promise(() => undefined)));
             const { session, adapter } = makeSession({ queryStatements: neverResolves });
-            const submit = await session.submitRequestMessage(Bytes(), new Uint8Array([7]));
+            const submit = await session.submitRequestMessage(rawCodec, new Uint8Array([7]));
             const requestId = submit._unsafeUnwrap().requestId;
             const waiter = session.waitForResponseMessage(requestId);
             const submitsBefore = adapter.submitStatement.mock.calls.length;
@@ -637,5 +866,243 @@ describe('session', () => {
             // No empty batch is submitted since there was no live on-chain request yet.
             expect(adapter.submitStatement.mock.calls.length).toBe(submitsBefore);
         });
+        it('does not resurrect the aborted request when a submit retry is pending', async () => {
+            let calls = 0;
+            const submitStatement = vi.fn(() => {
+                calls++;
+                return calls === 1 ? errAsync(new Error('transient')) : okAsync(undefined); // first request submit fails → retry scheduled
+            });
+            const { session, adapter } = makeSession({ submitStatement });
+            await delay();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1])); // submit #1 fails, schedules a retry
+            await session.clearOutgoingStatement(); // abort: drops outgoing state + empty supersede (submit #2)
+            const callsAfterAbort = adapter.submitStatement.mock.calls.length;
+            await new Promise(resolve => setTimeout(resolve, 100)); // let the (now-stale) retry window elapse
+            expect(adapter.submitStatement.mock.calls.length).toBe(callsAfterAbort); // retry must NOT re-send the request
+            session.dispose();
+        }, 3000);
+    });
+    // The spec mandates retrying queries (init) and submit_statement on connection failure. The
+    // session retries transient failures with a bounded backoff. (Spec §5.)
+    describe('resilience (transient-failure retries)', () => {
+        it('retries initialization after a transient query failure', async () => {
+            let attempts = 0;
+            const queryStatements = vi.fn(() => {
+                attempts++;
+                return attempts <= 2 ? errAsync(new Error('transient')) : okAsync([]); // first init attempt fails
+            });
+            const { session, adapter } = makeSession({ queryStatements });
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1])); // queued during init
+            await new Promise(resolve => setTimeout(resolve, 200)); // allow re-init + activation
+            expect(adapter.submitStatement).toHaveBeenCalled(); // queued message sent after successful re-init
+            session.dispose();
+        }, 3000);
+        it('retries a request submission that transiently fails', async () => {
+            let calls = 0;
+            const submitStatement = vi.fn(() => {
+                calls++;
+                return calls === 1 ? errAsync(new Error('transient')) : okAsync(undefined);
+            });
+            const { session, adapter } = makeSession({ submitStatement });
+            await delay();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1]));
+            await new Promise(resolve => setTimeout(resolve, 150)); // allow retry
+            expect(adapter.submitStatement.mock.calls.length).toBeGreaterThanOrEqual(2); // 1 failure + ≥1 retry
+            session.dispose();
+        }, 3000);
+        it('resyncs its expiry above the chain minimum after an ExpiryTooLow rejection', async () => {
+            // The in-memory expiry counter has drifted behind the channel's real priority (prior run /
+            // other writer / propagation lag). The chain reports the minimum; the retry must clear it.
+            const CHAIN_MIN = (0xffffffffn << 32n) | 4000000000n; // well above the wall-clock priority
+            let calls = 0;
+            const submitStatement = vi.fn((stmt) => {
+                calls++;
+                return calls === 1 ? errAsync(new ExpiryTooLowError(stmt.expiry ?? 0n, CHAIN_MIN)) : okAsync(undefined);
+            });
+            const { session, adapter } = makeSession({ submitStatement });
+            await delay();
+            void session.submitRequestMessage(rawCodec, new Uint8Array([1]));
+            await new Promise(resolve => setTimeout(resolve, 100)); // allow the retry (25ms backoff)
+            expect(adapter.submitStatement.mock.calls.length).toBeGreaterThanOrEqual(2);
+            const retried = adapter.submitStatement.mock.calls.at(-1)?.[0];
+            expect(retried.expiry ?? 0n).toBeGreaterThan(CHAIN_MIN); // healed past the chain minimum
+            session.dispose();
+        }, 3000);
+        it('rejects the pending waiter once request-submission retries are exhausted', async () => {
+            const { session } = makeSession({
+                submitStatement: vi.fn().mockReturnValue(errAsync(new Error('store rejected'))),
+            });
+            await delay();
+            const submit = await session.submitRequestMessage(rawCodec, new Uint8Array([1]));
+            const requestId = submit._unsafeUnwrap().requestId;
+            const waited = await session.waitForResponseMessage(requestId);
+            expect(waited.isErr()).toBe(true);
+        }, 2000);
+    });
+    describe('dispose', () => {
+        it('rejects pending waitForRequestMessage waiters', async () => {
+            const { session } = makeSession();
+            await delay();
+            const waiter = session.waitForRequestMessage(rawCodec, () => 'x');
+            session.dispose();
+            const result = await waiter;
+            expect(result.isErr()).toBe(true);
+        }, 2000);
+        it('cancels a pending init retry (no further queries)', async () => {
+            const queryStatements = vi.fn(() => errAsync(new Error('store down'))); // init always fails → schedules retry
+            const { session } = makeSession({ queryStatements });
+            await delay(); // first init attempt completes (2 queries) and schedules a retry
+            const callsBeforeDispose = queryStatements.mock.calls.length;
+            session.dispose();
+            await new Promise(resolve => setTimeout(resolve, 100)); // retry window elapses
+            expect(queryStatements.mock.calls.length).toBe(callsBeforeDispose); // disposed → no further init queries
+        }, 3000);
+    });
+    // The in-memory adapter replicates the store's observable contract; `fidelity` pins the double's
+    // behaviour, then end-to-end flows run two mirrored sessions (host + mobile) over ONE shared store.
+    describe('in-memory statement store', () => {
+        const hex = (fill) => `0x${fill.toString(16).padStart(2, '0').repeat(32)}`;
+        function makeSignedStatement(channel, expiry, topic, data) {
+            return {
+                channel: channel,
+                expiry,
+                topics: [topic],
+                data,
+                proof: { type: 'sr25519', value: { signature: `0x${'00'.repeat(64)}`, signer: `0x${'00'.repeat(32)}` } },
+            };
+        }
+        describe('fidelity', () => {
+            it('accepts a new statement and returns it from a matching query', async () => {
+                const store = createInMemoryStatementStore();
+                await store.submitStatement(makeSignedStatement(hex(0xaa), 10n, hex(0x01), new Uint8Array([1])));
+                const found = (await store.queryStatements({ matchAll: [new Uint8Array(32).fill(1)] }))._unsafeUnwrap();
+                expect(found).toHaveLength(1);
+                expect(found[0]?.expiry).toBe(10n);
+            });
+            it('replaces a same-channel statement only with a strictly higher expiry', async () => {
+                const store = createInMemoryStatementStore();
+                await store.submitStatement(makeSignedStatement(hex(0xaa), 10n, hex(0x01), new Uint8Array([1])));
+                const higher = await store.submitStatement(makeSignedStatement(hex(0xaa), 11n, hex(0x01), new Uint8Array([2])));
+                expect(higher.isOk()).toBe(true);
+                expect(store.currentStatements()).toHaveLength(1);
+                expect(store.currentStatements()[0]?.expiry).toBe(11n);
+            });
+            it('rejects a same-channel statement with equal or lower expiry (ExpiryTooLowError)', async () => {
+                const store = createInMemoryStatementStore();
+                await store.submitStatement(makeSignedStatement(hex(0xaa), 10n, hex(0x01), new Uint8Array([1])));
+                const equal = await store.submitStatement(makeSignedStatement(hex(0xaa), 10n, hex(0x01), new Uint8Array([9])));
+                const lower = await store.submitStatement(makeSignedStatement(hex(0xaa), 5n, hex(0x01), new Uint8Array([9])));
+                expect(equal.isErr()).toBe(true);
+                expect(equal._unsafeUnwrapErr()).toBeInstanceOf(ExpiryTooLowError);
+                expect(lower.isErr()).toBe(true);
+                // The original statement is untouched.
+                expect(store.currentStatements()[0]?.data).toEqual(new Uint8Array([1]));
+            });
+            it('treats a byte-identical resubmission as known (ok, no duplicate)', async () => {
+                const store = createInMemoryStatementStore();
+                const stmt = makeSignedStatement(hex(0xaa), 10n, hex(0x01), new Uint8Array([1]));
+                await store.submitStatement(stmt);
+                const again = await store.submitStatement(stmt);
+                expect(again.isOk()).toBe(true);
+                expect(store.currentStatements()).toHaveLength(1);
+            });
+            it('coexists statements on different channels sharing a topic', async () => {
+                const store = createInMemoryStatementStore();
+                await store.submitStatement(makeSignedStatement(hex(0xaa), 10n, hex(0x01), new Uint8Array([1])));
+                await store.submitStatement(makeSignedStatement(hex(0xbb), 10n, hex(0x01), new Uint8Array([2])));
+                const found = (await store.queryStatements({ matchAll: [new Uint8Array(32).fill(1)] }))._unsafeUnwrap();
+                expect(found).toHaveLength(2);
+            });
+            it('streams only post-subscription matching statements to live subscribers', async () => {
+                const store = createInMemoryStatementStore();
+                await store.submitStatement(makeSignedStatement(hex(0xaa), 10n, hex(0x01), new Uint8Array([1])));
+                const pages = [];
+                store.subscribeStatements({ matchAll: [new Uint8Array(32).fill(1)] }, page => pages.push(page));
+                // Pre-existing statement is NOT replayed; a new matching one is delivered.
+                expect(pages).toHaveLength(0);
+                await store.submitStatement(makeSignedStatement(hex(0xaa), 11n, hex(0x01), new Uint8Array([2])));
+                expect(pages).toHaveLength(1);
+                expect(pages[0]?.statements[0]?.expiry).toBe(11n);
+                // A non-matching topic is not delivered.
+                await store.submitStatement(makeSignedStatement(hex(0xcc), 10n, hex(0x02), new Uint8Array([3])));
+                expect(pages).toHaveLength(1);
+            });
+        });
+        describe('end-to-end flows (host ↔ mobile over a shared store)', () => {
+            it('completes a request → ACK → reply → ACK round trip', async () => {
+                const store = createInMemoryStatementStore();
+                const host = makeHost(store);
+                const mobile = makeMobile(store);
+                // Mobile acknowledges every incoming request and, on seeing the host's
+                // request, sends its application reply back as a new request.
+                mobile.respondToRequests(RemoteMsg, () => 'success');
+                const mobileGotRequest = mobile.waitForRequestMessage(RemoteMsg, msg => msg.kind === 'request' ? msg : undefined);
+                // Host acknowledges the mobile's reply.
+                host.respondToRequests(RemoteMsg, () => 'success');
+                await settle();
+                const hostAck = host.request(RemoteMsg, { id: 'h1', kind: 'request', respondingTo: '', body: 'sign this' });
+                const mobileReplyAck = mobileGotRequest.andThen(req => mobile.request(RemoteMsg, { id: 'm1', kind: 'reply', respondingTo: req.id, body: 'signature' }));
+                const hostReply = host.waitForRequestMessage(RemoteMsg, msg => msg.kind === 'reply' && msg.respondingTo === 'h1' ? msg.body : undefined);
+                await settle();
+                expect((await hostAck).isOk()).toBe(true); // mobile ACKed the host request
+                expect((await mobileReplyAck).isOk()).toBe(true); // host ACKed the mobile reply
+                expect((await hostReply)._unsafeUnwrap()).toBe('signature'); // host received the reply
+                host.dispose();
+                mobile.dispose();
+            });
+            it('answers an incoming request that went unanswered until a restart', async () => {
+                const store = createInMemoryStatementStore();
+                const host = makeHost(store);
+                // Host must be listening to receive the eventual ACK.
+                host.respondToRequests(RemoteMsg, () => 'success');
+                // Mobile receives the request but never responds (no responder registered).
+                let mobile = makeMobile(store);
+                mobile.subscribe(RemoteMsg, () => undefined); // activate the store subscription, but do not ACK
+                await settle();
+                const hostAck = host.request(RemoteMsg, { id: 'h1', kind: 'request', respondingTo: '', body: 'sign this' });
+                await settle();
+                const beforeRestart = await Promise.race([
+                    Promise.resolve(hostAck).then(() => 'resolved'),
+                    new Promise(resolve => setTimeout(() => resolve('pending'), 20)),
+                ]);
+                expect(beforeRestart).toBe('pending'); // unanswered while the responder is absent
+                // Restart: a fresh mobile session on the same store rediscovers the
+                // unanswered request via init() and now answers it.
+                mobile.dispose();
+                mobile = makeMobile(store);
+                mobile.respondToRequests(RemoteMsg, () => 'success');
+                await settle();
+                expect((await hostAck).isOk()).toBe(true);
+                host.dispose();
+                mobile.dispose();
+            });
+            it('delivers the mobile reply to the host independently of the request ACK', async () => {
+                // The application reply (waitForRequestMessage) and the transport ACK (request →
+                // waitForResponseMessage) are independent channels. Here the mobile sends ONLY the reply
+                // and never ACKs the host request — the host must still receive the reply while its request
+                // ACK stays outstanding.
+                const store = createInMemoryStatementStore();
+                const host = makeHost(store);
+                const mobile = makeMobile(store);
+                const mobileGotRequest = mobile.waitForRequestMessage(RemoteMsg, msg => msg.kind === 'request' ? msg : undefined);
+                void mobileGotRequest.andThen(() => 
+                // Fire-and-forget the reply (do not wait for the host to ACK it).
+                mobile.submitRequestMessage(RemoteMsg, { id: 'm1', kind: 'reply', respondingTo: 'h1', body: 'signature' }));
+                await settle();
+                const hostReply = host.waitForRequestMessage(RemoteMsg, msg => msg.kind === 'reply' && msg.respondingTo === 'h1' ? msg.body : undefined);
+                const hostAck = host.request(RemoteMsg, { id: 'h1', kind: 'request', respondingTo: '', body: 'sign this' });
+                await settle();
+                // The reply is delivered…
+                expect((await hostReply)._unsafeUnwrap()).toBe('signature');
+                // …while the transport ACK is still outstanding (mobile never sent it).
+                const ackState = await Promise.race([
+                    Promise.resolve(hostAck).then(() => 'resolved'),
+                    new Promise(resolve => setTimeout(() => resolve('pending'), 20)),
+                ]);
+                expect(ackState).toBe('pending');
+                host.dispose();
+                mobile.dispose();
+            });
+        });
     });
 });