@synapse-sdk/client 0.3.3 → 0.3.6

package/dist/synapse.d.ts

@@ -1,44 +1,58 @@
-import { type Age, type ClockInfo, type ErrorBody, type LocalTime, type ProjectSnapshot, type ServiceContract, type TimeOffsets, type TopicContract } from "@synapse-sdk/core";
+import { type Age, type ErrorBody, type ProjectSnapshot, type ServiceContract, type TopicContract } from "@synapse-sdk/core";
 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, Notice, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, Tasks, View, ViewOptions } from "./types.ts";
-/** How long the first `connect()` keeps trying a retryable failure before `failed` (SDK §2: the first connect is bounded). */
-export declare const FIRST_CONNECT_GIVE_UP_MS = 30000;
+import type { 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 StateValue } from "./util.ts";
+export { FIRST_CONNECT_GIVE_UP_MS } from "./node.ts";
 export declare class Synapse implements AsyncDisposable {
     #private;
     warn: Warn;
+    /**
+     * The node, usable at once and `idle` (no target) until `connect()`: constructing opens no connection. Where to connect
+     * (the url, its token, the certificate pin) is the target's, given to `connect()`. Throws `invalid_input` for options
+     * that can never work (a bad `name`).
+     */
     constructor(opts: ConnectOptions);
-    /** `await Synapse.connect(opts)`: a node with a session, or the reason there is none. */
-    static connect(opts: ConnectOptions): Promise<Synapse>;
-    /** Connects (once; later calls return the same promise). Resolves once a session is established. */
-    connect(): Promise<this>;
+    /**
+     * Connects the node to `target` (a string is the 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.
+     *
+     * Operator intent is never lost under quick clicking: the newest call wins. The node works toward its latest target; a
+     * call superseded by a newer `connect()` or `disconnect()` resolves quietly. The target already declared declares
+     * nothing and settles with it, except from its own `failed`, where it is dialed again.
+     *
+     * Bounded (SDK §2): a retryable failure is tried again, paced by the reconnect policy, until `FIRST_CONNECT_GIVE_UP_MS`
+     * after the first attempt, a hard bound (an attempt still outstanding then is cut); `unauthorized` gives up at once.
+     * Resolves once a session to *this* target is connected (or a newer call superseded it). Rejects with this target's
+     * error when the node rests `failed` (still usable: `connect()` dials again), `invalid_input` at once for a malformed
+     * target, `not_connected` once the node has ended (`close()`).
+     *
+     * With no target: the declared target, if there is one (settles with it, as above), else `SYNAPSE_ENDPOINT` (Bun/Node;
+     * the runtime sets it for every task it starts); neither (or a browser) is `invalid_input` and the node stays `idle`.
+     *
+     * The outcome is handled: `node.connect(url);` without a handler is safe (`useConnection()` shows `failed`); `await` still rejects.
+     */
+    connect(target?: ConnectTarget | string): Promise<this>;
+    /**
+     * Disconnects: the session, if any, is torn down and the node rests `idle` (no target), not ended. Every handle is kept,
+     * exactly as between two sessions, and a later `connect()` dials again. A `connect()` still pursuing is superseded (it
+     * resolves quietly). Resolves once the session is gone; already `idle`: at once. `not_connected` once the node has ended.
+     */
+    disconnect(): Promise<void>;
+    /** The node's engine (the SDK's own modules and tests use it). */
     get node(): Node;
-    get status(): ConnectionState;
-    get connected(): boolean;
-    /** Called on every change of the connection state; returns the unsubscribe. */
-    watchStatus(cb: (s: ConnectionState) => void): () => void;
-    /** Resolves on the next connected session (at once if connected); rejects once the node ended. */
-    whenConnected(): Promise<void>;
-    /** Declares a new target (broker, identity); resolves once connected to it (or rejects with why not). `null` disconnects for good. */
-    setTarget(target: ConnectTarget | null): Promise<void>;
-    /** Tells the runtime we are leaving, ends every handle, and resolves once the node has ended. */
-    /** During the first `connect()` it ends that attempt: the node ends `closed` and `connect()` rejects `not_connected`. */
+    /** 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. */
+    readonly status: StateValue<ConnectionState>;
+    /** Tells the runtime we are leaving, ends every handle, and resolves once the node has ended (`closed`, for good). A `connect()` in flight rejects `not_connected`. */
     close(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
-    /** Resolves once the node has ended (closed, failed, or the policy gave up). */
-    get ended(): Promise<void>;
     info(): Info;
     metrics(): Metrics;
-    /** Broker notices addressed to this node (an error body on `res` without a call). */
-    onNotice(cb: (n: ErrorBody) => void): () => void;
-    /** `promoted`/`demoted` notices (WP §3.5). */
-    onProjectNotice(cb: (n: Notice) => void): () => void;
+    /** Notices addressed to this node: `cb` per notice (an error body on `res` without a call, and a refused live override claim of this node's scene); returns the unsubscribe. */
+    notices(cb: (n: ErrorBody) => void): () => void;
     nowUs(): number;
-    clock(): ClockInfo;
-    timeOffsets(): TimeOffsets;
-    /** A publisher stamp in our clock (WP §7.4), when the offsets allow it. */
-    toLocalUs(tUs: number, dom: string): LocalTime | undefined;
     /** How old a message is now, in our clock. */
     ageUs(env: {
         tUs: number;
@@ -47,43 +61,53 @@ export declare class Synapse implements AsyncDisposable {
     /** A publisher of `topic`; resolves once the runtime admitted it on the current session (a refusal is asked again, paced, warned). */
     publisher<TIn, TOut>(topic: TopicContract<TIn, TOut>): Promise<Publisher<TIn>>;
     publisher<TIn = unknown>(topic: string): Promise<Publisher<TIn>>;
-    /** A subscription to `topic` (every publisher the catalog lists but ourselves); its follow task starts now. */
+    /**
+     * A subscription to `topic` (every publisher the catalog lists but ourselves), the stream: read it with `next()` or
+     * `for await`. Its follow task starts now. With `cb`, the callback form: the SDK runs the read loop and calls `cb` with
+     * each batch `next()` returns (a throwing `cb` is rethrown later; the loop goes on); the same subscription comes back
+     * (`unsubscribe()` ends it, `stats` counts it).
+     */
     subscribe<TIn, TOut>(topic: TopicContract<TIn, TOut>, opts?: SubscribeOptions): Subscription<TOut>;
+    subscribe<TIn, TOut>(topic: TopicContract<TIn, TOut>, cb: (batch: Envelope<TOut>[]) => void, opts?: SubscribeOptions): Subscription<TOut>;
     subscribe<TOut = unknown>(topic: string, opts?: SubscribeOptions): Subscription<TOut>;
-    /** The topic's latest value as a cell (SDK §4.3); subscribed while someone listens. */
+    subscribe<TOut = unknown>(topic: string, cb: (batch: Envelope<TOut>[]) => void, opts?: SubscribeOptions): Subscription<TOut>;
+    /** 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. `not_connected` between sessions. */
+    /** 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 runtime's `config` namespace (operators write it). */
-    config(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. */
-    get catalog(): Catalog;
-    /** Called when either catalog changes on the current session. */
-    watchCatalog(cb: (c: Catalog) => void): () => void;
-    /** The project state the current session last read (WP §3.5); `undefined` between sessions or before the first snapshot. */
-    project(): ProjectSnapshot | undefined;
-    watchProject(cb: (p: ProjectSnapshot | undefined) => void): () => void;
-    /** `synapse/project/activate {id}`: activates `id` (or joins it when active); promoted to operator. */
+    /** 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>;
+    /** The project state the current session last read (WP §3.5), a state value; `get()` is `undefined` between sessions or before the first snapshot. */
+    readonly project: StateValue<ProjectSnapshot | undefined>;
+    /**
+     * `synapse/project/activate {id}`: activates `id` when no project is active, or joins it when it is the active one;
+     * `project_busy` while another project is active (no takeover: deactivate it first). A web node is promoted to
+     * operator and resolves once the session with the new role is connected; an hmi stays `hmi` and resolves on the answer.
+     */
     activateProject(id: string): Promise<ProjectSnapshot>;
-    /** `synapse/project/deactivate {}`: every operator is demoted. */
+    /**
+     * `synapse/project/deactivate {}`: any operator or hmi may deactivate, except a project an hmi activated
+     * (`active.activated_by_hmi`), which only an hmi may (`not_operator`). Every web operator is demoted; when that
+     * demotes this node, resolves once the demoted session is connected. An hmi is never demoted.
+     */
     deactivateProject(): Promise<ProjectSnapshot>;
-    /** `synapse/project/join {as: "operator"}`: promoted on the active project, or `project_inactive`. */
+    /** `synapse/project/join {as: "operator"}`: an operator of the active project, or `project_inactive`. A web node resolves once the promoted session is connected; an hmi on the answer. */
     joinProject(as?: "operator"): Promise<ProjectSnapshot>;
-    /** `synapse/project/leave {}`: drops our standing (every session of our `user_id`). */
+    /**
+     * `synapse/project/leave {}`: drops our standing. For an hmi membership is per session: this session only (it stays
+     * `hmi`, never closed). For a web node it removes our `user_id`'s web sessions only; when that demotes this node,
+     * resolves once the demoted session is connected.
+     */
     leaveProject(): Promise<ProjectSnapshot>;
-    getProject(): Promise<ProjectSnapshot>;
     /**
      * The robot's task declarations, what runs (`status`), what the runtime can run (`catalog`), and the verbs; the same
      * object for the node's life. Each handle opens on its first touch and is the node's own (`node.close()` ends it).

package/dist/synapse.js

@@ -2,17 +2,17 @@
 // loop (`node.ts`) drives sessions; publishers, registrations, subscriptions and namespaces are their
 // 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 { ClockSync, SynapseError, ageOf, defaultDomId, fecSymbolSizeFor, isServiceContract, nowUs, resolveTopic, serviceName, toLocalUs, } from "@synapse-sdk/core";
-import { callStream, startOn } from "./calls.js";
-import { Node, resolveTarget, startNode } from "./node.js";
+import { SynapseError, ageOf, fecSymbolSizeFor, isServiceContract, nowUs, resolveTopic, serviceName, } from "@synapse-sdk/core";
+import { failedRun, startOn } from "./calls.js";
+import { Node, createNode, endpointDial, resolveTarget } from "./node.js";
 import { ServiceRegistration } from "./serve.js";
 import { openScene } from "./scene.js";
 import { Namespace, StoreHandleImpl, attachStore, openStore } from "./store.js";
 import { TasksFacet } from "./tasks.js";
 import { PublisherHandle, TopicPublisher, TopicSubscription, wasmFor } from "./topics.js";
 import { TopicView } from "./view.js";
-/** How long the first `connect()` keeps trying a retryable failure before `failed` (SDK §2: the first connect is bounded). */
-export const FIRST_CONNECT_GIVE_UP_MS = 30_000;
+import { watchState } from "./util.js";
+export { FIRST_CONNECT_GIVE_UP_MS } from "./node.js";
 /** The descriptor a publisher of `contract` on node `n` declares (as `TopicPublisher` builds it: a `fec` symbol size of 0 is the node's). */
 function wantedDesc(contract, n) {
     const d = contract.desc(n.dom);
@@ -24,73 +24,140 @@ function wantedDesc(contract, n) {
 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.
+ */
+class NodeCell {
+    node;
+    read;
+    watched;
+    constructor(node, read, watched) {
+        this.node = node;
+        this.read = read;
+        this.watched = watched;
+    }
+    get() { return this.read(); }
+    /** `cb` with the value on each change of what it is read from; returns the remover. */
+    onChange(cb) {
+        const listener = () => cb(this.read());
+        let un = [];
+        const bind = () => {
+            for (const u of un)
+                u();
+            const s = this.node.currentSession();
+            un = s ? this.watched(s).map(c => c.subscribe(listener)) : [];
+        };
+        bind();
+        const unLink = this.node.link.subscribe(() => { bind(); listener(); });
+        return () => { unLink(); 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). */
+    changed() {
+        const from = this.read();
+        if (this.node.isEnded)
+            return Promise.resolve(from);
+        return new Promise(resolve => {
+            let done = false;
+            const finish = (v) => { if (done)
+                return; done = true; un(); resolve(v); };
+            const un = this.onChange(v => { if (v !== from)
+                finish(v); });
+            void this.node.ended.promise.then(() => finish(this.read()));
+        });
+    }
+    /** The value after each change; ends when the node ends. */
+    watch() { return watchState(cb => this.onChange(cb), this.read, () => this.node.isEnded); }
+}
+const NO_TOPICS = Object.freeze({});
+const NO_SERVICES = Object.freeze({});
 export class Synapse {
     #node;
-    #connecting;
-    #starting;
     #publishers = new Map();
     #stores = new Map();
     warn;
-    // Private: the options hold the token and the credential, which nothing prints.
-    #opts;
+    /**
+     * The node, usable at once and `idle` (no target) until `connect()`: constructing opens no connection. Where to connect
+     * (the url, its token, the certificate pin) is the target's, given to `connect()`. Throws `invalid_input` for options
+     * that can never work (a bad `name`).
+     */
     constructor(opts) {
-        this.#opts = opts;
         this.warn = msg => console.warn(`[synapse] ${msg}`);
+        const n = this.#node = createNode(opts);
+        let lastLink = n.link.get(), lastState = n.state();
+        this.status = new NodeCell(n, () => {
+            const l = n.link.get();
+            if (l !== lastLink) {
+                lastLink = l;
+                lastState = n.state();
+            }
+            return lastState;
+        }, () => []);
+        let lastCatalog;
+        this.catalog = new NodeCell(n, () => {
+            const s = n.currentSession();
+            const topics = s?.topics.get().topics ?? NO_TOPICS, services = s?.services.get().services ?? NO_SERVICES;
+            if (lastCatalog?.topics !== topics || lastCatalog.services !== services)
+                lastCatalog = { topics, services, describe: name => services[name]?.card };
+            return lastCatalog;
+        }, s => [s.topics, s.services]);
+        this.project = new NodeCell(n, () => n.currentSession()?.project.get(), s => [s.project]);
     }
-    /** `await Synapse.connect(opts)`: a node with a session, or the reason there is none. */
-    static connect(opts) { return new Synapse(opts).connect(); }
-    /** Connects (once; later calls return the same promise). Resolves once a session is established. */
-    connect() {
-        this.#connecting ??= (async () => {
-            const started = startNode(this.#opts, FIRST_CONNECT_GIVE_UP_MS);
-            // The node as soon as its loop runs (or none: the options were refused), for a `close()` during the first dial.
-            this.#starting = started.then(s => s.node, () => undefined);
-            const { node, connected } = await started;
-            await connected;
-            this.#node = node;
-            return this;
-        })();
-        return this.#connecting;
-    }
-    get node() {
-        if (!this.#node)
-            throw new SynapseError("not_connected", "connect() has not completed");
-        return this.#node;
-    }
-    #session() { return this.node.currentSession(); }
-    // ------------------------------------------------------------------------------ lifecycle
-    get status() { return this.#node?.state() ?? { status: "connecting", attempt: 1 }; }
-    get connected() { return this.#node?.isConnected ?? false; }
-    /** Called on every change of the connection state; returns the unsubscribe. */
-    watchStatus(cb) { return this.node.link.subscribe(() => cb(this.node.state())); }
-    /** Resolves on the next connected session (at once if connected); rejects once the node ended. */
-    whenConnected() {
-        const n = this.node;
-        if (n.isConnected)
-            return Promise.resolve();
+    /**
+     * Connects the node to `target` (a string is the 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.
+     *
+     * Operator intent is never lost under quick clicking: the newest call wins. The node works toward its latest target; a
+     * call superseded by a newer `connect()` or `disconnect()` resolves quietly. The target already declared declares
+     * nothing and settles with it, except from its own `failed`, where it is dialed again.
+     *
+     * Bounded (SDK §2): a retryable failure is tried again, paced by the reconnect policy, until `FIRST_CONNECT_GIVE_UP_MS`
+     * after the first attempt, a hard bound (an attempt still outstanding then is cut); `unauthorized` gives up at once.
+     * Resolves once a session to *this* target is connected (or a newer call superseded it). Rejects with this target's
+     * error when the node rests `failed` (still usable: `connect()` dials again), `invalid_input` at once for a malformed
+     * target, `not_connected` once the node has ended (`close()`).
+     *
+     * With no target: the declared target, if there is one (settles with it, as above), else `SYNAPSE_ENDPOINT` (Bun/Node;
+     * the runtime sets it for every task it starts); neither (or a browser) is `invalid_input` and the node stays `idle`.
+     *
+     * The outcome is handled: `node.connect(url);` without a handler is safe (`useConnection()` shows `failed`); `await` still rejects.
+     */
+    connect(target) {
+        const n = this.#node;
+        let p;
         if (n.isEnded)
-            return Promise.reject(new SynapseError("not_connected", "node closed"));
-        return new Promise((resolve, reject) => {
-            const un = n.link.subscribe(l => { if (l.status === "connected") {
-                un();
-                resolve();
-            } });
-            // The node's end settles it (a resolved promise ignores the later reject).
-            void n.ended.promise.then(() => { un(); reject(new SynapseError("not_connected", "node closed")); });
-        });
-    }
-    /** Declares a new target (broker, identity); resolves once connected to it (or rejects with why not). `null` disconnects for good. */
-    setTarget(target) { return this.node.setTarget(target ? resolveTarget(this.node, target) : undefined); }
-    /** Tells the runtime we are leaving, ends every handle, and resolves once the node has ended. */
-    /** During the first `connect()` it ends that attempt: the node ends `closed` and `connect()` rejects `not_connected`. */
-    async close() {
-        const n = this.#node ?? (await this.#starting);
-        if (n)
-            await n.close();
+            p = Promise.reject(new SynapseError("not_connected", "node closed"));
+        else {
+            let dial;
+            try {
+                dial = target === undefined ? (n.target.get().dial ?? endpointDial(n)) : resolveTarget(n, typeof target === "string" ? { url: target } : target);
+            }
+            catch (e) {
+                return Promise.reject(e);
+            }
+            p = n.declare(dial).then(() => this);
+        }
+        p.catch(() => { });
+        return p;
     }
+    /**
+     * Disconnects: the session, if any, is torn down and the node rests `idle` (no target), not ended. Every handle is kept,
+     * exactly as between two sessions, and a later `connect()` dials again. A `connect()` still pursuing is superseded (it
+     * 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); }
+    /** The node's engine (the SDK's own modules and tests use it). */
+    get node() { return this.#node; }
+    #session() { return this.#node.currentSession(); }
+    // ------------------------------------------------------------------------------ lifecycle
+    /** 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. */
+    status;
+    /** Tells the runtime we are leaving, ends every handle, and resolves once the node has ended (`closed`, for good). A `connect()` in flight rejects `not_connected`. */
+    async close() { await this.#node.close(); }
     async [Symbol.asyncDispose]() { await this.close(); }
-    /** Resolves once the node has ended (closed, failed, or the policy gave up). */
-    get ended() { return this.node.ended.promise; }
     info() {
         const n = this.node;
         const id = n.target.get().identity;
@@ -98,21 +165,17 @@ export class Synapse {
         return { name: id.name ?? "", type: id.type, userId: id.user_id, prefix: s?.prefix ?? "", role: s?.role ?? "observer", dom: n.dom, brokerDom: s?.hello.dom ?? "", brokerVersion: s?.hello.broker_version ?? "", robot: s?.hello.robot ?? "", runtimeName: s?.hello.runtime_name ?? "", runtimeId: s?.hello.runtime_id ?? "", url: n.target.get().dial?.url ?? "" };
     }
     metrics() { const n = this.node; return { sessions: n.epochs, reconnects: n.reconnects, callsSent: n.callsSent, callsAnswered: n.callsAnswered }; }
-    /** Broker notices addressed to this node (an error body on `res` without a call). */
-    onNotice(cb) { this.node.notices.add(cb); return () => { this.node.notices.delete(cb); }; }
-    /** `promoted`/`demoted` notices (WP §3.5). */
-    onProjectNotice(cb) { this.node.projectNotices.add(cb); return () => { this.node.projectNotices.delete(cb); }; }
+    /** Notices addressed to this node: `cb` per notice (an error body on `res` without a call, and a refused live override claim of this node's scene); returns the unsubscribe. */
+    notices(cb) { this.node.notices.add(cb); return () => { this.node.notices.delete(cb); }; }
     // ---------------------------------------------------------------------------------- clock
     nowUs() { return nowUs(); }
-    clock() { const s = this.#session(); return s ? s.clock.get() : new ClockSync(this.node.dom.id, "", 0).info(); }
-    timeOffsets() { return this.#session()?.timeOffsets.get() ?? {}; }
-    /** A publisher stamp in our clock (WP §7.4), when the offsets allow it. */
-    toLocalUs(tUs, dom) { const s = this.#session(); return s ? toLocalUs(s.clock.get(), s.timeOffsets.get(), tUs, dom) : undefined; }
     /** How old a message is now, in our clock. */
     ageUs(env) { const s = this.#session(); return s ? ageOf(s.clock.get(), s.timeOffsets.get(), env.tUs, env.dom, nowUs()) : undefined; }
     async publisher(topic) {
         const contract = resolveTopic(topic);
         const n = this.node;
+        // Its descriptor names the node's time domain: final before any publisher is made.
+        await n.prepared;
         const name = contract.name;
         let p;
         let held;
@@ -157,9 +220,13 @@ export class Synapse {
         }
         return h;
     }
-    subscribe(topic, opts = {}) {
+    subscribe(topic, cbOrOpts, opts = {}) {
         const contract = resolveTopic(topic);
-        return new TopicSubscription(this.node, contract, opts, this.warn);
+        if (typeof cbOrOpts !== "function")
+            return new TopicSubscription(this.node, contract, cbOrOpts ?? {}, this.warn);
+        const sub = new TopicSubscription(this.node, contract, opts, this.warn);
+        sub.deliverTo(cbOrOpts);
+        return sub;
     }
     view(topic, opts = {}) {
         const contract = resolveTopic(topic);
@@ -169,13 +236,10 @@ export class Synapse {
     call(svc, args = {}, opts = {}) {
         const s = this.#session();
         if (!s)
-            throw new SynapseError("not_connected", "no session: the call was not sent");
+            return failedRun(new SynapseError("not_connected", "no session: the call was not sent"));
         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);
@@ -204,57 +268,57 @@ export class Synapse {
     // ---------------------------------------------------------------------------------- store
     /** Opens namespace `name` (SDK §9); resolves once the mirror is in (or the namespace is known absent). */
     store(name, opts = {}) { return openStore(this.node, this.#stores, name, opts, this.warn); }
-    /** The runtime's `config` namespace (operators write it). */
-    config(opts = {}) { return this.store("config", opts); }
     // ---------------------------------------------------------------------------------- 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. */
-    get catalog() {
-        const s = this.#session();
-        const topics = s?.topics.get().topics ?? {};
-        const services = s?.services.get().services ?? {};
-        return { topics, services, describe: name => services[name]?.card };
-    }
-    /** Called when either catalog changes on the current session. */
-    watchCatalog(cb) {
-        let un = [];
-        const bind = () => {
-            for (const u of un)
-                u();
-            un = [];
-            const s = this.#session();
-            if (!s)
-                return;
-            un.push(s.topics.subscribe(() => cb(this.catalog)), s.services.subscribe(() => cb(this.catalog)));
-        };
-        bind();
-        const unLink = this.node.link.subscribe(() => { bind(); cb(this.catalog); });
-        return () => { unLink(); for (const u of un)
-            u(); };
-    }
+    /** 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. */
+    catalog;
     // -------------------------------------------------------------------------------- project
-    /** The project state the current session last read (WP §3.5); `undefined` between sessions or before the first snapshot. */
-    project() { return this.#session()?.project.get(); }
-    watchProject(cb) {
-        let un;
-        const bind = () => { un?.(); un = this.#session()?.project.subscribe(p => cb(p)); };
-        bind();
-        const unLink = this.node.link.subscribe(() => { bind(); cb(this.project()); });
-        return () => { unLink(); un?.(); };
+    /** The project state the current session last read (WP §3.5), a state value; `get()` is `undefined` between sessions or before the first snapshot. */
+    project;
+    /**
+     * A project call on the current session. The runtime tells a web session whose role it changed before it answers on
+     * it (the notice, then the answer, on the same `res` track, read in order) and closes it `role_changed` after: a role
+     * that differs from the session's hello grant means the switch is coming, and the call resolves once a session other
+     * than the one it went out on is connected (`not_connected` if the node ends or is disconnected meanwhile, the error
+     * if it rests `failed`). An hmi's role is `hmi` from admission and never changes, so its calls resolve on the answer.
+     */
+    async #projectCall(op, args) {
+        const n = this.node;
+        const asked = n.currentSession();
+        if (!asked)
+            throw new SynapseError("not_connected", "no session: the call was not sent");
+        const snapshot = await startOn(n, asked, `synapse/project/${op}`, args, {}).result;
+        if (asked.role !== asked.hello.role) {
+            // The runtime replaces this session (the role changed): its close is expected, as one we make ourselves, so
+            // @moq/net's track and discovery lines about it are routine (moq_log.ts).
+            asked.log?.closing();
+            await n.switchedFrom(asked);
+        }
+        return snapshot;
     }
-    #projectCall(op, args) { return this.call(`synapse/project/${op}`, args).result; }
-    /** `synapse/project/activate {id}`: activates `id` (or joins it when active); promoted to operator. */
+    /**
+     * `synapse/project/activate {id}`: activates `id` when no project is active, or joins it when it is the active one;
+     * `project_busy` while another project is active (no takeover: deactivate it first). A web node is promoted to
+     * operator and resolves once the session with the new role is connected; an hmi stays `hmi` and resolves on the answer.
+     */
     activateProject(id) { return this.#projectCall("activate", { id }); }
-    /** `synapse/project/deactivate {}`: every operator is demoted. */
+    /**
+     * `synapse/project/deactivate {}`: any operator or hmi may deactivate, except a project an hmi activated
+     * (`active.activated_by_hmi`), which only an hmi may (`not_operator`). Every web operator is demoted; when that
+     * demotes this node, resolves once the demoted session is connected. An hmi is never demoted.
+     */
     deactivateProject() { return this.#projectCall("deactivate", {}); }
-    /** `synapse/project/join {as: "operator"}`: promoted on the active project, or `project_inactive`. */
+    /** `synapse/project/join {as: "operator"}`: an operator of the active project, or `project_inactive`. A web node resolves once the promoted session is connected; an hmi on the answer. */
     joinProject(as = "operator") { return this.#projectCall("join", { as }); }
-    /** `synapse/project/leave {}`: drops our standing (every session of our `user_id`). */
+    /**
+     * `synapse/project/leave {}`: drops our standing. For an hmi membership is per session: this session only (it stays
+     * `hmi`, never closed). For a web node it removes our `user_id`'s web sessions only; when that demotes this node,
+     * resolves once the demoted session is connected.
+     */
     leaveProject() { return this.#projectCall("leave", {}); }
-    getProject() { return this.#projectCall("get", {}); }
     // -------------------------------------------------------------------------------- tasks
     #tasks;
     /**

package/dist/tasks.d.ts

@@ -8,7 +8,7 @@ export declare const TASKS_NAMESPACES: {
     readonly status: "task_status";
     readonly catalog: "task_catalog";
 };
-/** What `status.value` is before the runtime said anything: neither scope's state known, no tasks. */
+/** What `status.get()` is before the runtime said anything: neither scope's state known, no tasks. */
 export declare const EMPTY_TASKS_STATUS: TasksStatus;
 /**
  * `task_status`'s rows as a `TasksStatus`. A run row is the one keyed `robot` or `project`; an instance