@synapse-sdk/client 0.3.0 → 0.3.4

package/dist/synapse.js

@@ -2,16 +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 { callStream, 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, openStore } from "./store.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);
@@ -21,96 +22,160 @@ function wantedDesc(contract, n) {
 }
 /** The parts of a descriptor two publishers of one topic on one node must agree on, as text (also for the refusal's message). */
 function descKey(d) {
-    return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null, fec: d.fec ?? null, layout: d.layout ?? null });
+    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 {
-    opts;
     #node;
-    #connecting;
-    #starting;
     #publishers = new Map();
     #stores = new Map();
     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) {
-        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;
         const s = n.currentSession();
-        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 ?? "", url: s?.url ?? n.target.get().dial?.url ?? "" };
+        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;
@@ -155,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);
@@ -167,7 +236,7 @@ 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);
     }
@@ -202,55 +271,65 @@ 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. */
     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;
+    /**
+     * 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).
+     */
+    get tasks() {
+        const n = this.node;
+        return (this.#tasks ??= new TasksFacet(name => attachStore(n, this.#stores, name, {}, m => this.warn(m)), svc => this.call(svc, {}).result, m => this.warn(m)));
+    }
 }

package/dist/tasks.d.ts

@@ -0,0 +1,37 @@
+import { SynapseError, type TasksReportItem, type TasksRun } from "@synapse-sdk/core";
+import type { StoreHandleImpl } from "./store.ts";
+import type { ReadonlyStoreHandle, TaskCatalogEntry, TaskDeclarations, Tasks, TasksStatus } from "./types.ts";
+import type { Warn } from "./topics.ts";
+/** The namespaces the facet reads and writes (the runtime's names). */
+export declare const TASKS_NAMESPACES: {
+    readonly declarations: "tasks";
+    readonly status: "task_status";
+    readonly catalog: "task_catalog";
+};
+/** 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
+ * row goes where its own `scope`, `entity` and `instance` say (its key is never parsed: an instance
+ * name may hold `:`). A row that cannot be placed is left out and passed to `unplaced` (the runtime
+ * never writes one). The instance rows are the mirror's own objects.
+ */
+export declare function tasksStatusOf(rows: Readonly<Record<string, unknown>>, unplaced?: (key: string) => void): TasksStatus;
+/** `node.tasks`. `attach(name)` hands out the node's handle on a namespace; `call` starts a call on the current session. */
+export declare class TasksFacet implements Tasks {
+    private readonly call;
+    readonly declarations: TaskDeclarations;
+    readonly status: ReadonlyStoreHandle<TasksStatus>;
+    readonly catalog: ReadonlyStoreHandle<Readonly<Record<string, TaskCatalogEntry>>>;
+    constructor(attach: (name: string) => StoreHandleImpl, call: (svc: string) => Promise<unknown>, warn: Warn);
+    runRobotTasks(): Promise<TasksRun>;
+    stopRobotTasks(): Promise<void>;
+    runProjectTasks(): Promise<TasksRun>;
+    stopProjectTasks(): Promise<void>;
+}
+/** `true` for a refused run, `preflight_failed` or `launch_failed`, whose `data.report` names each declaration at fault and why. */
+export declare function isTasksRefusal(e: unknown): e is SynapseError & {
+    readonly data: {
+        report: TasksReportItem[];
+    };
+};

package/dist/tasks.js

