@synapse-sdk/client 0.1.0 → 0.3.3

package/dist/synapse.d.ts

@@ -0,0 +1,93 @@
+import { type Age, type ClockInfo, type ErrorBody, type LocalTime, type ProjectSnapshot, type ServiceContract, type TimeOffsets, 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;
+export declare class Synapse implements AsyncDisposable {
+    #private;
+    warn: Warn;
+    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>;
+    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`. */
+    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;
+    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;
+        dom: string;
+    }): Age | undefined;
+    /** 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. */
+    subscribe<TIn, TOut>(topic: TopicContract<TIn, TOut>, 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. */
+    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. */
+    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. */
+    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. */
+    activateProject(id: string): Promise<ProjectSnapshot>;
+    /** `synapse/project/deactivate {}`: every operator is demoted. */
+    deactivateProject(): Promise<ProjectSnapshot>;
+    /** `synapse/project/join {as: "operator"}`: promoted on the active project, or `project_inactive`. */
+    joinProject(as?: "operator"): Promise<ProjectSnapshot>;
+    /** `synapse/project/leave {}`: drops our standing (every session of our `user_id`). */
+    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).
+     */
+    get tasks(): Tasks;
+}
+export type { Envelope, StoreHandleImpl };

package/dist/synapse.js

@@ -0,0 +1,268 @@
+// `Synapse` (SDK §2–§9): the public face of one node. It owns nothing the modules do not: the node's
+// 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 { 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;
+/** 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);
+    if (d.delivery === "datagram" && d.fec && d.fec.symbol_size === 0)
+        d.fec = { ...d.fec, symbol_size: fecSymbolSizeFor(n.knobs.maxDatagram) };
+    return d;
+}
+/** 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 });
+}
+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;
+    constructor(opts) {
+        this.#opts = opts;
+        this.warn = msg => console.warn(`[synapse] ${msg}`);
+    }
+    /** `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();
+        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();
+    }
+    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 ?? "", 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); }; }
+    // ---------------------------------------------------------------------------------- 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;
+        const name = contract.name;
+        let p;
+        let held;
+        for (;;) {
+            const entry = this.#publishers.get(name);
+            if (!entry) {
+                // Looked up and inserted in one step (no await between): a concurrent `publisher()` for the
+                // same name finds this entry and waits for it instead of making a second one.
+                const made = wasmFor(contract).then(wasm => new TopicPublisher(n, contract, n.knobs.maxDatagram, wasm, this.warn));
+                this.#publishers.set(name, made);
+                try {
+                    p = (await made);
+                }
+                catch (e) {
+                    if (this.#publishers.get(name) === made)
+                        this.#publishers.delete(name);
+                    throw e;
+                }
+                held = made;
+                break;
+            }
+            const live = await entry.catch(() => undefined);
+            // Gone meanwhile (its making failed, or its last handle closed): look again.
+            if (!live || this.#publishers.get(name) !== entry)
+                continue;
+            // A second one with another descriptor is not this one, and its intent never reached the runtime.
+            const have = descKey(live.desc), want = descKey(wantedDesc(contract, n));
+            if (have !== want)
+                throw new SynapseError("invalid_input", `topic ${name}: a publisher with a different descriptor exists on this node (live: ${have}; asked: ${want})`);
+            p = live;
+            held = entry;
+            break;
+        }
+        const h = new PublisherHandle(p, () => { if (this.#publishers.get(name) === held)
+            this.#publishers.delete(name); });
+        try {
+            await h.ready();
+        }
+        catch (e) {
+            h.close();
+            throw e;
+        }
+        return h;
+    }
+    subscribe(topic, opts = {}) {
+        const contract = resolveTopic(topic);
+        return new TopicSubscription(this.node, contract, opts, this.warn);
+    }
+    view(topic, opts = {}) {
+        const contract = resolveTopic(topic);
+        const { staleTime: _s, select: _sel, ...subOpts } = opts;
+        return new TopicView(this.node, () => new TopicSubscription(this.node, contract, subOpts, this.warn), opts, () => { });
+    }
+    call(svc, args = {}, opts = {}) {
+        const s = this.#session();
+        if (!s)
+            throw 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);
+        const contract = isServiceContract(svc) ? svc : undefined;
+        const card = contract ? contract.card() : { name, streaming: true, cancelable: true, min_role: opts.minRole ?? "agent", ...(opts.description ? { description: opts.description } : {}) };
+        if (opts.minRole)
+            card.min_role = opts.minRole;
+        if (opts.description)
+            card.description = opts.description;
+        if (this.#registrations.has(name))
+            throw new SynapseError("already_registered", `${name}: this node already provides it (one provider per service path)`);
+        const reg = new ServiceRegistration(n, name, card, contract, handler, this.warn);
+        this.#registrations.set(name, reg);
+        void reg.handle.exited.promise.then(() => { if (this.#registrations.get(name) === reg)
+            this.#registrations.delete(name); });
+        try {
+            await reg.ready();
+        }
+        catch (e) {
+            reg.unregister();
+            throw e;
+        }
+        return reg;
+    }
+    #registrations = new Map();
+    // ---------------------------------------------------------------------------------- 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(); };
+    }
+    // -------------------------------------------------------------------------------- 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?.(); };
+    }
+    #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. */
+    activateProject(id) { return this.#projectCall("activate", { id }); }
+    /** `synapse/project/deactivate {}`: every operator is demoted. */
+    deactivateProject() { return this.#projectCall("deactivate", {}); }
+    /** `synapse/project/join {as: "operator"}`: promoted on the active project, or `project_inactive`. */
+    joinProject(as = "operator") { return this.#projectCall("join", { as }); }
+    /** `synapse/project/leave {}`: drops our standing (every session of our `user_id`). */
+    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.value` 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,132 @@
+// `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";
+/** 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.value` 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: `value` 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 value() {
+        const rows = this.#handle().value;
+        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.value;
+    }
+    subscribe(listener) { return this.#handle().subscribe(listener); }
+}
+/** 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 value() { return this.#handle().value; }
+    get(instance) { return this.#handle().get(instance); }
+    get synced() { return this.#handle().synced; }
+    get status() { return this.#handle().status; }
+    ready() { return this.#handle().ready(); }
+    async set(a, b) {
+        const h = this.#handle();
+        await h.ready();
+        await (typeof a === "string" ? h.set(a, b) : 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); }
+    subscribe(listener) { return this.#handle().subscribe(listener); }
+}
+/** `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);
+}