@novasamatech/statement-store 0.9.0 → 0.9.2

package/dist/session/multiDeviceSession.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Multi-device session (mds.md §"Sending P2P Messages"): one statement addressed to every
+ * device a peer runs, and one subscription covering every device they publish from.
+ *
+ * See `session.ts` for the single-device variant, and `core.ts` for the shared driver.
+ */
+import type { StatementStoreAdapter } from '../adapter/types.js';
+import type { AccountId } from '../model/sessionAccount.js';
+import type { ExpiryAllocator } from '../submit/allocator.js';
+import type { PeerRoster } from './codec/incomingTopics.js';
+import type { StatementProver } from './statementProver.js';
+import type { Session } from './types.js';
+export type MultiDeviceSessionParams = {
+    /** This device: statement account (proof signer identity) and its X25519 encryption key. */
+    localDevice: {
+        statementAccountId: Uint8Array;
+        encryptionPrivateKey: Uint8Array;
+    };
+    /** This user's identity: account id and the identity chat key shared across own devices. */
+    localIdentity: {
+        accountId: AccountId;
+        chatPrivateKey: Uint8Array;
+        pin?: string;
+    };
+    /** The peer user's identity. */
+    remoteIdentity: {
+        accountId: AccountId;
+        chatPublicKey: Uint8Array;
+        pin?: string;
+    };
+    /** The peer's devices — observable, since `deviceAdded`/`deviceRemoved` change it at runtime. */
+    peerRoster: PeerRoster;
+    statementStore: StatementStoreAdapter;
+    prover: StatementProver;
+    allocator?: ExpiryAllocator;
+    maxRequestSize?: number;
+};
+/**
+ * Multi-device session (mds.md §"Sending P2P Messages").
+ *
+ * Outgoing: `topic = SessionId(D(A), B)` keyed by `x25519(ownDeviceEncPriv,
+ * peerIdentityChatPub)`, carrying a `multiRequest`/`multiResponse` envelope wrapped for
+ * every known peer device.
+ *
+ * Incoming: one topic per peer device, `SessionId(D(B'), A)` keyed by
+ * `x25519(ownIdentityChatPriv, D(B').encPub)` — covered by a single `matchAny`
+ * subscription that re-opens when the roster changes.
+ */
+export declare function createMultiDeviceSession({ localDevice, localIdentity, remoteIdentity, peerRoster, statementStore, prover, allocator, maxRequestSize, }: MultiDeviceSessionParams): Session;

package/dist/session/multiDeviceSession.js

@@ -0,0 +1,62 @@
+/**
+ * Multi-device session (mds.md §"Sending P2P Messages"): one statement addressed to every
+ * device a peer runs, and one subscription covering every device they publish from.
+ *
+ * See `session.ts` for the single-device variant, and `core.ts` for the shared driver.
+ */
+import { x25519 } from '@noble/curves/ed25519.js';
+import { createSessionId } from '../model/session.js';
+import { createAccountId } from '../model/sessionAccount.js';
+import { createExpiryAllocator } from '../submit/allocator.js';
+import { createStatementDecoder } from './codec/decoder.js';
+import { createEnvelope } from './codec/envelope.js';
+import { createRosterTopics } from './codec/incomingTopics.js';
+import { createBodyBuilder } from './codec/outgoingBody.js';
+import { DEFAULT_MAX_REQUEST_SIZE, createSessionCore } from './core.js';
+import { createEncryption } from './encyption.js';
+/**
+ * Multi-device session (mds.md §"Sending P2P Messages").
+ *
+ * Outgoing: `topic = SessionId(D(A), B)` keyed by `x25519(ownDeviceEncPriv,
+ * peerIdentityChatPub)`, carrying a `multiRequest`/`multiResponse` envelope wrapped for
+ * every known peer device.
+ *
+ * Incoming: one topic per peer device, `SessionId(D(B'), A)` keyed by
+ * `x25519(ownIdentityChatPriv, D(B').encPub)` — covered by a single `matchAny`
+ * subscription that re-opens when the roster changes.
+ */
+export function createMultiDeviceSession({ localDevice, localIdentity, remoteIdentity, peerRoster, statementStore, prover, allocator = createExpiryAllocator(), maxRequestSize = DEFAULT_MAX_REQUEST_SIZE, }) {
+    const outgoingSharedSecret = x25519.getSharedSecret(localDevice.encryptionPrivateKey, remoteIdentity.chatPublicKey);
+    const outgoingEncryption = createEncryption(outgoingSharedSecret);
+    const localDeviceAccount = {
+        accountId: createAccountId(localDevice.statementAccountId),
+        pin: localIdentity.pin,
+    };
+    const remoteIdentityAccount = { accountId: remoteIdentity.accountId, pin: remoteIdentity.pin };
+    const localIdentityAccount = { accountId: localIdentity.accountId, pin: localIdentity.pin };
+    const outgoingTopic = createSessionId(outgoingSharedSecret, localDeviceAccount, remoteIdentityAccount);
+    const envelope = createEnvelope({
+        ownStatementAccountId: localDevice.statementAccountId,
+        ownEncryptionPrivateKey: localDevice.encryptionPrivateKey,
+    });
+    return createSessionCore({
+        statementStore,
+        prover,
+        allocator,
+        maxRequestSize,
+        outgoingTopic,
+        bodyBuilder: createBodyBuilder({
+            topic: outgoingTopic,
+            encryption: outgoingEncryption,
+            multiDevice: { envelope, recipients: () => peerRoster.current() },
+        }),
+        incomingTopics: createRosterTopics({
+            localIdentity: localIdentityAccount,
+            remotePin: remoteIdentity.pin,
+            ownIdentityChatPrivateKey: localIdentity.chatPrivateKey,
+            peerRoster,
+        }),
+        decoder: createStatementDecoder({ prover, envelope, ownEncryption: outgoingEncryption }),
+        peerDevices: () => peerRoster.current(),
+    });
+}

