@synapse-sdk/client 0.1.0 → 0.3.0

package/dist/session.js

@@ -0,0 +1,745 @@
+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, identityQuery, isClientType, isRole, moqPriority, normalizeProjectSnapshot, normalizeServicesSnapshot, normalizeTimeOffsets, normalizeTopicsSnapshot, nowUs, parseSessionPath, rpcPath, 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`; }
+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;
+    }
+}
+/** 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, 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.#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;
+    }
+    #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: fail its calls, finish our track, close the connection. Idempotent. */
+    close() {
+        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;
+}
+/**
+ * Opens one session to `dial`: connect with our identity as query parameters (WP §3.1), wait for
+ * the hello on `client/<name>/hello` (readiness + grant proof + our prefix), find our `res` track at
+ * `runtime/rpc/<sid>`, announce our `req` track under the prefix. A refused admission shows up as
+ * the session closing before the hello: the close decides the error. `signal` abandons the dial: every
+ * wait stops at once and the half-open connection is closed (`canceled`), as the connect timeout does
+ * (`connection_lost`).
+ */
+export async function openSession(knobs, dial, dom, signal) {
+    const name = dial.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();
+    const pub = new Moq.Origin.Producer();
+    const sub = new Moq.Origin.Producer();
+    const sep = dial.url.includes("?") ? "&" : "?";
+    const url = new URL(`${dial.url}${sep}${identityQuery(dial.identity)}${knobs.project ? `&project=${knobs.project}` : ""}`);
+    // One controller for both ends of a dial: the connect timeout 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 });
+    // Settles (rejects) with the reason once the dial is stopped.
+    const stopped = new Promise((_, reject) => ac.signal.addEventListener("abort", () => reject(ac.signal.reason), { once: true }));
+    stopped.catch(() => { });
+    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)));
+    }
+    try {
+        // The close is the single source of truth for why a pre-hello session ended, unless the dial was stopped first.
+        const closedEarly = Promise.race([conn.closed.then(err => { throw closeError(err); }), stopped]);
+        closedEarly.catch(() => { });
+        const helloReq = sub.request(Moq.Path.from(helloPath(name)));
+        log.requested(helloPath(name));
+        const helloBc = await Promise.race([waitActive(helloReq, knobs.connectTimeoutMs, ac.signal), closedEarly]);
+        const helloSub = helloBc.track("hello").subscribe(latestSubscription(moqPriority(0)));
+        const g = await Promise.race([withTimeout(helloSub.recvGroup(), knobs.connectTimeoutMs), closedEarly]);
+        if (g === TIMEOUT || !g)
+            throw new SynapseError("connection_lost", "no hello from the broker");
+        const first = await Promise.race([withTimeout(g.readFrame(), knobs.connectTimeoutMs), closedEarly]);
+        if (first === TIMEOUT || !first)
+            throw new SynapseError("connection_lost", "empty hello");
+        helloSub.close();
+        helloReq.close();
+        const { header, hlen } = decodeHeader(first.payload);
+        if (header.type !== TYPES.RPC_RESP || header.flags & FLAGS.ERR)
+            throw new SynapseError("invalid_input", "hello frame is not a hello");
+        const hello = decodeBody(first.payload.subarray(hlen));
+        if (!hello || hello.hello !== true || typeof hello.prefix !== "string" || !isRole(hello.role) || !isClientType(hello.type) || typeof hello.dom !== "string")
+            throw new SynapseError("invalid_input", "malformed hello");
+        const sp = parseSessionPath(rpcPath(hello.prefix));
+        if (!sp || sp.name !== name)
+            throw new SynapseError("invalid_input", `hello prefix ${hello.prefix} is not client/${name}/<sid>`);
+        // The broker's response track for this session.
+        const resPath = `runtime/rpc/${sp.sid}`;
+        log.requested(resPath);
+        const resReq = sub.request(Moq.Path.from(resPath));
+        const res = await Promise.race([waitActive(resReq, knobs.connectTimeoutMs, ac.signal), closedEarly]);
+        const resSub = res.track("res").subscribe(callTrackSubscription(moqPriority(0)));
+        // Our request track (WP §8.2), under the prefix the hello names: the only place we may publish.
+        const reqBc = pub.createBroadcast(Moq.Path.from(rpcPath(hello.prefix)));
+        log.announced(rpcPath(hello.prefix));
+        const session = new Session(dial.url, conn, pub, sub, hello, knobs.maxDatagram, log, reqBc, res, resSub, dom);
+        reqBc.announce();
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbandon);
+        return session;
+    }
+    catch (e) {
+        clearTimeout(timer);
+        abandon();
+        try {
+            conn.close();
+        }
+        catch { /* ignore */ }
+        pub.close();
+        sub.close();
+        throw e instanceof SynapseError ? e : closeError(e instanceof Error ? e : new Error(describeError(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 };