@synapse-sdk/client 0.3.3 → 0.3.4

package/dist/scene_frames.d.ts

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

package/dist/scene_frames.js

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

package/dist/session.d.ts

@@ -83,7 +83,7 @@ export declare function ensureWebTransport(): Promise<void>;
 export declare function describeError(e: unknown): string;
 /**
  * The error of a session's close (`classify_close`): `admission_refused` travels as the application
- * close code (retryable: a live session may hold this name, the project may be settling), another
+ * close code (retryable: a live session holds this name; a crashed one is released after the idle timeout), another
  * application code is a broker-side failure, `unauthorized` is the relay's own refusal, everything
  * else is the transport (`connection_lost`); a clean close is a drop too (in one-shot mode a broker
  * GOAWAY looks like one).
@@ -164,6 +164,8 @@ export declare class Session {
     readonly log: MoqLogScope;
     /** Counts *established* sessions of the node (SDK §2); set by the node when attached. */
     epoch: number;
+    /** The target generation this session was opened for (`Target.generation`); set by the node's loop when attached. */
+    generation: number;
     readonly startedMs: number;
     readonly transport: "webtransport" | "websocket";
     /** Datagrams travel only over WebTransport; the WebSocket fallback is stream-only. */

package/dist/session.js

@@ -313,7 +313,7 @@ const ADMISSION_REFUSED_SESSION_CODE = 64 + ADMISSION_REFUSED_CLOSE_CODE;
 const ADMISSION_REFUSED_REASON = new RegExp(`app code=${ADMISSION_REFUSED_CLOSE_CODE}(?!\\d)`);
 /**
  * The error of a session's close (`classify_close`): `admission_refused` travels as the application
- * close code (retryable: a live session may hold this name, the project may be settling), another
+ * close code (retryable: a live session holds this name; a crashed one is released after the idle timeout), another
  * application code is a broker-side failure, `unauthorized` is the relay's own refusal, everything
  * else is the transport (`connection_lost`); a clean close is a drop too (in one-shot mode a broker
  * GOAWAY looks like one).
@@ -323,7 +323,7 @@ export function closeError(err) {
         return new SynapseError("connection_lost", { message: "session closed by the broker", source: "transport" });
     const text = `${err.message} ${err.reason ?? ""}`;
     if ((err instanceof Moq.Error.Session && err.code === ADMISSION_REFUSED_SESSION_CODE) || ADMISSION_REFUSED_REASON.test(text)) {
-        return new SynapseError("admission_refused", { message: "the runtime refused this connection, retryable: a live session may hold this name, the project may be settling, or the runtime is overloaded; retry with backoff", source: "broker", cause: err });
+        return new SynapseError("admission_refused", { message: "the runtime refused this connection; retryable: a live session holds this name (a crashed one is released after the idle timeout); the SDK keeps retrying with backoff", source: "broker", cause: err });
     }
     if (err instanceof Moq.Error.Session && err.code === Moq.SessionCode.Unauthorized)
         return new SynapseError("unauthorized", { message: text.trim(), source: "broker", cause: err });
@@ -446,6 +446,8 @@ export class Session {
     log;
     /** Counts *established* sessions of the node (SDK §2); set by the node when attached. */
     epoch = 0;
+    /** The target generation this session was opened for (`Target.generation`); set by the node's loop when attached. */
+    generation = 0;
     startedMs = performance.now();
     transport;
     /** Datagrams travel only over WebTransport; the WebSocket fallback is stream-only. */

package/dist/store.d.ts

@@ -3,7 +3,7 @@ import type { Node } from "./node.ts";
 import { type Session } from "./session.ts";
 import type { Warn } from "./topics.ts";
 import type { StoreChange, StoreHandle, StoreOptions, StoreStatus } from "./types.ts";
-import { AsyncQueue, type Deferred } from "./util.ts";
+import { AsyncQueue, type Deferred, type StateValue } from "./util.ts";
 export declare const ENDED_DESTROYED = "destroyed";
 export declare const ENDED_CONNECTION_LOST = "connection_lost";
 export declare const ENDED_CLIENT = "client";