package/dist/session/multiDeviceSession.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * End-to-end multi-device session: two users, each with their own device(s), talking over
+ * one shared in-memory statement store. Exercises the wire path the desktop chat client
+ * will use — `multiRequest`/`multiResponse` envelopes on device-derived topics.
+ */
+export {};

package/dist/session/multiDeviceSession.spec.js

@@ -0,0 +1,354 @@
+/**
+ * End-to-end multi-device session: two users, each with their own device(s), talking over
+ * one shared in-memory statement store. Exercises the wire path the desktop chat client
+ * will use — `multiRequest`/`multiResponse` envelopes on device-derived topics.
+ */
+import { x25519 } from '@noble/curves/ed25519.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { Bytes } from '@novasamatech/scale';
+import { okAsync } from 'neverthrow';
+import { describe, expect, it, vi } from 'vitest';
+import { createInMemoryStatementStore } from '../adapter/inMemory.js';
+import { createAccountId } from '../model/sessionAccount.js';
+import { createExpiryAllocator } from '../submit/allocator.js';
+import { createMultiDeviceSession } from './multiDeviceSession.js';
+const rawCodec = Bytes();
+// Proof verification is exercised in statementProver tests; here a stub keeps statements
+// well-formed without pulling in real sr25519 signing.
+const mockProver = {
+    generateMessageProof: statement => okAsync({
+        ...statement,
+        proof: { type: 'sr25519', value: { signature: `0x${'00'.repeat(64)}`, signer: `0x${'00'.repeat(32)}` } },
+    }),
+    verifyMessageProof: () => okAsync(true),
+};
+const delay = () => new Promise(resolve => setTimeout(resolve, 0));
+function createDevice() {
+    const encryptionPrivateKey = x25519.utils.randomSecretKey();
+    return {
+        statementAccountId: randomBytes(32),
+        encryptionPrivateKey,
+        encryptionPublicKey: x25519.getPublicKey(encryptionPrivateKey),
+    };
+}
+function createIdentity() {
+    const chatPrivateKey = x25519.utils.randomSecretKey();
+    return {
+        accountId: createAccountId(randomBytes(32)),
+        chatPrivateKey,
+        chatPublicKey: x25519.getPublicKey(chatPrivateKey),
+    };
+}
+/** A roster whose contents can be swapped at runtime, like a peer adding a device. */
+function mutableRoster(initial) {
+    let devices = initial;
+    const listeners = new Set();
+    const roster = {
+        current: () => devices,
+        subscribe(callback) {
+            listeners.add(callback);
+            return () => listeners.delete(callback);
+        },
+    };
+    return {
+        roster,
+        set(next) {
+            devices = next;
+            for (const listener of listeners)
+                listener(next);
+        },
+    };
+}
+const toTarget = (device) => ({
+    statementAccountId: device.statementAccountId,
+    encryptionPublicKey: device.encryptionPublicKey,
+});
+describe('multi-device session', () => {
+    it('completes a request → ACK round trip between two users', async () => {
+        const store = createInMemoryStatementStore();
+        const alice = createIdentity();
+        const bob = createIdentity();
+        const aliceDevice = createDevice();
+        const bobDevice = createDevice();
+        const aliceSession = createMultiDeviceSession({
+            localDevice: aliceDevice,
+            localIdentity: alice,
+            remoteIdentity: { accountId: bob.accountId, chatPublicKey: bob.chatPublicKey },
+            peerRoster: mutableRoster([toTarget(bobDevice)]).roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator: createExpiryAllocator(),
+        });
+        const bobSession = createMultiDeviceSession({
+            localDevice: bobDevice,
+            localIdentity: bob,
+            remoteIdentity: { accountId: alice.accountId, chatPublicKey: alice.chatPublicKey },
+            peerRoster: mutableRoster([toTarget(aliceDevice)]).roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator: createExpiryAllocator(),
+        });
+        await delay();
+        // Bob answers whatever Alice sends, which is what resolves her delivery promise.
+        const received = [];
+        bobSession.respondToRequests(rawCodec, request => {
+            if (request.payload.status === 'parsed')
+                received.push(request.payload.value);
+            return 'success';
+        });
+        // A session only opens its store subscription once something subscribes, so a caller
+        // awaiting `request()` must also be subscribed or the peer's ACK never arrives.
+        aliceSession.subscribe(rawCodec, vi.fn());
+        const payload = new TextEncoder().encode('hello bob');
+        await expect(aliceSession.request(rawCodec, payload)).toBeOk();
+        expect(received).toEqual([payload]);
+        aliceSession.dispose();
+        bobSession.dispose();
+    });
+    // A device inherits the pin of the identity it belongs to. If the sender and receiver
+    // disagree about which pin goes in the SessionIdParam, they derive different topics and
+    // messages silently never arrive — so exercise a round trip with pins set on both sides.
+    it('agrees on topics when both identities carry a pin', async () => {
+        const store = createInMemoryStatementStore();
+        const alice = createIdentity();
+        const bob = createIdentity();
+        const aliceDevice = createDevice();
+        const bobDevice = createDevice();
+        const alicePin = 'alice-pin';
+        const bobPin = 'bob-pin';
+        const aliceSession = createMultiDeviceSession({
+            localDevice: aliceDevice,
+            localIdentity: { ...alice, pin: alicePin },
+            remoteIdentity: { accountId: bob.accountId, chatPublicKey: bob.chatPublicKey, pin: bobPin },
+            peerRoster: mutableRoster([toTarget(bobDevice)]).roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator: createExpiryAllocator(),
+        });
+        const bobSession = createMultiDeviceSession({
+            localDevice: bobDevice,
+            localIdentity: { ...bob, pin: bobPin },
+            remoteIdentity: { accountId: alice.accountId, chatPublicKey: alice.chatPublicKey, pin: alicePin },
+            peerRoster: mutableRoster([toTarget(aliceDevice)]).roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator: createExpiryAllocator(),
+        });
+        await delay();
+        const seen = [];
+        bobSession.subscribe(rawCodec, messages => {
+            for (const message of messages) {
+                if (message.type === 'request' && message.payload.status === 'parsed')
+                    seen.push(message.payload.value);
+            }
+        });
+        const payload = new TextEncoder().encode('pinned hello');
+        await expect(aliceSession.submitRequestMessage(rawCodec, payload)).toBeOk();
+        await delay();
+        expect(seen).toEqual([payload]);
+        aliceSession.dispose();
+        bobSession.dispose();
+    });
+    describe('with no known peer devices', () => {
+        const emptyRosterSession = (store, queryStatements = vi.fn()) => {
+            const alice = createIdentity();
+            const bob = createIdentity();
+            return createMultiDeviceSession({
+                localDevice: createDevice(),
+                localIdentity: alice,
+                remoteIdentity: { accountId: bob.accountId, chatPublicKey: bob.chatPublicKey },
+                peerRoster: mutableRoster([]).roster,
+                statementStore: { ...store, queryStatements },
+                prover: mockProver,
+                allocator: createExpiryAllocator(),
+            });
+        };
+        // An empty `matchAny` has no defined meaning at the node; a store reading it as "match
+        // everything" would hand the session the entire store to decode.
+        it('does not ask the store to match an empty topic set', async () => {
+            const store = createInMemoryStatementStore();
+            const queryStatements = vi.fn().mockReturnValue(okAsync([]));
+            const session = emptyRosterSession(store, queryStatements);
+            await delay();
+            const filters = queryStatements.mock.calls.map(([f]) => f);
+            expect(filters.every(f => f.matchAny === undefined || f.matchAny.length > 0)).toBe(true);
+            session.dispose();
+        });
+        it('reports the real reason a send cannot go out', async () => {
+            const store = createInMemoryStatementStore();
+            const session = emptyRosterSession(store, vi.fn().mockReturnValue(okAsync([])));
+            await delay();
+            const result = await session.submitRequestMessage(rawCodec, new TextEncoder().encode('hi'));
+            expect(result.isErr()).toBe(true);
+            // Not "message too big", which is what an unbuildable statement used to look like.
+            expect(result._unsafeUnwrapErr().message).toContain('recipient devices');
+            session.dispose();
+        });
+    });
+    it('reaches every device of a multi-device peer', async () => {
+        const store = createInMemoryStatementStore();
+        const alice = createIdentity();
+        const bob = createIdentity();
+        const aliceDevice = createDevice();
+        const bobLaptop = createDevice();
+        const bobPhone = createDevice();
+        const aliceSession = createMultiDeviceSession({
+            localDevice: aliceDevice,
+            localIdentity: alice,
+            remoteIdentity: { accountId: bob.accountId, chatPublicKey: bob.chatPublicKey },
+            peerRoster: mutableRoster([toTarget(bobLaptop), toTarget(bobPhone)]).roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator: createExpiryAllocator(),
+        });
+        // Both of Bob's devices run their own session against the same identity.
+        const bobSessions = [bobLaptop, bobPhone].map(device => createMultiDeviceSession({
+            localDevice: device,
+            localIdentity: bob,
+            remoteIdentity: { accountId: alice.accountId, chatPublicKey: alice.chatPublicKey },
+            peerRoster: mutableRoster([toTarget(aliceDevice)]).roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator: createExpiryAllocator(),
+        }));
+        await delay();
+        const seen = bobSessions.map(() => []);
+        bobSessions.forEach((session, index) => {
+            session.subscribe(rawCodec, messages => {
+                for (const message of messages) {
+                    if (message.type === 'request' && message.payload.status === 'parsed') {
+                        seen[index].push(message.payload.value);
+                    }
+                }
+            });
+        });
+        const payload = new TextEncoder().encode('hello both devices');
+        await expect(aliceSession.submitRequestMessage(rawCodec, payload)).toBeOk();
+        await delay();
+        // One statement, one envelope — decrypted independently by each recipient device.
+        expect(seen[0]).toEqual([payload]);
+        expect(seen[1]).toEqual([payload]);
+        aliceSession.dispose();
+        for (const session of bobSessions)
+            session.dispose();
+    });
+    it('addresses a device the peer adds mid-session', async () => {
+        const store = createInMemoryStatementStore();
+        const alice = createIdentity();
+        const bob = createIdentity();
+        const aliceDevice = createDevice();
+        const bobLaptop = createDevice();
+        const bobPhone = createDevice();
+        const bobRoster = mutableRoster([toTarget(bobLaptop)]);
+        const aliceSession = createMultiDeviceSession({
+            localDevice: aliceDevice,
+            localIdentity: alice,
+            remoteIdentity: { accountId: bob.accountId, chatPublicKey: bob.chatPublicKey },
+            peerRoster: bobRoster.roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator: createExpiryAllocator(),
+        });
+        await delay();
+        // The new device comes online and Alice learns about it (deviceAdded, in production).
+        bobRoster.set([toTarget(bobLaptop), toTarget(bobPhone)]);
+        const phoneSession = createMultiDeviceSession({
+            localDevice: bobPhone,
+            localIdentity: bob,
+            remoteIdentity: { accountId: alice.accountId, chatPublicKey: alice.chatPublicKey },
+            peerRoster: mutableRoster([toTarget(aliceDevice)]).roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator: createExpiryAllocator(),
+        });
+        await delay();
+        const seen = [];
+        phoneSession.subscribe(rawCodec, messages => {
+            for (const message of messages) {
+                if (message.type === 'request' && message.payload.status === 'parsed')
+                    seen.push(message.payload.value);
+            }
+        });
+        const payload = new TextEncoder().encode('now includes the phone');
+        await expect(aliceSession.submitRequestMessage(rawCodec, payload)).toBeOk();
+        await delay();
+        expect(seen).toEqual([payload]);
+        aliceSession.dispose();
+        phoneSession.dispose();
+    });
+    it('opens ONE subscription regardless of how many devices the peer has', async () => {
+        const store = createInMemoryStatementStore();
+        const alice = createIdentity();
+        const bob = createIdentity();
+        const peerDevices = [createDevice(), createDevice(), createDevice()].map(toTarget);
+        const session = createMultiDeviceSession({
+            localDevice: createDevice(),
+            localIdentity: alice,
+            remoteIdentity: { accountId: bob.accountId, chatPublicKey: bob.chatPublicKey },
+            peerRoster: mutableRoster(peerDevices).roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator: createExpiryAllocator(),
+        });
+        await delay();
+        session.subscribe(rawCodec, vi.fn());
+        expect(store.activeSubscriptions()).toBe(1);
+        session.dispose();
+    });
+    // The initialization-phase read-back that removes the need for a client-side outbox:
+    // a fresh session recovers its unacknowledged batch from the store alone.
+    it('restores its unacknowledged outgoing batch from the store after a restart', async () => {
+        const store = createInMemoryStatementStore();
+        const alice = createIdentity();
+        const bob = createIdentity();
+        const aliceDevice = createDevice();
+        const bobDevice = createDevice();
+        const allocator = createExpiryAllocator();
+        const params = {
+            localDevice: aliceDevice,
+            localIdentity: alice,
+            remoteIdentity: { accountId: bob.accountId, chatPublicKey: bob.chatPublicKey },
+            peerRoster: mutableRoster([toTarget(bobDevice)]).roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator,
+        };
+        const first = createMultiDeviceSession(params);
+        await delay();
+        const payload = new TextEncoder().encode('unacked message');
+        await expect(first.submitRequestMessage(rawCodec, payload)).toBeOk();
+        await delay();
+        first.dispose(); // Bob never answered.
+        // A brand-new session over the same store must recover the pending batch, so the next
+        // message extends it rather than silently dropping the earlier one.
+        const restored = createMultiDeviceSession(params);
+        await delay();
+        const bobSeen = [];
+        const bobSession = createMultiDeviceSession({
+            localDevice: bobDevice,
+            localIdentity: bob,
+            remoteIdentity: { accountId: alice.accountId, chatPublicKey: alice.chatPublicKey },
+            peerRoster: mutableRoster([toTarget(aliceDevice)]).roster,
+            statementStore: store,
+            prover: mockProver,
+            allocator: createExpiryAllocator(),
+        });
+        bobSession.subscribe(rawCodec, messages => {
+            for (const message of messages) {
+                if (message.type === 'request' && message.payload.status === 'parsed')
+                    bobSeen.push(message.payload.value);
+            }
+        });
+        await delay();
+        const second = new TextEncoder().encode('second message');
+        await expect(restored.submitRequestMessage(rawCodec, second)).toBeOk();
+        await delay();
+        // The replacing statement carries BOTH messages, so a peer that only ever sees the
+        // surviving statement still gets the un-acked one. (Bob also saw the pre-replacement
+        // statement during his own init, hence the trailing-pair assertion — de-duplicating by
+        // message id is the application layer's job, not the transport's.)
+        expect(bobSeen.slice(-2)).toEqual([payload, second]);
+        restored.dispose();
+        bobSession.dispose();
+    });
+});

