@net-mesh/browser 0.37.0

package/dist/node.js

@@ -0,0 +1,1085 @@
+/**
+ * `BrowserNode` — the surface a page actually uses.
+ *
+ * A thin, typed, camelCased layer over the wasm node: it owns the one
+ * `on_event` registration, re-types everything the boundary throws,
+ * parses `query`'s JSON without rounding 64-bit ids, and applies the
+ * Stage 5 failure-typing correction to an ICE failure when — and only
+ * when — the distinguishing evidence can be obtained.
+ */
+import { EventHub, parseEvent, parseJsonPreservingU64, toBase64, } from './events.js';
+import { fromWasmError, IdentityError, OrgCancelledError, RtcError } from './errors.js';
+import { clientStreamOrgTrampoline, duplexOrgTrampoline, OrgDuplex, OrgHandleRegistry, OrgServe, OrgStream, OrgUpload, streamingOrgTrampoline, toWasmOrgCallOptions, toWasmOrgServeOptions, unaryOrgTrampoline, } from './org.js';
+import { LeafStream } from './stream.js';
+import { acceptPeer as driveAccept, connectPeer as driveConnect, handshakePeer as driveHandshake, } from './peer-driver.js';
+import { classifyRtcError, probeBootstrapReachable, probeStunBinding, } from './udp-probe.js';
+import { idArg, loadLeafWasm, } from './wasm.js';
+/**
+ * Convert a decimal `u64` node id — {@link NodeDescriptor.nodeId},
+ * or any other decimal mesh id — into the 16-lowercase-hex-digit
+ * spelling the peer methods require.
+ *
+ * Explicit, because the alternative is worse in both directions. The
+ * leaf refuses a decimal peer id deliberately (one contract: `0009`
+ * must not name two different nodes depending on which method read
+ * it), and a wrapper that guessed which spelling it had been handed
+ * would dial whichever node its guess produced. So the caller says
+ * which conversion it means.
+ *
+ * `BigInt` rather than `Number`: a mesh id is a full `u64` and
+ * `parseInt` would round it.
+ *
+ * @throws TypeError if `nodeId` is not a decimal integer inside
+ * `u64`.
+ */
+export function peerIdHex(nodeId) {
+    if (!/^\d+$/.test(nodeId)) {
+        throw new TypeError(`a decimal node id is digits only, got ${JSON.stringify(nodeId)}`);
+    }
+    const value = BigInt(nodeId);
+    if (value > 0xffffffffffffffffn) {
+        throw new TypeError(`${nodeId} does not fit in a u64 node id`);
+    }
+    return value.toString(16).padStart(16, '0');
+}
+/** A browser-native Net node. */
+export class BrowserNode {
+    inner;
+    bootstrapUrl;
+    failureTyping;
+    hub = new EventHub();
+    nodeId;
+    closed = false;
+    /**
+     * Streams this node handed out and that are still open, so closing
+     * the node can end them.
+     *
+     * The direct surface's half of the same guarantee `MeshSession`
+     * gives across a leader change: after `close()` the wasm node
+     * delivers nothing and no stream will ever emit again, so a
+     * consumer sitting in `await iterator.next()` would never settle.
+     * Nothing else can end it — the queue is fed only by the stream's
+     * `on_message` callback, and a closed node does not call it. So
+     * the node owns the set and drains it, which turns "no more data,
+     * ever" into the end of the iteration a page is already written to
+     * handle.
+     */
+    streams = new Set();
+    /**
+     * The live org handles (plan §4.5), so {@link BrowserNode.close}
+     * can retire ownership: pending calls fail typed and each dropped
+     * caller handle emits exactly one CANCEL.
+     */
+    orgHandles = new OrgHandleRegistry();
+    /** The last `rtc_addr` an anchor told us about; the probe's subject. */
+    anchorRtcAddr;
+    /** Set once the leaf reports a session — a bootstrap that demonstrably worked. */
+    bootstrapObserved = false;
+    /** @internal — use {@link connect}. */
+    constructor(inner, bootstrapUrl, failureTyping, anchorRtcAddr) {
+        this.inner = inner;
+        this.bootstrapUrl = bootstrapUrl;
+        this.failureTyping = failureTyping;
+        this.nodeId = inner.node_id_hex();
+        this.anchorRtcAddr = anchorRtcAddr;
+        inner.on_event((json) => this.ingest(json));
+    }
+    /** This node's mesh id, hex. */
+    nodeIdHex() {
+        return this.nodeId;
+    }
+    /** The anchor's mesh id, hex. */
+    anchorIdHex() {
+        return this.inner.anchor_id_hex();
+    }
+    /**
+     * This node's origin hash, hex.
+     *
+     * Distinct from {@link BrowserNode.nodeIdHex} and not a synonym:
+     * the origin hash rides every packet header this node seals, names
+     * its nRPC reply channels (`<service>.replies.<origin>`), and is
+     * what a receiver compares an event payload's
+     * `EventMeta.origin_hash` against — a direct peer whose header
+     * origin and payload origin disagree has the frame dropped before
+     * admission. A page that hands this node a pre-encoded event
+     * payload to send must build it with THIS value.
+     */
+    originHashHex() {
+        return this.inner.origin_hash_hex();
+    }
+    /**
+     * Run the enrollment exchange.
+     *
+     * {@link connect} already awaits it, so a page needs this only to
+     * drive or observe the step — a harness proving that an unenrolled
+     * leaf is exactly what a provisional peer looks like, for instance.
+     * Until a leaf is enrolled the anchor keeps its peer provisional and
+     * §12 refuses everything above the transport, which surfaces here as
+     * `rpc-timeout` on calls rather than as a transport failure.
+     */
+    async enroll() {
+        try {
+            await this.inner.enroll();
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Whether the anchor has admitted this leaf. `false` means the
+     * session is still §12-provisional, so a call will die on its
+     * deadline — check this before blaming a `rpc-timeout` on a slow
+     * anchor.
+     */
+    isEnrolled() {
+        return this.inner.is_enrolled();
+    }
+    /**
+     * Call an nRPC service and resolve its reply.
+     *
+     * Rejects with {@link RpcError} (`rpc-refused`, `rpc-timeout`,
+     * `session-lost`, `leader-lost`, `rpc-malformed`) — never with a
+     * silent retry, which is §8's rule for a call whose leader or
+     * session went away.
+     */
+    async call(service, payload, timeoutMs) {
+        try {
+            return await this.inner.call(service, payload, timeoutMs);
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Subscribe to a channel. Messages arrive as `channel_message`
+     * events; the leaf only delivers channels this node subscribed to,
+     * and `channelHash` is its hash of the name.
+     */
+    async subscribe(channel) {
+        try {
+            await this.inner.subscribe(channel);
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /** Publish one payload to a channel. */
+    async publish(channel, payload) {
+        try {
+            await this.inner.publish(channel, payload);
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Open a reliable or fire-and-forget stream.
+     *
+     * The stream is retained until it or the node closes, so
+     * {@link BrowserNode.close} can end the consumers it handed out.
+     *
+     * On a **closed** node this is a typed refusal, not a dead handle:
+     * the leaf's own fence (`Inner::admit`) rejects every outbound
+     * operation on a node that no longer holds the origin's identity,
+     * and that is re-typed here as `SessionError` (`kind: 'session'`)
+     * like every other boundary failure. There is deliberately no
+     * second check in TypeScript — one fence, on the side that owns
+     * the node's lifetime.
+     */
+    openStream(options) {
+        let inner;
+        try {
+            inner = this.inner.open_stream(options);
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+        const stream = new LeafStream(inner, () => this.streams.delete(stream));
+        this.streams.add(stream);
+        return stream;
+    }
+    // ── Organization-scoped streaming (plan §4.5) ────────────────────────
+    //
+    // Eight verbs, identical on `MeshSession`. Terminal outcomes are the
+    // §4.3 vocabulary (`errors.ts`'s `OrgStreamError` family).
+    /**
+     * Call an org-protected unary service.
+     *
+     * Rejects with the §4.3 typed error: an **opening denial** is
+     * {@link OrgAdmissionDeniedError} carrying the coarse reason and
+     * nothing finer — a precise remote reason would be a credential
+     * oracle. Never a silent retry: the caller is told and decides.
+     *
+     * **Suspension and closure (plan §4.5).** Deadlines are absolute: a
+     * frozen tab extends no lease and no window, so a call whose
+     * deadline passes while its tab is suspended retires with its
+     * deadline terminal on wake — {@link OrgTimeoutError}, or
+     * {@link OrgIndeterminateError} where the work may already be
+     * executing elsewhere. Nothing resumes automatically: a retired
+     * call is never transparently re-opened, because re-opening is a
+     * fresh call with a fresh proof and MAY repeat effects. Node or tab
+     * close retires ownership — pending calls fail typed, and each
+     * dropped caller handle emits exactly one CANCEL.
+     */
+    async callOrg(service, payload, options) {
+        try {
+            return await this.inner.call_org(service, payload, toWasmOrgCallOptions(options));
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Call an org-protected server-streaming service; resolve to the
+     * response stream.
+     *
+     * An **opening denial** rejects here with
+     * {@link OrgAdmissionDeniedError} (coarse) — a denial is a
+     * rejection, never a terminal item. Midstream, the stream's FINAL
+     * error item carries the §4.3 outcome: revocation is
+     * `AdmissionDenied('denied')` ({@link OrgRevokedError} where the
+     * cause is known), deadline/cancel retirement is
+     * {@link OrgTimeoutError}/{@link OrgCancelledError}. The async
+     * iterator throws that typed error at the terminal error item.
+     *
+     * **Suspension and closure (plan §4.5).** Deadlines are absolute: a
+     * frozen tab extends no lease and no window, so a call whose
+     * deadline passes while its tab is suspended retires with its
+     * deadline terminal on wake — {@link OrgTimeoutError}, or
+     * {@link OrgIndeterminateError} where the work may already be
+     * executing elsewhere. Nothing resumes automatically: a retired
+     * call is never transparently re-opened, because re-opening is a
+     * fresh call with a fresh proof and MAY repeat effects. Node or tab
+     * close retires ownership — pending calls fail typed, and each
+     * dropped caller handle emits exactly one CANCEL.
+     */
+    async callOrgStreaming(service, payload, options) {
+        try {
+            const handle = await this.inner.call_org_streaming(service, payload, toWasmOrgCallOptions(options));
+            const stream = new OrgStream(handle, () => handle.cancel(), () => this.orgHandles.delete(stream));
+            this.orgHandles.add(stream);
+            return stream;
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Open an org-protected client-streaming upload. `finish()` is the
+     * half-close and the reply await, and it rejects with the typed
+     * terminal error (§4.3).
+     *
+     * An **opening denial** rejects here with
+     * {@link OrgAdmissionDeniedError} (coarse).
+     *
+     * **Suspension and closure (plan §4.5).** Deadlines are absolute: a
+     * frozen tab extends no lease and no window, so a call whose
+     * deadline passes while its tab is suspended retires with its
+     * deadline terminal on wake — {@link OrgTimeoutError}, or
+     * {@link OrgIndeterminateError} where the work may already be
+     * executing elsewhere. Nothing resumes automatically: a retired
+     * call is never transparently re-opened, because re-opening is a
+     * fresh call with a fresh proof and MAY repeat effects. Node or tab
+     * close retires ownership — pending calls fail typed, and each
+     * dropped caller handle emits exactly one CANCEL.
+     */
+    async callOrgClientStream(service, options) {
+        try {
+            const handle = await this.inner.call_org_client_stream(service, toWasmOrgCallOptions(options));
+            const upload = new OrgUpload(handle, () => this.orgHandles.delete(upload));
+            this.orgHandles.add(upload);
+            return upload;
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Open an org-protected duplex call: an upload sink and an
+     * independent response stream.
+     *
+     * An **opening denial** rejects here with
+     * {@link OrgAdmissionDeniedError} (coarse). Midstream outcomes are
+     * the §4.3 terminals on each half.
+     *
+     * **Suspension and closure (plan §4.5).** Deadlines are absolute: a
+     * frozen tab extends no lease and no window, so a call whose
+     * deadline passes while its tab is suspended retires with its
+     * deadline terminal on wake — {@link OrgTimeoutError}, or
+     * {@link OrgIndeterminateError} where the work may already be
+     * executing elsewhere. Nothing resumes automatically: a retired
+     * call is never transparently re-opened, because re-opening is a
+     * fresh call with a fresh proof and MAY repeat effects. Node or tab
+     * close retires ownership — pending calls fail typed, and each
+     * dropped caller handle emits exactly one CANCEL.
+     */
+    async callOrgDuplex(service, options) {
+        try {
+            const handle = await this.inner.call_org_duplex(service, toWasmOrgCallOptions(options));
+            const call = new OrgDuplex(handle, () => this.orgHandles.delete(call));
+            this.orgHandles.add(call);
+            return call;
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Serve an org-protected unary service. `access` is `'same-org'`
+     * (owner-org traffic only) or `'granted'` (capability grants too);
+     * anything else is refused loudly at registration.
+     *
+     * **Handler drop (F-S3.1-2).** The retire supervisor may drop the
+     * handler future without a final poll — cancellation is observed
+     * through the retirement observables (the terminal item, the sink's
+     * typed closed refusal, and `retired`), never assumed as a
+     * handler-side event; a detached observer holding `retired`
+     * observes the signal. After retirement a handler sees typed
+     * refusals and any return value it produces is discarded.
+     *
+     * **`close()` is a retirement, not a graceful unregister (C9's
+     * protected split).** Closing the returned handle retires its live
+     * protected calls — each with its exact retirement terminal, the
+     * deadline/cancel/revocation vocabulary — and refuses new openings
+     * on the service. Deliberately NOT the public path's
+     * let-existing-calls-finish behavior.
+     */
+    serveOrg(service, access, handler, options) {
+        try {
+            const serve = new OrgServe(this.inner.serve_org(service, access, unaryOrgTrampoline(handler), toWasmOrgServeOptions(options)), () => this.orgHandles.delete(serve));
+            this.orgHandles.add(serve);
+            return serve;
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Serve an org-protected server-streaming service: one request in,
+     * items out through the {@link OrgResponseSink}.
+     *
+     * **Handler drop (F-S3.1-2).** The retire supervisor may drop the
+     * handler future without a final poll — cancellation is observed
+     * through the retirement observables (the terminal item, the sink's
+     * typed closed refusal, and `retired`), never assumed as a
+     * handler-side event; a detached observer holding `retired`
+     * observes the signal. After retirement a handler sees typed
+     * refusals and any return value it produces is discarded.
+     *
+     * **`close()` is a retirement, not a graceful unregister (C9's
+     * protected split).** Closing the returned handle retires its live
+     * protected calls — each with its exact retirement terminal, the
+     * deadline/cancel/revocation vocabulary — and refuses new openings
+     * on the service. Deliberately NOT the public path's
+     * let-existing-calls-finish behavior.
+     */
+    serveOrgStreaming(service, access, handler, options) {
+        try {
+            const serve = new OrgServe(this.inner.serve_org_streaming(service, access, streamingOrgTrampoline(handler), toWasmOrgServeOptions(options)), () => this.orgHandles.delete(serve));
+            this.orgHandles.add(serve);
+            return serve;
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Serve an org-protected client-streaming service: requests in
+     * through the {@link OrgRequestStream}, one reply out.
+     *
+     * **Handler drop (F-S3.1-2).** The retire supervisor may drop the
+     * handler future without a final poll — cancellation is observed
+     * through the retirement observables (the terminal item, the sink's
+     * typed closed refusal, and `retired`), never assumed as a
+     * handler-side event; a detached observer holding `retired`
+     * observes the signal. After retirement a handler sees typed
+     * refusals and any return value it produces is discarded.
+     *
+     * **`close()` is a retirement, not a graceful unregister (C9's
+     * protected split).** Closing the returned handle retires its live
+     * protected calls — each with its exact retirement terminal, the
+     * deadline/cancel/revocation vocabulary — and refuses new openings
+     * on the service. Deliberately NOT the public path's
+     * let-existing-calls-finish behavior.
+     */
+    serveOrgClientStream(service, access, handler, options) {
+        try {
+            const serve = new OrgServe(this.inner.serve_org_client_stream(service, access, clientStreamOrgTrampoline(handler), toWasmOrgServeOptions(options)), () => this.orgHandles.delete(serve));
+            this.orgHandles.add(serve);
+            return serve;
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Serve an org-protected duplex service: requests in and items out,
+     * independently, through the request stream and the sink.
+     *
+     * **Handler drop (F-S3.1-2).** The retire supervisor may drop the
+     * handler future without a final poll — cancellation is observed
+     * through the retirement observables (the terminal item, the sink's
+     * typed closed refusal, and `retired`), never assumed as a
+     * handler-side event; a detached observer holding `retired`
+     * observes the signal. After retirement a handler sees typed
+     * refusals and any return value it produces is discarded.
+     *
+     * **`close()` is a retirement, not a graceful unregister (C9's
+     * protected split).** Closing the returned handle retires its live
+     * protected calls — each with its exact retirement terminal, the
+     * deadline/cancel/revocation vocabulary — and refuses new openings
+     * on the service. Deliberately NOT the public path's
+     * let-existing-calls-finish behavior.
+     */
+    serveOrgDuplex(service, access, handler, options) {
+        try {
+            const serve = new OrgServe(this.inner.serve_org_duplex(service, access, duplexOrgTrampoline(handler), toWasmOrgServeOptions(options)), () => this.orgHandles.delete(serve));
+            this.orgHandles.add(serve);
+            return serve;
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Sign and send a `0x0D02` signalling envelope to `peer` — the
+     * session-independent path, so no session with `peer` is needed.
+     *
+     * `dialogHex` is the attempt's id, 16 lowercase hex digits — the
+     * same value {@link BrowserNode.offerPeer} resolves to. Never a
+     * number: a `u64` dialog through a JS number comes back rounded,
+     * and an envelope signed for a dialog that names no attempt kills
+     * the attempt at its ICE deadline.
+     */
+    async signal(peerHex, dialogHex, kind, payload) {
+        try {
+            // Both ids cross as strings, verbatim, and a non-string is
+            // refused "is not a peer id" / "is not a dialog id" — peer
+            // first, the order `LeafNode::signal` parses in — before the
+            // wasm seam, whose String marshaling corrupts on a number
+            // (finding #52).
+            await this.inner.signal(idArg(peerHex, 'peer'), idArg(dialogHex, 'dialog'), kind, payload);
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Connect **directly** to another browser node — plan §9, from a
+     * page.
+     *
+     * The whole sequence, driven here so a page does not have to:
+     * bring up the relayed session through the anchor if there is not
+     * one, offer, trickle candidates both ways as signed envelopes,
+     * and run the Noise handshake over the DataChannel that results.
+     * The direct session then **replaces** the relayed one rather than
+     * joining it (§9 step 4), through the node's own session-table
+     * fence.
+     *
+     * `nodeIdHex` is the peer's mesh id in the spelling every peer
+     * method takes: 16 lowercase HEX digits —
+     * {@link BrowserNode.nodeIdHex} on the other tab, or
+     * {@link NodeDescriptor.peerIdHex} from a
+     * {@link BrowserNode.query} descriptor. It is **not**
+     * {@link NodeDescriptor.nodeId}, which is that id's decimal
+     * spelling; pass {@link peerIdHex} over it, or the decimal digits
+     * name a different node.
+     *
+     * **Nothing else is passed, and nothing else can be.** No SDP, no
+     * candidate, no key: the peer's Noise static comes from its
+     * signature-verified announcement and the pre-shared key from the
+     * credential this node connected with. A page that could supply a
+     * key could supply any key.
+     *
+     * **Idempotent on a healthy pair.** When the pair is already direct
+     * and its channel open, this resolves `direct` with the live dialog
+     * and sends nothing: a second offer would replace the working link
+     * and close it under the other side. So a library may call it "to be
+     * sure" before opening a stream.
+     *
+     * Returns a {@link PeerConnectOutcome}. It **rejects** only for
+     * something that is not a disposition of the attempt — a closed
+     * node, a peer that answered `Reject`, a malformed peer id.
+     */
+    async connectPeer(nodeIdHex) {
+        // Already direct and open: the pair it has. A new offer would
+        // replace the working link and close it under the other side.
+        let settled;
+        try {
+            settled = this.inner.peer_direct_dialog(idArg(nodeIdHex, 'peer'));
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+        if (settled !== undefined && settled !== null)
+            return { type: 'direct', peer: nodeIdHex, dialog: settled };
+        return driveConnect(nodeIdHex, this.peerPrimitives(), parseAttemptStatus);
+    }
+    /**
+     * The four primitives the shared drive loop calls, bound to this
+     * tab's own node.
+     *
+     * The dialog-named `*_in` forms, not the peer-only ones: one
+     * primitive set for both surfaces means one classification, and a
+     * direct caller loses nothing by naming the dialog it already
+     * holds.
+     */
+    peerPrimitives() {
+        return {
+            offer: (peer) => this.inner.peer_offer(peer),
+            acceptOffer: (peer) => this.inner.peer_accept_offer(peer),
+            candidate: (peer, dialog) => this.inner.peer_candidate_in(peer, dialog),
+            handshake: (peer, dialog) => this.inner.peer_handshake_in(peer, dialog),
+        };
+    }
+    /**
+     * Run the offerer's Noise handshake on an attempt whose
+     * DataChannel is already open, and type the result the way
+     * {@link BrowserNode.connectPeer} types it.
+     *
+     * `connectPeer` is the drive loop plus exactly this call, so there
+     * is one classifier and not two. It is public because the four
+     * `#[wasm_bindgen]` methods are a page surface in their own right:
+     * a page that drove `peer_offer`, `peer_accept_offer` and
+     * `peer_candidate` itself — because it wanted to observe or
+     * intervene between them — would otherwise have to re-derive the
+     * typing of the last step, and a second classifier is a second
+     * set of bugs.
+     *
+     * `dialog` is the id `peer_offer` returned, and it is CHECKED
+     * rather than assumed: `peer_handshake` resolves to the dialog it
+     * actually ran for, and any mismatch is this caller's attempt
+     * having been replaced underneath it. Reporting `direct` with the
+     * caller's own dialog on any success is how a stale caller was
+     * told its superseded attempt had connected — while the leaf had
+     * handshaken the attempt that replaced it.
+     */
+    async handshakePeer(nodeIdHex, dialog) {
+        return driveHandshake(nodeIdHex, dialog, this.peerPrimitives());
+    }
+    /**
+     * Accept the offer `nodeIdHex` sent, and drive the attempt to a
+     * direct session — {@link BrowserNode.connectPeer}'s counterpart.
+     *
+     * Call it when a `signal` event arrives from that peer: the offer
+     * it answers is the **verified envelope** the leaf already holds,
+     * so the page neither sees nor supplies the SDP.
+     *
+     * The answerer does not run the handshake — §9 step 4 puts Noise
+     * in the offerer's role, so this waits for the direct session to
+     * install from the inbound message instead. Same
+     * {@link PeerConnectOutcome}, same meanings.
+     */
+    async acceptPeer(nodeIdHex) {
+        return driveAccept(nodeIdHex, this.peerPrimitives(), parseAttemptStatus);
+    }
+    /**
+     * Read one `peer_candidate` status for a live attempt.
+     *
+     * Exposed because it is the only way to observe an attempt without
+     * driving it to a conclusion — which is what a witness asserting
+     * the shape of the exchange needs, and what a page showing
+     * connection progress wants.
+     */
+    async peerAttempt(nodeIdHex) {
+        try {
+            return parseAttemptStatus(await this.inner.peer_candidate(nodeIdHex));
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * Every leaf counter, including each drop reason. Values are exact
+     * decimal strings because they are `u64` on the Rust side.
+     */
+    counters() {
+        return parseCounters(this.inner.counters_json());
+    }
+    /**
+     * The RTC transport's `RtcStats`, in the **same field names** the
+     * native `RtcStats` uses — plan §10's telemetry surface on the
+     * leaf.
+     *
+     * Values are exact decimal strings, for the reason
+     * {@link BrowserNode.counters} gives. `notApplicable` is not a
+     * counter: it maps each native field a leaf has no meaning for to
+     * the reason it has none, because a field frozen at `0` reads as
+     * an observation ("no ingress overflow", "no STUN requests
+     * answered") and a browser leaf is not entitled to those claims.
+     * Native makes the same choice in the other direction — it
+     * carries no `udpBlocked`/`udp_blocked` field at all — so
+     * `udp_blocked` is the one term here with no native counterpart.
+     *
+     * `ice_pending` is absent on both sides on purpose: it is
+     * `ice_attempted - (direct + relayed + failed + udp_blocked)`,
+     * the attempts still in flight, and the §10 identity is exact
+     * only where that residual is zero. Derive it; do not expect it.
+     */
+    rtcStats() {
+        return parseRtcStats(this.inner.rtc_stats_json());
+    }
+    /**
+     * Arm the network-change re-attempt trigger: `online` events and
+     * an ICE `disconnected` → `failed` transition drive **one**
+     * bounded re-attempt per network change, per peer.
+     *
+     * Opt-in, and that is a decision rather than an omission.
+     * Re-dialling is policy and policy is the application's: a page
+     * may be holding a pair on the routed path deliberately, may be
+     * tearing down, may be on a metered link. §9 step 6 makes the
+     * routed session a supported disposition rather than a degraded
+     * one, so "this pair is relayed" is not a fault the library may
+     * assume it should fix.
+     *
+     * Idempotent — a second call installs no second listener. Only
+     * pairs this node took direct **as the offerer** are
+     * re-attempted: `connectPeer`'s side owns the repair, and both
+     * ends re-offering one network change would be two attempts per
+     * pair plus a supersession race.
+     *
+     * Once armed, {@link BrowserNode.retryReport} is how a page
+     * observes it.
+     */
+    enableNetworkRetry() {
+        try {
+            this.inner.arm_network_retry();
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /**
+     * What the re-attempt owner has seen and done.
+     *
+     * `started` is the assertion that matters: one network change, one
+     * re-attempt, however many observations of it the browser
+     * delivered. `triggers` is how many arrived and `coalesced` is
+     * the difference the owner absorbed — reported rather than
+     * hidden, because "the trigger never fired" and "it fired and was
+     * absorbed" are different facts and only one of them is a defect.
+     */
+    retryReport() {
+        return parseRetryReport(this.inner.retry_report());
+    }
+    /** Publish this node's capabilities as a signed fold announcement. */
+    async announce(capabilities) {
+        try {
+            await this.inner.announce([...capabilities]);
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+    /** Find the nodes offering a capability. */
+    async query(capability) {
+        let json;
+        try {
+            json = await this.inner.query(capability);
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+        return parseDescriptors(json);
+    }
+    /** Listen for one event tag. Returns a cancel handle. */
+    on(type, handler) {
+        return this.hub.on(type, handler);
+    }
+    /** Listen for every event. Returns a cancel handle. */
+    onEvent(handler) {
+        return this.hub.onAny(handler);
+    }
+    /** Consume events as an async iterable. */
+    events() {
+        return this.hub.events();
+    }
+    /**
+     * Narrow an ICE failure to `udp-blocked` when the evidence is there.
+     *
+     * Anything that is not an `ice-timeout` is returned untouched. For an
+     * `ice-timeout` it gathers the two observations the correction
+     * requires — the anchor answering over HTTPS, and a STUN binding to
+     * the address that anchor published going unanswered — and returns
+     * the classification {@link classifyRtcError} makes of them. With no
+     * address to probe there is no evidence, and the error comes back
+     * unchanged.
+     *
+     * Public because a page holding an `rtc_failure` event's error, or a
+     * Playwright witness holding a rejection, wants the same narrowing
+     * the connect path gets.
+     */
+    async refineIceFailure(error) {
+        return refineIceFailure(error, {
+            bootstrapUrl: this.bootstrapUrl,
+            bootstrapObserved: this.bootstrapObserved,
+            anchorRtcAddr: this.anchorRtcAddr,
+            failureTyping: this.failureTyping,
+        });
+    }
+    /**
+     * Close the node, its streams and its event surface.
+     *
+     * **Every stream this node handed out is ended first**, and that
+     * is a behaviour change: an iterator parked in `for await`
+     * completes here rather than hanging forever on a node that will
+     * never emit again, and `onMessage` listeners are dropped. It is
+     * the disposition the leader-proxied surface already gave its
+     * streams on a generation change (`MeshSession.endStreams`), so
+     * the two surfaces now dispose of a stream the same way; the
+     * direct one was the outlier.
+     *
+     * The order is load-bearing: the streams go before
+     * `inner.close()`, because a wasm `LeafStream.close` retires its
+     * handle *through the node* and a node already closed would
+     * report that as a failed close instead of performing it.
+     *
+     * **Every one of those closes is attempted.** `close` latches and
+     * empties its set before the loop, so there is no second chance at
+     * any of it: a child whose `close` threw out of the loop left the
+     * next child open with its iterator parked forever, the hub
+     * dispatching, the leaf never closed — and the retry a page then
+     * makes returns immediately, because the latch is set. So each
+     * obligation is discharged independently and the failures are
+     * collected, which is the only reading under which the latch is
+     * honest.
+     *
+     * Reported, not swallowed: if anything threw, this throws an
+     * `AggregateError` whose `errors` are the {@link LeafError}s in
+     * teardown order — always an aggregate, however many failed,
+     * because "how many parts of the close failed" is not a shape a
+     * caller should have to branch on to find out that one did. A
+     * host-supplied {@link LeafWasmStreamLike} is the surface that
+     * makes this reachable; the leaf's own `close` does not throw.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const failures = [];
+        // Ownership retirement first, while the node can still put a
+        // CANCEL on the wire (plan §4.5): one per dropped caller handle,
+        // each consumer settled with its typed terminal.
+        for (const failure of this.orgHandles.retireAll(new OrgCancelledError('org:rpc:cancelled: the node is closed'))) {
+            failures.push(fromWasmError(failure));
+        }
+        const open = [...this.streams];
+        this.streams.clear();
+        for (const stream of open) {
+            try {
+                stream.close();
+            }
+            catch (error) {
+                failures.push(fromWasmError(error));
+            }
+        }
+        try {
+            this.hub.close();
+        }
+        catch (error) {
+            failures.push(fromWasmError(error));
+        }
+        try {
+            this.inner.close();
+        }
+        catch (error) {
+            failures.push(fromWasmError(error));
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, `close: ${failures.length} of this node's teardown steps failed`);
+        }
+    }
+    /**
+     * The one `on_event` callback. Two events teach the probe something:
+     * `connected` proves the HTTPS bootstrap worked and carries the
+     * `rtc_addr` the anchor published, which is the only address this
+     * package may aim a STUN probe at.
+     */
+    ingest(json) {
+        const event = parseEvent(json);
+        if (event.type === 'connected') {
+            this.bootstrapObserved = true;
+            if (event.rtcAddr !== null)
+                this.anchorRtcAddr = event.rtcAddr;
+        }
+        this.hub.dispatch(event);
+    }
+}
+/**
+ * Connect to the mesh through an anchor.
+ *
+ * Loads and instantiates the leaf wasm (once per page, whatever the
+ * number of `connect()` calls), hands it the credential, and resolves a
+ * {@link BrowserNode}. Rejects with a typed {@link LeafError}; an ICE
+ * failure is classified per {@link BrowserNode.refineIceFailure}.
+ */
+export async function connect(options) {
+    const request = buildConnectRequest(options);
+    const failureTyping = options.failureTyping ?? {};
+    const wasm = await loadLeafWasm(options);
+    try {
+        const inner = await wasm.LeafNode.connect(request);
+        return new BrowserNode(inner, options.bootstrapUrl ?? null, failureTyping, options.anchorRtcAddr ?? null);
+    }
+    catch (error) {
+        throw await refineIceFailure(fromWasmError(error), {
+            bootstrapUrl: options.bootstrapUrl ?? null,
+            bootstrapObserved: false,
+            anchorRtcAddr: options.anchorRtcAddr ?? null,
+            failureTyping,
+        });
+    }
+}
+/**
+ * Build exactly the options object `LeafNode.connect` reads, credential
+ * resolved, origin defaulted, custodial identity validated.
+ *
+ * Exported because `src/leader/` builds `MeshSession.open`'s options on
+ * top of it: the two surfaces take the same connect keys, and a key
+ * added here must not be silently missing there. A dropped option is
+ * invisible from a page — it has already cost one witness — so the two
+ * share the builder rather than each listing the keys.
+ */
+export function buildConnectRequest(options) {
+    return {
+        credentialB64: resolveCredential(options),
+        origin: options.origin ?? defaultOrigin(),
+        ...(options.bootstrapUrl === undefined ? {} : { bootstrapUrl: options.bootstrapUrl }),
+        ...(options.iceServers ? { iceServers: options.iceServers } : {}),
+        ...resolveCustodialIdentity(options),
+    };
+}
+/**
+ * Parse a `counters_json()` payload. Values stay strings because they
+ * are `u64` on the Rust side and a JS number would round the large
+ * ones. Exported for the session surface, whose `counters_json` is a
+ * promise but whose payload is identical.
+ */
+export function parseCounters(json) {
+    const parsed = JSON.parse(json);
+    if (parsed === null || typeof parsed !== 'object')
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        out[key] = typeof value === 'string' ? value : String(value);
+    }
+    return out;
+}
+/**
+ * Parse one `peer_candidate` reading.
+ *
+ * `remainingMs` stays a string for the reason every other `u64` on
+ * this boundary does, and `state` is validated rather than cast: an
+ * unrecognised state would otherwise fall through both the
+ * `iceTimeout` and the `open` arm of a drive loop and spin until the
+ * leaf's own deadline, which is the slowest possible way to report a
+ * boundary that changed shape.
+ *
+ * `candidateError` is carried through as a value. The leaf warns it
+ * to the console as well, but a console line is not something a
+ * page, a witness or a diagnostic can read — and this parser used to
+ * drop the field, which made the leaf's machine-readable diagnostic
+ * unreachable from TypeScript.
+ *
+ * Exported for the unit tests, which drive it with fixed payloads.
+ */
+export function parseAttemptStatus(json) {
+    const parsed = JSON.parse(json);
+    if (parsed === null || typeof parsed !== 'object') {
+        throw new TypeError(`peer_candidate did not answer an object: ${json}`);
+    }
+    const raw = parsed;
+    const state = raw.state;
+    if (state !== 'gathering' &&
+        state !== 'open' &&
+        state !== 'iceTimeout' &&
+        state !== 'udpBlocked' &&
+        state !== 'failed') {
+        throw new TypeError(`peer_candidate answered an unknown state: ${String(state)}`);
+    }
+    const candidateError = raw.candidateError;
+    return {
+        dialog: String(raw.dialog ?? ''),
+        state,
+        sent: Number(raw.sent ?? 0),
+        applied: Number(raw.applied ?? 0),
+        answered: raw.answered === true,
+        direct: raw.direct === true,
+        remainingMs: String(raw.remainingMs ?? '0'),
+        candidateError: typeof candidateError === 'string' ? candidateError : null,
+    };
+}
+/**
+ * Parse an `rtc_stats_json()` payload.
+ *
+ * `not_applicable` is lifted out rather than left among the
+ * counters: a consumer iterating the reading must not find a field
+ * whose value is a sentence where every other value is a number.
+ *
+ * Exported for the unit tests, which drive it with fixed payloads.
+ */
+export function parseRtcStats(json) {
+    const parsed = JSON.parse(json);
+    if (parsed === null || typeof parsed !== 'object') {
+        throw new TypeError(`rtc_stats_json did not answer an object: ${json}`);
+    }
+    const counters = {};
+    const notApplicable = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (key === 'not_applicable') {
+            if (value === null || typeof value !== 'object')
+                continue;
+            for (const [field, reason] of Object.entries(value)) {
+                notApplicable[field] = String(reason);
+            }
+            continue;
+        }
+        counters[key] = typeof value === 'string' ? value : String(value);
+    }
+    return { counters, notApplicable };
+}
+/**
+ * Parse a `retry_report()` payload.
+ *
+ * Counts stay strings because they are `u64`, for the reason
+ * {@link parseCounters} gives. Exported for the unit tests.
+ */
+export function parseRetryReport(json) {
+    const parsed = JSON.parse(json);
+    if (parsed === null || typeof parsed !== 'object') {
+        throw new TypeError(`retry_report did not answer an object: ${json}`);
+    }
+    const raw = parsed;
+    return {
+        armed: raw.armed === true,
+        online: String(raw.online ?? '0'),
+        iceFailed: String(raw.iceFailed ?? '0'),
+        triggers: String(raw.triggers ?? '0'),
+        started: String(raw.started ?? '0'),
+        coalesced: String(raw.coalesced ?? '0'),
+        notEligible: String(raw.notEligible ?? '0'),
+        openEpisodes: Number(raw.openEpisodes ?? 0),
+        owned: Number(raw.owned ?? 0),
+        last: typeof raw.last === 'string' ? raw.last : null,
+    };
+}
+/**
+ * The orchestration half of the correction: gather the observations,
+ * then let the pure classifier decide. Exported for the unit tests,
+ * which drive it with fake probes.
+ */
+export async function refineIceFailure(error, context) {
+    if (!(error instanceof RtcError) || error.failure.type !== 'iceTimeout')
+        return error;
+    if (context.failureTyping.probeOnIceTimeout === false)
+        return error;
+    const probed = context.anchorRtcAddr;
+    if (probed === null) {
+        // No subject, no claim. The plan's whole point: an ICE timeout
+        // alone is never promoted.
+        return error;
+    }
+    const stunProbe = await probeStunBinding(probed, context.failureTyping.stun);
+    if (stunProbe.type !== 'unanswered')
+        return error;
+    const bootstrapOk = context.bootstrapObserved ||
+        (context.bootstrapUrl !== null &&
+            (await probeBootstrapReachable(context.bootstrapUrl, context.failureTyping.bootstrap)));
+    return classifyRtcError({ bootstrapOk, stunProbe, probed });
+}
+/**
+ * Parse `query`'s JSON array — `{ node_id, entity_id, capabilities,
+ * rtc_addr, noise_pubkey, version }` per entry, with `node_id` and
+ * `version` kept as exact decimal strings. Exported for the unit tests.
+ *
+ * `peerIdHex` is derived beside the decimal `nodeId`, never instead
+ * of it: the peer methods take hex and the announcement carries
+ * decimal, and a consumer that cannot see both cannot tell which it
+ * is holding. A `node_id` that is not a decimal `u64` is a boundary
+ * that changed shape and is refused rather than turned into an
+ * address.
+ */
+export function parseDescriptors(json) {
+    const parsed = parseJsonPreservingU64(json);
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const entry of parsed) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const fields = { ...entry };
+        const capabilities = fields.capabilities;
+        const nodeId = exactId(fields.node_id);
+        out.push({
+            nodeId,
+            peerIdHex: peerIdHex(nodeId),
+            entityId: text(fields.entity_id),
+            capabilities: Array.isArray(capabilities)
+                ? capabilities.filter((item) => typeof item === 'string')
+                : [],
+            rtcAddr: text(fields.rtc_addr),
+            noisePubkey: text(fields.noise_pubkey),
+            version: text(fields.version),
+        });
+    }
+    return out;
+}
+/** A 32-byte secret is 64 hex digits, nothing else. */
+const SECRET_HEX = /^[0-9a-fA-F]{64}$/;
+/**
+ * Validate the custodial identity options and return exactly the keys
+ * the wasm side reads.
+ *
+ * **Loud, never silent.** A malformed secret, or a Noise half without
+ * an entity half, throws {@link IdentityError} here rather than
+ * reaching the leaf — the same rule the Rust side now follows. The
+ * failure this guards against has already cost a witness once: a
+ * dropped or unusable identity option that falls through to a
+ * generated identity looks like two tabs disagreeing about who they
+ * are, with nothing in either log saying why.
+ */
+function resolveCustodialIdentity(options) {
+    const { entitySecretHex, noiseSecretHex } = options;
+    if (entitySecretHex === undefined) {
+        if (noiseSecretHex !== undefined) {
+            throw new IdentityError('noiseSecretHex was supplied without entitySecretHex: the leaf would generate the entity half, ' +
+                'so the identity would not be the one you meant to inject');
+        }
+        return {};
+    }
+    if (!SECRET_HEX.test(entitySecretHex)) {
+        throw new IdentityError(`entitySecretHex must be 32 bytes of hex (64 hex digits), got ${entitySecretHex.length} characters`);
+    }
+    if (noiseSecretHex === undefined)
+        return { entitySecretHex };
+    if (!SECRET_HEX.test(noiseSecretHex)) {
+        throw new IdentityError(`noiseSecretHex must be 32 bytes of hex (64 hex digits), got ${noiseSecretHex.length} characters`);
+    }
+    return { entitySecretHex, noiseSecretHex };
+}
+function exactId(value) {
+    if (typeof value === 'string')
+        return value;
+    return typeof value === 'number' ? String(value) : '';
+}
+function text(value) {
+    if (typeof value === 'string')
+        return value.length > 0 ? value : null;
+    return typeof value === 'number' ? String(value) : null;
+}
+function resolveCredential(options) {
+    if (options.credentialB64 !== undefined)
+        return options.credentialB64;
+    const credential = options.credential;
+    if (typeof credential === 'string')
+        return credential;
+    if (credential instanceof Uint8Array)
+        return toBase64(credential);
+    throw new Error('connect() needs a credential: pass credentialB64 or credential');
+}
+function defaultOrigin() {
+    const origin = globalThis.location?.origin;
+    if (typeof origin === 'string' && origin.length > 0)
+        return origin;
+    throw new Error('connect() needs an origin: there is no location.origin in this context');
+}