p2party 0.14.7 → 0.14.10

package/README.md

@@ -9,7 +9,8 @@
 Protocol-v4 end-to-end encryption and reliable file transfer over a WebRTC
 room mesh.
 
-Apache-2.0 · [LICENSE.md](LICENSE.md)
+Apache-2.0 · [License](LICENSE.md) · [Getting started](docs/getting-started.md) ·
+[Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
 
 > Status: protocol v4 is an intentional wire break — v3 peers and persisted v3
 > crypto rows are not resumed. The current code has not completed an
@@ -33,7 +34,7 @@ Apache-2.0 · [LICENSE.md](LICENSE.md)
   decoy slots can hide a message's exact payload length within its transfer.
 - Each outbound message has its own transfer identity and data channel, a
   cancellable handle, authenticated receipts, selective retransmission, and
-  reconnect resume.
+  reconnect and sender-reload recovery from a bounded durable outbox.
 - Text and files up to the enforced 10 GiB application limit are supported.
   Browser builds use IndexedDB and, where available, OPFS for disk-backed large
   file receipt.
@@ -248,15 +249,14 @@ reconverge and exchange byte-exact messages 0.5–6.5 s after wake, and four
 in-flight 8 MiB transfer configurations finish byte-exact with the sender
 reporting `delivered`.
 
-Two limits, since they are as real as the fixes. Resume follows a live page: a
-send in flight does not survive reloading the sending page, though a reloaded
-receiver replays receipts for what it already holds so a still-live sender
-resends only the gaps. And when a frozen identity responder is carrying an
-in-flight transfer, reconvergence takes about 37 s rather than the usual 5–7 s
-— the surviving SCTP association accepts our new streams but not the peer's, so
-recovery waits out the 30 s handshake step timeout. The transfer completes
-correctly; the latency is a known open item on the
-[roadmap](ROADMAP.md#near-term).
+Prepared sends now survive sender reloads in the same browser storage and
+identity. Pending state and retry/cancel APIs are described in
+[durable transfer recovery](docs/getting-started.md). A failed `handle.done`
+reports the outcome of that attempt; it does not mean its pending data was
+removed. The outbox retains prepared sends for up to 24 hours and cannot recover
+an upload whose preparation never finished or whose browser storage was erased.
+Current measured recovery results and remaining compatibility limits are in
+[the browser report](docs/e2e/README.md).
 
 ## Wire format
 
@@ -795,14 +795,9 @@ is what this package compiles.
 
 ## No build step: a script tag and the CDN
 
-> **`0.14.7` is not on the CDN yet.** The release pipeline uploads its objects
-> from the tarball it publishes, and that pipeline has not run for this
-> version: every path under `https://cdn.p2party.com/@0.14.7/` currently
-> answers 404, and npm still resolves `p2party` to an older release. The
-> snippet below is generated from this build and is what the release will
-> serve — until then, either pin the version `npm view p2party version` reports
-> (its objects are live) or self-host the bundle, which works today and is
-> described in the next section.
+> **`0.14.10` is a local release candidate.** This work does not publish npm
+> packages or CDN assets. The snippet names the candidate's intended release
+> path; use the generated local bundle until that version is published.
 
 A release publishes its browser bundle, its database worker and its
 cryptographic module as immutable, versioned CDN objects. The version is in the
@@ -815,8 +810,8 @@ script in and `window.p2party` is there — no npm, no bundler, no build:
 <title>p2party in one file</title>
 
 <script
-  src="https://cdn.p2party.com/@0.14.7/p2party.min.js"
-  integrity="sha384-Wh2Pxka9YN2oAZmzYgaoyLmfKQMXsMO4AfUmshluGmYjfS0+ahOZGCTBGHtKTcC9"
+  src="https://cdn.p2party.com/@0.14.10/p2party.min.js"
+  integrity="sha384-z5PjsRDKjtPcQ9JhEwkPyr/7zthzQgjjh6pSTdjTmhZrwVhhhFS/KhRkGtmJwqJX"
   crossorigin="anonymous"
 ></script>
 
@@ -855,7 +850,7 @@ https://cdn.p2party.com/@<version>/libcrypto.wasm  the cryptographic module
 The `integrity` value above is this release's bundle, and the release build
 fails if the README and the built artifact ever disagree — so it is safe to
 copy verbatim. The worker, if you host it yourself, is
-`integrity=sha384-BudWf1U+vDU/j4pf2sX+bLogS/7MuPyzKRA9AfLoZqdbduUCwYr42p38rEoQRXa8`.
+`integrity=sha384-iZfBJVoMgpK1+s2shZQucC0OUSBaX4eHMTjHj4NqzGApUodsP9T16+EHgyDKTVQP`.
 
 The WASM is integrity-checked whether or not you pin the script: that hash is
 compiled into the bundle and cannot be turned off.
@@ -894,7 +889,7 @@ immutable, versioned path, so a URL names exactly one build and is safe to
 cache forever:
 
 ```sh
-curl -O "https://cdn.p2party.com/@$(npm view p2party version)/libcrypto.wasm"
+curl --compressed -O "https://cdn.p2party.com/@$(npm view p2party version)/libcrypto.wasm"
 ```
 
 Two caveats, both current as of this release. The CDN carries only three
@@ -905,6 +900,14 @@ the tarball. And nothing is uploaded for this release yet, which is why the
 command above asks npm for a version that is actually published instead of
 naming this one.
 
+New CDN uploads gzip all three objects; WASM keeps `Content-Type:
+application/wasm` and uses `Content-Encoding: gzip`. Browsers decode it before
+SRI verification, and `curl --compressed` saves those same decoded bytes for
+the checks below. Existing raw WASM objects remain untouched when their decoded
+content matches; enabling compression never overwrites a published version.
+Upload preparation compresses the validated artifacts already in `lib/`; it
+does not replace them from a local development crypto build.
+
 Check what you downloaded before you serve it. The SHA-256 and the SRI value
 are both recorded in the provenance file:
 

package/THIRD_PARTY_NOTICES.md

@@ -68,7 +68,7 @@ SOFTWARE.
 
 ## Emscripten-generated runtime
 
-The WebAssembly and JavaScript glue are built with Emscripten 6.0.2.
+The WebAssembly and JavaScript glue are built with Emscripten 6.0.9.
 
 Verbatim upstream license:
 
@@ -416,11 +416,6 @@ The browser bundle and/or installed runtime dependency graph includes:
 - `redux-thunk` 3.1.0 — Copyright (c) 2015-present Dan Abramov
 - `reselect` 5.1.1 — Copyright (c) 2015-2018 Reselect Contributors
 - `immer` 11.1.15 — Copyright (c) 2017 Michel Weststrate
-- `class-validator` 0.15.1 — Copyright (c) 2015-2020 TypeStack
-- `validator` 13.15.23 — Copyright (c) 2018 Chris O'Hara
-  `<cohara87@gmail.com>`
-- `libphonenumber-js` 1.12.27 — Copyright (c) 2016 @catamphetamine
-  `<purecatamphetamine@gmail.com>`
 
 Each component above is MIT-licensed. Verbatim grant and disclaimer:
 
@@ -456,3 +451,35 @@ Permission to use, copy, modify, and/or distribute this software for any purpose
 
 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 ```
+
+## Emscripten TypeScript declarations
+
+The module-scoped `EmscriptenModule` and factory types are adapted from
+`@types/emscripten` 1.41.5 in DefinitelyTyped. All inherited LibCrypto members
+are retained; unrelated global declarations are not included.
+
+Verbatim upstream license:
+
+```text
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE
+```

package/docs/getting-started.md

@@ -109,6 +109,14 @@ bytes are deliberately absent from the public policy, Redux, persistent room
 records, and logs. PIN mode adds CPace authentication to the identity and
 ML-KEM handshake; it does not replace identity possession.
 
+The SDK retries an unexpectedly closed signaling socket with bounded backoff.
+Let that controller own recovery: do not call `connect()` on every disconnected
+render or browser focus event. Call it for initial admission and a deliberate
+retry, such as entering a corrected PIN. Terminal PIN or policy failures stay
+visible and do not trigger automatic peer discovery or transport retries.
+A fresh connection request from the other peer can retry that peer's failed
+edge; the existing PIN-attempt throttle still applies.
+
 Scheduled timing cover is wired as of 0.14: a policy may pin `coverMode:
 "scheduled"` with a cadence, lane count, and frames per cell, and every edge in
 the room then emits fixed-size cells on that schedule whether or not data is
@@ -117,8 +125,10 @@ their live transport wiring is not complete.
 
 ## Send, cancel, and read
 
-Wait until the room has peers before sending. Each logical send has a random
-transfer ID and opens a per-message data channel on every eligible peer edge.
+Wait until the room has known recipient identities before sending. Each logical
+send has a random transfer ID. Immediate mode opens a per-message data channel
+on each eligible edge; scheduled mode places its chunks into the existing
+fixed-cadence cover lanes.
 
 ```ts
 const handle = p2party.sendMessage("hello room", "chat", room.id);
@@ -147,8 +157,97 @@ void cancel; // Remove when a UI event uses it.
 
 `sendMessage()` returns a `MessageTransferHandle`, not a promise. `done`
 settles after all started peer sends and cleanup and reports ordered per-peer
-outcomes. A peer may be delivered, failed during setup/transfer, or skipped
-because it is disconnected, unauthenticated, or the transfer was cancelled.
+outcomes for that attempt. A peer may be delivered, failed during setup/transfer,
+or skipped because it is disconnected, unauthenticated, or the transfer was
+cancelled. A rejected attempt can still have a durable pending transfer: do not
+label it delivered, or assume that its resend source was discarded.
+
+The sender publishes its outbox record only after every staged chunk, the
+Merkle tree, and its local message copy have committed. A reload before that
+point cannot resume preparation; select the original file again. After
+publication, a reload or an exhausted reconnect budget retains the original
+transfer ID, Merkle root and staged bytes for retry. Nothing is rehashed or
+randomly repadded on a resumed send.
+
+```ts
+import type { PendingMessage } from "p2party";
+
+const pending: PendingMessage[] = await p2party.listPendingMessages(room.id);
+for (const message of pending) {
+  console.log(message.filename, message.phase, message.remainingRecipients);
+}
+
+// Use a deliberate retry button. It may take the room's scheduled delivery
+// time to settle; leave cancellation available while this promise is pending.
+try {
+  const attempts = await p2party.resumePendingMessages(room.id);
+  for (const attempt of attempts) console.table(attempt.outcomes);
+} catch (error) {
+  // AggregateError.errors contains failed attempts; their pending records stay
+  // available unless explicitly cancelled or expired.
+  console.error(error);
+}
+
+// Exact logical-send cancellation also works after the original handle was
+// lost to a reload. It fences queued writes before removing retained staging.
+if (pending[0])
+  await p2party.cancelPendingMessage(room.id, pending[0].transferId);
+```
+
+Authenticated-peer events trigger a serialized retry pass, including a bounded
+claim after an old tab's lease expires. A failed pass does not start an endless
+retry timer. Explicit retry requires verified signaling and a matching
+currently authenticated recipient; it never calls `connect()`, prompts for a
+passkey, or supplies a PIN. A PIN room must first be admitted with the user's
+current in-memory PIN. PIN and policy failures remain terminal until a deliberate
+authentication retry.
+
+The immutable outbox binds the sender's public key and durable identity
+revision, room capability and canonical policy, channel, and recipient public
+keys. Session peer IDs may change. Only one tab can own a transfer's 30-second
+lease at a time; it renews every 10 seconds. A stale tab cannot publish queued
+writes or renew a replacement owner's lease. Terminal signaling refusal stops
+its current owners, and switching identity invalidates the old outbox.
+
+Confirmed recipients are recorded separately and never retried. A recipient's
+explicit cancellation also ends retries to that recipient without cancelling
+other recipients. Immediate retries rebuild the have-set from authenticated
+receipt replay, so older receivers that discarded a closed channel's partial
+can still recover. Scheduled retries preserve the receipt bitmap and send
+missing chunks plus at most one already-received real chunk as a completion
+probe. The fixed cover cadence and lane count remain unchanged.
+
+Retention and admission have explicit limits:
+
+- Published pending transfers expire 24 hours after publication. Active owners
+  are protected while they run; a completed recipient is never reported as a
+  new delivery merely because staging remains.
+- Interrupted preparation expires after one hour. Its `phase` remains
+  `"staging"`; an expired `retryAfter` means its owner is gone, not that the
+  unfinished file can resume.
+- At most 32 pending transfers and 64 recipients per transfer are admitted.
+  Their aggregate storage reservation is capped at 12 GiB and charges padded
+  cells, metadata, proofs and the sender's local copy. Browser quota can impose
+  a smaller limit than the 10 GiB per-message protocol maximum. Admission
+  refuses excess work rather than evicting another pending send.
+- Incomplete received transfers expire after 24 hours without local receive
+  activity. Cleanup uses the device's activity clock, not the sender's message
+  timestamp. It protects active writes, completed messages and sender copies,
+  checks the room/receive owner, and fences writes queued before cancellation.
+
+Storage sweeps run when pending transfers are listed or an authentication event
+checks for resumable work. Maintenance runs immediately on the first check,
+then at most once every 30 seconds, and defers while receive queues are busy.
+Committed expiry also removes the old room view and retires its mapped receive
+key, preserving newer receives and connection generations.
+Cancelling or deleting a message removes its pending
+outbox; leaving a room discards that room's pending work. Successful completion
+removes resend staging while retaining completed local history.
+
+The outbox reuses the already-staged message bytes in browser storage; it is
+not a new encryption-at-rest guarantee for files or message history. It stores
+no PIN, passkey assertion, plaintext ratchet key or message key. A resumed send
+derives fresh message encryption state from the currently authenticated edge.
 
 For an inbound message, take `merkleRootHex` (and, if needed, `sha512Hex`) from
 the room's exported `messages` state:

package/docs/protocol-v4-security.md

@@ -17,9 +17,9 @@ There are three different acknowledgements in the system:
 2. The protocol-v4 handshake runs over the open main channel. After HELLO,
    responder CONFIRM, initiator CONFIRM, and responder FINISH, the peers have
    authenticated the same hybrid root and initial ratchet keys.
-3. Authenticated 65-byte receipt frames acknowledge message chunks and final
-   transfer completion. They are delivery/reconciliation signals, not handshake
-   establishment.
+3. Immediate 65-byte receipts on authenticated message channels, or encrypted
+   scheduled control cells, acknowledge chunks and transfer completion. They
+   are delivery/reconciliation signals, not handshake establishment.
 
 An open data channel therefore is necessary transport readiness, not an
 established p2party crypto session.
@@ -66,15 +66,65 @@ byte so the sparse post-quantum healing epoch cannot wrap.
 
 The fixed frame geometry absorbs the ratchet and AEAD overhead into the cell
 budget. Random padding and decoy slots can hide the exact payload length within
-one transfer's chosen number of frames. Receipts have a distinct fixed 65-byte
-geometry. Handshake flights are suite- and step-dependent rather than
-65,490-byte cells.
+one transfer's chosen number of frames. Immediate receipts have a distinct
+65-byte geometry and immediate pause/cancel controls are 66 bytes. Scheduled
+receipt batches, terminal receipts and CANCELs occupy existing 65,490-byte
+cover slots. Handshake flights are suite- and step-dependent.
 
 Per-message channels give each transfer an independent lifecycle for
 cancellation, bounded channel accounting, receipts, selective retransmission,
 and reconnect resume. Channel isolation is a UX and reliability property; it
 does not make timing or channel count invisible.
 
+### Durable selective resume and cancellation
+
+A chunk acknowledgement becomes live only after its per-recipient outbox
+update commits. Receipt acceptance binds room, peer ID, peer public key,
+random transfer ID, Merkle root and original chunk index. Scheduled cells
+add direction, PQ epoch, AEAD and counter replay checks; their terminal token
+must equal the transfer root. Stale asynchronous storage responses cannot
+advance a replacement owner's live state. Recipient refusal is persisted
+separately from completion and stops only that recipient's retry.
+
+Scheduled chunk receipts use a separate encrypted subtype with up to 64 tokens
+per root. Existing subtype 3 remains terminal-only: older clients interpreted
+any token in that subtype as completion. Older protocol-v4 clients drop the
+new subtype and retain terminal-only scheduled delivery, including full replay
+when necessary. Selective scheduled resume therefore requires supporting peers.
+
+Have-set membership is O(1) in memory and does not allocate a set copy per
+scheduled slot. A resume scans indices once, sends missing real chunks and
+may send one completion probe. Storage lookup costs, initial file preparation
+and scanning remain; this is not a claim of sublinear total file processing.
+Batching and selective resume reduce real work within the existing schedule,
+whose observable cell count remains fixed.
+
+Immediate resume uses the channel protocol `p2party-resume-v1` and a capability
+echo to distinguish pause from explicit cancellation. Type-6 controls are
+authenticated by the concrete DTLS/SCTP channel and current identity gate,
+with an exact-root check; they do not have a separate application AEAD.
+Legacy peers retain close-as-cancel behavior. A fresh immediate attempt
+rebuilds its have-set from paced receiver receipts instead of assuming a
+legacy receiver retained its partial. Remote cancellation drains pending
+writes, then atomically checks room, sender and incomplete status before
+deleting receiver data; completed files and sender self-copies are preserved.
+
+### Sparse-PQ healing during scheduled sends
+
+Local healing waits for queued or admitted real jobs, message channels,
+derive-to-enqueue reservations and queued receive work to drain. An atomic
+application reservation closes the race between deriving a message key and
+admitting its scheduled producer. Dummy cover does not block healing.
+
+An incoming exchange blocks new admission and drains reservations, then
+persists its new epoch before adopting it. Epoch adoption invalidates old-key
+real producers on the same scheduler and wakes bounded sender recovery.
+Recovery requires an actual epoch advance when reusing that runtime and
+re-derives the missing chunks. If sealing was already in flight, its retired
+cell is wiped and the slot remains dummy; pending explicit CANCEL is resealed
+under the new epoch. Lane timing continues throughout this transition.
+Persistence failure leaves the prior live epoch unchanged for exact retry.
+
 ## Guarantees, assuming authenticated peer keys
 
 With a correctly pinned peer Ed25519 identity, uncompromised endpoints, matching
@@ -128,7 +178,7 @@ receives its normalized value. A fragment is not a server-blind meeting point.
 
 ## Signaling and TURN correctness boundary
 
-SDK 0.14.7 makes legacy signaling state transitions correlated and bounded; it
+SDK 0.14.10 makes legacy signaling state transitions correlated and bounded; it
 does not make that signaling path blind.
 
 - A room response is accepted only for the exact current socket, room

package/docs/references.md

@@ -172,6 +172,6 @@ third-party security audit. Cite the implementation:
 @software{p2party,
   title  = {p2party: protocol-v4 end-to-end encryption over a WebRTC room mesh},
   url    = {https://github.com/p2party/p2party-js},
-  note   = {Version 0.14.7}
+  note   = {Version 0.14.10}
 }
 ```

package/docs/session-api.md

@@ -381,6 +381,15 @@ The bootstrap ML-KEM exchange protects the initial root. Healing periodically
 re-runs it so a later post-quantum compromise cannot unwind an old session.
 The session owns the state machine; the caller owns scheduling and transport.
 
+The browser SDK separately coordinates queued scheduled producers with epoch
+changes, persists per-recipient chunk receipts, and implements WebRTC pause and
+CANCEL controls. Those transport/outbox services are not part of
+`p2party/session`. A session integrator must coordinate its own pending output
+and recovery when `pqEpoch` changes; the session does not selectively resend
+previously returned frames or interpret cover receipt subtypes. See the
+[wire format](wire-format.md#scheduled-control-cells--65490-bytes) for the browser
+contract.
+
 Control frames are the same 65,490-byte size as chunk frames, so the outer
 framing MUST record which kind a record is — the session will reject a control
 frame handed to `decrypt()` and vice versa.

package/docs/wire-format.md

@@ -1,26 +1,29 @@
 # Wire format
 
-Every byte here is derived from
-[`src/utils/constants.ts`](../src/utils/constants.ts), which is the single
-source of truth and is byte-matched in `utils.h`. For what these frames do and
-do not protect, read the
+Chunk geometry is defined in
+[`src/utils/constants.ts`](../src/utils/constants.ts) and byte-matched in
+`utils.h`. Scheduled control subtypes are defined in
+[`coverCell.ts`](../src/cryptography/coverCell.ts); immediate transfer controls
+are defined in [`immediateDisposition.ts`](../src/handlers/immediateDisposition.ts).
+For what these frames do and do not protect, read the
 [protocol-v4 security boundary](protocol-v4-security.md).
 
-
 ## Outer frame types
 
 One tag byte leads every frame on a data channel.
 
-| Tag | Name         | Size on the wire | Carries                         |
-| --- | ------------ | ---------------- | ------------------------------- |
-| 1   | `HANDSHAKE`  | step-dependent   | HELLO, CONFIRM, FINISH          |
-| 2   | `CHUNK`      | 65,490 B         | one fixed application cell      |
-| 3   | `RECEIPT`    | 65 B             | SHA-512 acknowledgement token   |
-| 4   | `COVER`      | 65,490 B         | a scheduled cell, real or decoy |
-| 5   | `PQ_CONTROL` | 65,490 B         | sparse-PQ OFFER / ADVANCE / ACK |
+| Tag | Name                    | Size on the wire | Carries                               |
+| --- | ----------------------- | ---------------- | ------------------------------------- |
+| 1   | `HANDSHAKE`             | step-dependent   | HELLO, CONFIRM, FINISH                |
+| 2   | `CHUNK`                 | 65,490 B         | one fixed application cell            |
+| 3   | `RECEIPT`               | 65 B             | SHA-512 acknowledgement token         |
+| 4   | `COVER`                 | 65,490 B         | scheduled dummy or encrypted control  |
+| 5   | `PQ_CONTROL`            | 65,490 B         | sparse-PQ OFFER / ADVANCE / ACK       |
+| 6   | `IMMEDIATE_DISPOSITION` | 66 B             | immediate resume capability or CANCEL |
 
-Tags 2, 4, and 5 are deliberately identical in size. An observer cannot tell an
-application cell from a decoy or from a healing exchange by looking at the wire.
+Tags 2, 4, and 5 have equal payload lengths. The frame tags travel inside
+WebRTC's DTLS transport; packetization, timing and total traffic remain
+observable. Scheduled real data uses tag 2 in a scheduled lane slot.
 
 ## Chunk frame — 65,490 bytes
 
@@ -52,6 +55,81 @@ application cell from a decoy or from a healing exchange by looking at the wire.
 
 Both per-chunk acknowledgements and the terminal content-hash acknowledgement
 use this exact geometry, so a completion is not distinguishable by size.
+Chunk tokens bind the transfer Merkle root, original chunk index and leaf hash.
+The sender resolves them through its staged chunk index and persists the
+per-recipient acknowledgement before updating the live have-set. A terminal
+immediate receipt must equal the message's content hash. These frames use the
+authenticated concrete message channel and its current identity gate.
+
+## Scheduled control cells — 65,490 bytes
+
+```text
+type=4(1) || edge binding(32) || counter(8) || reserved zero(8) ||
+PQ epoch(8) || nonce(12) || ciphertext(65,405) || AEAD tag(16)
+```
+
+All 69 header bytes are authenticated. The key binds the room's suite, edge,
+direction and PQ epoch. After authentication and counter replay rejection,
+the plaintext is `subtype(1) || payload length(4, BE) || payload || zero pad`:
+
+| Subtype | Meaning          | Payload                                                                |
+| ------- | ---------------- | ---------------------------------------------------------------------- |
+| 1       | Dummy            | Empty                                                                  |
+| 2       | CANCEL           | Transfer Merkle root (64 B)                                            |
+| 3       | Terminal receipt | Transfer Merkle root (64 B), followed by the same root as token (64 B) |
+| 4       | Chunk receipts   | Transfer Merkle root (64 B), followed by 1–64 chunk tokens (64 B each) |
+
+Subtype 4's authenticated payload length determines the token count; partial
+tokens, empty batches and batches over 64 tokens are rejected. Only tokens for
+one transfer root share a batch. A subtype 3 token unequal to its root cannot
+complete a send. Each chunk token must resolve to the tracked transfer, root
+and a valid original index. The durable owner also binds room, recipient ID
+and public key; a stale owner cannot advance live state after a storage await.
+A recipient's CANCEL records refusal only for that recipient.
+
+Receipts and CANCELs replace dummy slots in the existing schedule. The pending
+outbound control queue is bounded to 4,096 token/control units; dropping a
+queued acknowledgement may require a later retransmission. A terminal receipt
+supersedes unsent chunk acknowledgements for the same root, preserving the
+first available reverse slot for completion even at long cadences. Other roots
+and queued CANCEL controls retain their order. Live have-set
+membership uses an O(1) `Set` lookup without copying the set per slot. A resumed
+producer scans original indices once and emits missing chunks. It also selects
+index zero once per attempt to recover a lost terminal receipt: if that index
+was already acknowledged, this costs one extra completion probe. Index scanning
+and durable token lookups do not imply globally sublinear processing, and fewer
+real chunks do not reduce the fixed scheduled cell count.
+
+Subtype 4 is a protocol-v4 wire addition. Earlier clients reject and drop this
+unknown subtype and keep using subtype 3 completion. They cannot selectively
+resume scheduled chunks; a missing terminal receipt can require whole-transfer
+replay. Subtype 3 is never reused for chunk tokens, because earlier clients
+treated any subtype 3 receipt for a tracked root as completion. These additions
+do not introduce a fallback to an earlier cryptographic protocol version.
+
+## Immediate pause and cancellation — 66 bytes
+
+```text
+type=6(1) || kind(1) || transfer Merkle root(64)
+```
+
+Kind 0 announces resume support; kind 1 is explicit CANCEL. An immediate
+message channel opened with DCEP protocol `p2party-resume-v1` promises that a
+bare close may pause the transfer. A supporting receiver echoes kind 0 after
+the identity gate opens; the opener then also treats a bare remote close as
+pause. CANCEL is accepted once per concrete channel, only under its current
+authenticated gate and exact root. Malformed, unknown, stale and cross-root
+controls have no effect. This control relies on the authenticated DTLS/SCTP
+channel; it has no separate application AEAD envelope.
+
+An explicit cancellation sends kind 1 before closing. A transient failed
+attempt closes without CANCEL, allowing a supporting receiver to retain its
+partial data for bounded resume. Earlier clients ignore type 6 and retain
+their close-as-cancel behavior. At a fresh immediate attempt the new sender
+starts a fresh live chunk have-set and rebuilds it from the receiver's paced
+receipt replay, so deleted legacy partials cause full resend
+instead of trusting stale acknowledgements. The store-free session API does
+not implement this WebRTC channel contract.
 
 ## Handshake ladder
 
@@ -88,6 +166,16 @@ rather than something both sides have to reconcile. Each side persists its
 mutated state **before** dispatching, and application traffic is blocked while
 an epoch is in flight.
 
+The browser scheduler starts a local exchange only when no real producer,
+derive-to-enqueue reservation, message channel or queued receive work remains.
+Dummy/control cover alone does not hold it back. A remote exchange blocks new
+application admission and drains reservations before the durable transition;
+it does not wait for a long scheduled send to finish. A committed new epoch
+retires old-key real producers and publishes a cover generation change on the
+same runtime. The sender re-derives the remaining transfer under that epoch;
+fixed lane timing continues with dummy tails. An unrelated generation notice
+cannot authorize reuse of the same runtime without an actual PQ epoch advance.
+
 ## Room policy — 32 bytes
 
 A room's policy is a fixed 32-byte record (magic `"P2RP"`) that pins the ML-KEM

package/lib/api/signalingServerApi.d.ts

@@ -8,6 +8,44 @@ export interface WebSocketParams {
 export interface WebSocketMessage {
     content: WebSocketMessagePongResponse | WebSocketMessageCandidateSend | WebSocketMessageDescriptionSend | WebSocketMessageChallengeResponse | WebSocketMessageRoomIdRequest | WebSocketMessageLeaveRoomRequest | WebSocketMessagePeersRequest | WebSocketMessageConnectionResponse | WebSocketMessagePeerConnectionRequest;
 }
+/**
+ * The host the reconnect controller reads Redux state from and dispatches
+ * through. Bound on every connect attempt; the tests rebind it directly. It is
+ * NOT the store import, so this module keeps its existing dependency edges.
+ */
+type SignalingReconnectHost = {
+    dispatch: (action: unknown) => unknown;
+    getState: () => unknown;
+};
+export declare const setSignalingReconnectHost: (host: SignalingReconnectHost | null) => void;
+/**
+ * Record how a socket ended, so the reconnect ladder can refuse a close the
+ * server means as final. `selfInitiated` is what keeps the SDK's own protective
+ * closes out of the policy: `onOverflow` closes with 1008 when this tab's
+ * ingress backlog is exceeded, and local overload is exactly what bounded
+ * backoff is for.
+ */
+export declare const noteSignalingSocketClose: (close: Readonly<{
+    code: number;
+    selfInitiated: boolean;
+}>) => void;
+/**
+ * A ladder rung is a floor, never shortened, and at most 25 % longer. Without
+ * this every client a server restart disconnected walks the identical
+ * 1/2/4/8 s ladder and re-handshakes in lockstep, which is the same stampede
+ * the restart caused. The spread lives here rather than in the controller
+ * because the controller's ladder is exact by contract and its tests assert
+ * exact delays; the scheduler this module injects is the seam that perturbs it.
+ */
+export declare const signalingReconnectDelayWithJitter: (delayMs: number) => number;
+/**
+ * C4: a socket close that carries no browser wake event is otherwise terminal.
+ * `settleClosedSocket` detects; this reconnects. Shared by the close handler,
+ * the error handler and the heartbeat watchdog, so a peer whose socket died
+ * while its edges stayed authenticated is found again within 1-30 s instead of
+ * never.
+ */
+export declare const signalingReconnect: import("../utils/signalingReconnectController").SignalingReconnectController;
 type CurrentSocketApi = Pick<BaseQueryApi, "dispatch" | "getState">;
 /**
  * Send a correlated leave on the exact authenticated socket and wait for its