@synapse-sdk/client 0.1.0 → 0.3.3

package/dist/session.js

@@ -0,0 +1,963 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// One MoQ session to the broker (WP §2, §8.2, §10): the link that comes and goes. A `Session` is
+// one admitted connection (hello received) and everything learned on it — the hello, the role the
+// runtime's notices grant, the catalogs, the project state, the offsets table, the clock estimate —
+// its `req` track and the calls pending on it, and its own tasks (the `res` demux, four snapshot
+// watchers, the clock probe), which write only into it. A task that loses its track records why and
+// closes the connection, nothing else: the node's loop (`node.ts`) sees the close and does the rest.
+import * as Moq from "@moq/net";
+import { ADMISSION_REFUSED_CLOSE_CODE, ClockSync, FLAGS, STREAM_GROUP_SPAN_MS, STREAM_SUBSCRIBE_MAX_AGE_MS, SynapseError, TYPES, decode as decodeBody, decodeHeader, frame, headerLength, helloPath, SID_LEN, connectPath, encodeConnectRequest, isClientType, isRole, moqPriority, normalizeProjectSnapshot, normalizeServicesSnapshot, normalizeTimeOffsets, normalizeTopicsSnapshot, nowUs, sessionPrefix, toHex, } from "@synapse-sdk/core";
+import { moqLogScope } from "./moq_log.js";
+import { Cell, deferred, withTimeout, TIMEOUT } from "./util.js";
+// ------------------------------------------------------------------------------ moq plumbing
+/** Default datagram budget (WP §6.2): Chrome reports `maxDatagramSize` 1024; native quinn hops allow about 1150. */
+export function defaultMaxDatagram() { return isNodeLike() ? 1150 : 1024; }
+export function isNodeLike() { return typeof globalThis.process?.versions?.node === "string"; }
+/** A `stream` reader never abandons a finished group: an effectively infinite moq latency budget (`u32::MAX` ms, as the Rust client). */
+export const STREAM_READER_MAX_AGE_MS = 0xffff_ffff;
+export const streamSubscription = (priority) => ({ priority, maxAge: Moq.Time.Milli(STREAM_READER_MAX_AGE_MS) });
+/** The latest-value subscription (snapshot tracks, `desc`, `card`): newest group only. */
+export const latestSubscription = (priority, maxAgeMs = 0) => ({ priority, maxAge: Moq.Time.Milli(maxAgeMs) });
+/**
+ * The age budget of a call track's group (Rust `CALL_GROUP_MAX_AGE`, 60 s): the retention every call
+ * track we write (`req`, `out`) declares, the budget its readers (`res`, `calls`) subscribe with, and how
+ * long a reader waits for the group due while a later group is held.
+ */
+export const CALL_GROUP_MAX_AGE_MS = 60_000;
+export const callTrackInfo = (priority) => ({ priority, maxAge: Moq.Time.Milli(CALL_GROUP_MAX_AGE_MS) });
+/** A call track reader's subscription (`res`, `calls`): the call track budget. */
+export const callTrackSubscription = (priority) => ({ priority, maxAge: Moq.Time.Milli(CALL_GROUP_MAX_AGE_MS) });
+/**
+ * Retention of a one-frame track (`card`, `desc`): the frame lives as long as the track. The Rust moq
+ * keeps a track's latest group for the track's life; the JS one prunes it after its default 5 s, so a
+ * subscriber joining later would get nothing.
+ */
+export const RETAINED_FRAME_MAX_AGE_MS = 0xffff_ffff;
+/** A call track starts a new group after this many frames (moq's cap on a group). */
+export const CALL_GROUP_FRAMES = 8192;
+/** A `stream` topic subscriber's age budget (`STREAM_SUBSCRIBE_MAX_AGE`, 3 × the group span): a reader further behind skips whole groups. */
+export const streamTopicSubscription = (priority) => ({ priority, maxAge: Moq.Time.Milli(STREAM_SUBSCRIBE_MAX_AGE_MS) });
+/** moq's caps on one group. */
+const MAX_GROUP_FRAMES = 8192;
+const MAX_GROUP_BYTES = 32 * 1024 * 1024;
+/**
+ * A `stream` topic's writer (WP §6, the Rust `TrackWriter`): frames go into one MoQ group at a time, in
+ * order; the writer finishes the open group and starts the next when the open one is older than
+ * `STREAM_GROUP_SPAN_MS`, or when the next frame would pass moq's caps. A late joiner reads from the
+ * start of the group the relay holds, so it is at most one span behind.
+ */
+export class StreamWriter {
+    track;
+    #group;
+    #openedMs = 0;
+    #frames = 0;
+    #bytes = 0;
+    constructor(track) {
+        this.track = track;
+    }
+    write(header, body) {
+        const payload = frame(header, body);
+        const now = performance.now();
+        if (!this.#group || now - this.#openedMs >= STREAM_GROUP_SPAN_MS || this.#frames + 1 > MAX_GROUP_FRAMES || this.#bytes + payload.length > MAX_GROUP_BYTES) {
+            this.#group?.close();
+            this.#group = this.track.appendGroup();
+            this.#openedMs = now;
+            this.#frames = 0;
+            this.#bytes = 0;
+        }
+        this.#group.writeFrame({ timestamp: moqTimestamp(header.tUs), payload });
+        this.#frames++;
+        this.#bytes += payload.length;
+    }
+    close() { try {
+        this.#group?.close();
+    }
+    catch { /* closed */ } try {
+        this.track.close();
+    }
+    catch { /* closed */ } }
+}
+export function moqTimestamp(tUs) {
+    const n = typeof tUs === "bigint" ? Number(tUs) : tUs;
+    return Moq.Time.Timestamp.fromMicros(n > 0 ? n : 0);
+}
+/** The error for a frame refused because it is over moq's 32 MiB limit (Rust `frame_too_large`): `invalid_input`, naming the limit. */
+export function frameTooLarge(what, len) {
+    return new SynapseError("invalid_input", { message: `${what}: ${len} bytes exceeds the frame limit`, source: "sdk" });
+}
+/**
+ * A call track writer (`req`, `out`): frames into one group after another. The open group is finished
+ * and the next one started when the next frame would pass `CALL_GROUP_FRAMES` frames or moq's 32 MiB of
+ * bytes in the group. A frame over 32 MiB on its own is refused (`frameTooLarge`) before anything is written.
+ */
+export class CallWriter {
+    track;
+    #group;
+    #inGroup = 0;
+    /** Bytes in the open group (moq's own count: frame payloads). */
+    #bytes = 0;
+    constructor(track) {
+        this.track = track;
+        this.#group = track.appendGroup();
+    }
+    static create(bc, name) { return new CallWriter(bc.createTrack(name, callTrackInfo(moqPriority(0)))); }
+    write(header, body) {
+        // The frame's size (header + body), as moq counts it; `seq` is a fixed-width field, so it does not change it.
+        const size = headerLength(header) + body.length;
+        if (size > MAX_GROUP_BYTES)
+            throw frameTooLarge("frame", body.length);
+        if (this.#inGroup + 1 > CALL_GROUP_FRAMES || this.#bytes + size > MAX_GROUP_BYTES) {
+            const next = this.track.appendGroup();
+            const done = this.#group;
+            this.#group = next;
+            done.close();
+            this.#inGroup = 0;
+            this.#bytes = 0;
+        }
+        // The frame's `seq` is its index within its group (Rust `CallWriter::write`).
+        const payload = frame({ ...header, seq: this.#inGroup }, body);
+        this.#group.writeFrame({ timestamp: moqTimestamp(header.tUs), payload });
+        this.#inGroup++;
+        this.#bytes += payload.length;
+    }
+    close() { try {
+        this.#group.close();
+    }
+    catch { /* closed */ } try {
+        this.track.close();
+    }
+    catch { /* closed */ } }
+}
+/** One latest-value frame (`desc`, `card`, a snapshot): its own group, one frame, closed; the relay caches the newest. */
+export function writeLatest(track, header, body) {
+    const g = track.appendGroup();
+    g.writeFrame({ timestamp: moqTimestamp(header.tUs), payload: frame(header, body) });
+    g.close();
+}
+/** Waits for a requested broadcast to become routable. */
+export async function waitActive(req, timeoutMs, signal) {
+    const t0 = performance.now();
+    for (;;) {
+        const a = req.active.peek();
+        if (a)
+            return a;
+        if (signal?.aborted)
+            throw signal.reason instanceof Error ? signal.reason : new SynapseError("canceled", "aborted");
+        const left = timeoutMs - (performance.now() - t0);
+        if (left <= 0)
+            throw new SynapseError("connection_lost", `broadcast ${req.path} never appeared`);
+        const r = await withTimeout(Promise.race([req.active.changed(), signal ? new Promise(res => signal.addEventListener("abort", () => res(undefined), { once: true })) : new Promise(() => { })]), Math.min(left, 250));
+        if (r === TIMEOUT)
+            continue;
+    }
+}
+/**
+ * Reads a call track (`res`, `calls`, a FEC `report`) frame by frame, as the Rust `read_call_track`:
+ * groups are taken strictly in sequence from group 0, group k read to its end before group k+1. A
+ * group that arrives before its turn is held (a track's groups travel on streams of their own, so
+ * group 1 can arrive before group 0). The read ends with an error when a group older than the one due
+ * arrives, when a group's read fails (reset or expired), when the subscription fails, or when the
+ * group due has not arrived within `CALL_GROUP_MAX_AGE_MS` while a later group is held (that wait
+ * is armed only then; with nothing later held the reader waits for the next group with no timer).
+ * Returns `null` when the track ended cleanly or `signal` aborted, otherwise the error.
+ */
+export async function readTrack(sub, onFrame, signal) {
+    const abort = () => sub.close();
+    signal?.addEventListener("abort", abort, { once: true });
+    const held = new Map();
+    let next = 0;
+    // When the group due must have arrived: set while a later group is held, cleared when it comes.
+    let deadline;
+    try {
+        for (;;) {
+            let g = held.get(next);
+            if (g)
+                held.delete(next);
+            else {
+                let got;
+                if (held.size === 0)
+                    got = await sub.recvGroup();
+                else {
+                    deadline ??= performance.now() + CALL_GROUP_MAX_AGE_MS;
+                    const r = await withTimeout(sub.recvGroup(), Math.max(0, deadline - performance.now()));
+                    if (r === TIMEOUT)
+                        return new Error(`group ${next} did not arrive within the age budget while later groups did`);
+                    got = r;
+                }
+                if (!got)
+                    return null;
+                if (got.sequence > next) {
+                    held.set(got.sequence, got);
+                    continue;
+                }
+                if (got.sequence < next)
+                    return new Error(`group ${got.sequence} arrived where group ${next} was due`);
+                g = got;
+            }
+            deadline = undefined;
+            for (;;) {
+                if (signal?.aborted)
+                    return null;
+                const f = await g.readFrame();
+                if (!f)
+                    break;
+                const r = onFrame(f.payload);
+                if (r)
+                    await r;
+            }
+            next++;
+        }
+    }
+    catch (e) {
+        return e;
+    }
+    finally {
+        signal?.removeEventListener("abort", abort);
+        for (const g of held.values()) {
+            try {
+                g.close();
+            }
+            catch { /* closed */ }
+        }
+    }
+}
+/**
+ * Reads a latest-value track (a snapshot) as the Rust `watch_snapshots`: each group as it arrives,
+ * its first frame handed to `apply`. Returns `null` when `signal` aborted, otherwise why the track
+ * was lost (the subscription failed or ended).
+ */
+async function readLatest(sub, apply, signal) {
+    const abort = () => sub.close();
+    signal.addEventListener("abort", abort, { once: true });
+    try {
+        for (;;) {
+            const g = await sub.recvGroup();
+            if (signal.aborted)
+                return null;
+            if (!g)
+                return new Error("track ended");
+            let f;
+            try {
+                f = await g.readFrame();
+            }
+            catch {
+                f = undefined;
+            }
+            if (f)
+                apply(f.payload);
+        }
+    }
+    catch (e) {
+        return e;
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+    }
+}
+export async function readDatagrams(sub, onDatagram, signal) {
+    const abort = () => sub.close();
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+        for (;;) {
+            const d = await sub.recvDatagram();
+            if (!d)
+                return null;
+            const r = onDatagram(d.payload);
+            if (r)
+                await r;
+        }
+    }
+    catch (e) {
+        return e;
+    }
+    finally {
+        signal?.removeEventListener("abort", abort);
+    }
+}
+let polyfillInstalled;
+/** Installs `@moq/web-transport` in Bun/Node when the runtime has no WebTransport. Browsers skip this. */
+export function ensureWebTransport() {
+    if (typeof globalThis.WebTransport !== "undefined")
+        return Promise.resolve();
+    if (!isNodeLike())
+        return Promise.resolve();
+    polyfillInstalled ??= (async () => {
+        const spec = "@moq/web-transport";
+        try {
+            const m = (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ spec)));
+            m.install();
+        }
+        catch (e) {
+            throw new SynapseError("not_supported", { message: `WebTransport is unavailable and @moq/web-transport could not be loaded: ${e instanceof Error ? e.message : String(e)}`, cause: e });
+        }
+    })();
+    return polyfillInstalled;
+}
+/** A connect failure's text (`@moq/net` races WebTransport against WebSocket and rejects with an `AggregateError`). */
+export function describeError(e) {
+    if (e instanceof AggregateError) {
+        const parts = e.errors.map(describeError).filter(Boolean);
+        return parts.length ? parts.join("; ") : e.message || e.name;
+    }
+    return e instanceof Error ? e.message || e.name : String(e);
+}
+/** The MoQ session-close code the broker's refusal arrives as: application codes sit at 64 + code on the wire. */
+const ADMISSION_REFUSED_SESSION_CODE = 64 + ADMISSION_REFUSED_CLOSE_CODE;
+const ADMISSION_REFUSED_REASON = new RegExp(`app code=${ADMISSION_REFUSED_CLOSE_CODE}(?!\\d)`);
+/**
+ * The error of a session's close (`classify_close`): `admission_refused` travels as the application
+ * close code (retryable: a live session may hold this name, the project may be settling), another
+ * application code is a broker-side failure, `unauthorized` is the relay's own refusal, everything
+ * else is the transport (`connection_lost`); a clean close is a drop too (in one-shot mode a broker
+ * GOAWAY looks like one).
+ */
+export function closeError(err) {
+    if (!err)
+        return new SynapseError("connection_lost", { message: "session closed by the broker", source: "transport" });
+    const text = `${err.message} ${err.reason ?? ""}`;
+    if ((err instanceof Moq.Error.Session && err.code === ADMISSION_REFUSED_SESSION_CODE) || ADMISSION_REFUSED_REASON.test(text)) {
+        return new SynapseError("admission_refused", { message: "the runtime refused this connection, retryable: a live session may hold this name, the project may be settling, or the runtime is overloaded; retry with backoff", source: "broker", cause: err });
+    }
+    if (err instanceof Moq.Error.Session && err.code === Moq.SessionCode.Unauthorized)
+        return new SynapseError("unauthorized", { message: text.trim(), source: "broker", cause: err });
+    const t = text.toLowerCase();
+    if (t.includes("unauthorized"))
+        return new SynapseError("unauthorized", { message: text.trim(), source: "broker", cause: err });
+    return new SynapseError("connection_lost", { message: text.trim() || err.name, source: "transport", cause: err });
+}
+/** `https://host:port/<root>` → `http://host:port/certificate.sha256`, the broker's plain-HTTP helper. */
+export function brokerCertHelperUrl(brokerUrl) { const u = new URL(brokerUrl); return `http://${u.host}/certificate.sha256`; }
+/**
+ * The runtime's URL when the caller gave none: `SYNAPSE_ENDPOINT` (Bun/Node; the runtime sets it for every task it starts).
+ * A browser has no environment: there, as with neither, `invalid_input`.
+ */
+export function urlOrEndpoint(url) {
+    if (url !== undefined)
+        return url;
+    const env = globalThis.process?.env?.SYNAPSE_ENDPOINT?.trim();
+    if (env)
+        return env;
+    throw new SynapseError("invalid_input", { message: "no url given and SYNAPSE_ENDPOINT is not set", source: "sdk" });
+}
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+/** The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node), then the helper, then `undefined` = unpinned. Per attempt. */
+export async function discoverBrokerCertSha256(brokerUrl, opts = {}) {
+    const env = globalThis.process?.env?.SYNAPSE_BROKER_CERT_SHA256?.trim();
+    if (env)
+        return env;
+    const signal = opts.signal ? AbortSignal.any([opts.signal, AbortSignal.timeout(opts.timeoutMs ?? 2000)]) : AbortSignal.timeout(opts.timeoutMs ?? 2000);
+    try {
+        const res = await fetch(brokerCertHelperUrl(brokerUrl), { signal });
+        if (!res.ok)
+            return undefined;
+        const text = (await res.text()).trim();
+        return SHA256_HEX.test(text) ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `token_from_url`: `url` without its `jwt=` query parameters, and the last non-empty one (as the relays
+ * read it). A URL without `jwt=`, or one that does not parse, is returned as it is (the dial reports it).
+ */
+export function tokenFromUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return { url, token: undefined };
+    }
+    if (!u.searchParams.has("jwt"))
+        return { url, token: undefined };
+    const token = u.searchParams.getAll("jwt").filter(v => v !== "").at(-1);
+    u.searchParams.delete("jwt");
+    return { url: u.toString(), token };
+}
+/**
+ * `Dial::new`: the one place a user's target becomes a dial. A `jwt=` in the URL is the token (the form
+ * the relays read), moved out of the URL here so no URL kept or printed afterwards holds it; a `token`
+ * given as such wins over one in the URL.
+ */
+export function makeDial(url, identity, cert, token) {
+    const t = tokenFromUrl(url);
+    return { url: t.url, identity, cert, token: token ?? t.token };
+}
+/** `root_runtime_id`: a root names a runtime when it is exactly `runtimes/<runtime id>` (a canonical lowercase UUID). */
+export function isRuntimeRoot(root) { return /^runtimes\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(root); }
+/**
+ * `with_root`: the URL to dial for `url`. `url` itself when it names a path (a runtime's root, or a
+ * relay's `runtimes/<runtime_id>`); else `url` with the root the runtime names at its plain-HTTP helper
+ * (`http://<host>:<port>/root`, the port of `url`, 443 when it has none), asked at every attempt. A
+ * helper that cannot be reached, answers non-2xx or answers incompletely is `connection_lost` (the
+ * runtime may be coming back); an answer that is not a root (`runtimes/<runtime id>` exactly; a relay has
+ * none: it serves many runtimes) is `invalid_input`, naming the fix. `signal` abandons the ask (its reason).
+ */
+export async function withRoot(url, signal) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch (e) {
+        throw new SynapseError("invalid_input", { message: `broker url ${JSON.stringify(url)}: ${describeError(e)}`, source: "sdk" });
+    }
+    if (u.pathname !== "" && u.pathname !== "/")
+        return url;
+    const addr = `${u.hostname}:${u.port || (u.protocol === "http:" ? "80" : "443")}`;
+    const timeout = AbortSignal.timeout(2000);
+    const lost = (why) => new SynapseError("connection_lost", { message: `root helper at ${addr}: ${why}`, source: "transport" });
+    let root;
+    try {
+        const res = await fetch(`http://${addr}/root`, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
+        if (!res.ok)
+            throw lost(`answered ${res.status} ${res.statusText}`.trim());
+        root = (await res.text()).trim();
+    }
+    catch (e) {
+        if (signal?.aborted)
+            throw signal.reason;
+        if (e instanceof SynapseError)
+            throw e;
+        throw timeout.aborted ? new SynapseError("connection_lost", { message: `root helper at ${addr} did not answer`, source: "transport" }) : lost(describeError(e));
+    }
+    if (!isRuntimeRoot(root)) {
+        throw new SynapseError("invalid_input", { message: `${url} names no runtime (its /root helper returned ${JSON.stringify(root.slice(0, 80))}); give the full path, e.g. https://relay:4443/runtimes/<runtime_id>`, source: "sdk" });
+    }
+    u.pathname = `/${root}`;
+    return u.toString();
+}
+/** The key of a call in the session's pending map. */
+export const callKey = (id) => toHex(id);
+export class Session {
+    url;
+    conn;
+    pub;
+    sub;
+    hello;
+    maxDatagram;
+    log;
+    /** Counts *established* sessions of the node (SDK §2); set by the node when attached. */
+    epoch = 0;
+    startedMs = performance.now();
+    transport;
+    /** Datagrams travel only over WebTransport; the WebSocket fallback is stream-only. */
+    datagrams;
+    #role;
+    #admitting = true;
+    #req;
+    #calls = new Map();
+    #closing;
+    /** The views this session reads (latest values). */
+    topics = new Cell({ topics: {} });
+    services = new Cell({ services: {} });
+    timeOffsets = new Cell({});
+    project = new Cell(undefined);
+    clock;
+    /** Where notices go: the node's loop sets this at attach. */
+    onNotice;
+    #tasks = new AbortController();
+    #taskDone = [];
+    /** Settles with the close's error once the connection closed. */
+    closed;
+    constructor(url, conn, pub, sub, hello, maxDatagram, log, connect, reqBc, res, resSub, dom) {
+        this.url = url;
+        this.conn = conn;
+        this.pub = pub;
+        this.sub = sub;
+        this.hello = hello;
+        this.maxDatagram = maxDatagram;
+        this.log = log;
+        this.#connect = connect;
+        this.#reqBc = reqBc;
+        this.#role = hello.role;
+        this.transport = conn.transport;
+        this.datagrams = conn.transport === "webtransport";
+        this.#req = CallWriter.create(reqBc, "req");
+        this.clock = new Cell(new ClockSync(dom, hello.dom, 0).info());
+        this.closed = conn.closed.then(err => { log.release(); return err; });
+        this.#resSub = resSub;
+        this.#res = res;
+    }
+    /** Our connect request `client/<name>/<sid>/connect` and its track: the session lasts as long as it is announced (PLAN v0.26 §3.1); a clean close withdraws it first. */
+    #connect;
+    #reqBc;
+    #resSub;
+    #res;
+    get prefix() { return this.hello.prefix; }
+    get role() { return this.#role; }
+    nowUs() { return nowUs(); }
+    /** Whether the session still takes requests (not torn down). */
+    get isLive() { return this.#admitting; }
+    /** The broker's reason, when it closed this session with a closing notice (or a watcher lost its track). */
+    get closingReason() { return this.#closing; }
+    /** Appends a frame to our `req` track (WP §8.6). `connection_lost` once the session has ended. */
+    writeReq(header, body) {
+        if (!this.#admitting)
+            throw new SynapseError("connection_lost", { message: "the session has ended", source: "sdk" });
+        try {
+            this.#req.write(header, body);
+        }
+        catch (e) {
+            throw reqWriteError(e, "req frame", body.length);
+        }
+    }
+    /** Writes call `id`'s request and registers where its frames go, both while the session takes requests. */
+    /** `deliver(null)` = the session ended with the call pending. */
+    writeCall(header, body, id, deliver) {
+        if (!this.#admitting)
+            throw new SynapseError("connection_lost", { message: "the session has ended", source: "sdk" });
+        const k = callKey(id);
+        this.#calls.set(k, deliver);
+        try {
+            this.#req.write(header, body);
+        }
+        catch (e) {
+            this.#calls.delete(k);
+            throw reqWriteError(e, "call request", body.length);
+        }
+    }
+    forgetCall(id) { this.#calls.delete(callKey(id)); }
+    /** A frame for call `id`; its terminal frame forgets the call. */
+    #deliver(id, f) {
+        const k = callKey(id);
+        const d = this.#calls.get(k);
+        if (f.header.flags & FLAGS.END)
+            this.#calls.delete(k);
+        d?.(f);
+    }
+    /** Stops taking requests and fails every call pending here (`deliver(null)`: `connection_lost`). The first step of a teardown; idempotent. */
+    endCalls() {
+        this.#admitting = false;
+        const calls = [...this.#calls.values()];
+        this.#calls.clear();
+        for (const d of calls)
+            d(null);
+    }
+    /** A task of this session lost what it reads, or the broker announced the close: record `reason` (the first stands) and close the connection. The loop does the rest. */
+    lost(reason) {
+        this.#closing ??= reason;
+        try {
+            this.conn.close();
+        }
+        catch { /* closed */ }
+    }
+    /** Starts the session's tasks: the `res` demux, the four snapshot watchers, the clock probe (unless the broker shares our domain). Each writes only into this session. */
+    start(sync, startCall) {
+        const signal = this.#tasks.signal;
+        this.#taskDone.push(this.#readRes(signal));
+        this.#taskDone.push(this.#watch("runtime/topics", "catalog", signal, b => this.topics.set(normalizeTopicsSnapshot(decodeBody(b)))));
+        this.#taskDone.push(this.#watch("runtime/services", "catalog", signal, b => this.services.set(normalizeServicesSnapshot(decodeBody(b)))));
+        this.#taskDone.push(this.#watch("runtime/time", "offsets", signal, b => this.timeOffsets.set(normalizeTimeOffsets(decodeBody(b)))));
+        this.#taskDone.push(this.#watch("runtime/project", "state", signal, b => this.project.set(normalizeProjectSnapshot(decodeBody(b)))));
+        if (!sync.sameDom)
+            this.#taskDone.push(this.#clockTask(sync, startCall, signal));
+    }
+    /** The `res` track (WP §8.6): a call's frame to its call; a notice to the loop; a closing notice closes the session; a broken track closes it too. */
+    async #readRes(signal) {
+        const onFrame = (payload) => {
+            let header, hlen;
+            try {
+                ({ header, hlen } = decodeHeader(payload));
+            }
+            catch {
+                return;
+            }
+            const body = payload.subarray(hlen);
+            let decoded;
+            try {
+                decoded = decodeBody(body);
+            }
+            catch {
+                return;
+            }
+            const call = decoded?.call;
+            if (call instanceof Uint8Array && call.length === 16) {
+                this.#deliver(call, { header, body });
+                return;
+            }
+            if (header.flags & FLAGS.ERR) {
+                const b = decoded;
+                if (b && typeof b.code === "string")
+                    this.onNotice?.({ kind: "error", body: b });
+                return;
+            }
+            const n = decoded;
+            if (!n || typeof n !== "object" || !("notice" in n))
+                return;
+            if (n.notice === "closing") {
+                this.lost(typeof n.reason === "string" ? n.reason : "closing");
+                return;
+            }
+            if ((n.notice === "promoted" || n.notice === "demoted") && isRole(n.role)) {
+                this.#role = n.role;
+                this.onNotice?.({ kind: "project", notice: { kind: n.notice, role: n.role, project: typeof n.project === "string" ? n.project : null } });
+            }
+        };
+        const err = await readTrack(this.#resSub, onFrame, signal);
+        if (signal.aborted || !this.#admitting)
+            return;
+        this.lost(`res track: ${err instanceof Error ? err.message : "ended"}`);
+    }
+    /** One snapshot watcher: follows `path`/`track` for the life of the session; a lost track closes the session (a view that froze would lie). */
+    async #watch(path, track, signal, apply) {
+        let why;
+        try {
+            const req = this.sub.request(Moq.Path.from(path));
+            const bc = await waitActive(req, 10_000, signal);
+            const sub = bc.track(track).subscribe(latestSubscription(moqPriority(1)));
+            const err = await readLatest(sub, payload => { try {
+                const { hlen } = decodeHeader(payload);
+                apply(payload.subarray(hlen));
+            }
+            catch { /* undecodable snapshot dropped */ } }, signal);
+            why = err instanceof Error ? err.message : "track ended";
+        }
+        catch (e) {
+            why = e instanceof Error ? e.message : String(e);
+        }
+        if (signal.aborted || !this.#admitting)
+            return;
+        this.lost(`${path} ${track} watcher: ${why}`);
+    }
+    /** The clock probe (WP §8.7): `synapse/time` calls on this session feeding the estimate, for the session's life. */
+    async #clockTask(sync, startCall, signal) {
+        while (!signal.aborted) {
+            const at = sync.nextProbeAt();
+            if (at === undefined)
+                return;
+            const wait = at - nowUs();
+            if (wait > 0) {
+                await new Promise(r => { const t = setTimeout(r, wait / 1000); signal.addEventListener("abort", () => { clearTimeout(t); r(); }, { once: true }); });
+                if (signal.aborted)
+                    return;
+            }
+            const req = sync.request(nowUs());
+            let resp;
+            try {
+                resp = (await withTimeout(startCall("synapse/time", req), 2000));
+                if (resp === TIMEOUT) {
+                    sync.probeLost();
+                    continue;
+                }
+            }
+            catch (e) {
+                sync.probeLost();
+                if (e instanceof SynapseError && (e.code === "not_connected" || e.code === "connection_lost"))
+                    return;
+                continue;
+            }
+            sync.response(resp, nowUs());
+            this.clock.set(sync.info());
+        }
+    }
+    /** Stops and awaits the tasks (bounded), then closes the session: track finished, MoQ close sent. */
+    async teardown(graceMs = 1000) {
+        this.endCalls();
+        this.#tasks.abort();
+        await withTimeout(Promise.allSettled(this.#taskDone), graceMs);
+        this.close();
+        await withTimeout(this.closed, graceMs);
+    }
+    /** The synchronous end: withdraw our connect request (the runtime ends the session), fail its calls, finish our track, close the connection. Idempotent. */
+    close() {
+        withdraw(this.#connect);
+        this.#admitting = false;
+        this.#tasks.abort();
+        this.log.closing();
+        try {
+            this.#req.close();
+        }
+        catch { /* closed */ }
+        try {
+            this.#reqBc.close();
+        }
+        catch { /* closed */ }
+        try {
+            this.#resSub.close();
+        }
+        catch { /* closed */ }
+        try {
+            this.#res.close();
+        }
+        catch { /* closed */ }
+        try {
+            this.conn.close();
+        }
+        catch { /* closed */ }
+        try {
+            this.pub.close();
+        }
+        catch { /* closed */ }
+        try {
+            this.sub.close();
+        }
+        catch { /* closed */ }
+    }
+    createBroadcast(path) { this.log.announced(path); return this.pub.createBroadcast(Moq.Path.from(path)); }
+    request(path) { this.log.requested(path); return this.sub.request(Moq.Path.from(path)); }
+}
+function certOption(hash) {
+    return hash ? { serverCertificateHashes: [{ algorithm: "sha-256", value: hash.trim() }] } : undefined;
+}
+/** What a connect attempt that got no answer reports (PLAN v0.26 §4 step 1): the request may have gone nowhere. */
+export const NO_ANSWER = "no runtime answered under this root (a relay drops out-of-scope publishes silently: check the token)";
+/** A session id for one connect attempt (PLAN v0.26 §5.1): 8 lowercase hex characters, 32 random bits. */
+export function mintSid() { return toHex(crypto.getRandomValues(new Uint8Array(SID_LEN / 2))); }
+/** Withdraws a connect request: the track finished, the broadcast un-announced and closed. Idempotent. */
+function withdraw(c) {
+    try {
+        c.track.close();
+    }
+    catch { /* closed */ }
+    try {
+        c.bc.close();
+    }
+    catch { /* closed */ }
+}
+/**
+ * Asks the runtime for a session over an established connection (PLAN v0.26 §3.1): mint a `sid` for
+ * this attempt, write our connect request (`RPC_CALL`, `END`) on track `hello` of
+ * `client/<name>/<sid>/connect` and announce it on `pub`, then wait on `sub` for the answer on
+ * `client/<name>/<sid>/hello`: the hello (our prefix and role), or an error frame (`END|ERR`, the
+ * runtime's refusal, which is the attempt's error as it is: `admission_refused` when a live session
+ * holds the name, `invalid_input`, ...). Then our `res` track at the path the hello grants (`hello.res`,
+ * `runtime/rpc/@<epoch>`, PLAN v0.26 §7.2). No answer within
+ * `timeoutMs` is `not_connected` (`NO_ANSWER`). On any failure the request is withdrawn. `signal`
+ * abandons the wait (its reason is the error).
+ */
+export async function requestSession(pub, sub, request, timeoutMs, log, signal) {
+    const { name } = request;
+    const sid = mintSid();
+    // Our connect request, written before it is announced (the runtime reads it once it sees it).
+    const path = connectPath(name, sid);
+    const bc = pub.createBroadcast(Moq.Path.from(path));
+    const connect = { bc, track: CallWriter.create(bc, "hello") };
+    connect.track.write({ flags: FLAGS.END, type: TYPES.RPC_CALL, seq: 0, tUs: nowUs() }, encodeConnectRequest(request));
+    bc.announce();
+    log.announced(path);
+    const noAnswer = () => new SynapseError("not_connected", { message: NO_ANSWER, source: "sdk" });
+    const stopped = (e) => { throw signal.aborted ? signal.reason : e; };
+    const opened = [];
+    try {
+        const hp = helloPath(name, sid);
+        log.requested(hp);
+        // Routed only: wait for the runtime to announce its answer (a blind subscription before it exists is reset as unroutable).
+        const helloReq = sub.request(Moq.Path.from(hp), { announced: true });
+        opened.push(helloReq);
+        const helloBc = await waitActive(helloReq, timeoutMs, signal).catch(() => stopped(noAnswer()));
+        const helloSub = helloBc.track("hello").subscribe(latestSubscription(moqPriority(0)));
+        opened.push(helloSub);
+        const read = async () => {
+            const g = await helloSub.recvGroup();
+            if (!g)
+                throw new SynapseError("connection_lost", "hello track ended");
+            const f = await g.readFrame();
+            if (!f)
+                throw new SynapseError("connection_lost", "empty hello");
+            return f.payload;
+        };
+        const abort = new Promise((_, reject) => { if (signal.aborted)
+            reject(signal.reason); signal.addEventListener("abort", () => reject(signal.reason), { once: true }); });
+        abort.catch(() => { });
+        const reading = read();
+        reading.catch(() => { });
+        const payload = await Promise.race([withTimeout(reading, timeoutMs), abort]).catch(e => stopped(e instanceof SynapseError ? e : new SynapseError("connection_lost", { message: `hello: ${describeError(e)}`, source: "transport", cause: e })));
+        if (payload === TIMEOUT)
+            throw noAnswer();
+        const hello = readAnswer(payload, name, sid);
+        // Our `res` track, at the path the hello grants (the runtime publishes it before it writes the hello).
+        const rp = hello.res;
+        log.requested(rp);
+        const resReq = sub.request(Moq.Path.from(rp), { announced: true });
+        opened.push(resReq);
+        const res = await waitActive(resReq, timeoutMs, signal).catch(() => stopped(new SynapseError("connection_lost", { message: "broker never announced our response track", source: "transport" })));
+        const resSub = res.track("res").subscribe(callTrackSubscription(moqPriority(0)));
+        helloSub.close();
+        helloReq.close();
+        return { connect, hello, res, resSub };
+    }
+    catch (e) {
+        for (const o of opened) {
+            try {
+                o.close();
+            }
+            catch { /* closed */ }
+        }
+        withdraw(connect);
+        throw e;
+    }
+}
+/** The runtime's answer frame: the hello for `client/<name>/<sid>`, or its refusal as the error. */
+function readAnswer(payload, name, sid) {
+    let header, hlen, body;
+    try {
+        ({ header, hlen } = decodeHeader(payload));
+        body = decodeBody(payload.subarray(hlen));
+    }
+    catch (e) {
+        throw new SynapseError("invalid_input", { message: `the runtime's answer is not one this SDK understands (${describeError(e)})`, source: "sdk" });
+    }
+    if (header.type !== TYPES.RPC_RESP)
+        throw new SynapseError("invalid_input", { message: "hello frame is not a hello", source: "sdk" });
+    // The runtime's refusal: its error body is the attempt's error.
+    if (header.flags & FLAGS.ERR) {
+        const b = body;
+        if (!b || typeof b !== "object" || typeof b.code !== "string")
+            throw new SynapseError("invalid_input", { message: "the runtime's refusal is not one this SDK understands", source: "sdk" });
+        throw SynapseError.fromBody(b, { source: "broker" });
+    }
+    const h = body;
+    // A hello this SDK cannot read is a runtime/SDK version mismatch: said once, not retried.
+    if (!h || typeof h !== "object" || h.hello !== true || typeof h.name !== "string" || typeof h.prefix !== "string" || typeof h.rpc !== "string" || typeof h.res !== "string" || !isRole(h.role) || !isClientType(h.type) || typeof h.dom !== "string" || typeof h.broker_version !== "string") {
+        throw new SynapseError("invalid_input", { message: "the runtime's hello is not one this SDK understands; runtime and SDK versions differ", source: "sdk" });
+    }
+    const hello = { ...h, robot: typeof h.robot === "string" ? h.robot : "", runtime_name: typeof h.runtime_name === "string" ? h.runtime_name : "", runtime_id: typeof h.runtime_id === "string" ? h.runtime_id : "" };
+    if (hello.prefix !== sessionPrefix(name, sid))
+        throw new SynapseError("invalid_input", { message: `hello prefix ${JSON.stringify(hello.prefix)} is not client/${name}/${sid}`, source: "sdk" });
+    // The request path the hello grants is under our prefix: `<prefix>/rpc/@<epoch>` (PLAN v0.26 §7.1).
+    const granted = `${hello.prefix}/rpc/@`;
+    if (!hello.rpc.startsWith(granted) || hello.rpc.length === granted.length)
+        throw new SynapseError("invalid_input", { message: `hello rpc ${JSON.stringify(hello.rpc)} is not under ${hello.prefix}/rpc/`, source: "sdk" });
+    // The reply path it grants is under `runtime/rpc/` (`runtime/rpc/@<epoch>`, PLAN v0.26 §7.2).
+    if (!hello.res.startsWith("runtime/rpc/") || hello.res.length === "runtime/rpc/".length)
+        throw new SynapseError("invalid_input", { message: `hello res ${JSON.stringify(hello.res)} is not under runtime/rpc/`, source: "sdk" });
+    return hello;
+}
+/** How long a failed pre-hello step waits for the session's close to be observed (Rust `CLOSE_GRACE`). */
+const CLOSE_GRACE_MS = 1000;
+/**
+ * Opens one session to `dial` (PLAN v0.26 §3.1): the path to dial is the URL's own or, for a bare
+ * `https://host:port`, the root the runtime names (`withRoot`, asked at every attempt); dial with our name
+ * (the relay level's scope) and the token (`jwt=`, through a relay) as the only query parameters; ask the runtime for a session (`requestSession`: our identity and project
+ * intent go in the connect request), then announce our `req` track on the path the hello grants (`hello.rpc`).
+ * A relay's refusal of the connection shows up as the session closing: an observed close wins, and a
+ * transport failure of a step is settled against the close (`CLOSE_GRACE_MS`). `signal` abandons the
+ * dial: every wait stops at once and the half-open connection is closed (`canceled`); the connection
+ * not established within the connect timeout is `connection_lost`.
+ */
+export async function openSession(knobs, dial, dom, signal) {
+    const { identity } = dial;
+    const name = identity.name;
+    if (!name)
+        throw new SynapseError("internal", "identity without a name");
+    if (knobs.transport !== "websocket")
+        await ensureWebTransport();
+    const abandoned = () => new SynapseError("canceled", { message: "the dial was abandoned", source: "sdk" });
+    if (signal?.aborted)
+        throw abandoned();
+    // The path to dial: the URL's own, or (none given) the runtime's root, asked of it now (a runtime started again elsewhere on this address may be another runtime).
+    const base = await withRoot(dial.url, signal).catch((e) => { throw signal?.aborted ? abandoned() : e; });
+    const pub = new Moq.Origin.Producer();
+    const sub = new Moq.Origin.Producer();
+    // Only the name and the token travel in the URL: the relay level's scope (`client/<name>/**`) and, through a relay, the token that
+    // grants it (`jwt=`, PLAN v0.26 §3.5). Who we are goes to the runtime in the connect request.
+    const url = new URL(base);
+    url.searchParams.append("name", name);
+    if (dial.token !== undefined)
+        url.searchParams.append("jwt", dial.token);
+    // One controller for the dial: the connect timeout (until the connection is established) and the caller's `signal`.
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(new SynapseError("connection_lost", "connect timed out")), knobs.connectTimeoutMs);
+    const onAbandon = () => ac.abort(abandoned());
+    signal?.addEventListener("abort", onAbandon, { once: true });
+    const log = moqLogScope();
+    const abandon = () => { signal?.removeEventListener("abort", onAbandon); log.closing(); log.release(); };
+    let conn;
+    try {
+        const props = { url, publish: pub.consume(), consume: sub, signal: ac.signal };
+        const wt = certOption(dial.cert);
+        if (wt)
+            props.webtransport = wt;
+        if (knobs.transport === "webtransport")
+            props.websocket = { enabled: false };
+        else if (knobs.transport === "websocket")
+            props.websocket = { enabled: true, delay: Moq.Time.Milli(0) };
+        conn = await Moq.Connection.connect(props);
+    }
+    catch (e) {
+        clearTimeout(timer);
+        pub.close();
+        sub.close();
+        abandon();
+        // Stopped (timeout or `signal`): that reason, whatever error the connect rejected with.
+        if (ac.signal.aborted && ac.signal.reason instanceof SynapseError)
+            throw ac.signal.reason;
+        if (e instanceof SynapseError)
+            throw e;
+        throw closeError(e instanceof Error ? e : new Error(describeError(e)));
+    }
+    clearTimeout(timer);
+    const request = { type: identity.type, name, user_id: identity.user_id, credential: identity.credential, project: knobs.project, dom };
+    // The handshake's own controller: the caller's `signal`, or the close winning the race below.
+    const hs = new AbortController();
+    const onStop = () => hs.abort(ac.signal.reason);
+    if (ac.signal.aborted)
+        onStop();
+    else
+        ac.signal.addEventListener("abort", onStop, { once: true });
+    // A close is the single source of truth for why a pre-hello session ended: an observed close wins the race.
+    let closed = false;
+    const closedEarly = conn.closed.then((err) => { closed = true; throw closeError(err); });
+    closedEarly.catch(() => { });
+    let answered;
+    try {
+        answered = await Promise.race([closedEarly, requestSession(pub, sub, request, knobs.connectTimeoutMs, log, hs.signal)]);
+    }
+    catch (e) {
+        hs.abort(e);
+        let err = e instanceof SynapseError ? e : closeError(e instanceof Error ? e : new Error(describeError(e)));
+        // A step that tripped over a closing connection before its close was observed: the close decides.
+        if (!closed && err.code === "connection_lost")
+            err = await settlePreHello(err, conn.closed);
+        ac.signal.removeEventListener("abort", onStop);
+        abandon();
+        try {
+            conn.close();
+        }
+        catch { /* ignore */ }
+        pub.close();
+        sub.close();
+        throw err;
+    }
+    ac.signal.removeEventListener("abort", onStop);
+    signal?.removeEventListener("abort", onAbandon);
+    // Our request track (WP §8.2), on the path the hello grants (`<prefix>/rpc/@<epoch>`, PLAN v0.26 §7.1): the broadcast and its
+    // `req` track created (in the `Session`), then announced, so the runtime finds `req` as soon as it sees the broadcast.
+    const { hello, connect, res, resSub } = answered;
+    const reqBc = pub.createBroadcast(Moq.Path.from(hello.rpc));
+    log.announced(hello.rpc);
+    const session = new Session(base, conn, pub, sub, hello, knobs.maxDatagram, log, connect, reqBc, res, resSub, dom);
+    reqBc.announce();
+    return session;
+}
+/** `settle_pre_hello`: a pre-hello step failed with `err`; if the session closes within the grace that close is the error (a plain transport loss keeps `err`'s text alongside), otherwise `err`. */
+async function settlePreHello(err, closed) {
+    const c = await withTimeout(closed, CLOSE_GRACE_MS);
+    if (c === TIMEOUT)
+        return err;
+    const e = closeError(c);
+    return e.code === "connection_lost" ? new SynapseError("connection_lost", { message: `${e.message} (${err.message})`, source: e.source, cause: e.cause }) : e;
+}
+/** The error a call pending on a session that ended reports (WP §8.4: the request was written, so it may have run). */
+/** `data` is `{ outcome: "unknown" }`, with `reason` when the session's close had one (Rust `outcome_unknown_data`). */
+export function outcomeUnknown(closing) {
+    const data = { outcome: "unknown" };
+    if (closing !== undefined)
+        data.reason = closing;
+    return new SynapseError("connection_lost", { message: closing ? `${closing}: the session ended with the call pending; its outcome is unknown` : "the session ended with the call pending; its outcome is unknown", source: "transport", data });
+}
+/** A failed write on our `req` track (Rust `write_req`): an oversized frame is `invalid_input` naming `what`; anything else `connection_lost`. */
+function reqWriteError(e, what, len) {
+    if (e instanceof SynapseError && e.code === "invalid_input")
+        return frameTooLarge(what, len);
+    return new SynapseError("connection_lost", { message: describeError(e), source: "transport", cause: e });
+}
+export { deferred };