@synapse-sdk/client 0.3.4 → 0.3.7

package/dist/calls.d.ts

@@ -1,7 +1,7 @@
 import { SynapseError, type CallId, type ServiceContract } from "@synapse-sdk/core";
 import type { Node } from "./node.ts";
 import { type RespFrame, type Session } from "./session.ts";
-import type { CallEvent, CallOptions, Run, RunStatus } from "./types.ts";
+import type { CallOptions, Run, RunStatus } from "./types.ts";
 /** A fresh call id (WP §8.2): 16 random bytes. */
 export declare function newCallId(): CallId;
 export declare class RunImpl<U, R> implements Run<U, R> {
@@ -17,12 +17,14 @@ export declare class RunImpl<U, R> implements Run<U, R> {
     get status(): RunStatus;
     get result(): Promise<R>;
     then<A = R, B = never>(onFulfilled?: ((v: R) => A | PromiseLike<A>) | null, onRejected?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    catch<B = never>(onRejected?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<R | B>;
+    finally(onFinally?: (() => void) | null): Promise<R>;
     /** The session's demux hands frames here; `null` = the session ended with the call pending. */
     deliver(f: RespFrame | null): void;
     /** Starts the per-frame reader once the request is written (frames can arrive before `writeCall` returns). */
     start(): void;
-    nextUpdate(): Promise<U | undefined>;
-    updates(): AsyncIterable<U>;
+    next(): Promise<U | undefined>;
+    [Symbol.asyncIterator](): AsyncIterator<U>;
     /** Cooperative cancel (WP §8.4): tells the broker, then waits for its `canceled` terminal frame. `connection_lost` without sending once the session ended. */
     cancel(reason?: string): Promise<void>;
     /** Dropped with the call in flight: the runtime is told (best effort). */
@@ -39,5 +41,3 @@ export declare function startOn<U, R>(node: Node, session: Session, svc: string,
  * unhandled rejection.
  */
 export declare function failedRun<U, R>(error: SynapseError): Run<U, R>;
-/** `callStream`: the updates and the result as one ordered stream; `break` cancels. */
-export declare function callStream<U, R>(run: Run<U, R>): AsyncGenerator<CallEvent<U, R>, void, undefined>;

package/dist/calls.js

@@ -4,7 +4,7 @@
 // a frame on a later session (WP §8.4: ownership is checked, never inferred).
 import { FLAGS, SynapseError, TYPES, decode as decodeBody, encode as encodeBody, nowUs, toHex, validateSync } from "@synapse-sdk/core";
 import { outcomeUnknown } from "./session.js";
-import { AsyncQueue, deferred } from "./util.js";
+import { AsyncQueue, deferred, rethrowLater } from "./util.js";
 /** A fresh call id (WP §8.2): 16 random bytes. */
 export function newCallId() { const b = new Uint8Array(16); crypto.getRandomValues(b); return b; }
 export class RunImpl {
@@ -42,6 +42,8 @@ export class RunImpl {
     get status() { return this.#status; }
     get result() { return this.#result.promise; }
     then(onFulfilled, onRejected) { return this.#result.promise.then(onFulfilled, onRejected); }
+    catch(onRejected) { return this.then(undefined, onRejected); }
+    finally(onFinally) { return this.#result.promise.finally(onFinally); }
     /** The session's demux hands frames here; `null` = the session ended with the call pending. */
     deliver(f) { this.#frames.push(f); }
     /** Starts the per-frame reader once the request is written (frames can arrive before `writeCall` returns). */
@@ -93,11 +95,17 @@ export class RunImpl {
                     continue;
                 u = r.value;
             }
-            this.#updates.push(u);
-            try {
-                this.opts.onUpdate?.(u);
+            // The callback form takes the stream (as `subscribe(topic, cb)`): a throwing `onUpdate` is rethrown later and the reading goes on.
+            if (this.opts.onUpdate) {
+                try {
+                    this.opts.onUpdate(u);
+                }
+                catch (e) {
+                    rethrowLater(e);
+                }
             }
-            catch { /* the caller's */ }
+            else
+                this.#updates.push(u);
         }
     }
     #updates = new AsyncQueue(4096);
@@ -129,8 +137,8 @@ export class RunImpl {
             this.#result.resolve(r.value);
         }
     }
-    async nextUpdate() { return this.#updates.next(); }
-    updates() { return this.#updates; }
+    next() { return this.#updates.next(); }
+    [Symbol.asyncIterator]() { return this.#updates[Symbol.asyncIterator](); }
     #sendCancel(reason) {
         if (!this.session.isLive)
             return;
@@ -191,21 +199,11 @@ export function failedRun(error) {
         status: "failed",
         result,
         then: (onFulfilled, onRejected) => result.then(onFulfilled, onRejected),
-        nextUpdate: async () => undefined,
-        updates: async function* () { },
+        catch: onRejected => result.catch(onRejected),
+        finally: onFinally => result.finally(onFinally),
+        next: async () => undefined,
+        [Symbol.asyncIterator]: async function* () { },
         cancel: async () => { },
         [Symbol.asyncDispose]: async () => { },
     };
 }
-/** `callStream`: the updates and the result as one ordered stream; `break` cancels. */
-export async function* callStream(run) {
-    try {
-        for await (const u of run.updates())
-            yield { type: "update", data: u };
-        yield { type: "result", data: await run.result };
-    }
-    finally {
-        if (run.status === "pending" || run.status === "running")
-            run.cancel("caller").catch(() => { });
-    }
-}

package/dist/index.d.ts

@@ -1,11 +1,10 @@
 export * from "@synapse-sdk/core";
 export { Synapse, FIRST_CONNECT_GIVE_UP_MS } from "./synapse.ts";
 export { defaultReconnectPolicy, exponentialPolicy, fixedPolicy, withMaxAttempts } from "./node.ts";
-export { callStream } from "./calls.ts";
 export { isTasksRefusal } from "./tasks.ts";
 export { setMoqDebug } from "./moq_log.ts";
 export type * from "./types.ts";
-export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport } from "./session.ts";
+export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport, namesRoot } from "./session.ts";
 export { replaceEqualDeep, shallowEqual } from "./util.ts";
 export { orderAfter, orderBefore, orderBetween, ulid } from "./scene.ts";
 export { derivedFrameKey, derivedFrameName, materializeFrames, materializeHardpoints, validateDerivedFrame, type MaterializeReport } from "./scene_frames.ts";

package/dist/index.js

@@ -2,10 +2,9 @@
 export * from "@synapse-sdk/core";
 export { Synapse, FIRST_CONNECT_GIVE_UP_MS } from "./synapse.js";
 export { defaultReconnectPolicy, exponentialPolicy, fixedPolicy, withMaxAttempts } from "./node.js";
-export { callStream } from "./calls.js";
 export { isTasksRefusal } from "./tasks.js";
 export { setMoqDebug } from "./moq_log.js";
-export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport } from "./session.js";
+export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport, namesRoot } from "./session.js";
 export { replaceEqualDeep, shallowEqual } from "./util.js";
 export { orderAfter, orderBefore, orderBetween, ulid } from "./scene.js";
 export { derivedFrameKey, derivedFrameName, materializeFrames, materializeHardpoints, validateDerivedFrame } from "./scene_frames.js";

package/dist/keyserver.d.ts

@@ -0,0 +1,37 @@
+import { SynapseError } from "@synapse-sdk/core";
+import type { Discovery, DiscoveryState, FetchToken } from "./types.ts";
+import type { Cell } from "./util.ts";
+/** The key server a node asks when `setAuth` names none. */
+export declare const DEFAULT_AUTH_URL = "https://e9e413af.synapse.build";
+/** The discovery value with no credential set, or just after `setAuth` (a new object each time: a change). */
+export declare const idleDiscovery: () => DiscoveryState;
+/** The refusal when no credential is set or the sign-in gives none. */
+export declare const notSignedIn: () => SynapseError;
+/** `GET /discover`'s body as the `Discovery` value; `undefined` when it does not have that shape. */
+export declare function discoveryOf(body: unknown): Discovery | undefined;
+/**
+ * One `setAuth(fetchToken, { authUrl })` of one node: the key server's client and the caches it fills. A new one at every
+ * `setAuth` (the old one's caches go with it). It writes the node's `discovery` value only while it is the node's
+ * current one (`current`), so an answer arriving after a `setAuth` changes nothing.
+ */
+export declare class Auth {
+    #private;
+    private readonly fetchToken;
+    private readonly discovery;
+    private readonly current;
+    constructor(fetchToken: FetchToken, authUrl: string, discovery: Cell<DiscoveryState>, current: (a: Auth) => boolean);
+    /** `GET /discover`, setting the value (`pending`, then `success` or `error`, the last data kept); one at a time: a call while one is out joins it. */
+    discover(): Promise<Discovery>;
+    /** The discover answer: the value's when it is `success` (`cached`), else fetched now. */
+    known(): Promise<{
+        discovery: Discovery;
+        cached: boolean;
+    }>;
+    /** The token for cluster `id`: the kept one while it does not expire within `FRESH_FOR_S` (`cached`), else `POST /clusters/{id}/token`, kept. */
+    clusterToken(id: string): Promise<{
+        token: string;
+        cached: boolean;
+    }>;
+    /** Forgets the token of cluster `id` (the relay refused it). */
+    dropToken(id: string): void;
+}

package/dist/keyserver.js

@@ -0,0 +1,146 @@
+// The key server for a signed-in person (PLAN v0.38 §3.3): what a node set with `setAuth` asks it, `GET /discover`
+// (the relay and the person's clusters with their runtimes) and `POST /clusters/{id}/token` (a cluster token), with
+// the person's credential fetched at each request and sent only in the `Authorization` header. Both answers are kept
+// in memory, per node, until the next `setAuth`: the discover answer as the node's `discovery` state value, the cluster
+// tokens by cluster id while fresh (`FRESH_FOR_S`). Nothing is written anywhere else; no token is ever put in a URL, an
+// error or a log line.
+import { SynapseError } from "@synapse-sdk/core";
+import { describeError } from "./session.js";
+import { FRESH_FOR_S, knownOfListed, label } from "./target.js";
+/** The key server a node asks when `setAuth` names none. */
+export const DEFAULT_AUTH_URL = "https://e9e413af.synapse.build";
+/** The discovery value with no credential set, or just after `setAuth` (a new object each time: a change). */
+export const idleDiscovery = () => ({ status: "idle" });
+/** The refusal when no credential is set or the sign-in gives none. */
+export const notSignedIn = () => new SynapseError("unauthorized", { message: "not signed in: sign in first", source: "sdk" });
+const isTable = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** An answer that is not what the key server says it sends: `connection_lost` (retried; never a caller's mistake). */
+const unreadable = (what) => new SynapseError("connection_lost", { message: `the key server's answer to ${what} could not be read`, source: "sdk" });
+/** `GET /discover`'s body as the `Discovery` value; `undefined` when it does not have that shape. */
+export function discoveryOf(body) {
+    if (!isTable(body) || typeof body.relay !== "string" || typeof body.user_id !== "string" || !Array.isArray(body.clusters))
+        return undefined;
+    const clusters = [];
+    for (const c of body.clusters) {
+        if (!isTable(c) || typeof c.id !== "string" || typeof c.name !== "string" || !isTable(c.owner) || !isTable(c.runtimes))
+            return undefined;
+        const o = c.owner;
+        if (typeof o.kind !== "string" || typeof o.id !== "string" || (o.slug !== undefined && o.slug !== null && typeof o.slug !== "string"))
+            return undefined;
+        const owner = typeof o.slug === "string" ? { kind: o.kind, id: o.id, slug: o.slug } : { kind: o.kind, id: o.id };
+        const runtimes = {};
+        for (const [name, id] of Object.entries(c.runtimes)) {
+            if (typeof id !== "string")
+                return undefined;
+            runtimes[name] = id;
+        }
+        const listed = { id: c.id, name: c.name, owner };
+        clusters.push({ ...listed, label: label(knownOfListed(listed)), runtimes });
+    }
+    return { relay: body.relay, userId: body.user_id, clusters };
+}
+/**
+ * One `setAuth(fetchToken, { authUrl })` of one node: the key server's client and the caches it fills. A new one at every
+ * `setAuth` (the old one's caches go with it). It writes the node's `discovery` value only while it is the node's
+ * current one (`current`), so an answer arriving after a `setAuth` changes nothing.
+ */
+export class Auth {
+    fetchToken;
+    discovery;
+    current;
+    #tokens = new Map();
+    #pending;
+    #authUrl;
+    constructor(fetchToken, authUrl, discovery, current) {
+        this.fetchToken = fetchToken;
+        this.discovery = discovery;
+        this.current = current;
+        this.#authUrl = authUrl.replace(/\/+$/, "");
+    }
+    #set(f) { if (this.current(this))
+        this.discovery.set(f(this.discovery.get())); }
+    /** `GET /discover`, setting the value (`pending`, then `success` or `error`, the last data kept); one at a time: a call while one is out joins it. */
+    discover() {
+        return this.#pending ??= (async () => {
+            this.#set(p => (p.data ? { status: "pending", data: p.data } : { status: "pending" }));
+            try {
+                const d = discoveryOf(await this.#request("GET", "/discover"));
+                if (!d)
+                    throw unreadable("discover");
+                this.#set(() => ({ status: "success", data: d }));
+                return d;
+            }
+            catch (e) {
+                const err = e instanceof SynapseError ? e : new SynapseError("internal", { message: describeError(e), source: "sdk" });
+                this.#set(p => (p.data ? { status: "error", data: p.data, error: err } : { status: "error", error: err }));
+                throw err;
+            }
+            finally {
+                this.#pending = undefined;
+            }
+        })();
+    }
+    /** The discover answer: the value's when it is `success` (`cached`), else fetched now. */
+    async known() {
+        const v = this.discovery.get();
+        if (this.current(this) && v.status === "success" && v.data)
+            return { discovery: v.data, cached: true };
+        return { discovery: await this.discover(), cached: false };
+    }
+    /** The token for cluster `id`: the kept one while it does not expire within `FRESH_FOR_S` (`cached`), else `POST /clusters/{id}/token`, kept. */
+    async clusterToken(id) {
+        const kept = this.#tokens.get(id);
+        if (kept && kept.exp > Math.floor(Date.now() / 1000) + FRESH_FOR_S)
+            return { token: kept.token, cached: true };
+        const body = await this.#request("POST", `/clusters/${encodeURIComponent(id)}/token`);
+        const exp = isTable(body) && typeof body.expires_at === "string" ? Date.parse(body.expires_at) : NaN;
+        if (!isTable(body) || typeof body.token !== "string" || body.token === "" || Number.isNaN(exp))
+            throw unreadable("a cluster token request");
+        this.#tokens.set(id, { token: body.token, exp: Math.floor(exp / 1000) });
+        return { token: body.token, cached: false };
+    }
+    /** Forgets the token of cluster `id` (the relay refused it). */
+    dropToken(id) { this.#tokens.delete(id); }
+    /**
+     * One request with the credential fetched now. The key server's answers (PLAN v0.38 §3.3.5): `401` `unauthorized`
+     * (and every cache dropped), `400`/`403`/`404` `invalid_input`, anything else not 2xx, or no answer, `connection_lost`;
+     * each with the key server's own sentence when it sent one.
+     */
+    async #request(method, path) {
+        let credential;
+        try {
+            credential = await this.fetchToken();
+        }
+        catch (e) {
+            throw new SynapseError("connection_lost", { message: `signing in gave no credential: ${describeError(e)}`, source: "sdk" });
+        }
+        if (!credential)
+            throw notSignedIn();
+        let res;
+        try {
+            res = await globalThis.fetch(`${this.#authUrl}${path}`, { method, headers: { Authorization: `Bearer ${credential}` } });
+        }
+        catch (e) {
+            throw new SynapseError("connection_lost", { message: `the key server could not be reached: ${describeError(e)}`, source: "transport" });
+        }
+        let body;
+        try {
+            body = JSON.parse(await res.text());
+        }
+        catch {
+            body = undefined;
+        }
+        if (res.ok)
+            return body;
+        const sentence = isTable(body) && typeof body.error === "string" && body.error !== "" ? body.error : `the key server answered ${res.status}`;
+        if (res.status === 401) {
+            const err = new SynapseError("unauthorized", { message: sentence, source: "sdk" });
+            this.#tokens.clear();
+            this.#set(p => (p.status === "success" ? { status: "error", data: p.data, error: err } : p));
+            throw err;
+        }
+        if (res.status === 400 || res.status === 403 || res.status === 404)
+            throw new SynapseError("invalid_input", { message: sentence, source: "sdk" });
+        throw new SynapseError("connection_lost", { message: sentence, source: "sdk" });
+    }
+}

package/dist/node.d.ts

@@ -1,6 +1,7 @@
 import { SynapseError, type ClientType, type ErrorBody, type Identity, type TimeDomain } from "@synapse-sdk/core";
+import { Auth } from "./keyserver.ts";
 import { Session, type Dial, type SessionKnobs } from "./session.ts";
-import type { ConnectOptions, ConnectTarget, ConnectionState, Notice, ReconnectPolicy } from "./types.ts";
+import type { ConnectOptions, ConnectTarget, ConnectionState, DiscoveryState, FetchToken, Notice, ReconnectPolicy } from "./types.ts";
 import { Cell, type Deferred } from "./util.ts";
 /** `initial × 2^(attempt−1)` capped at `max`, times an equal jitter U(0.5, 1); never gives up. */
 export declare function exponentialPolicy(initialMs: number, maxMs: number): ReconnectPolicy;
@@ -108,6 +109,13 @@ export declare class Node {
     readonly projectNotices: Set<(n: Notice) => void>;
     /** Resolves once the node has ended for good: `close()`, and nothing else. */
     readonly ended: Deferred<void>;
+    /**
+     * The signed-in person's key server (`setAuth`), asked when a target named by name is dialed (PLAN v0.38 §3.2);
+     * `undefined`: nobody is signed in. Read at each attempt, never by a live session: signing out ends no session.
+     */
+    auth: Auth | undefined;
+    /** The key server's answer about the signed-in person, kept by `auth` (`node.discovery`). */
+    readonly discovery: Cell<DiscoveryState>;
     epochs: number;
     reconnects: number;
     callsSent: number;
@@ -118,6 +126,8 @@ export declare class Node {
         finalDom?: Promise<TimeDomain>;
     });
     get isEnded(): boolean;
+    /** `setAuth`: a new key-server client for `fetchToken` (none: signed out); what the previous one kept is forgotten and `discovery` is `idle` again. */
+    setAuth(fetchToken: FetchToken | undefined, authUrl: string): void;
     get isConnected(): boolean;
     /** Whether the node rests `failed` on target `generation` (a `failed` of an older target, not yet replaced by the loop, is not this target's). */
     failedOn(generation: number): boolean;
@@ -161,6 +171,13 @@ export declare class Node {
     /** Starts the loop (once the time domain is final). `first` is a `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
     run(stand: Stand, first: Reply | undefined, signals: boolean): void;
 }
+/**
+ * Dials `dial`, a target named as the CLI names it, through the key server of `auth` (`resolveViaKeyserver`), with `open`.
+ * When the relay refuses (`unauthorized`) a cluster token that came from the cache, that token is dropped, one is asked
+ * again and dialed once more within this attempt (a token the relay stopped taking before its expiry costs one request,
+ * not a `failed`); a second refusal is the attempt's. A token given as such is dialed as it is.
+ */
+export declare function dialByName<T>(dial: Dial, auth: Auth, open: (at: Dial) => Promise<T>): Promise<T>;
 /** Resolves the identity a node declares (`resolve_identity`): a missing name is minted, a `web`/`hmi` node without a `user_id` mints one. */
 export declare function resolveIdentity(o: {
     type: ClientType;
@@ -168,7 +185,12 @@ export declare function resolveIdentity(o: {
     userId?: string;
     credential?: string;
 }): Identity;
-/** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
+/**
+ * Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). A url that is not a URL is a
+ * target as the CLI names it (`infra-1@devel`): its grammar is checked now, and it is resolved at every attempt (through
+ * the key server when a person is signed in, else from the CLI's files); with neither (a browser, nobody signed in) it is
+ * refused at once.
+ */
 export declare function resolveTarget(node: Node, t: ConnectTarget): Dial;
 /** A given broker url that is not a URL is the caller's mistake: `invalid_input`. */
 export declare function checkUrl(url: string): void;

package/dist/node.js

@@ -8,6 +8,8 @@
 // the handles replay when told.
 import { ClockSync, SynapseError, calibrateMonotonicClock, defaultDomId, isValidClientName, mintName, mintUserId, nowUs } from "@synapse-sdk/core";
 import { closeOnSignals, forgetOnSignals } from "./signals.js";
+import { BROWSER_REFUSAL, canReadFiles, isUrl, parseTargetStrict, resolveStr, resolveViaKeyserver } from "./target.js";
+import { Auth, idleDiscovery } from "./keyserver.js";
 import { Session, closeError, defaultMaxDatagram, discoverBrokerCertSha256, makeDial, openSession, urlOrEndpoint } from "./session.js";
 import { startOn } from "./calls.js";
 import { AsyncQueue, Cell, deferred } from "./util.js";
@@ -84,6 +86,13 @@ export class Node {
     /** The loop's mailbox: unbounded, so no `close()` or target change is ever dropped. */
     #commands = new AsyncQueue(Infinity);
     #monitors = new Set();
+    /**
+     * The signed-in person's key server (`setAuth`), asked when a target named by name is dialed (PLAN v0.38 §3.2);
+     * `undefined`: nobody is signed in. Read at each attempt, never by a live session: signing out ends no session.
+     */
+    auth;
+    /** The key server's answer about the signed-in person, kept by `auth` (`node.discovery`). */
+    discovery = new Cell(idleDiscovery());
     epochs = 0;
     reconnects = 0;
     callsSent = 0;
@@ -98,6 +107,11 @@ export class Node {
         this.prepared = opts.finalDom ? opts.finalDom.then(d => { this.dom = d; }) : Promise.resolve();
     }
     get isEnded() { return this.#endedFlag; }
+    /** `setAuth`: a new key-server client for `fetchToken` (none: signed out); what the previous one kept is forgotten and `discovery` is `idle` again. */
+    setAuth(fetchToken, authUrl) {
+        this.auth = fetchToken ? new Auth(fetchToken, authUrl, this.discovery, a => this.auth === a) : undefined;
+        this.discovery.set(idleDiscovery());
+    }
     get isConnected() { return this.link.get().status === "connected"; }
     /** Whether the node rests `failed` on target `generation` (a `failed` of an older target, not yet replaced by the loop, is not this target's). */
     failedOn(generation) { const l = this.link.get(); return l.status === "failed" && l.generation === generation; }
@@ -328,9 +342,19 @@ async function runLoop(node, commands, stand, first) {
                 if (ac.signal.aborted)
                     return { kind: "opened", result: new SynapseError("canceled", "superseded") };
                 try {
-                    // The pin: given, else discovered per attempt (a restarted dev broker has a fresh certificate), else unpinned.
-                    const cert = dial.cert ?? await discoverBrokerCertSha256(dial.url, { signal: ac.signal });
-                    return { kind: "opened", result: await openSession(node.knobs, { ...dial, cert }, node.dom.id, ac.signal) };
+                    const open = async (at) => {
+                        // The pin: given, else discovered per attempt (a restarted dev broker has a fresh certificate), else unpinned.
+                        const cert = at.cert ?? await discoverBrokerCertSha256(at.url, { signal: ac.signal });
+                        return openSession(node.knobs, { ...at, cert }, node.dom.id, ac.signal);
+                    };
+                    // A URL is dialed as it is. A target named as the CLI names it is resolved now, by one source chosen per attempt
+                    // (PLAN v0.38 §3.2): the key server when a person is signed in (`setAuth`), else the CLI's files (a token the
+                    // CLI refreshed since the last attempt is this attempt's). A token given as such wins.
+                    const auth = node.auth;
+                    const session = isUrl(dial.url) ? await open(dial)
+                        : auth ? await dialByName(dial, auth, open)
+                            : await resolveStr(dial.url).then(r => open({ ...dial, url: r.url, token: dial.token ?? r.token }));
+                    return { kind: "opened", result: session };
                 }
                 catch (e) {
                     return { kind: "opened", result: e instanceof SynapseError ? e : new SynapseError("connection_lost", { message: String(e), cause: e }) };
@@ -476,6 +500,26 @@ async function runLoop(node, commands, stand, first) {
         }
     }
 }
+/**
+ * Dials `dial`, a target named as the CLI names it, through the key server of `auth` (`resolveViaKeyserver`), with `open`.
+ * When the relay refuses (`unauthorized`) a cluster token that came from the cache, that token is dropped, one is asked
+ * again and dialed once more within this attempt (a token the relay stopped taking before its expiry costs one request,
+ * not a `failed`); a second refusal is the attempt's. A token given as such is dialed as it is.
+ */
+export async function dialByName(dial, auth, open) {
+    const r = await resolveViaKeyserver(dial.url, auth);
+    const at = { ...dial, url: r.url, token: dial.token ?? r.token };
+    try {
+        return await open(at);
+    }
+    catch (e) {
+        if (!(e instanceof SynapseError) || e.code !== "unauthorized" || dial.token !== undefined || !r.cached || r.cluster === undefined)
+            throw e;
+        auth.dropToken(r.cluster);
+        const { token } = await auth.clusterToken(r.cluster);
+        return open({ ...at, token });
+    }
+}
 /** Ends session `s`: the node stops naming it (handles are told, the status is true from that instant), then the session is torn down (calls failed, tasks awaited, close sent). */
 async function teardown(node, s, next) {
     node.setLink(next);
@@ -495,9 +539,25 @@ export function resolveIdentity(o) {
         id.credential = o.credential;
     return id;
 }
-/** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
+/**
+ * Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). A url that is not a URL is a
+ * target as the CLI names it (`infra-1@devel`): its grammar is checked now, and it is resolved at every attempt (through
+ * the key server when a person is signed in, else from the CLI's files); with neither (a browser, nobody signed in) it is
+ * refused at once.
+ */
 export function resolveTarget(node, t) {
-    checkUrl(t.url);
+    if (isUrl(t.url))
+        checkUrl(t.url);
+    else {
+        if (!node.auth && !canReadFiles())
+            throw new SynapseError("invalid_input", { message: BROWSER_REFUSAL, source: "sdk" });
+        try {
+            parseTargetStrict(t.url);
+        }
+        catch (e) {
+            throw new SynapseError("invalid_input", { message: `${e instanceof Error ? e.message : String(e)}, or a URL`, source: "sdk" });
+        }
+    }
     const cur = node.target.get().identity;
     if (t.name !== undefined && !isValidClientName(t.name))
         throw new SynapseError("invalid_input", `name ${JSON.stringify(t.name)} is not [a-z0-9_-]{1,64}`);

package/dist/scene.d.ts

@@ -132,8 +132,10 @@ export declare class Mirror {
     epoch: string | undefined;
     version: number;
     hash: string;
-    /** An authored diff skipped a version; cleared by the next snapshot. */
-    gap: boolean;
+    /** An authored diff skipped a version (not applied; the track is read again from its snapshot): the highest version seen then. Cleared once the copy is back at it (PLAN v0.34 §2.2). */
+    gap: number | undefined;
+    /** The live track's first keyframe of the incarnation is in the copy. */
+    liveKeyed: boolean;
     pending: number;
     authored: Entities;
     live: LiveTable;
@@ -146,12 +148,16 @@ export declare class Mirror {
     dropHandle(id: number): void;
     /** The hierarchy now (recomputed only after a change of the ids, a parent or an order; the same object while equal). */
     tree(): SceneTree;
-    /** A snapshot of incarnation `epoch` replaces the authored copy. Not yet `attached`: the reader catches up first (`attach`). */
+    /** A snapshot of incarnation `epoch` replaces the authored copy. The first one is not yet `attached`: that is the task's, once the copy is at the version the open answered. */
     applySnapshot(epoch: string, s: Snapshot): void;
-    /** The reader has applied everything this node held when it bound the incarnation. */
+    /** The copy is current as of the attach (the task checked it): `attached`. */
     attach(): void;
-    /** One applied batch: its ops folded into the authored copy. */
-    applyDiff(d: Diff, warn: Warn): void;
+    /**
+     * One applied batch: its ops folded into the authored copy, when it is the next version. Otherwise it is not applied
+     * (`false`): a gap, `synced` false until the copy is back at the version seen; the reader reads the track again from
+     * its snapshot (PLAN v0.34 §2.2).
+     */
+    applyDiff(d: Diff, warn: Warn): boolean;
     /** A keyframe replaces the live table. */
     applyKeyframe(k: LiveFrame): void;
     /** One tick folded into the live table; its removals go to the feeds. */
@@ -177,18 +183,22 @@ type Event = {
 } | {
     kind: "nodeEnded";
 }
+/** The answer of `synapse/scene/open` of attempt `attempt`. */
+ | {
+    kind: "opened";
+    attempt: number;
+    result: Result<unknown>;
+}
 /** The reader applied an authored frame of incarnation `epoch`: the mirror is at `version`. */
  | {
     kind: "applied";
     epoch: string;
     version: number;
 }
-/** Reading `attempt` caught up with incarnation `epoch` at `version`: the task binds the claims, then attaches the handle. */
+/** The reader applied the live track's first keyframe of incarnation `epoch`. */
  | {
-    kind: "attach";
-    attempt: number;
+    kind: "liveKeyed";
     epoch: string;
-    version: number;
 }
 /** The reader of attempt `attempt` ended: the incarnation it bound and its final frame's reason (none: the tracks or the session went). */
  | {
@@ -385,7 +395,8 @@ export declare class SceneHandleImpl implements SceneHandle {
 }
 /**
  * The active project's scene (one per project; one task per node, shared by every handle). Resolves
- * once the handle is attached, or at once `detached` when the runtime says no project is active; the
+ * once the handle is attached (the copy at the version `synapse/scene/open` answered, or past it), or at
+ * once `detached` when the runtime says no project is active; the
  * handle then follows the incarnations as they come and go. Without a session (before the first, between
  * two) the task waits for the next one, like after a drop.
  */