@net-mesh/browser 0.37.0

package/dist/leader/events.js

@@ -0,0 +1,116 @@
+/**
+ * §8's lifecycle, as events.
+ *
+ * A session emits every {@link LeafEvent} the direct surface does,
+ * plus five tags of its own. They are here rather than in
+ * `src/events.ts` because they describe the *lifecycle*, not the node:
+ * a page using {@link BrowserNode} never sees them, and a page using a
+ * session cannot explain a leader change without them.
+ *
+ * `parseEvent` carries an unknown tag through intact, so a bundle
+ * whose leaf is newer than its wrapper stays legible; this module
+ * refines exactly the five it knows and leaves the rest as they
+ * arrived.
+ */
+import { parseEvent } from '../events.js';
+/**
+ * Parse one event JSON string from a session.
+ *
+ * Never throws: this runs inside a callback the wasm module invokes,
+ * and an exception there would unwind through Rust. Anything that is
+ * not one of the five lifecycle tags goes to `parseEvent`, so the node
+ * events and the unknown-tag passthrough behave exactly as they do on
+ * the direct surface.
+ */
+export function parseSessionEvent(json) {
+    const base = parseEvent(json);
+    if (base.type !== 'unknown')
+        return base;
+    const refined = refine(base);
+    return refined ?? base;
+}
+/**
+ * `true` for the six tags a session adds, so a page can filter the
+ * lifecycle out of the event stream without listing them.
+ */
+export function isLifecycleEvent(event) {
+    switch (event.type) {
+        case 'leader_changed':
+        case 'subscription_restored':
+        case 'leader_lost':
+        case 'generation_fenced':
+        case 'not_leader':
+        case 'promotion_failed':
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * Refine an event `parseEvent` did not recognise.
+ *
+ * `raw` is whatever `parseJsonPreservingU64` produced, so the exact
+ * decimal strings for `generation`, `presented` and `current` are
+ * already intact — they are in `U64_EVENT_KEYS`, which is what keeps
+ * a large generation from being rounded into a fence that no longer
+ * fences.
+ */
+function refine(event) {
+    const raw = event.raw;
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const fields = { ...raw };
+    switch (event.tag) {
+        case 'leader_changed':
+            return { type: 'leader_changed', generation: exact(fields.generation) };
+        case 'subscription_restored':
+            return {
+                type: 'subscription_restored',
+                channel: typeof fields.channel === 'string' ? fields.channel : '',
+            };
+        case 'leader_lost': {
+            // `failed` is a `usize` count, not a `u64` id: a number is
+            // exact for it, and it is deliberately not in `U64_EVENT_KEYS`.
+            const failed = Number(fields.failed);
+            return {
+                type: 'leader_lost',
+                generation: exact(fields.generation),
+                failed: Number.isFinite(failed) ? failed : 0,
+            };
+        }
+        case 'generation_fenced':
+            return {
+                type: 'generation_fenced',
+                presented: exact(fields.presented),
+                current: exact(fields.current),
+            };
+        case 'not_leader':
+            return {
+                type: 'not_leader',
+                presented: exact(fields.presented),
+                current: exact(fields.current),
+            };
+        case 'promotion_failed':
+            return {
+                type: 'promotion_failed',
+                generation: exact(fields.generation),
+                detail: typeof fields.detail === 'string' ? fields.detail : '',
+            };
+        default:
+            return null;
+    }
+}
+/**
+ * A `u64` field, kept exactly as it arrived.
+ *
+ * Five call sites that must agree: a generation read as a number
+ * anywhere is a generation that rounds above 2^53, and a rounded
+ * generation is a fence that silently stops fencing.
+ */
+function exact(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return '0';
+}

package/dist/leader/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * §8's session surface: one node per origin, leader-elected.
+ *
+ * `connect()` gives a page this tab's node; `openSession()` gives it
+ * the origin's node, whichever tab is running it. See
+ * {@link MeshSession} for the three methods that are promises here and
+ * synchronous on the direct surface, and why.
+ */
+export { MeshSession, openSession } from './session.js';
+export type { SessionOptions, SessionRole } from './session.js';
+export { isLifecycleEvent, parseSessionEvent } from './events.js';
+export type { GenerationFencedEvent, LeaderChangedEvent, LeaderLostEvent, NotLeaderEvent, SessionEvent, SessionEventOf, SessionLifecycleEvent, SubscriptionRestoredEvent, } from './events.js';
+export { asSessionModule } from './wasm.js';
+export type { LeafWasmSession, LeafWasmSessionModule, LeafWasmSessionOptions, } from './wasm.js';

package/dist/leader/index.js

@@ -0,0 +1,11 @@
+/**
+ * §8's session surface: one node per origin, leader-elected.
+ *
+ * `connect()` gives a page this tab's node; `openSession()` gives it
+ * the origin's node, whichever tab is running it. See
+ * {@link MeshSession} for the three methods that are promises here and
+ * synchronous on the direct surface, and why.
+ */
+export { MeshSession, openSession } from './session.js';
+export { isLifecycleEvent, parseSessionEvent } from './events.js';
+export { asSessionModule } from './wasm.js';

package/dist/leader/session.d.ts

@@ -0,0 +1,539 @@
+/**
+ * `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 { type OrgAccess, type OrgByteStream, type OrgCallOptions, type OrgClientStreamHandler, type OrgDuplexHandler, type OrgDuplexHandles, type OrgServeHandle, type OrgServeOptions, type OrgStreamingHandler, type OrgUnaryHandler, type OrgUploadCall } from '../org.js';
+import { type ConnectOptions, type NodeDescriptor, type PeerConnectOutcome } from '../node.js';
+import { LeafStream, type OpenStreamOptions } from '../stream.js';
+import { type SessionEvent, type SessionEventOf, type SessionLifecycleEvent } from './events.js';
+import { type Unsubscribe } from '../events.js';
+/** Whether this tab runs the node or talks to the tab that does. */
+export type SessionRole = 'leader' | 'follower';
+/** {@link openSession}'s argument. */
+export interface SessionOptions extends ConnectOptions {
+    /**
+     * Capabilities to announce, and to re-announce whenever this tab
+     * becomes the leader.
+     *
+     * On the session rather than on `announce()` because a new leader
+     * has to re-publish them without being asked — D2's restoration
+     * step. Calling `announce()` as well is fine and additive.
+     */
+    capabilities?: readonly string[];
+    /**
+     * Channels this tab depends on.
+     *
+     * Declared up front so a *new* leader can restore them: the leader
+     * keeps the union of every follower's declaration subscribed, and a
+     * tab that only called `subscribe()` after a handoff would have a
+     * window where its channel was not subscribed by anybody.
+     */
+    subscriptions?: readonly string[];
+    /** The IndexedDB database holding the identity. Defaults to `net-mesh-leaf`. */
+    dbName?: string;
+    /**
+     * Override the Web Lock and `BroadcastChannel` name. Defaults to
+     * `net-mesh/<origin>/<identity-fingerprint>`.
+     *
+     * For tests that need two independent elections inside one origin.
+     * A page should not set it: two scopes on one identity is two nodes
+     * on one identity, which is the eviction §8 exists to prevent.
+     */
+    lockScope?: string;
+}
+/** The origin's Net node, as this tab sees it. */
+export declare class MeshSession {
+    private readonly 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.
+     */
+    private readonly hub;
+    /**
+     * 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.
+     */
+    private readonly streams;
+    /**
+     * 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.
+     */
+    private 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.
+     */
+    private readonly orgHandles;
+    private closed;
+    /** `'leader'` if this tab runs the node, `'follower'` if another does. */
+    role(): SessionRole;
+    /**
+     * 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(): string;
+    /** The node's id, 16 lowercase hex digits, or `null` before one is known. */
+    nodeIdHex(): string | null;
+    /** The identity fingerprint the Web Lock is named after. */
+    fingerprint(): string;
+    /** The Web Lock and `BroadcastChannel` name. */
+    scope(): string;
+    /**
+     * 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(): number | 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.
+     */
+    call(service: string, payload: Uint8Array, timeoutMs?: number): Promise<Uint8Array>;
+    /**
+     * Subscribe to a channel.
+     *
+     * Also adds it to what a future leader restores, so a handoff does
+     * not silently drop it.
+     */
+    subscribe(channel: string): Promise<void>;
+    /**
+     * 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.
+     */
+    unsubscribe(channel: string): Promise<void>;
+    /** Publish one payload to a channel. */
+    publish(channel: string, payload: Uint8Array): Promise<void>;
+    /** Publish this node's capability announcement. */
+    announce(capabilities: readonly string[]): Promise<void>;
+    /** Find the nodes offering a capability. */
+    query(capability: string): Promise<NodeDescriptor[]>;
+    /** Every leaf counter. Values stay strings because they are `u64`. */
+    counters(): Promise<Record<string, string>>;
+    /**
+     * 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.
+     */
+    enroll(): Promise<void>;
+    /** Whether the anchor has admitted this node. */
+    isEnrolled(): Promise<boolean>;
+    /**
+     * Sign and send a `0x0D02` signalling envelope — the
+     * session-independent path, so no session with `peer` is needed.
+     */
+    signal(peerHex: string, dialogHex: string, kind: string, payload: Uint8Array): Promise<void>;
+    /**
+     * 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.
+     */
+    connectPeer(nodeIdHex: string): Promise<PeerConnectOutcome>;
+    /**
+     * Answer the offer `nodeIdHex` filed — {@link connectPeer}'s
+     * counterpart, on whichever tab holds the lock.
+     */
+    acceptPeer(nodeIdHex: string): Promise<PeerConnectOutcome>;
+    /**
+     * 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.
+     */
+    private peerPrimitives;
+    /**
+     * 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.
+     */
+    openStream(options: OpenStreamOptions): Promise<LeafStream>;
+    /**
+     * 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.
+     */
+    callOrg(service: string, payload: Uint8Array, options: OrgCallOptions): Promise<Uint8Array>;
+    /**
+     * 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.
+     */
+    callOrgStreaming(service: string, payload: Uint8Array, options: OrgCallOptions): Promise<OrgByteStream>;
+    /**
+     * 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.
+     */
+    callOrgClientStream(service: string, options: OrgCallOptions): Promise<OrgUploadCall>;
+    /**
+     * 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.
+     */
+    callOrgDuplex(service: string, options: OrgCallOptions): Promise<OrgDuplexHandles>;
+    /**
+     * 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: string, access: OrgAccess, handler: OrgUnaryHandler, options: OrgServeOptions): OrgServeHandle;
+    /**
+     * 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: string, access: OrgAccess, handler: OrgStreamingHandler, options: OrgServeOptions): OrgServeHandle;
+    /**
+     * 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: string, access: OrgAccess, handler: OrgClientStreamHandler, options: OrgServeOptions): OrgServeHandle;
+    /**
+     * 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: string, access: OrgAccess, handler: OrgDuplexHandler, options: OrgServeOptions): OrgServeHandle;
+    /** Listen for one event tag. Returns a cancel handle. */
+    on<T extends SessionEvent['type']>(type: T, handler: (event: SessionEventOf<T>) => void): Unsubscribe;
+    /** Listen for every event. Returns a cancel handle. */
+    onEvent(handler: (event: SessionEvent) => void): Unsubscribe;
+    /**
+     * 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: (event: SessionLifecycleEvent) => void): Unsubscribe;
+    /** Consume events as an async iterable. */
+    events(): AsyncIterableIterator<SessionEvent>;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    private endStreams;
+    /**
+     * 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.
+     */
+    private guard;
+}
+/**
+ * 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 declare function openSession(options: SessionOptions): Promise<MeshSession>;