@@ -78,11 +78,19 @@ type Event = {
     epoch: string;
     version: number;
     reply: Deferred<void>;
-} | {
+}
+/** A write of handle `handle` (its parked writes are refused when it leaves). */
+ | {
     kind: "write";
+    handle: number;
     op: string;
     args: WriteOp;
     reply: Deferred<unknown>;
+}
+/** Handle `handle` was closed, others remain: its parked writes are refused. */
+ | {
+    kind: "leave";
+    handle: number;
 } | {
     kind: "writeDone";
     op: string;
@@ -107,6 +115,7 @@ export declare class Namespace {
     readonly mailbox: AsyncQueue<Event>;
     readonly exited: Deferred<void>;
     handles: number;
+    nextHandle: number;
     constructor(name: string, opts: StoreOptions, node: Node, warn: Warn);
     post(e: Event): boolean;
     request<T>(make: (reply: Deferred<T>) => Event): Promise<T>;
@@ -116,32 +125,34 @@ export declare function startNamespace(ns: Namespace, registry: Map<string, Name
 export declare class StoreHandleImpl implements StoreHandle {
     #private;
     private readonly ns;
+    /** The handle's own state, a state value: `get()` (the same object while unchanged), `onChange`, `changed()`, `watch()`. */
+    readonly status: StateValue<StoreStatus>;
     constructor(ns: Namespace);
     get name(): string;
-    /** The whole value, what the runtime has; the same object while nothing changed (reference-stable for React). */
-    get value(): Record<string, unknown>;
+    /** `get()`: the whole value, what the runtime has; the same object while nothing changed (reference-stable for React). `get(key)`: that key's value, `undefined` when absent. */
+    get(): Record<string, unknown>;
     get(key: string): unknown;
     get synced(): boolean;
-    get status(): StoreStatus;
-    /** `set(key, value)` or `set({ ...several keys })` (one atomic write); resolves once `value` shows it. */
+    /** `set(key, value)` or `set({ ...several keys })` (one atomic write); resolves once `get()` shows it. */
     set(keyOrValues: string | Record<string, unknown>, value?: unknown): Promise<void>;
     delete(key: string): Promise<void>;
     clear(): Promise<void>;
     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 framework bridge (React's `useStore`): called on every change of the value or the status. */
-    subscribe(listener: () => void): () => void;
+    /** The whole value after its next change (`store_gone` once this handle is closed). */
+    changed(): Promise<Record<string, 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). */
-    join(): Promise<void>;
-    /** `join()` under the SDK's word (Publisher and Registration have `ready()` too). */
     ready(): Promise<void>;
     close(): void;
     [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * `store(name, opts)`: one task per namespace per node; a second `store` with the same options joins
- * it (no open written), with other options `invalid_input`; one exiting is waited out.
+ * it (no open written), with other options `invalid_input`; one exiting is waited out. Without a session
+ * (before the first, between two) the task waits for the next one, like after a drop; it resolves once in.
  */
 export declare function openStore(node: Node, registry: Map<string, Namespace>, name: string, opts: StoreOptions, warn: Warn): Promise<StoreHandleImpl>;
 /**

package/dist/store.js

@@ -6,13 +6,14 @@
 // here. A refusal is asked again, paced, with a warning (R6); a transient reply paced, silently; an
 // incarnation that ends (writer gone, project switch, the owner restarted) replays the intent;
 // `destroyed` ends the handle. Writes name the epoch the mirror holds; the runtime checks ownership
-// (`not_owner`). Between incarnations (a session change, a replay) nothing is known: `store_gone`.
+// (`not_owner`). Between incarnations (a session change, a replay) nothing is known: a write then is
+// parked by the task and sent once the handle binds again (`store_gone` if it ends first).
 import * as Moq from "@moq/net";
 import { FLAGS, STORE_TRACK, SynapseError, decode as decodeBody, decodeHeader, moqPriority, storeBasePath, storeRobotScoped, } from "@synapse-sdk/core";
 import { startOn } from "./calls.js";
 import { REFOLLOW_PACE_MS, holderOf, isTransient, refusalPaceMs } from "./channel.js";
 import { latestSubscription, waitActive } from "./session.js";
-import { AsyncQueue, TIMEOUT, deferred, withTimeout } from "./util.js";
+import { AsyncQueue, StatusCell, TIMEOUT, deferred, withTimeout } from "./util.js";
 export const ENDED_DESTROYED = "destroyed";
 export const ENDED_CONNECTION_LOST = "connection_lost";
 export const ENDED_CLIENT = "client";
@@ -206,6 +207,7 @@ export class Namespace {
     mailbox = new AsyncQueue(Infinity);
     exited = deferred();
     handles = 0;
+    nextHandle = 0;
     constructor(name, opts, node, warn) {
         this.name = name;
         this.opts = opts;
@@ -239,6 +241,9 @@ async function run(ns, registry) {
     let unwatchProject;
     const joining = [];
     let versionWaiters = [];
+    /** Writes that came while no incarnation was bound (a replay, or no session yet), in arrival order: sent once the handle binds again, refused `store_gone` if it ends first. Each counts in `pending`. */
+    let parked = [];
+    const ABSENT = "the namespace is absent: open it with an access mode to create it";
     const leaveIncarnation = () => { for (const w of versionWaiters.splice(0))
         w.reply.reject(gone(name, `the handle left the incarnation before version ${w.version}`)); };
     const stopPhase = () => {
@@ -358,9 +363,12 @@ async function run(ns, registry) {
             const done = follow(ns, s, announced, access?.epoch, stop.signal);
             phase = { kind: "following", attempt, stop, done };
             void done.then(reason => post({ kind: "followEnded", attempt, reason }));
-            if (!access)
+            // Absent: honestly in (nothing to load), and nothing to write to (the parked writes are refused).
+            if (!access) {
                 for (const j of joining.splice(0))
                     j.resolve();
+                refuseParked(ABSENT);
+            }
             return;
         }
         announced.close();
@@ -389,6 +397,9 @@ async function run(ns, registry) {
         if (state.loaded && state.epoch === epoch && state.version >= wanted)
             for (const j of joining.splice(0))
                 j.resolve();
+        // The handle is bound again (the reader applied the snapshot that names the epoch): the writes parked meanwhile go out, in order, naming it.
+        if (state.ended === undefined && state.epoch !== undefined)
+            sendParked();
     };
     const join = (reply) => {
         if (phase.kind === "waitingProject") {
@@ -426,14 +437,53 @@ async function run(ns, registry) {
                 again(REFOLLOW_PACE_MS);
         }
     };
-    const write = (op, args, reply) => {
+    /**
+     * A write. Ended or absent: `store_gone`. Between incarnations (a replay, or no session yet) it is parked: a write is
+     * intent, sent once the handle binds again (the runtime decides it then), refused `store_gone` if the handle ends first;
+     * it has no deadline of its own. Bound: sent after any parked before it, naming the mirror's epoch (and claim).
+     */
+    const write = (handle, op, args, reply) => {
         if (state.ended !== undefined) {
             reply.reject(gone(name, `the handle ended (${state.ended})`));
             return;
         }
+        if (state.epoch === undefined) {
+            if (state.absent) {
+                reply.reject(gone(name, ABSENT));
+                return;
+            }
+            parked.push({ handle, op, args, reply });
+            state.setPending(state.pending + 1);
+            return;
+        }
+        sendParked();
+        send(op, args, reply);
+    };
+    /** The parked writes go out, in arrival order (the handle is bound). */
+    const sendParked = () => {
+        if (!parked.length)
+            return;
+        const ws = parked;
+        parked = [];
+        state.setPending(state.pending - ws.length);
+        for (const w of ws)
+            send(w.op, w.args, w.reply);
+    };
+    /** The parked writes are refused `store_gone` (`why`): all of them (the handle ended, or the namespace is absent), or those of handle `of` (that handle was closed, others stay open). */
+    const refuseParked = (why, of) => {
+        const ws = parked.filter(w => of === undefined || w.handle === of);
+        if (!ws.length)
+            return;
+        parked = parked.filter(w => !ws.includes(w));
+        state.setPending(state.pending - ws.length);
+        for (const w of ws)
+            w.reply.reject(gone(name, why));
+    };
+    /** One write on the wire, naming the bound epoch (and claim); answered by the broker (`writeDone`). */
+    const send = (op, args, reply) => {
         const epoch = state.epoch;
         if (epoch === undefined) {
-            reply.reject(state.absent ? gone(name, "the namespace is absent: open it with an access mode to create it") : gone(name, "no incarnation is bound: the intent is being replayed"));
+            reply.reject(gone(name, "no incarnation is bound"));
             return;
         }
         if (!session) {
@@ -534,7 +584,10 @@ async function run(ns, registry) {
                     waitVersion(ev.epoch, ev.version, ev.reply);
                     break;
                 case "write":
-                    write(ev.op, ev.args, ev.reply);
+                    write(ev.handle, ev.op, ev.args, ev.reply);
+                    break;
+                case "leave":
+                    refuseParked(`the handle ended (${ENDED_CLIENT})`, ev.handle);
                     break;
                 case "writeDone":
                     if (writeDone(ev.op, ev.result, ev.reply)) {
@@ -567,6 +620,7 @@ async function run(ns, registry) {
         for (const j of joining.splice(0))
             j.reject(e);
         leaveIncarnation();
+        refuseParked(`the handle ended (${state.ended ?? reason ?? ENDED_CLIENT})`);
         {
             const p = ph();
             if (p.kind === "following" || p.kind === "paced")
@@ -580,7 +634,7 @@ async function run(ns, registry) {
             if (ev.kind === "writeDone")
                 writeDone(ev.op, ev.result, ev.reply);
             else if (ev.kind === "write")
-                write(ev.op, ev.args, ev.reply);
+                write(ev.handle, ev.op, ev.args, ev.reply);
             else if (ev.kind === "opened") {
                 const p = ph();
                 if (p.kind === "opening" && p.o.attempt === ev.attempt) {
@@ -771,31 +825,39 @@ async function follow(ns, session, announced, want, signal) {
 export class StoreHandleImpl {
     ns;
     #closed = false;
+    /** This handle's id in its namespace: its parked writes are refused when it closes. */
+    #id;
     /** Resolved when this handle closes: its version waits end. */
     #left = deferred();
     /** This handle's change feeds: closed with it. */
     #feeds = new Set();
     #valueObj;
     #valueOf;
+    /** Told when this handle closes (its status says `ended: client` from then on, whatever the namespace does). */
+    #onClose = new Set();
+    /** The handle's own state, a state value: `get()` (the same object while unchanged), `onChange`, `changed()`, `watch()`. */
+    status;
+    #status;
     constructor(ns) {
         this.ns = ns;
         ns.handles++;
+        this.#id = ns.nextHandle++;
+        this.status = this.#status = new StatusCell(() => this.ns.state.status(this.ns.node.isConnected, this.#closed), l => { const un = this.ns.state.subscribe(l); this.#onClose.add(l); return () => { un(); this.#onClose.delete(l); }; }, () => this.#closed || this.ns.state.ended !== undefined);
     }
     #ended() { return gone(this.ns.name, `the handle ended (${ENDED_CLIENT})`); }
     get name() { return this.ns.name; }
-    /** The whole value, what the runtime has; the same object while nothing changed (reference-stable for React). */
-    get value() {
+    get(key) {
         const flat = this.ns.state.flat;
+        if (key !== undefined)
+            return flat.get(key);
         if (this.#valueOf !== flat) {
             this.#valueOf = flat;
             this.#valueObj = Object.fromEntries(flat);
         }
         return this.#valueObj;
     }
-    get(key) { return this.ns.state.flat.get(key); }
-    get synced() { return this.status.synced; }
-    get status() { return this.ns.state.status(this.ns.node.isConnected, this.#closed); }
-    /** `set(key, value)` or `set({ ...several keys })` (one atomic write); resolves once `value` shows it. */
+    get synced() { return this.status.get().synced; }
+    /** `set(key, value)` or `set({ ...several keys })` (one atomic write); resolves once `get()` shows it. */
     async set(keyOrValues, value) {
         const v = typeof keyOrValues === "string" ? await this.#write("put", { key: keyOrValues, value }) : await this.#write("put_many", { values: keyOrValues });
         await this.#reached(v);
@@ -803,11 +865,11 @@ export class StoreHandleImpl {
     async delete(key) { await this.#reached(await this.#write("delete", { key })); }
     async clear() { await this.#reached(await this.#write("clear", {})); }
     async destroy() { await this.#write("destroy", {}); }
-    /** The wire half of a write: the runtime's answer, the version it assigned. */
+    /** The wire half of a write: the runtime's answer, the version it assigned (between incarnations the task holds it until the handle binds again). */
     async #write(op, args) {
         if (this.#closed)
             throw this.#ended();
-        const r = await this.ns.request(reply => ({ kind: "write", op, args, reply }));
+        const r = await this.ns.request(reply => ({ kind: "write", handle: this.#id, op, args, reply }));
         const v = r?.version;
         return typeof v === "number" ? v : typeof v === "bigint" ? Number(v) : 0;
     }
@@ -830,7 +892,7 @@ export class StoreHandleImpl {
         try {
             for await (const batch of q) {
                 if (key === undefined)
-                    yield this.value;
+                    yield this.get();
                 else if (batch.some(c => c.key === key))
                     yield this.ns.state.flat.get(key);
             }
@@ -840,12 +902,25 @@ export class StoreHandleImpl {
             this.ns.state.unwatch(q);
         }
     }
-    /** The framework bridge (React's `useStore`): called on every change of the value or the status. */
-    subscribe(listener) { return this.ns.state.subscribe(listener); }
+    /** The whole value after its next change (`store_gone` once this handle is closed). */
+    changed() {
+        if (this.#closed)
+            return Promise.reject(this.#ended());
+        const from = this.get();
+        const d = deferred();
+        const un = this.ns.state.subscribe(() => { const v = this.get(); if (v !== from) {
+            un();
+            this.#onClose.delete(gone);
+            d.resolve(v);
+        } });
+        const gone = () => { un(); this.#onClose.delete(gone); d.reject(this.#ended()); };
+        this.#onClose.add(gone);
+        return d.promise;
+    }
+    /** `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). */
-    join() { return this.ns.request(reply => ({ kind: "join", reply })); }
-    /** `join()` under the SDK's word (Publisher and Registration have `ready()` too). */
-    ready() { return this.join(); }
+    ready() { return this.ns.request(reply => ({ kind: "join", reply })); }
     close() {
         if (this.#closed)
             return;
@@ -854,18 +929,29 @@ export class StoreHandleImpl {
         for (const q of this.#feeds)
             this.ns.state.unwatch(q);
         this.#feeds.clear();
+        for (const l of [...this.#onClose]) {
+            try {
+                l();
+            }
+            catch (e) {
+                queueMicrotask(() => { throw e; });
+            }
+        }
+        this.#onClose.clear();
+        this.#status.dispose();
         if (--this.ns.handles === 0)
             this.ns.post({ kind: "close" });
+        else
+            this.ns.post({ kind: "leave", handle: this.#id });
     }
     async [Symbol.asyncDispose]() { this.close(); }
 }
 /**
  * `store(name, opts)`: one task per namespace per node; a second `store` with the same options joins
- * it (no open written), with other options `invalid_input`; one exiting is waited out.
+ * it (no open written), with other options `invalid_input`; one exiting is waited out. Without a session
+ * (before the first, between two) the task waits for the next one, like after a drop; it resolves once in.
  */
 export async function openStore(node, registry, name, opts, warn) {
-    if (!node.currentSession())
-        throw new SynapseError("not_connected");
     for (;;) {
         const live = registry.get(name);
         if (live) {
@@ -877,7 +963,7 @@ export async function openStore(node, registry, name, opts, warn) {
                 throw new SynapseError("invalid_input", `store ${JSON.stringify(name)}: this node already has it open with other options`);
             const h = new StoreHandleImpl(live);
             try {
-                await h.join();
+                await h.ready();
             }
             catch (e) {
                 h.close();
@@ -890,7 +976,7 @@ export async function openStore(node, registry, name, opts, warn) {
         const h = new StoreHandleImpl(ns);
         startNamespace(ns, registry);
         try {
-            await h.join();
+            await h.ready();
         }
         catch (e) {
             h.close();

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 { 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 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,13 +61,20 @@ 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, or read `updates()` first. 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. */
@@ -64,26 +85,32 @@ export declare class Synapse implements AsyncDisposable {
     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. */
     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).