@net-mesh/browser 0.37.0

package/dist/leader/session.js

@@ -0,0 +1,770 @@
+/**
+ * `MeshSession` — one node per origin, whichever tab you opened.
+ *
+ * §8's decision is that a browser origin runs exactly one Net node:
+ * tabs contend for a Web Lock, the holder runs the node on the main
+ * thread, and the others attach over a `BroadcastChannel` and get the
+ * same API. This is that API in TypeScript.
+ *
+ * The difference from {@link BrowserNode} is one of scope, not of
+ * capability: `connect()` gives a page *this tab's* node, and
+ * `openSession()` gives it *the origin's* node. Everything a page can
+ * do with one it can do with the other — nRPC calls, channels,
+ * streams, announcements, queries, enrollment — and three methods are
+ * promises here that are synchronous there, because on a follower the
+ * answer lives in another tab:
+ *
+ * | | `BrowserNode` | `MeshSession` |
+ * |---|---|---|
+ * | `openStream` | synchronous | promise |
+ * | `counters` | synchronous | promise |
+ * | `isEnrolled` | synchronous | promise |
+ *
+ * Failures are the same taxonomy, re-typed by the same mapper, so a
+ * proxied refusal and a direct one arrive as the same class. The one
+ * addition is {@link NotLeaderError}: a tab that was superseded — a
+ * suspended tab that resumed, say — is refused rather than served, and
+ * that refusal is typed.
+ */
+import { fromWasmError, OrgCancelledError, OrgLeaderLostError, } from '../errors.js';
+import { clientStreamOrgTrampoline, duplexOrgTrampoline, OrgDuplex, OrgHandleRegistry, OrgServe, OrgStream, OrgUpload, streamingOrgTrampoline, toWasmOrgCallOptions, toWasmOrgServeOptions, unaryOrgTrampoline, } from '../org.js';
+import { buildConnectRequest, parseAttemptStatus, parseCounters, parseDescriptors, } from '../node.js';
+import { acceptPeer as driveAccept, connectPeer as driveConnect, } from '../peer-driver.js';
+import { LeafStream } from '../stream.js';
+import { idArg, loadLeafWasm } from '../wasm.js';
+import { isLifecycleEvent, parseSessionEvent, } from './events.js';
+import { asSessionModule } from './wasm.js';
+import { EventHub } from '../events.js';
+/** The origin's Net node, as this tab sees it. */
+export class MeshSession {
+    inner;
+    /**
+     * The same fan-out the direct surface uses, instantiated over the
+     * wider event union. One implementation, so a throwing listener,
+     * the never-unwind-into-Rust rule and the iterator buffering behave
+     * identically on both surfaces.
+     */
+    hub = new EventHub();
+    /**
+     * Streams this session handed out, so the ones still open can be
+     * ended when leadership moves.
+     *
+     * A stream is session-scoped and is **not** restored across a
+     * leader change, which the Rust side enforces by binding each
+     * handle to its opening generation. That enforcement makes a stale
+     * `send` reject — but it says nothing about a consumer sitting in
+     * `await stream[Symbol.asyncIterator]().next()`, which would simply
+     * never settle: the wasm stream stops emitting and nothing tells
+     * the queue to end. So the session owns the set and closes it,
+     * which is what turns "no more data, ever" into the end of the
+     * iteration a page is already written to handle.
+     */
+    streams = new Set();
+    /**
+     * The generation the streams in that set were opened under.
+     *
+     * Tracked because the generation moving is the *only* signal an
+     * abrupt leader disappearance gives. A page that crashes or
+     * navigates away never sends its `leader_lost` announcement: the
+     * promoted follower fails its own pending requests and reports
+     * `leader_changed`, and so does every other surviving follower
+     * when the successor's Leadership arrives. The Rust handle then
+     * correctly suppresses the old stream's bytes by its opening
+     * generation — which is precisely what leaves a consumer sitting
+     * in `await iterator.next()` forever, waiting on a stream that is
+     * now guaranteed never to emit again.
+     */
+    streamGeneration;
+    /**
+     * The live org handles (plan §4.5), retired when leadership moves
+     * or the session closes: pending calls fail typed and each dropped
+     * caller handle emits exactly one CANCEL.
+     */
+    orgHandles = new OrgHandleRegistry();
+    closed = false;
+    /** @internal — use {@link openSession}. */
+    constructor(inner) {
+        this.inner = inner;
+        this.streamGeneration = inner.generation();
+        inner.on_event((json) => this.hub.deliver(json, parseSessionEvent));
+        this.hub.onAny((event) => {
+            // `leader_lost` is this tab losing the leader it was talking
+            // to; `not_leader` is this tab discovering it *was* the leader
+            // and is not any more. Either way every stream this session
+            // handed out belonged to a node that is gone — and neither
+            // moves this tab's generation, so both are named explicitly.
+            if (event.type === 'leader_lost' || event.type === 'not_leader') {
+                // The generation that owned the calls is the one they were
+                // issued under — typed `LeaderLost`, never resumed.
+                this.orgHandles.retireAll(new OrgLeaderLostError(this.streamGeneration));
+                this.endStreams();
+                return;
+            }
+            // And the abrupt case: a generation that moved under us. Read
+            // off the session rather than out of the event, so a
+            // `leader_changed` that merely repeats the generation this
+            // tab already holds ends nothing — a duplicate notification
+            // must not kill the streams the new generation just opened.
+            const current = this.inner.generation();
+            if (current === this.streamGeneration)
+                return;
+            const previous = this.streamGeneration;
+            this.streamGeneration = current;
+            this.orgHandles.retireAll(new OrgLeaderLostError(previous));
+            this.endStreams();
+        });
+    }
+    /** `'leader'` if this tab runs the node, `'follower'` if another does. */
+    role() {
+        return this.inner.role() === 'leader' ? 'leader' : 'follower';
+    }
+    /**
+     * The generation in force for this tab, as an exact decimal string.
+     *
+     * A string because it is a `u64`: a number would round above 2^53,
+     * and a rounded generation is a fence that has stopped fencing.
+     */
+    generation() {
+        return this.inner.generation();
+    }
+    /** The node's id, 16 lowercase hex digits, or `null` before one is known. */
+    nodeIdHex() {
+        return this.inner.node_id_hex() ?? null;
+    }
+    /** The identity fingerprint the Web Lock is named after. */
+    fingerprint() {
+        return this.inner.fingerprint();
+    }
+    /** The Web Lock and `BroadcastChannel` name. */
+    scope() {
+        return this.inner.scope();
+    }
+    /**
+     * How long this tab took to take over, in milliseconds, or `null` if
+     * it was the origin's first leader.
+     *
+     * Measured from the lock coming free to the node being re-bootstrapped
+     * and the subscriptions and announcement restored. It is a
+     * measurement, not a promise: the interruption a *peer* observes is
+     * bounded by Net's own failure detection, which is a different and
+     * much larger number.
+     */
+    interruptionMs() {
+        return this.inner.interruption_ms() ?? null;
+    }
+    /**
+     * Call an nRPC service.
+     *
+     * Rejects with {@link RpcError} — including `leader-lost` when the
+     * tab running the node was replaced while the call was in flight.
+     * Never a silent retry: §8's rule is that the caller is told and
+     * decides.
+     *
+     * On a follower the deadline is armed here as well as on the
+     * leader, and that is true whether or not `timeoutMs` was given:
+     * omitting it takes the leaf's own 30 s default rather than
+     * leaving the promise to a leader that may be frozen. Either way
+     * expiry is `rpc-indeterminate` — the work may already have been
+     * admitted in the other tab, and nothing here re-issues it.
+     */
+    async call(service, payload, timeoutMs) {
+        return await this.guard(() => this.inner.call(service, payload, timeoutMs));
+    }
+    /**
+     * Subscribe to a channel.
+     *
+     * Also adds it to what a future leader restores, so a handoff does
+     * not silently drop it.
+     */
+    async subscribe(channel) {
+        await this.guard(() => this.inner.subscribe(channel));
+    }
+    /**
+     * Release this tab's claim on a channel.
+     *
+     * Not `subscribe` run backwards. The origin runs one node and the
+     * leader holds **one** membership for the union of every tab's
+     * declarations, so this drops this tab's claim and the membership
+     * itself is given up only when no other tab still wants the
+     * channel. One tab closing a subscription therefore cannot stop
+     * another tab that is still reading the same channel.
+     *
+     * Also removes it from what a future leader restores, so a handoff
+     * does not silently bring back a channel this tab released.
+     */
+    async unsubscribe(channel) {
+        await this.guard(() => this.inner.unsubscribe(channel));
+    }
+    /** Publish one payload to a channel. */
+    async publish(channel, payload) {
+        await this.guard(() => this.inner.publish(channel, payload));
+    }
+    /** Publish this node's capability announcement. */
+    async announce(capabilities) {
+        await this.guard(() => this.inner.announce([...capabilities]));
+    }
+    /** Find the nodes offering a capability. */
+    async query(capability) {
+        return parseDescriptors(await this.guard(() => this.inner.query(capability)));
+    }
+    /** Every leaf counter. Values stay strings because they are `u64`. */
+    async counters() {
+        return parseCounters(await this.guard(() => this.inner.counters_json()));
+    }
+    /**
+     * Run the enrollment exchange if the node is not enrolled.
+     *
+     * Works on a follower too: one node per origin means one enrollment
+     * per origin, so a follower asking to enroll is asking the only
+     * session there is.
+     */
+    async enroll() {
+        await this.guard(() => this.inner.enroll());
+    }
+    /** Whether the anchor has admitted this node. */
+    async isEnrolled() {
+        return await this.guard(() => this.inner.is_enrolled());
+    }
+    /**
+     * Sign and send a `0x0D02` signalling envelope — the
+     * session-independent path, so no session with `peer` is needed.
+     */
+    async signal(peerHex, dialogHex, kind, payload) {
+        // The same id marshaling `BrowserNode.signal` applies (finding
+        // #52): strings verbatim, a non-string refused by the parsers'
+        // names — peer first — before the wasm seam.
+        await this.guard(() => this.inner.signal(idArg(peerHex, 'peer'), idArg(dialogHex, 'dialog'), kind, payload));
+    }
+    /**
+     * Connect directly to `nodeIdHex` (§9), wherever the node is.
+     *
+     * The same drive loop `BrowserNode.connectPeer` runs — literally
+     * the same function, from `peer-driver.ts`, with this session's
+     * primitives instead of the direct node's. One loop means the
+     * offerer and the answerer cannot disagree about what supersession
+     * or a terminal reading looks like, which is a disagreement neither
+     * side could detect.
+     *
+     * On a follower every step is a proxy round trip and the attempt
+     * runs on the leader tab's node. A step whose attempt was replaced
+     * while the request was in flight is refused by the leaf before it
+     * touches the replacement, and arrives here as `superseded`.
+     *
+     * **Idempotent on a healthy pair**, as `BrowserNode.connectPeer` is: an
+     * already-direct, open pair resolves `direct` with its live dialog and
+     * nothing is offered — a second offer would replace the working link
+     * and close it under the peer. A leader too old to answer that reading
+     * is asked for an offer, as before.
+     */
+    async connectPeer(nodeIdHex) {
+        let settled;
+        try {
+            settled = (await this.inner.peer_direct_dialog(nodeIdHex)) ?? undefined;
+        }
+        catch {
+            // A closed session is refused by the offer below, typed; an older
+            // leader simply has no such reading.
+            settled = undefined;
+        }
+        if (settled !== undefined)
+            return { type: 'direct', peer: nodeIdHex, dialog: settled };
+        return driveConnect(nodeIdHex, this.peerPrimitives(), parseAttemptStatus);
+    }
+    /**
+     * Answer the offer `nodeIdHex` filed — {@link connectPeer}'s
+     * counterpart, on whichever tab holds the lock.
+     */
+    async acceptPeer(nodeIdHex) {
+        return driveAccept(nodeIdHex, this.peerPrimitives(), parseAttemptStatus);
+    }
+    /**
+     * The proxied primitives, each re-typed by the same mapper every
+     * other method here uses, so a proxied refusal is the same class a
+     * direct one is — which is what lets one drive loop classify both.
+     */
+    peerPrimitives() {
+        return {
+            offer: (peer) => this.guard(() => this.inner.peer_offer(peer)),
+            acceptOffer: (peer) => this.guard(() => this.inner.peer_accept_offer(peer)),
+            candidate: (peer, dialog) => this.guard(() => this.inner.peer_candidate(peer, dialog)),
+            handshake: (peer, dialog) => this.guard(() => this.inner.peer_handshake(peer, dialog)),
+        };
+    }
+    /**
+     * Open a reliable or fire-and-forget stream.
+     *
+     * A promise where {@link BrowserNode.openStream} is synchronous: on
+     * a follower the stream is opened by the tab that owns the
+     * DataChannel. The object it resolves to is the same
+     * {@link LeafStream}, so `await stream.send(bytes)` and
+     * `for await (const payload of stream)` read the same either way.
+     *
+     * A stream is **not** restored across a leader change — it is
+     * session-scoped, and pretending otherwise would hide a real
+     * interruption. A page that wants one back opens one. What this
+     * session does guarantee is that the interruption is *observable*:
+     * the handle is retained here and ended when leadership moves, so
+     * `for await (const payload of stream)` finishes instead of hanging
+     * on a node that is gone.
+     *
+     * That guarantee has to cover the open itself. On a follower this
+     * is a proxy round trip, so a result can arrive *after* the
+     * leadership-loss notification that already drained the retained
+     * set — and the handle it carries was stamped by Rust with the
+     * generation the request was issued under, so it is stale on
+     * arrival. Registering it would put a permanently silent stream
+     * into a set nothing will drain again. The generation is therefore
+     * captured before the await and compared after it, and a crossing
+     * result is ended exactly as a consumer a microtask later would
+     * have seen it.
+     */
+    async openStream(options) {
+        const openedUnder = this.inner.generation();
+        const stream = new LeafStream(await this.guard(() => this.inner.open_stream(options)));
+        if (this.closed || this.inner.generation() !== openedUnder) {
+            // Leadership (or this session) went away while the open was in
+            // flight. Ending it here is the same disposition a consumer
+            // would have got a microtask later, rather than a live handle
+            // on a dead node.
+            stream.close();
+            return stream;
+        }
+        this.streams.add(stream);
+        return stream;
+    }
+    // ── Organization-scoped streaming (plan §4.5) ────────────────────────
+    //
+    // The same eight verbs as `BrowserNode`, on whichever tab holds the
+    // node. On a follower every call rides a **transparent envelope of
+    // the same nRPC frame bytes** over the existing proxy vocabulary —
+    // a new shape would cost proxy vocabulary — and its correlation is
+    // this tab's self-minted id plus the gate generation it presented,
+    // never the wire id or incarnation (those come back in the stream
+    // resolution). Exact peer/session attribution is preserved through
+    // direct and proxied callbacks alike and across leader replacement.
+    /**
+     * 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.
+     *
+     * **Leader replacement.** A pending proxied call fails typed
+     * `LeaderLost` on a generation move and is NEVER resumed; a
+     * successor generation's calls carry fresh correlation and fresh
+     * proofs.
+     *
+     * **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 in another tab. 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) {
+        return await this.guard(() => this.inner.call_org(service, payload, toWasmOrgCallOptions(options)));
+    }
+    /**
+     * 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.
+     *
+     * **Leader replacement.** A pending proxied call fails typed
+     * `LeaderLost` on a generation move and is NEVER resumed; a
+     * successor generation's calls carry fresh correlation and fresh
+     * proofs. An open that lands after the move is retired on arrival
+     * rather than handed out live.
+     *
+     * **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 in another tab. 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) {
+        const openedUnder = this.inner.generation();
+        let stream;
+        try {
+            const handle = await this.inner.call_org_streaming(service, payload, toWasmOrgCallOptions(options));
+            stream = new OrgStream(handle, () => handle.cancel(), () => this.orgHandles.delete(stream));
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+        if (this.closed || this.inner.generation() !== openedUnder) {
+            // Leadership (or this session) went away while the open was in
+            // flight. Retired on arrival is the same disposition a
+            // consumer would have got a microtask later — never a live
+            // handle on a dead generation, and never resumed on the
+            // successor's.
+            stream.retire(this.closed
+                ? new OrgCancelledError('org:rpc:cancelled: the session is closed')
+                : new OrgLeaderLostError(openedUnder));
+            return stream;
+        }
+        this.orgHandles.add(stream);
+        return stream;
+    }
+    /**
+     * 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).
+     *
+     * **Leader replacement.** A pending proxied call fails typed
+     * `LeaderLost` on a generation move and is NEVER resumed; a
+     * successor generation's calls carry fresh correlation and fresh
+     * proofs. An open that lands after the move is retired on arrival
+     * rather than handed out live.
+     *
+     * **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 in another tab. 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) {
+        const openedUnder = this.inner.generation();
+        let upload;
+        try {
+            const handle = await this.inner.call_org_client_stream(service, toWasmOrgCallOptions(options));
+            upload = new OrgUpload(handle, () => this.orgHandles.delete(upload));
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+        if (this.closed || this.inner.generation() !== openedUnder) {
+            upload.retire(this.closed
+                ? new OrgCancelledError('org:rpc:cancelled: the session is closed')
+                : new OrgLeaderLostError(openedUnder));
+            return upload;
+        }
+        this.orgHandles.add(upload);
+        return upload;
+    }
+    /**
+     * 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.
+     *
+     * **Leader replacement.** A pending proxied call fails typed
+     * `LeaderLost` on a generation move and is NEVER resumed; a
+     * successor generation's calls carry fresh correlation and fresh
+     * proofs. An open that lands after the move is retired on arrival
+     * rather than handed out live.
+     *
+     * **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 in another tab. 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) {
+        const openedUnder = this.inner.generation();
+        let call;
+        try {
+            const handle = await this.inner.call_org_duplex(service, toWasmOrgCallOptions(options));
+            call = new OrgDuplex(handle, () => this.orgHandles.delete(call));
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+        if (this.closed || this.inner.generation() !== openedUnder) {
+            call.retire(this.closed
+                ? new OrgCancelledError('org:rpc:cancelled: the session is closed')
+                : new OrgLeaderLostError(openedUnder));
+            return call;
+        }
+        this.orgHandles.add(call);
+        return call;
+    }
+    /**
+     * 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.
+     *
+     * On a follower the registration rides the proxy registry and
+     * inbound calls dispatch to the registering follower; teardown
+     * follows the retire discipline — a generation move fences the
+     * registration's calls and streams, never resurrected.
+     *
+     * **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}.
+     *
+     * On a follower the registration rides the proxy registry and
+     * inbound calls dispatch to the registering follower; teardown
+     * follows the retire discipline — a generation move fences the
+     * registration's calls and streams, never resurrected.
+     *
+     * **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.
+     *
+     * On a follower the registration rides the proxy registry and
+     * inbound calls dispatch to the registering follower; teardown
+     * follows the retire discipline — a generation move fences the
+     * registration's calls and streams, never resurrected.
+     *
+     * **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.
+     *
+     * On a follower the registration rides the proxy registry and
+     * inbound calls dispatch to the registering follower; teardown
+     * follows the retire discipline — a generation move fences the
+     * registration's calls and streams, never resurrected.
+     *
+     * **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);
+        }
+    }
+    /** 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);
+    }
+    /**
+     * Listen for the five lifecycle tags only — `leader_changed`,
+     * `subscription_restored`, `leader_lost`, `generation_fenced`,
+     * `not_leader`.
+     *
+     * A page that wants to render "reconnecting" wants exactly these and
+     * none of the node traffic.
+     */
+    onLifecycle(handler) {
+        return this.hub.onAny((event) => {
+            if (isLifecycleEvent(event))
+                handler(event);
+        });
+    }
+    /** Consume events as an async iterable. */
+    events() {
+        return this.hub.events();
+    }
+    /**
+     * Stand down and release the lock.
+     *
+     * On a leader this is what lets a follower promote, so a page that
+     * navigates away without calling it leaves the handoff to the
+     * browser's own lock release.
+     *
+     * Every stream this session handed out is ended first, in that
+     * order: a consumer awaiting the next payload has to be settled by
+     * something, and after `inner.close()` nothing will ever emit
+     * again.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Ownership retirement first, while the transport still exists:
+        // one CANCEL per dropped caller handle, each consumer settled
+        // with its typed terminal (plan §4.5).
+        this.orgHandles.retireAll(new OrgCancelledError('org:rpc:cancelled: the session is closed'));
+        this.endStreams();
+        this.hub.close();
+        this.inner.close();
+    }
+    /**
+     * End every stream this session handed out.
+     *
+     * `LeafStream.close` ends each waiting consumer and clears the
+     * listeners, which is precisely the disposition D2 specifies for a
+     * stream across a leader change: failed and observable, never
+     * resurrected and never left pending. Called on explicit
+     * leadership loss, on a generation that moved under this tab, and
+     * on close; idempotent, because a page may have closed a stream
+     * itself.
+     */
+    endStreams() {
+        const open = [...this.streams];
+        this.streams.clear();
+        for (const stream of open)
+            stream.close();
+    }
+    /**
+     * Re-type whatever the boundary threw.
+     *
+     * One wrapper for every method because they all cross the same
+     * boundary and a proxied failure must arrive as the same class a
+     * direct one does — that is the whole point of the failure text
+     * being carried verbatim through the proxy instead of re-parsed on
+     * the Rust side.
+     */
+    async guard(operation) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            throw fromWasmError(error);
+        }
+    }
+}
+/**
+ * Join the origin's Net node, electing a leader if there is none.
+ *
+ * Resolves as soon as this tab knows its role: the leader once it has
+ * bootstrapped, a follower once it has attached. A follower keeps
+ * queueing for the lock in the background, so when the leader goes
+ * away it promotes itself, re-bootstraps with the same identity and
+ * restores the subscriptions — without the page doing anything.
+ *
+ * Rejects with a typed {@link LeafError}. {@link IdentityError} covers
+ * the two refusals worth knowing by name: a context with no Web Locks
+ * API (where one-node-per-origin cannot be enforced, so the leaf
+ * refuses rather than let two tabs evict each other) and a context
+ * with no IndexedDB (where an identity cannot be stored, so the page
+ * must inject one).
+ */
+export async function openSession(options) {
+    const module = asSessionModule(await loadLeafWasm(options));
+    const request = {
+        // Shared with `connect()` deliberately: the two surfaces take the
+        // same connect keys, and a key added to one must not be silently
+        // missing from the other.
+        ...buildConnectRequest(options),
+        ...(options.capabilities ? { capabilities: [...options.capabilities] } : {}),
+        ...(options.subscriptions ? { subscriptions: [...options.subscriptions] } : {}),
+        ...(options.dbName === undefined ? {} : { dbName: options.dbName }),
+        ...(options.lockScope === undefined ? {} : { lockScope: options.lockScope }),
+    };
+    try {
+        return new MeshSession(await module.MeshSession.open(request));
+    }
+    catch (error) {
+        throw fromWasmError(error);
+    }
+}