@@ -0,0 +1,146 @@
+// `node.tasks` (PLAN v0.29 SDK pass 2): the robot's task declarations (namespace `tasks`), what runs
+// (`task_status`, read-only, typed by scope), what the runtime can run (`task_catalog`, read-only), and
+// the four verbs. Each handle is a handle on the node's own namespace task (`store.ts`), opened on its
+// first touch and held for the node's life: `node.store("task_status")` and `node.tasks.status` are one
+// subscription. Nothing here is decided: the mirror is the runtime's, the verbs' replies are its
+// answers, and the typed values are computed from the mirror (no copy), with structural sharing so an
+// unchanged part keeps its object.
+import { SynapseError } from "@synapse-sdk/core";
+import { replaceEqualDeep } from "./util.js";
+import { ulid } from "./scene.js";
+/** The namespaces the facet reads and writes (the runtime's names). */
+export const TASKS_NAMESPACES = { declarations: "tasks", status: "task_status", catalog: "task_catalog" };
+/** What `status.get()` is before the runtime said anything: neither scope's state known, no tasks. */
+export const EMPTY_TASKS_STATUS = { robot: { state: undefined, tasks: {} }, project: { state: undefined, tasks: {} } };
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** A run row (`robot` / `project`: `{state, since, reason?}`) as the scope's run fields. */
+function runOf(row) {
+    if (!isObject(row))
+        return { state: undefined };
+    const out = { state: row.state };
+    if (row.since !== undefined)
+        out.since = row.since;
+    if (row.reason !== undefined)
+        out.reason = row.reason;
+    return out;
+}
+/**
+ * `task_status`'s rows as a `TasksStatus`. A run row is the one keyed `robot` or `project`; an instance
+ * row goes where its own `scope`, `entity` and `instance` say (its key is never parsed: an instance
+ * name may hold `:`). A row that cannot be placed is left out and passed to `unplaced` (the runtime
+ * never writes one). The instance rows are the mirror's own objects.
+ */
+export function tasksStatusOf(rows, unplaced = () => { }) {
+    const robot = {};
+    const project = {};
+    for (const [key, row] of Object.entries(rows)) {
+        if (key === "robot" || key === "project")
+            continue;
+        if (!isObject(row) || typeof row.instance !== "string") {
+            unplaced(key);
+            continue;
+        }
+        if (row.scope === "robot")
+            robot[row.instance] = row;
+        else if (row.scope === "project" && typeof row.entity === "string")
+            (project[row.entity] ??= {})[row.instance] = row;
+        else
+            unplaced(key);
+    }
+    return { robot: { ...runOf(rows.robot), tasks: robot }, project: { ...runOf(rows.project), tasks: project } };
+}
+/**
+ * A read-only handle over one namespace of the node: `get()` is `derive` of the mirror, recomputed only
+ * when the mirror changed and shared structurally with the previous value. The namespace is opened on
+ * the first touch of any member.
+ */
+class DerivedHandle {
+    open;
+    derive;
+    #h;
+    #from;
+    #value;
+    constructor(open, derive, empty) {
+        this.open = open;
+        this.derive = derive;
+        this.#value = empty;
+    }
+    #handle() { return (this.#h ??= this.open()); }
+    get() {
+        const rows = this.#handle().get();
+        if (rows !== this.#from) {
+            this.#from = rows;
+            this.#value = replaceEqualDeep(this.#value, this.derive(rows));
+        }
+        return this.#value;
+    }
+    get synced() { return this.#handle().synced; }
+    ready() { return this.#handle().ready(); }
+    async *watch() {
+        for await (const _ of this.#handle().watch())
+            yield this.get();
+    }
+    onChange(cb) { return this.#handle().onChange(() => cb(this.get())); }
+}
+/** The robot's declarations: the node's handle on `tasks`; every write waits for the value to be current first. */
+class Declarations {
+    open;
+    #h;
+    constructor(open) {
+        this.open = open;
+    }
+    #handle() { return (this.#h ??= this.open()); }
+    get(instance) {
+        const h = this.#handle();
+        return (instance === undefined ? h.get() : h.get(instance));
+    }
+    get synced() { return this.#handle().synced; }
+    get status() { return this.#handle().status; }
+    changed() { return this.#handle().changed(); }
+    ready() { return this.#handle().ready(); }
+    async set(a, b) {
+        const h = this.#handle();
+        await h.ready();
+        if (typeof a === "string") {
+            await h.set(a, b);
+            return;
+        }
+        // One object: a declaration (its `ref` is a string) gets a minted instance; else it is a map of declarations.
+        if (typeof a.ref === "string") {
+            const instance = ulid();
+            await h.set(instance, a);
+            return instance;
+        }
+        await h.set(a);
+    }
+    async delete(instance) { const h = this.#handle(); await h.ready(); await h.delete(instance); }
+    async clear() { const h = this.#handle(); await h.ready(); await h.clear(); }
+    watch(instance) { return this.#handle().watch(instance); }
+    onChange(cb) { return this.#handle().onChange(cb); }
+}
+/** `node.tasks`. `attach(name)` hands out the node's handle on a namespace; `call` starts a call on the current session. */
+export class TasksFacet {
+    call;
+    declarations;
+    status;
+    catalog;
+    constructor(attach, call, warn) {
+        this.call = call;
+        const warned = new Set();
+        const unplaced = (key) => { if (!warned.has(key)) {
+            warned.add(key);
+            warn(`tasks: status row ${JSON.stringify(key)} names no scope and instance; left out`);
+        } };
+        this.declarations = new Declarations(() => attach(TASKS_NAMESPACES.declarations));
+        this.status = new DerivedHandle(() => attach(TASKS_NAMESPACES.status), rows => tasksStatusOf(rows, unplaced), EMPTY_TASKS_STATUS);
+        this.catalog = new DerivedHandle(() => attach(TASKS_NAMESPACES.catalog), rows => rows, {});
+    }
+    async runRobotTasks() { return (await this.call("synapse/tasks/run_robot")); }
+    async stopRobotTasks() { await this.call("synapse/tasks/stop_robot"); }
+    async runProjectTasks() { return (await this.call("synapse/tasks/run_project")); }
+    async stopProjectTasks() { await this.call("synapse/tasks/stop_project"); }
+}
+/** `true` for a refused run, `preflight_failed` or `launch_failed`, whose `data.report` names each declaration at fault and why. */
+export function isTasksRefusal(e) {
+    return e instanceof SynapseError && (e.code === "preflight_failed" || e.code === "launch_failed") && isObject(e.data) && Array.isArray(e.data.report);
+}

package/dist/topics.d.ts

@@ -39,10 +39,22 @@ export declare class TopicPublisher<TIn, TOut> implements Intent {
      * frame the codec refuses is refused (`invalid_input`) without taking a `seq`.
      */
     publishFrame(type: number, flags: number, tUs: number, tlvs: Tlv[], body: Uint8Array): void;
-    /** The typed form: validates against the contract's schema, encodes (msgpack, or the bytes of a raw topic). */
+    /**
+     * The typed form: validates against the contract's schema and encodes msgpack; a raw topic's bytes
+     * go as given, and on a `video/*` topic as a `MEDIA` frame whose `KEY`/`CONFIG`/`RECOVERY` flags
+     * are read off the bitstream (Rust `Publisher<RawBody>::publish`).
+     */
     publish(value: TIn, opts?: PublishOptions): void;
+    /** An encoder's frame with the flags it already carries and its `STAGES` stamps (no re-parse); `tUs` 0 = now. The video helper's path (Rust `publish_media_frame`), not a user verb. */
+    publishMediaFrame(f: MediaFrame): void;
     stats(): PublisherStats;
 }
+/**
+ * The key of a publisher handle's encoder-frame path, the JS spelling of Rust's `pub(crate)
+ * publish_media_frame`: `@synapse-sdk/media`'s `videoPublisher` reaches it by the same
+ * `Symbol.for` key (the two packages share no module), so it is on no public type.
+ */
+export declare const PUBLISH_MEDIA_FRAME: unique symbol;
 /** The application's handle: the last one closed ends the publisher's task (`unregister`). */
 export declare class PublisherHandle<TIn, TOut> implements Publisher<TIn> {
     #private;
@@ -53,10 +65,8 @@ export declare class PublisherHandle<TIn, TOut> implements Publisher<TIn> {
     get verdict(): Verdict;
     ready(): Promise<void>;
     publish(value: TIn, opts?: PublishOptions): void;
-    /** Any frame type and TLVs (`MEDIA` with `STAGES`, WP §4); raw topics only. */
-    publishFrame(type: number, flags: number, tUs: number, tlvs: Tlv[], body: Uint8Array): void;
-    /** `tUs` 0 = capture now (as the Rust client stamps it). */
-    publishMedia(f: MediaFrame): void;
+    /** `@synapse-sdk/media`'s video publisher: an encoder's frame with its flags and `STAGES` (see `PUBLISH_MEDIA_FRAME`). */
+    [PUBLISH_MEDIA_FRAME](f: MediaFrame): void;
     stats(): PublisherStats;
     close(): void;
     [Symbol.asyncDispose](): Promise<void>;
@@ -119,7 +129,12 @@ export declare class TopicSubscription<T> implements Subscription<T> {
     dropFecOf(publisher: string): void;
     /** A new session (or none): the `fec` frames and a batch held by `throttleMs` are the previous session's and go. */
     clearFec(): void;
-    /** The decoding step: header facts plus the body through the contract, or `mismatch` and dropped. */
+    /**
+     * The established descriptor's `content_type` (the catalog's, the runtime's statement), set by the
+     * follow task from each snapshot: bodies decode by it, not by what this subscription declared.
+     */
+    contentType: string | undefined;
+    /** The decoding step: header facts plus the body by the established `content_type` (msgpack → a value, validated when the contract has a schema; anything else → bytes), or `mismatch` and dropped. */
     envelope(payload: Uint8Array, publisher: string, dom: string): Envelope<T> | undefined;
     /**
      * The next batch, never empty; `undefined` once the subscription or the node ended. Drains what
@@ -132,5 +147,7 @@ export declare class TopicSubscription<T> implements Subscription<T> {
     /** Ends the subscription: the follow task stops, every track is closed, a pending `next()` returns `undefined`. */
     unsubscribe(): void;
     [Symbol.asyncDispose](): Promise<void>;
+    /** The callback form's read loop (`node.subscribe(topic, cb)`): `cb` with each batch `next()` returns, until the subscription ends; a throwing `cb` is rethrown later and the loop goes on. */
+    deliverTo(cb: (batch: Envelope<T>[]) => void): void;
 }
 export {};