@synapse-sdk/client 0.3.4 → 0.3.7

package/dist/session.d.ts

@@ -89,14 +89,24 @@ export declare function describeError(e: unknown): string;
  * GOAWAY looks like one).
  */
 export declare function closeError(err: Error | null): SynapseError;
-/** `https://host:port/<root>` → `http://host:port/certificate.sha256`, the broker's plain-HTTP helper. */
+/**
+ * `https://host[:port]` → `http://host:port/certificate.sha256`, the runtime's plain-HTTP helper on the
+ * runtime's own port (443 when the URL names none, as the Rust SDK). Before 2026-10-17 the default
+ * port was lost and a relay URL was asked on port 80, which no relay answers: a 2 s stall per attempt.
+ */
 export declare function brokerCertHelperUrl(brokerUrl: string): string;
+/** Whether `url` names a root (`/runtimes/<id>`, `/cluster/<c>/runtimes/<id>`): a relay, a deployment with a real certificate, never asked for a pin (`withRoot` makes the same split). */
+export declare function namesRoot(url: string): boolean;
 /**
  * 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. */
+/**
+ * The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node); else, for a
+ * runtime URL (no path: a self-signed certificate, pinned), its helper; a URL that names a root (a relay) is
+ * never asked and connects unpinned, against the system's roots. `undefined` = unpinned. Per attempt.
+ */
 export declare function discoverBrokerCertSha256(brokerUrl: string, opts?: {
     timeoutMs?: number;
     signal?: AbortSignal;

package/dist/session.js

@@ -332,8 +332,20 @@ export function closeError(err) {
         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`; }
+/**
+ * `https://host[:port]` → `http://host:port/certificate.sha256`, the runtime's plain-HTTP helper on the
+ * runtime's own port (443 when the URL names none, as the Rust SDK). Before 2026-10-17 the default
+ * port was lost and a relay URL was asked on port 80, which no relay answers: a 2 s stall per attempt.
+ */
+export function brokerCertHelperUrl(brokerUrl) { const u = new URL(brokerUrl); return `http://${u.hostname}:${u.port || (u.protocol === "http:" ? "80" : "443")}/certificate.sha256`; }
+/** Whether `url` names a root (`/runtimes/<id>`, `/cluster/<c>/runtimes/<id>`): a relay, a deployment with a real certificate, never asked for a pin (`withRoot` makes the same split). */
+export function namesRoot(url) { try {
+    const p = new URL(url).pathname;
+    return p !== "" && p !== "/";
+}
+catch {
+    return false;
+} }
 /**
  * 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`.
@@ -347,22 +359,35 @@ export function urlOrEndpoint(url) {
     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. */
+/**
+ * The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node); else, for a
+ * runtime URL (no path: a self-signed certificate, pinned), its helper; a URL that names a root (a relay) is
+ * never asked and connects unpinned, against the system's roots. `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 {
+    if (namesRoot(brokerUrl))
         return undefined;
-    }
+    const timeoutMs = opts.timeoutMs ?? 2000;
+    const signal = opts.signal ? AbortSignal.any([opts.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+    const fetched = (async () => {
+        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;
+        }
+    })();
+    // Bun does not abort a connect that gets no answer (measured 2026-10-17: a filtered port hung the dial for
+    // good); the race bounds the wait whatever the runtime does with the signal.
+    const r = await withTimeout(fetched, timeoutMs);
+    return r === TIMEOUT ? undefined : r;
 }
 /**
  * `token_from_url`: `url` without its `jwt=` query parameters, and the last non-empty one (as the relays
@@ -429,7 +454,7 @@ export async function withRoot(url, signal) {
         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" });
+        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>/cluster/<cluster>/runtimes/<runtime_id>`, source: "sdk" });
     }
     u.pathname = `/${root}`;
     return u.toString();

package/dist/store.d.ts

@@ -9,6 +9,8 @@ export declare const ENDED_CONNECTION_LOST = "connection_lost";
 export declare const ENDED_CLIENT = "client";
 /** A watcher this many batches behind is ended, never grown. */
 export declare const STORE_FEED_CAP = 256;
+/** How long an incarnation the open's reply named has to show up on the announcement cursor (no "live" marker in @moq/net's JS cursor). */
+export declare const ANNOUNCE_WITHIN_MS = 1000;
 /** The mirror and what the runtime said about the namespace; written by the task and its reader only. */
 export declare class State {
     #private;
@@ -24,7 +26,8 @@ export declare class State {
     onDeath: StoreOnDeath | undefined;
     absent: boolean;
     loaded: boolean;
-    gap: boolean;
+    /** A 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;
     pending: number;
     ended: string | undefined;
     subscribe(l: () => void): () => void;
@@ -32,7 +35,11 @@ export declare class State {
     /** A feed its reader has left: it is closed and gets nothing more. */
     unwatch(q: AsyncQueue<StoreChange[]>): void;
     applySnapshot(s: StoreSnapshot): void;
-    applyDiff(d: StoreDiff, warn: Warn): void;
+    /**
+     * One diff, applied 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: StoreDiff, warn: Warn): boolean;
     /** Nothing of the incarnation is known until the runtime answers the next open. */
     reset(): void;
     opened(a: StoreAccess | undefined): void;
@@ -140,11 +147,12 @@ export declare class StoreHandleImpl implements StoreHandle {
     destroy(): Promise<void>;
     /** `for await (const value of store.watch())`: the whole value after each change; `store.watch(key)`: that key's value each time it changes. Ends with the handle; leaving the loop removes the feed. */
     watch(key?: string): AsyncGenerator<unknown, void, undefined>;
-    /** The whole value after its next change (`store_gone` once this handle is closed). */
+    /** The whole value after its next change; `changed(key)`: that key's value after its next change (`undefined` after a delete), as `watch(key)` yields it. `store_gone` once this handle is closed. Armed at the call. */
     changed(): Promise<Record<string, unknown>>;
+    changed(key: string): Promise<unknown>;
     /** `cb` with the whole value on every change of the value or the status (the framework bridge, React's `useStore`); returns the remover. */
     onChange(cb: (value: Record<string, unknown>) => void): () => void;
-    /** Waits for the namespace to be in (the first snapshot applied, or absent). */
+    /** Waits for the namespace to be in: the value current as of the open (the version the runtime answered applied), or the namespace absent. */
     ready(): Promise<void>;
     close(): void;
     [Symbol.asyncDispose](): Promise<void>;

package/dist/store.js

@@ -21,7 +21,7 @@ const ENDED_STORE_GONE = "store_gone";
 /** A watcher this many batches behind is ended, never grown. */
 export const STORE_FEED_CAP = 256;
 /** How long an incarnation the open's reply named has to show up on the announcement cursor (no "live" marker in @moq/net's JS cursor). */
-const ANNOUNCE_WITHIN_MS = 1000;
+export const ANNOUNCE_WITHIN_MS = 1000;
 const isFinal = (reason) => reason === ENDED_DESTROYED;
 const gone = (name, why) => new SynapseError("store_gone", `store ${JSON.stringify(name)}: ${why}`);
 // ------------------------------------------------------------------------------------- state
@@ -39,7 +39,8 @@ export class State {
     onDeath;
     absent = false;
     loaded = false;
-    gap = false;
+    /** A 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;
     pending = 0;
     ended;
     #listeners = new Set();
@@ -92,13 +93,22 @@ export class State {
         this.onDeath = s.on_death;
         this.absent = false;
         this.loaded = true;
-        this.gap = false;
+        this.#heal();
         this.#emit(records);
     }
+    /** A gap is over once the copy is back at the highest version seen when it opened. */
+    #heal() { if (this.gap !== undefined && this.version >= this.gap)
+        this.gap = undefined; }
+    /**
+     * One diff, applied 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, warn) {
         if (d.version !== this.version + 1) {
-            warn(`store: diff out of sequence (have ${this.version}, got ${d.version}); not synced until the next snapshot`);
-            this.gap = true;
+            warn(`store: diff out of sequence (have ${this.version}, got ${d.version}): not applied; reading the track again from its snapshot`);
+            this.gap = Math.max(this.gap ?? d.version, d.version);
+            this.#notify();
+            return false;
         }
         const records = [];
         const flat = new Map(this.flat);
@@ -119,7 +129,9 @@ export class State {
         }
         this.flat = flat;
         this.version = d.version;
+        this.#heal();
         this.#emit(records);
+        return true;
     }
     #clear() {
         const records = [...this.rows].map(([key, r]) => ({ kind: "delete", key, previousValue: r.v, by: undefined }));
@@ -135,7 +147,7 @@ export class State {
         this.epoch = undefined;
         this.version = 0;
         this.loaded = false;
-        this.gap = false;
+        this.gap = undefined;
         this.mode = undefined;
         this.owner = undefined;
         this.mine = false;
@@ -151,7 +163,7 @@ export class State {
         this.epoch = undefined;
         this.version = 0;
         this.loaded = false;
-        this.gap = false;
+        this.gap = undefined;
         this.mode = a?.mode;
         this.owner = a?.owner ?? undefined;
         this.mine = a?.mine ?? false;
@@ -177,7 +189,7 @@ export class State {
     status(nodeConnected, closed = false) {
         const ended = closed ? ENDED_CLIENT : this.ended;
         const connected = ended === undefined && nodeConnected;
-        return { synced: connected && this.pending === 0 && !this.gap && (this.loaded || this.absent), connected, pending: this.pending, mode: this.mode, owner: this.owner, mine: this.mine, minRole: this.minRole, onDeath: this.onDeath, absent: this.absent, version: this.version, epoch: this.epoch, ended };
+        return { synced: connected && this.pending === 0 && this.gap === undefined && (this.loaded || this.absent), connected, pending: this.pending, mode: this.mode, owner: this.owner, mine: this.mine, minRole: this.minRole, onDeath: this.onDeath, absent: this.absent, version: this.version, epoch: this.epoch, ended };
     }
 }
 function sameValue(a, b) {
@@ -686,7 +698,8 @@ function announcedEpoch(base, prefix) {
 /**
  * Reads the incarnation the open bound (`want`; `undefined`: absent, the first one announced), writing
  * the mirror and telling the task of each frame applied; returns how the track ended (`undefined`:
- * no final frame — the session, or the broker, went; the task replays).
+ * no final frame — the session, or the broker, went; the task replays). A diff out of sequence is not applied: the
+ * subscription is let go and the track subscribed again, which delivers the open group from its snapshot (PLAN v0.34 §2.2).
  */
 async function follow(ns, session, announced, want, signal) {
     const { state, warn, name } = ns;
@@ -739,74 +752,86 @@ async function follow(ns, session, announced, want, signal) {
             return undefined;
         }
         announced.close();
-        sub = bc.track(STORE_TRACK).subscribe(latestSubscription(moqPriority(1)));
-        const s = sub;
+        const track = bc.track(STORE_TRACK);
         // Closing the subscriber ends `recvGroup`, not a read on the group it already handed us: that group is closed too.
         let g;
-        signal.addEventListener("abort", () => { s.close(); g?.close(); }, { once: true });
-        // The first group read is the open one, from its start: a snapshot, then the diffs.
-        for (;;) {
-            g = await s.recvGroup();
-            if (!g)
-                break;
+        signal.addEventListener("abort", () => { sub?.close(); g?.close(); }, { once: true });
+        // A gap: this subscription is let go and the track subscribed again, which delivers the open group from its
+        // snapshot (PLAN v0.34 §2.2; no counter, no timer).
+        subscribe: for (;;) {
+            if (signal.aborted)
+                return undefined;
+            try {
+                sub?.close();
+            }
+            catch { /* closed */ }
+            const s = sub = track.subscribe(latestSubscription(moqPriority(1)));
+            // The first group read is the open one, from its start: a snapshot, then the diffs.
             for (;;) {
-                let f;
-                try {
-                    f = await g.readFrame();
-                }
-                catch {
-                    break;
-                }
-                if (!f)
+                g = await s.recvGroup();
+                if (!g)
                     break;
-                let header, hlen;
-                try {
-                    ({ header, hlen } = decodeHeader(f.payload));
-                }
-                catch {
-                    warn(`store ${name}: frame not decodable`);
-                    continue;
-                }
-                let body;
-                try {
-                    body = decodeBody(f.payload.subarray(hlen));
-                }
-                catch {
-                    warn(`store ${name}: frame body not decodable`);
-                    continue;
-                }
-                if (header.flags & FLAGS.END) {
-                    const fin = body;
-                    return fin && typeof fin.reason === "string" ? fin.reason : ENDED_STORE_GONE;
-                }
-                // A stopped reader no longer writes the mirror: it belongs to the next incarnation (or to none).
-                if (header.flags & FLAGS.KEY) {
-                    const snap = body;
-                    if (!snap || snap.epoch !== epoch) {
-                        warn(`store ${name}: snapshot of another epoch dropped`);
-                        continue;
+                for (;;) {
+                    let f;
+                    try {
+                        f = await g.readFrame();
                     }
-                    if (signal.aborted)
-                        continue;
-                    if (state.ended === undefined)
-                        state.applySnapshot(snap);
-                    ns.post({ kind: "applied", epoch, version: snap.version });
-                }
-                else if (header.flags & FLAGS.DELTA) {
-                    const diff = body;
-                    if (!diff || typeof diff.version !== "number") {
-                        warn(`store ${name}: diff not decodable`);
+                    catch {
+                        break;
+                    }
+                    if (!f)
+                        break;
+                    let header, hlen;
+                    try {
+                        ({ header, hlen } = decodeHeader(f.payload));
+                    }
+                    catch {
+                        warn(`store ${name}: frame not decodable`);
                         continue;
                     }
-                    if (signal.aborted)
+                    let body;
+                    try {
+                        body = decodeBody(f.payload.subarray(hlen));
+                    }
+                    catch {
+                        warn(`store ${name}: frame body not decodable`);
                         continue;
-                    if (state.ended === undefined && state.loaded)
-                        state.applyDiff(diff, warn);
-                    ns.post({ kind: "applied", epoch, version: diff.version });
+                    }
+                    if (header.flags & FLAGS.END) {
+                        const fin = body;
+                        return fin && typeof fin.reason === "string" ? fin.reason : ENDED_STORE_GONE;
+                    }
+                    // A stopped reader no longer writes the mirror: it belongs to the next incarnation (or to none).
+                    if (header.flags & FLAGS.KEY) {
+                        const snap = body;
+                        if (!snap || snap.epoch !== epoch) {
+                            warn(`store ${name}: snapshot of another epoch dropped`);
+                            continue;
+                        }
+                        if (signal.aborted)
+                            continue;
+                        if (state.ended === undefined)
+                            state.applySnapshot(snap);
+                        ns.post({ kind: "applied", epoch, version: snap.version });
+                    }
+                    else if (header.flags & FLAGS.DELTA) {
+                        const diff = body;
+                        if (!diff || typeof diff.version !== "number") {
+                            warn(`store ${name}: diff not decodable`);
+                            continue;
+                        }
+                        if (signal.aborted)
+                            continue;
+                        if (state.ended === undefined && state.loaded && !state.applyDiff(diff, warn)) {
+                            g.close();
+                            continue subscribe;
+                        }
+                        ns.post({ kind: "applied", epoch, version: diff.version });
+                    }
                 }
             }
+            return undefined; // the track ended with no final frame: the session (or the broker) went
         }
-        return undefined; // the track ended with no final frame: the session (or the broker) went
     }
     catch {
         return undefined;
@@ -902,10 +927,15 @@ export class StoreHandleImpl {
             this.ns.state.unwatch(q);
         }
     }
-    /** The whole value after its next change (`store_gone` once this handle is closed). */
-    changed() {
+    changed(key) {
         if (this.#closed)
             return Promise.reject(this.#ended());
+        if (key !== undefined) {
+            // the first step of `watch(key)`, started now (its feed opens at the first `next()`), then left
+            const it = this.watch(key)[Symbol.asyncIterator]();
+            return it.next().then(r => { void it.return(undefined); if (r.done)
+                throw this.#ended(); return r.value; });
+        }
         const from = this.get();
         const d = deferred();
         const un = this.ns.state.subscribe(() => { const v = this.get(); if (v !== from) {
@@ -919,7 +949,7 @@ export class StoreHandleImpl {
     }
     /** `cb` with the whole value on every change of the value or the status (the framework bridge, React's `useStore`); returns the remover. */
     onChange(cb) { return this.ns.state.subscribe(() => cb(this.get())); }
-    /** Waits for the namespace to be in (the first snapshot applied, or absent). */
+    /** Waits for the namespace to be in: the value current as of the open (the version the runtime answered applied), or the namespace absent. */
     ready() { return this.ns.request(reply => ({ kind: "join", reply })); }
     close() {
         if (this.#closed)

package/dist/synapse.d.ts

@@ -2,7 +2,7 @@ import { type Age, type ErrorBody, type ProjectSnapshot, type ServiceContract, t
 import { Node } from "./node.ts";
 import { StoreHandleImpl } from "./store.ts";
 import { type Warn } from "./topics.ts";
-import type { CallEvent, CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Envelope, Info, Metrics, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, Tasks, View, ViewOptions } from "./types.ts";
+import type { CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Discovery, DiscoveryState, Envelope, FetchToken, Info, Metrics, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, Tasks, View, ViewOptions } from "./types.ts";
 import { type StateValue } from "./util.ts";
 export { FIRST_CONNECT_GIVE_UP_MS } from "./node.ts";
 export declare class Synapse implements AsyncDisposable {
@@ -15,7 +15,8 @@ export declare class Synapse implements AsyncDisposable {
      */
     constructor(opts: ConnectOptions);
     /**
-     * Connects the node to `target` (a string is the url), the one connect verb: the first connect, and how an HMI moves
+     * Connects the node to `target` (a string is the url: a URL, or in Bun/Node a target such as `"infra-1@devel"`, see
+     * `ConnectTarget.url`), the one connect verb: the first connect, and how an HMI moves
      * from one robot's runtime to another. The current session, if any, is torn down before `target` is dialed; every
      * handle re-binds to the new session as across a reconnect. Identity fields `target` leaves out keep the node's.
      *
@@ -41,6 +42,30 @@ export declare class Synapse implements AsyncDisposable {
      * resolves quietly). Resolves once the session is gone; already `idle`: at once. `not_connected` once the node has ended.
      */
     disconnect(): Promise<void>;
+    /**
+     * Signs a person in for connecting by name (`connect("infra-1@devel")`) through the key server: `fetchToken` gives the
+     * person's credential and is called each time the key server is asked (never kept); `authUrl` is the key server
+     * (default `https://e9e413af.synapse.build`; an `http://` one is taken as it is, for a key server on your own machine while
+     * developing, never in production: the credential travels in the header). `setAuth(undefined)` signs out. Either way,
+     * what the node kept from the key server (your clusters, the cluster tokens) is forgotten and `discovery` is `idle` again.
+     *
+     * A live session is never touched: the sign-in is read only when the node dials, so signing out ends nothing now, and
+     * the next dial of a target named by name fails `unauthorized` (`failed`). With a person signed in, a target named by
+     * name is resolved through the key server also in Bun/Node, instead of the CLI's files. Call it before `connect()`.
+     */
+    setAuth(fetchToken: FetchToken | undefined, opts?: {
+        authUrl?: string;
+    }): void;
+    /**
+     * Asks the key server for the signed-in person's clusters and their runtimes, sets `discovery` from the answer and
+     * resolves with it; one request at a time (a call while one is out joins it). Rejects `unauthorized` when nobody is
+     * signed in (`setAuth`; `discovery` stays `idle`) or the key server does not take the sign-in, `invalid_input` when it
+     * refuses the request, `connection_lost` when it cannot be reached or is busy (its sentence when it gave one). Without
+     * a sign-in it does not read the CLI's files.
+     */
+    discover(): Promise<Discovery>;
+    /** What the key server said about the signed-in person (`discover()`), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. Connecting by name reads the same answer. */
+    readonly discovery: StateValue<DiscoveryState>;
     /** The node's engine (the SDK's own modules and tests use it). */
     get node(): Node;
     /** Where the node stands (`ConnectionState`), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. */
@@ -74,18 +99,15 @@ export declare class Synapse implements AsyncDisposable {
     /** The topic's latest value as a view (SDK §4.3); subscribed while someone listens. */
     view<TIn, TOut, S = TOut>(topic: TopicContract<TIn, TOut>, opts?: ViewOptions<TOut, S>): View<S>;
     view<TOut = unknown, S = TOut>(topic: string, opts?: ViewOptions<TOut, S>): View<S>;
-    /** Starts a call on the current session (SDK §5.2): `await` it for the result, or read `updates()` first. With no session (before the first, between two) the Run is already failed `not_connected`: nothing was sent. */
+    /** Starts a call on the current session (SDK §5.2): `await` it for the result, read its updates (`for await (const u of run)`, `await run.next()`), or pass `onUpdate`. With no session (before the first, between two) the Run is already failed `not_connected`: nothing was sent. */
     call<TArgs, TInput, U, R>(svc: ServiceContract<TArgs, TInput, U, R>, args: TArgs, opts?: CallOptions<U>): Run<U, R>;
     call<U = unknown, R = unknown>(svc: string, args?: unknown, opts?: CallOptions<U>): Run<U, R>;
-    /** The call's updates and result as one ordered stream; `break` cancels. */
-    callStream<TArgs, TInput, U, R>(svc: ServiceContract<TArgs, TInput, U, R>, args: TArgs, opts?: CallOptions<U>): AsyncGenerator<CallEvent<U, R>, void, undefined>;
-    callStream<U = unknown, R = unknown>(svc: string, args?: unknown, opts?: CallOptions<U>): AsyncGenerator<CallEvent<U, R>, void, undefined>;
     /** Registers `handler` as the provider of `svc`; resolves once the runtime lists us on the current session. One provider per service path per node. */
     serve<TArgs, TInput, U, R>(svc: ServiceContract<TArgs, TInput, U, R>, handler: ServeHandler<TInput, U, R>, opts?: ServeOptions): Promise<Registration>;
     serve<I = unknown, U = unknown, R = unknown>(svc: string, handler: ServeHandler<I, U, R>, opts?: ServeOptions): Promise<Registration>;
     /** Opens namespace `name` (SDK §9); resolves once the mirror is in (or the namespace is known absent). */
     store(name: string, opts?: StoreOptions): Promise<StoreHandle>;
-    /** The active project's scene (PLAN v0.24 §5); resolves attached, or at once `detached` when no project is active. */
+    /** The active project's scene (PLAN v0.24 §5); resolves attached (current as of the attach: at the version the runtime answered), or at once `detached` when no project is active. */
     scene(): Promise<SceneHandle>;
     /** The runtime's catalogs as the current session last read them (empty between sessions), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. */
     readonly catalog: StateValue<Catalog>;

package/dist/synapse.js

@@ -3,8 +3,9 @@
 // own tasks, told about sessions by the loop; every fact about the world is read from the current
 // `Session` (the runtime's statement) at the moment it is asked for, never copied here.
 import { SynapseError, ageOf, fecSymbolSizeFor, isServiceContract, nowUs, resolveTopic, serviceName, } from "@synapse-sdk/core";
-import { callStream, failedRun, startOn } from "./calls.js";
+import { failedRun, startOn } from "./calls.js";
 import { Node, createNode, endpointDial, resolveTarget } from "./node.js";
+import { DEFAULT_AUTH_URL, notSignedIn } from "./keyserver.js";
 import { ServiceRegistration } from "./serve.js";
 import { openScene } from "./scene.js";
 import { Namespace, StoreHandleImpl, attachStore, openStore } from "./store.js";
@@ -25,18 +26,21 @@ function descKey(d) {
     return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null, fec: d.fec ?? null });
 }
 /**
- * A fact of the node as a state value (`node.status`, `node.catalog`, `node.project`): `read` is the fact now, the same
- * object while it is unchanged. It changes with the node's link and, while connected, with the current session's values
- * that `watched` names; a callback is rebound to the new session's values on every link change.
+ * A fact of the node as a state value (`node.status`, `node.catalog`, `node.project`, `node.discovery`): `read` is the fact
+ * now, the same object while it is unchanged. It changes with the node's link, with the node's own values `kept` names,
+ * and, while connected, with the current session's values that `watched` names; a callback is rebound to the new
+ * session's values on every link change.
  */
 class NodeCell {
     node;
     read;
     watched;
-    constructor(node, read, watched) {
+    kept;
+    constructor(node, read, watched, kept = []) {
         this.node = node;
         this.read = read;
         this.watched = watched;
+        this.kept = kept;
     }
     get() { return this.read(); }
     /** `cb` with the value on each change of what it is read from; returns the remover. */
@@ -51,7 +55,9 @@ class NodeCell {
         };
         bind();
         const unLink = this.node.link.subscribe(() => { bind(); listener(); });
-        return () => { unLink(); for (const u of un)
+        const unKept = this.kept.map(c => c.subscribe(listener));
+        return () => { unLink(); for (const u of unKept)
+            u(); for (const u of un)
             u(); };
     }
     /** The value after its next change; once the node ends, the value then, whether or not it changed (nothing will change any more). */
@@ -104,9 +110,11 @@ export class Synapse {
             return lastCatalog;
         }, s => [s.topics, s.services]);
         this.project = new NodeCell(n, () => n.currentSession()?.project.get(), s => [s.project]);
+        this.discovery = new NodeCell(n, () => n.discovery.get(), () => [], [n.discovery]);
     }
     /**
-     * Connects the node to `target` (a string is the url), the one connect verb: the first connect, and how an HMI moves
+     * Connects the node to `target` (a string is the url: a URL, or in Bun/Node a target such as `"infra-1@devel"`, see
+     * `ConnectTarget.url`), the one connect verb: the first connect, and how an HMI moves
      * from one robot's runtime to another. The current session, if any, is torn down before `target` is dialed; every
      * handle re-binds to the new session as across a reconnect. Identity fields `target` leaves out keep the node's.
      *
@@ -149,6 +157,34 @@ export class Synapse {
      * resolves quietly). Resolves once the session is gone; already `idle`: at once. `not_connected` once the node has ended.
      */
     disconnect() { return this.#node.declare(undefined); }
+    // -------------------------------------------------------------------------------- sign-in
+    /**
+     * Signs a person in for connecting by name (`connect("infra-1@devel")`) through the key server: `fetchToken` gives the
+     * person's credential and is called each time the key server is asked (never kept); `authUrl` is the key server
+     * (default `https://e9e413af.synapse.build`; an `http://` one is taken as it is, for a key server on your own machine while
+     * developing, never in production: the credential travels in the header). `setAuth(undefined)` signs out. Either way,
+     * what the node kept from the key server (your clusters, the cluster tokens) is forgotten and `discovery` is `idle` again.
+     *
+     * A live session is never touched: the sign-in is read only when the node dials, so signing out ends nothing now, and
+     * the next dial of a target named by name fails `unauthorized` (`failed`). With a person signed in, a target named by
+     * name is resolved through the key server also in Bun/Node, instead of the CLI's files. Call it before `connect()`.
+     */
+    setAuth(fetchToken, opts = {}) { this.#node.setAuth(fetchToken, opts.authUrl ?? DEFAULT_AUTH_URL); }
+    /**
+     * Asks the key server for the signed-in person's clusters and their runtimes, sets `discovery` from the answer and
+     * resolves with it; one request at a time (a call while one is out joins it). Rejects `unauthorized` when nobody is
+     * signed in (`setAuth`; `discovery` stays `idle`) or the key server does not take the sign-in, `invalid_input` when it
+     * refuses the request, `connection_lost` when it cannot be reached or is busy (its sentence when it gave one). Without
+     * a sign-in it does not read the CLI's files.
+     */
+    discover() {
+        const auth = this.#node.auth;
+        const p = auth ? auth.discover() : Promise.reject(notSignedIn());
+        p.catch(() => { });
+        return p;
+    }
+    /** What the key server said about the signed-in person (`discover()`), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. Connecting by name reads the same answer. */
+    discovery;
     /** The node's engine (the SDK's own modules and tests use it). */
     get node() { return this.#node; }
     #session() { return this.#node.currentSession(); }
@@ -240,9 +276,6 @@ export class Synapse {
         const contract = isServiceContract(svc) ? svc : undefined;
         return startOn(this.node, s, serviceName(svc), args, opts, contract);
     }
-    callStream(svc, args = {}, opts = {}) {
-        return callStream(this.call(svc, args, opts));
-    }
     async serve(svc, handler, opts = {}) {
         const n = this.node;
         const name = serviceName(svc);
@@ -273,7 +306,7 @@ export class Synapse {
     store(name, opts = {}) { return openStore(this.node, this.#stores, name, opts, this.warn); }
     // ---------------------------------------------------------------------------------- scene
     #scenes = { current: undefined };
-    /** The active project's scene (PLAN v0.24 §5); resolves attached, or at once `detached` when no project is active. */
+    /** The active project's scene (PLAN v0.24 §5); resolves attached (current as of the attach: at the version the runtime answered), or at once `detached` when no project is active. */
     scene() { return openScene(this.node, this.#scenes, this.warn); }
     // -------------------------------------------------------------------------------- catalog
     /** The runtime's catalogs as the current session last read them (empty between sessions), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. */