package/dist/session/scale/statementData.d.ts

@@ -8,6 +8,28 @@ export declare const Response: import("scale-ts").Codec<{
     requestId: string;
     responseCode: ResponseStatus;
 }>;
+/**
+ * One recipient device of a multi-device envelope. `encryptedKey` is the envelope's
+ * one-shot symmetric key wrapped for this device (see `session/codec/envelope.ts`).
+ *
+ * `statementAccountId` is a FIXED 32-byte array, matching Android's `RequestDeviceInfo`
+ * (paritytech/polkadot-app-android-v2#605) and desktop. Pre-#605 Android builds emit
+ * `Vec<u8>` here and are not interoperable.
+ */
+export declare const RequestDeviceInfo: import("scale-ts").Codec<{
+    statementAccountId: Uint8Array<ArrayBufferLike>;
+    encryptedKey: Uint8Array<ArrayBufferLike>;
+}>;
+/**
+ * Statement `data` payload, after the outer pairwise decryption.
+ *
+ * Variant indices are wire format — scale-ts assigns them by declaration order, so
+ * entries may only be APPENDED, never reordered:
+ *   0 request       — single-device (base-spec.md)
+ *   1 response      — single-device
+ *   2 multiRequest  — multi-device envelope (mds.md)
+ *   3 multiResponse — multi-device envelope
+ */
 export declare const StatementData: import("scale-ts").Codec<{
     tag: "request";
     value: {
@@ -20,4 +42,22 @@ export declare const StatementData: import("scale-ts").Codec<{
         requestId: string;
         responseCode: ResponseStatus;
     };
+} | {
+    tag: "multiRequest";
+    value: {
+        encryptedRequest: Uint8Array<ArrayBufferLike>;
+        devicesInfo: {
+            statementAccountId: Uint8Array<ArrayBufferLike>;
+            encryptedKey: Uint8Array<ArrayBufferLike>;
+        }[];
+    };
+} | {
+    tag: "multiResponse";
+    value: {
+        encryptedResponse: Uint8Array<ArrayBufferLike>;
+        devicesInfo: {
+            statementAccountId: Uint8Array<ArrayBufferLike>;
+            encryptedKey: Uint8Array<ArrayBufferLike>;
+        }[];
+    };
 }>;

package/dist/session/scale/statementData.js

@@ -31,7 +31,39 @@ export const Response = Struct({
     requestId: str,
     responseCode: ResponseCode,
 });
+/**
+ * One recipient device of a multi-device envelope. `encryptedKey` is the envelope's
+ * one-shot symmetric key wrapped for this device (see `session/codec/envelope.ts`).
+ *
+ * `statementAccountId` is a FIXED 32-byte array, matching Android's `RequestDeviceInfo`
+ * (paritytech/polkadot-app-android-v2#605) and desktop. Pre-#605 Android builds emit
+ * `Vec<u8>` here and are not interoperable.
+ */
+export const RequestDeviceInfo = Struct({
+    statementAccountId: Bytes(32),
+    encryptedKey: Bytes(),
+});
+const MultiRequest = Struct({
+    encryptedRequest: Bytes(),
+    devicesInfo: Vector(RequestDeviceInfo),
+});
+const MultiResponse = Struct({
+    encryptedResponse: Bytes(),
+    devicesInfo: Vector(RequestDeviceInfo),
+});
+/**
+ * Statement `data` payload, after the outer pairwise decryption.
+ *
+ * Variant indices are wire format — scale-ts assigns them by declaration order, so
+ * entries may only be APPENDED, never reordered:
+ *   0 request       — single-device (base-spec.md)
+ *   1 response      — single-device
+ *   2 multiRequest  — multi-device envelope (mds.md)
+ *   3 multiResponse — multi-device envelope
+ */
 export const StatementData = Enum({
     request: Request,
     response: Response,
+    multiRequest: MultiRequest,
+    multiResponse: MultiResponse,
 });

package/dist/session/session.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Single-device session (base-spec.md): the pairwise Request/Response transport used by
+ * SSO and any peer known to run exactly one device.
+ *
+ * See `multiDeviceSession.ts` for the mds.md variant, and `core.ts` for the shared driver.
+ */
 import type { StatementStoreAdapter } from '../adapter/types.js';
 import type { LocalSessionAccount, RemoteSessionAccount } from '../model/sessionAccount.js';
 import type { ExpiryAllocator } from '../submit/allocator.js';
@@ -31,13 +37,17 @@ export type SessionParams = {
      * identical to the previous per-session behavior.
      */
     allocator?: ExpiryAllocator;
+    /**
+     * Statement size budget in bytes; the batch is sized against
+     * `maxRequestSize - STATEMENT_OVERHEAD`. Defaults to
+     * {@link DEFAULT_MAX_REQUEST_SIZE} — override only to be MORE conservative than the
+     * chain, never less.
+     */
     maxRequestSize?: number;
 };
 /**
- * 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.
+ * Single-device session (base-spec.md). Wire output is unchanged from before the
+ * multi-device seams existed: `StatementData.request`/`.response` on
+ * `SessionId(A, B)`, listening on `SessionId(B, A)`.
  */
-export declare const STATEMENT_OVERHEAD: number;
 export declare function createSession({ localAccount, remoteAccount, statementStore, encryption, prover, sessionKey, allocator, maxRequestSize, }: SessionParams): Session;