@synapse-sdk/client 0.3.0 → 0.3.4

package/dist/scene_frames.d.ts

@@ -1,7 +1,7 @@
 import type { SceneEntity, SceneTxn, Xform } from "./types.ts";
 /** The ops the materializers queue. */
 type FrameTxn = Pick<SceneTxn, "spawn" | "patch" | "rename" | "despawn">;
-/** The entities to reconcile against: `scene.entities` (id → entity) or a list of entities. */
+/** The entities to reconcile against: `scene.get()` (id → entity) or a list of entities. */
 type Entities = Iterable<SceneEntity> | Readonly<Record<string, SceneEntity>>;
 /** The presentation name of a materialized derived frame: `<parent name>_<frame>` (e.g. `ur5e_tool0`). */
 export declare function derivedFrameName(parentName: string, frame: string): string;
@@ -28,7 +28,7 @@ export interface MaterializeReport {
 /**
  * Reconciles `robot`'s `robot.frames` with its derived frames (those with `props.from` equal to
  * `provenance`, default `"urdf"`; a frame without `from` counts as `"urdf"`), queueing the ops on
- * `txn`. `entities` is the scene now (`scene.entities`). `restPoses` maps declared names to poses
+ * `txn`. `entities` is the scene now (`scene.get()`). `restPoses` maps declared names to poses
  * (FK at the authored joints, the caller's work); a name with no frame yet and no pose is an error,
  * never a spawn, so a call with no poses only renames, backfills `from` and retracts.
  *

package/dist/scene_frames.js

@@ -29,7 +29,7 @@ export function validateDerivedFrame(frame, parentId) {
 /**
  * Reconciles `robot`'s `robot.frames` with its derived frames (those with `props.from` equal to
  * `provenance`, default `"urdf"`; a frame without `from` counts as `"urdf"`), queueing the ops on
- * `txn`. `entities` is the scene now (`scene.entities`). `restPoses` maps declared names to poses
+ * `txn`. `entities` is the scene now (`scene.get()`). `restPoses` maps declared names to poses
  * (FK at the authored joints, the caller's work); a name with no frame yet and no pose is an error,
  * never a spawn, so a call with no poses only renames, backfills `from` and retracts.
  *

package/dist/session.d.ts

@@ -1,5 +1,5 @@
 import * as Moq from "@moq/net";
-import { ClockSync, SynapseError, type CallId, type ClockInfo, type ErrorBody, type Header, type Hello, type Identity, type ProjectSnapshot, type Role, type ServicesSnapshot, type TimeOffsets, type TopicsSnapshot } from "@synapse-sdk/core";
+import { ClockSync, SynapseError, type CallId, type ClockInfo, type ConnectRequest, type ErrorBody, type Header, type Hello, type Identity, type ProjectSnapshot, type Role, type ServicesSnapshot, type TimeOffsets, type TopicsSnapshot } from "@synapse-sdk/core";
 import { type MoqLogScope } from "./moq_log.ts";
 import { Cell, deferred } from "./util.ts";
 import type { Notice } from "./types.ts";
@@ -83,7 +83,7 @@ export declare function ensureWebTransport(): Promise<void>;
 export declare function describeError(e: unknown): string;
 /**
  * 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
+ * close code (retryable: a live session holds this name; a crashed one is released after the idle timeout), 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).
@@ -91,20 +91,51 @@ export declare function describeError(e: unknown): string;
 export declare function closeError(err: Error | null): SynapseError;
 /** `https://host:port/<root>` → `http://host:port/certificate.sha256`, the broker's plain-HTTP helper. */
 export declare function brokerCertHelperUrl(brokerUrl: string): string;
+/**
+ * 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 declare function urlOrEndpoint(url: string | undefined): string;
 /** 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 declare function discoverBrokerCertSha256(brokerUrl: string, opts?: {
     timeoutMs?: number;
     signal?: AbortSignal;
 }): Promise<string | 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 declare function tokenFromUrl(url: string): {
+    url: string;
+    token: string | undefined;
+};
+/**
+ * `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 declare function makeDial(url: string, identity: Identity, cert: string | undefined, token: string | undefined): Dial;
+/** `root_runtime_id`: a root names a runtime when it is exactly `runtimes/<runtime id>` (a canonical lowercase UUID). */
+export declare function isRuntimeRoot(root: string): boolean;
+/**
+ * `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 declare function withRoot(url: string, signal?: AbortSignal): Promise<string>;
 export interface RespFrame {
     header: Header;
     body: Uint8Array;
 }
-/** What one attempt dials (`Dial`). */
+/** What one attempt dials (`Dial`): built by `makeDial` only, so `url` never holds the token. */
 export interface Dial {
     url: string;
     identity: Identity;
     cert: string | undefined;
+    token: string | undefined;
 }
 export interface SessionKnobs {
     transport: "auto" | "webtransport" | "websocket";
@@ -133,6 +164,8 @@ export declare class Session {
     readonly log: MoqLogScope;
     /** Counts *established* sessions of the node (SDK §2); set by the node when attached. */
     epoch: number;
+    /** The target generation this session was opened for (`Target.generation`); set by the node's loop when attached. */
+    generation: number;
     readonly startedMs: number;
     readonly transport: "webtransport" | "websocket";
     /** Datagrams travel only over WebTransport; the WebSocket fallback is stream-only. */
@@ -147,7 +180,7 @@ export declare class Session {
     onNotice: ((n: BrokerNotice) => void) | undefined;
     /** Settles with the close's error once the connection closed. */
     readonly closed: Promise<Error | null>;
-    constructor(url: string, conn: Moq.Connection.Established, pub: Moq.Origin.Producer, sub: Moq.Origin.Producer, hello: Hello, maxDatagram: number, log: MoqLogScope, reqBc: Moq.Broadcast.Producer, res: Moq.Broadcast.Consumer, resSub: Moq.Track.Subscriber, dom: string);
+    constructor(url: string, conn: Moq.Connection.Established, pub: Moq.Origin.Producer, sub: Moq.Origin.Producer, hello: Hello, maxDatagram: number, log: MoqLogScope, connect: ConnectTrack, reqBc: Moq.Broadcast.Producer, res: Moq.Broadcast.Consumer, resSub: Moq.Track.Subscriber, dom: string);
     get prefix(): string;
     get role(): Role;
     nowUs(): number;
@@ -169,18 +202,48 @@ export declare class Session {
     start(sync: ClockSync, startCall: (svc: string, args: unknown) => Promise<unknown>): void;
     /** Stops and awaits the tasks (bounded), then closes the session: track finished, MoQ close sent. */
     teardown(graceMs?: number): Promise<void>;
-    /** The synchronous end: fail its calls, finish our track, close the connection. Idempotent. */
+    /** The synchronous end: withdraw our connect request (the runtime ends the session), fail its calls, finish our track, close the connection. Idempotent. */
     close(): void;
     createBroadcast(path: string): Moq.Broadcast.Producer;
     request(path: string): Moq.Origin.Requesting;
 }
+/** What a connect attempt that got no answer reports (PLAN v0.26 §4 step 1): the request may have gone nowhere. */
+export declare 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 declare function mintSid(): string;
+/** Our connect request broadcast `client/<name>/<sid>/connect` and its `hello` track: the session lasts as long as it is announced. */
+export interface ConnectTrack {
+    bc: Moq.Broadcast.Producer;
+    track: CallWriter;
+}
+/** What the runtime answered a connect request with: the hello, and our `res` track at the path it grants (`hello.res`). */
+export interface Answered {
+    connect: ConnectTrack;
+    hello: Hello;
+    res: Moq.Broadcast.Consumer;
+    resSub: Moq.Track.Subscriber;
+}
+/**
+ * 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 declare function requestSession(pub: Moq.Origin.Producer, sub: Moq.Origin.Producer, request: ConnectRequest, timeoutMs: number, log: MoqLogScope, signal: AbortSignal): Promise<Answered>;
 /**
- * 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`).
+ * 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 declare function openSession(knobs: SessionKnobs, dial: Dial, dom: string, signal?: AbortSignal): Promise<Session>;
 /** The error a call pending on a session that ended reports (WP §8.4: the request was written, so it may have run). */

package/dist/session.js

@@ -13,7 +13,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // 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 { 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
@@ -313,7 +313,7 @@ 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
+ * close code (retryable: a live session holds this name; a crashed one is released after the idle timeout), 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).
@@ -323,7 +323,7 @@ export function closeError(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 });
+        return new SynapseError("admission_refused", { message: "the runtime refused this connection; retryable: a live session holds this name (a crashed one is released after the idle timeout); the SDK keeps retrying 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 });
@@ -334,6 +334,18 @@ export function closeError(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 = {}) {
@@ -352,6 +364,76 @@ export async function discoverBrokerCertSha256(brokerUrl, opts = {}) {
         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 {
@@ -364,6 +446,8 @@ export class Session {
     log;
     /** Counts *established* sessions of the node (SDK §2); set by the node when attached. */
     epoch = 0;
+    /** The target generation this session was opened for (`Target.generation`); set by the node's loop when attached. */
+    generation = 0;
     startedMs = performance.now();
     transport;
     /** Datagrams travel only over WebTransport; the WebSocket fallback is stream-only. */
@@ -385,7 +469,7 @@ export class Session {
     #taskDone = [];
     /** Settles with the close's error once the connection closed. */
     closed;
-    constructor(url, conn, pub, sub, hello, maxDatagram, log, reqBc, res, resSub, dom) {
+    constructor(url, conn, pub, sub, hello, maxDatagram, log, connect, reqBc, res, resSub, dom) {
         this.url = url;
         this.conn = conn;
         this.pub = pub;
@@ -393,6 +477,7 @@ export class Session {
         this.hello = hello;
         this.maxDatagram = maxDatagram;
         this.log = log;
+        this.#connect = connect;
         this.#reqBc = reqBc;
         this.#role = hello.role;
         this.transport = conn.transport;
@@ -403,6 +488,8 @@ export class Session {
         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;
@@ -581,8 +668,9 @@ export class Session {
         this.close();
         await withTimeout(this.closed, graceMs);
     }
-    /** The synchronous end: fail its calls, finish our track, close the connection. Idempotent. */
+    /** 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();
@@ -621,16 +709,145 @@ export class Session {
 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`: 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`).
+ * 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 name = dial.identity.name;
+    const { identity } = dial;
+    const name = identity.name;
     if (!name)
         throw new SynapseError("internal", "identity without a name");
     if (knobs.transport !== "websocket")
@@ -638,18 +855,21 @@ export async function openSession(knobs, dial, dom, signal) {
     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();
-    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`.
+    // 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 });
-    // 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;
@@ -676,48 +896,30 @@ export async function openSession(knobs, dial, dom, signal) {
             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 {
-        // 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;
+        answered = await Promise.race([closedEarly, requestSession(pub, sub, request, knobs.connectTimeoutMs, log, hs.signal)]);
     }
     catch (e) {
-        clearTimeout(timer);
+        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();
@@ -725,8 +927,26 @@ export async function openSession(knobs, dial, dom, signal) {
         catch { /* ignore */ }
         pub.close();
         sub.close();
-        throw e instanceof SynapseError ? e : closeError(e instanceof Error ? e : new Error(describeError(e)));
-    }
+        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`). */