@synapse-sdk/client 0.1.0 → 0.3.3

package/dist/types.d.ts

@@ -0,0 +1,820 @@
+import type { Card, ClientType, Delivery, FecParams, Role, ServiceRef, StoreMode, StoreOnDeath, StoreRow, TimeDomain, TopicRef, TrackDesc, Tlv, JsonSchema } from "@synapse-sdk/core";
+import type { SynapseError, TasksRun } from "@synapse-sdk/core";
+export type { Card, ClientType, Delivery, FecParams, Role, ServiceRef, StoreMode, StoreOnDeath, StoreRow, TimeDomain, TopicRef, TrackDesc };
+/** What the reconnect policy is asked before every attempt. */
+export interface RetryContext {
+    attempt: number;
+}
+/** How long to wait before the next connect attempt; `null` = give up (SDK §2, WP §10.4). */
+export interface ReconnectPolicy {
+    /** The first delay; also the healthy threshold: a session that lived at least this long resets the backoff. */
+    initialMs: number;
+    nextRetryDelayMs(ctx: RetryContext): number | null;
+}
+export type Transport = "auto" | "webtransport" | "websocket";
+export interface ConnectOptions {
+    /**
+     * The runtime, `https://host:4470` (the path to dial is learned from the runtime at every attempt). Through a relay: the relay with
+     * the runtime's path, `https://relay:4443/runtimes/<runtime_id>`, and `token`. A `jwt=` in the URL is taken as the token.
+     * Absent: `SYNAPSE_ENDPOINT` (Bun/Node; the runtime sets it for every task it starts); a browser has no environment,
+     * so there it is `invalid_input`.
+     */
+    url?: string;
+    /** The relay token that lets this node through a relay; none for a runtime dialed directly. Never printed. */
+    token?: string;
+    /** This node's type (WP §3.1): bounds the role it may exercise; the runtime grants the role. */
+    type: ClientType;
+    /** This node's name `[a-z0-9_-]{1,64}`; minted (`<type>-<6 hex>`) when absent and kept across reconnects. */
+    name?: string;
+    /** Shared across one human's clients so they are promoted and demoted together (WP §3.5); a `web`/`hmi` node without one mints one. */
+    userId?: string;
+    /** Reserved for signed credentials. */
+    credential?: string;
+    /** Pin of the broker's self-signed certificate (SHA-256 hex). Absent: `SYNAPSE_BROKER_CERT_SHA256`, then the broker's helper, then unpinned. */
+    brokerCertSha256?: string;
+    /** Time-domain id override (WP §7.3); default per runtime. */
+    domId?: string;
+    /** Standing project intent (WP §3.5), sent with the connect request. */
+    project?: "operator";
+    /** `null` = no reconnect: a dropped session ends the node `closed`. Default: 100 ms → 10 s, ×2, jitter, unlimited. */
+    reconnect?: ReconnectPolicy | null;
+    transport?: Transport;
+    connectTimeoutMs?: number;
+    /** Datagram budget the FEC symbol size is derived from (WP §6.2); default 1024 in browsers, 1150 in Bun/Node. */
+    maxDatagram?: number;
+    /** Bun/Node: close cleanly on SIGINT/SIGTERM (default true). */
+    signals?: boolean;
+}
+/** Where the node should be connected: the argument of `setTarget` (fields left out keep the node's current ones). */
+export interface ConnectTarget {
+    url: string;
+    type?: ClientType;
+    name?: string;
+    userId?: string;
+    credential?: string;
+    brokerCertSha256?: string;
+    /** The relay token for *this* target; left out = no token (a token for another runtime would be refused). */
+    token?: string;
+}
+export type ConnectionState = {
+    status: "connecting";
+    attempt: number;
+} | {
+    status: "connected";
+    url: string;
+    sinceMs: number;
+} | {
+    status: "reconnecting";
+    attempt: number;
+    reason: string;
+    error: SynapseError;
+    nextRetryAtMs: number;
+} | {
+    status: "closing";
+} | {
+    status: "closed";
+    reason: string;
+} | {
+    status: "failed";
+    error: SynapseError;
+};
+/** This node's identity and the current session's hello facts; empty strings between sessions. */
+export interface Info {
+    name: string;
+    type: ClientType;
+    userId?: string;
+    prefix: string;
+    role: Role;
+    dom: TimeDomain;
+    brokerDom: string;
+    brokerVersion: string; /** The robot the runtime serves (fixed for the runtime's life; empty between sessions). */
+    robot: string; /** The runtime's name in its cluster, from the current session's hello (empty between sessions). */
+    runtimeName: string; /** The runtime's id, from the current session's hello (empty between sessions): kept across the runtime's restarts. */
+    runtimeId: string;
+    url: string;
+}
+/** A `promoted`/`demoted` notice on the session (WP §3.5). */
+export type Notice = {
+    kind: "promoted";
+    role: Role;
+    project: string | null;
+} | {
+    kind: "demoted";
+    role: Role;
+    project: string | null;
+};
+export interface PublishOptions {
+    /** The frame's `t_us` (this node's clock): the capture time, if you have one; default now. */
+    tUs?: number;
+    flags?: number;
+}
+/** Where a publisher stands with the runtime on the current session. */
+export type Verdict = {
+    status: "unbound";
+} | {
+    status: "pending";
+    epoch: number;
+} | {
+    status: "admitted";
+    epoch: number;
+};
+export interface PublisherStats {
+    published: number;
+    droppedDisconnected: number;
+    fec?: {
+        blocks: number;
+        plain: number;
+        superseded: number;
+    };
+}
+export interface Publisher<TIn> extends AsyncDisposable {
+    readonly topic: string;
+    readonly verdict: Verdict;
+    /** Resolves once admitted and announced on the current session; `not_connected` once the node ended. A refusal is asked again, paced and warned about. */
+    ready(): Promise<void>;
+    /**
+     * Synchronous: writes to the installed track, or drops and counts while unbound (SDK §12.4). A
+     * msgpack topic takes a value; a raw topic takes bytes, sent as given; on a `video/*` topic the
+     * bytes are one access unit (Annex-B for `video/h264`), sent as a `MEDIA` frame whose
+     * `KEY`/`CONFIG`/`RECOVERY` flags are read off the bitstream.
+     */
+    publish(value: TIn, opts?: PublishOptions): void;
+    stats(): PublisherStats;
+    close(): void;
+}
+export interface Envelope<T> {
+    data: T;
+    tUs: number;
+    seq: number;
+    /** The publisher's name. */
+    publisher: string;
+    /** The publisher's time-domain id. */
+    dom: string;
+    flags: number;
+    type: number;
+    tlvs: Tlv[];
+    /** Flag `KEY`: an IDR, a decoder may start here (video). */
+    key: boolean;
+    /** Flag `CONFIG`: the access unit carries SPS/PPS (video). */
+    config: boolean;
+    /** Flag `RECOVERY`: a recovery point, a gradual start point (video). */
+    recovery: boolean;
+}
+export interface SubscribeOptions {
+    /** Deliver at most one message per interval, newest wins (skipped counted `coalesced`). */
+    throttleMs?: number;
+    /** `queueDepth` 1 (default): a read returns the newest message of each publisher with news; 0: every message, in order. */
+    queueDepth?: 0 | 1;
+    /** MoQ priority 0..7 (default 3). */
+    priority?: number;
+    /** `stream` topics: how far behind the live edge the relay may serve (ms; default 0 = live edge). */
+    maxAgeMs?: number;
+    /** Drop a message older than this on arrival (same-domain publishers only). */
+    deadlineMs?: number;
+    /** `fec` publishers: override the reassembly give-up budget. */
+    fecDeadlineMs?: number;
+    /** `fec` publishers: send WP §6.4 reports (default true). */
+    fecFeedback?: boolean;
+}
+export interface SubStats {
+    read: number;
+    superseded: number;
+    staleDrops: number;
+    mismatch: number;
+    fecGiveup: number;
+    repaired: number;
+    coalesced: number;
+}
+export interface Subscription<T> extends AsyncIterable<Envelope<T>[]>, AsyncDisposable {
+    readonly topic: string;
+    readonly stats: SubStats;
+    /** The next batch (never empty): latest per publisher (`queueDepth` 1) or everything ready (0). `undefined` once the node ended. */
+    next(): Promise<Envelope<T>[] | undefined>;
+    unsubscribe(): void;
+}
+export type ViewStatus = "pending" | "live" | "stale";
+export interface ViewState<S> {
+    data: S | undefined;
+    status: ViewStatus;
+    connection: ConnectionState["status"];
+    /** This node's clock when the value changed, µs. */
+    lastChangeAtUs: number | undefined;
+}
+export interface ViewOptions<T, S> extends SubscribeOptions {
+    /** A value older than this (by its publisher's stamp, on our clock) reads as `stale`. */
+    staleTime?: number;
+    select?: (v: T) => S;
+}
+/** A topic's value now, as a cell: `get()` any time, `subscribe` for changes (the framework bridge), `changed()` for the next one; subscribed from creation until `close()`. */
+export interface View<S> extends AsyncDisposable {
+    get(): ViewState<S>;
+    subscribe(listener: () => void): () => void;
+    ready(): Promise<void>;
+    changed(): Promise<ViewState<S>>;
+    close(): void;
+}
+export type RunStatus = "pending" | "running" | "succeeded" | "failed" | "canceled";
+export interface CallOptions<U = unknown> {
+    /** End-to-end deadline enforced by the broker (WP §8.4). */
+    deadlineMs?: number;
+    /** Local: fail `idle_timeout` (and cancel) when no frame arrives for this long. */
+    idleTimeoutMs?: number;
+    signal?: AbortSignal;
+    onUpdate?: (u: U) => void;
+}
+/** A started call (WP §8.3): its updates, its result, and cancel. */
+/** `await run` is `await run.result`. */
+export interface Run<U, R> extends AsyncDisposable, PromiseLike<R> {
+    readonly id: string;
+    readonly status: RunStatus;
+    /** The next progress update; `undefined` once the terminal frame arrived (then `result`). */
+    nextUpdate(): Promise<U | undefined>;
+    updates(): AsyncIterable<U>;
+    readonly result: Promise<R>;
+    /** Cooperative cancel: tells the broker, resolves on its `canceled` frame. */
+    cancel(reason?: string): Promise<void>;
+}
+export type CallEvent<U, R> = {
+    type: "update";
+    data: U;
+} | {
+    type: "result";
+    data: R;
+};
+export interface ServeContext<U> {
+    readonly call: string;
+    readonly caller: string;
+    readonly role: Role;
+    readonly deadlineMs: number | undefined;
+    /** Aborted when the caller cancels or the registration ends; `reason` names why. */
+    readonly signal: AbortSignal;
+    update(u: U): void;
+}
+export type ServeHandler<I, U, R> = (input: I, ctx: ServeContext<U>) => R | Promise<R>;
+export interface ServeOptions {
+    minRole?: Role;
+    description?: string;
+}
+export type RegVerdict = {
+    status: "unbound";
+} | {
+    status: "pending";
+    epoch: number;
+} | {
+    status: "registered";
+    epoch: number;
+};
+export interface Registration extends AsyncDisposable {
+    readonly name: string;
+    readonly verdict: RegVerdict;
+    /** The current binding id (fresh per session and renewal); `undefined` while unbound. */
+    readonly bind: string | undefined;
+    ready(): Promise<void>;
+    unregister(): void;
+}
+export interface StoreOptions {
+    access?: StoreMode;
+    onDeath?: StoreOnDeath;
+}
+export interface StoreStatus {
+    /** The value is current: connected, nothing of ours pending, every change the runtime sent applied. */
+    synced: boolean;
+    connected: boolean;
+    pending: number;
+    mode: StoreMode | undefined;
+    owner: string | undefined;
+    mine: boolean;
+    minRole: Role | undefined;
+    onDeath: StoreOnDeath | undefined;
+    absent: boolean;
+    /** Diagnostics: the last applied version and the bound incarnation. */
+    version: number;
+    epoch: string | undefined;
+    /** `destroyed`, `connection_lost` or `client`. */
+    ended: string | undefined;
+}
+export type StoreChange = {
+    kind: "put";
+    key: string;
+    value: unknown;
+    previousValue: unknown | undefined;
+    by: string | undefined;
+} | {
+    kind: "delete";
+    key: string;
+    previousValue: unknown;
+    by: string | undefined;
+};
+/**
+ * A namespace as a value kept current (SDK §9): `value`/`get` read it, `set`/`delete` resolve once the
+ * value shows the write, `synced` says whether it is current, `watch()` follows changes. The runtime
+ * decides every write (`not_owner`, `unauthorized`, `store_gone`).
+ */
+export interface StoreHandle extends AsyncDisposable {
+    readonly name: string;
+    /** The whole value, what the runtime has (the same object while nothing changed). */
+    readonly value: Record<string, unknown>;
+    get(key: string): unknown;
+    readonly synced: boolean;
+    readonly status: StoreStatus;
+    /** `set(key, value)`, or `set({ ... })` for several keys as one atomic write; resolves once `value` shows it. */
+    set(key: string, value: unknown): Promise<void>;
+    set(values: Record<string, unknown>): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /** Ends the namespace for everyone (the owner, or an operator); every handle ends `destroyed`. */
+    destroy(): Promise<void>;
+    /** The whole value after each change; with `key`, that key's value each time it changes (`undefined` after a delete). */
+    watch(key?: string): AsyncIterable<unknown>;
+    /** The framework bridge (React): called on every change of the value or the status. */
+    subscribe(listener: () => void): () => void;
+    close(): void;
+}
+export type Vec3 = [number, number, number];
+/** A rotation as a quaternion `[x, y, z, w]`. */
+export type Quat = [number, number, number, number];
+/** A transform relative to the parent: translation, rotation, scale (each absent = identity). */
+export interface Xform {
+    t?: Vec3;
+    q?: Quat;
+    s?: Vec3;
+}
+/** Which plane an entity lives in: `authored` (the project's), `calibration` (the robot's), `live` (never persisted). */
+export type SceneLayer = "authored" | "calibration" | "live";
+/** Each flag holds only when it is `true`. `locked` refuses patch/reparent/rename/despawn (a flags-only patch passes). */
+export interface SceneFlags {
+    locked?: boolean;
+    bound?: boolean;
+    static?: boolean;
+    derived?: boolean;
+}
+/** Written by the runtime on every change of the entity: revision, the runtime's clock (µs), who wrote it. */
+export interface SceneMeta {
+    rev: number;
+    t: number;
+    by: string | null;
+}
+/**
+ * One piece of an entity's `visual` or `collision` list (pieces are the geometry unit), placed by its
+ * own `xform` inside the entity. The shapes and their fields are the scene spec's §1.2.
+ */
+export type Piece = ({
+    kind: "box";
+    size: Vec3;
+} | {
+    kind: "sphere";
+    radius: number;
+} | {
+    kind: "cylinder";
+    radius: number;
+    length: number;
+} | {
+    kind: "capsule";
+    radius: number;
+    length: number;
+} | {
+    kind: "blob";
+    blob: string;
+}) & {
+    xform?: Xform;
+    color?: string;
+    [key: string]: unknown;
+};
+export interface Physics {
+    dynamic?: boolean;
+    collide?: boolean;
+    mass?: number;
+    material?: {
+        friction?: number;
+        restitution?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/** A robot's declaration: its description (URDF), the topic of its joint states, its control, the frames materialized into the tree. */
+export interface RobotComponent {
+    description?: string;
+    joints_topic?: string;
+    control?: unknown;
+    frames?: string[];
+    floating_base?: boolean;
+    [key: string]: unknown;
+}
+/** A named mounting point of an entity; materialized as a derived frame. */
+export interface Hardpoint {
+    name: string;
+    mate_type?: string | null;
+    xform?: Xform;
+    [key: string]: unknown;
+}
+/**
+ * An entity of the scene. The fields below are the ones the runtime and the early users read;
+ * every other key passes through untouched.
+ */
+export interface SceneEntity {
+    /** A ULID; never changes. */
+    id: string;
+    kind: string;
+    /** Unique across the authored and calibration planes. */
+    name?: string;
+    /** The parent's id; `null` is the world root. */
+    parent: string | null;
+    /** The place among its siblings (lowercase hex; siblings sort by `(order, id)`); absent on live entities. */
+    order?: string;
+    layer: SceneLayer;
+    xform?: Xform;
+    flags?: SceneFlags;
+    meta?: SceneMeta;
+    lifetime_ms?: number;
+    visual?: Piece[];
+    collision?: Piece[];
+    physics?: Physics;
+    robot?: RobotComponent;
+    /** Joint name → position; on a robot the authored ones are its rest configuration, the live plane overrides them. */
+    joints?: Record<string, number>;
+    /** Presentation/status the live plane sets per entity. */
+    state?: Record<string, unknown>;
+    hardpoints?: Hardpoint[];
+    /** The entity's tasks (`instance` → declaration): what the runtime runs for it while the project's tasks run. */
+    tasks?: Record<string, TaskDeclaration>;
+    /** Passed through untouched; the runtime does not read it (`tasks` supersedes it). */
+    behaviors?: Record<string, unknown>;
+    possession?: Record<string, unknown>;
+    labels?: string[];
+    props?: Record<string, unknown>;
+    asset?: {
+        id: string;
+        prefab?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * An id's live row (`scene.entity(id, { plane: "live" })`), each key present only when the row has it:
+ * `entity` is a live-layer entity's upsert row; `pose`, `joints`, `state` are the lanes; `stamp` is the
+ * newest lane stamp (the runtime's clock).
+ */
+export interface SceneEntityLive {
+    entity?: SceneEntity;
+    pose?: {
+        t: Vec3;
+        q: Quat;
+    };
+    joints?: Record<string, number>;
+    state?: Record<string, unknown>;
+    stamp?: number;
+}
+/** One node of the hierarchy: ids and ordering only (a pose, rename or patch does not change it). */
+export interface SceneTreeNode {
+    id: string;
+    children: SceneTreeNode[];
+}
+/**
+ * The hierarchy now, as its roots: siblings in `(order, id)` order (an entity without an `order`
+ * after the ordered ones); an entity whose parent is not in the scene is a root.
+ */
+export type SceneTree = SceneTreeNode[];
+/**
+ * A value of the scene, kept current: `get()` the value now (the same object until it changes),
+ * `subscribe` for each change (the framework bridge), `changed()` for the next one. It reads the
+ * handle's copy of the scene (no subscription of its own) and ends with the handle.
+ */
+export interface SceneView<T> {
+    get(): T;
+    subscribe(listener: () => void): () => void;
+    /** Resolves with the value after its next change (with the value as it is when the handle closes). */
+    changed(): Promise<T>;
+}
+/** `attached`: the scene of the active project is in; `detached`: none is (no project active, a session gap, between incarnations); `closed`: for good. */
+export type SceneState = "attached" | "detached" | "closed";
+export interface SceneStatus {
+    state: SceneState;
+    /** Attached, connected, no write of ours in flight, every authored change the runtime sent applied. */
+    synced: boolean;
+    /** Authoring batches awaiting the runtime's answer. */
+    pending: number;
+    /** The authored plane's version and hash as this handle has them (0 and "" while detached). */
+    version: number;
+    hash: string;
+    /** `live()` batches dropped because the handle was not attached. */
+    detachedDrops: number;
+}
+/** An authored change as the runtime applied it (the `watchChanges` feed). */
+export type SceneDiffOp = {
+    op: "spawn";
+    entity: SceneEntity;
+} | {
+    op: "despawn";
+    id: string;
+    removed: string[];
+    old_parent: string | null;
+    old_order: string | null;
+} | {
+    op: "patch";
+    id: string;
+    set: Partial<SceneEntity>;
+    rev: number;
+} | {
+    op: "reparent";
+    id: string;
+    parent: string | null;
+    order: string;
+    xform?: Xform;
+    old_parent: string | null;
+    old_order: string | null;
+    rev: number;
+} | {
+    op: "rename";
+    id: string;
+    name: string;
+    old_name: string | null;
+    rev: number;
+};
+/** An op of an authoring batch (`apply`): the runtime validates every one. */
+export type SceneOp = {
+    op: "spawn";
+    entity: Partial<SceneEntity> & {
+        id: string;
+    };
+} | {
+    op: "despawn";
+    id: string;
+    cascade?: boolean;
+} | {
+    op: "patch";
+    id: string;
+    set: Partial<SceneEntity>;
+} | {
+    op: "reparent";
+    id: string;
+    parent: string | null;
+    before?: string;
+    after?: string;
+    preserve_world?: boolean;
+} | {
+    op: "rename";
+    id: string;
+    name: string;
+};
+/**
+ * What `spawn` takes besides the kind: the name, the parent (default the world root), the components.
+ * The id is minted here (a ULID) unless `id` is given: a known id kept, as a restore of despawned
+ * entities needs (the runtime refuses one already in use, `conflict`).
+ */
+export type SceneSpawnOptions = {
+    name: string;
+    parent?: string | null;
+    id?: string;
+} & Partial<Omit<SceneEntity, "id" | "kind" | "name" | "parent" | "order" | "meta">>;
+/** Where `reparent` puts the entity among its new siblings (default: after the last). */
+export type ScenePlace = {
+    before: string;
+} | {
+    after: string;
+};
+/** One authoring batch being built (`txn`): sent as one atomic `apply`. */
+export interface SceneTxn {
+    /** Spawns an entity of `kind`; returns its id. */
+    spawn(kind: string, opts: SceneSpawnOptions): string;
+    /** Sets components of `id` (an object merges into an object one level deep). */
+    patch(id: string, set: Partial<SceneEntity>): void;
+    rename(id: string, name: string): void;
+    reparent(id: string, parent: string | null, place?: ScenePlace): void;
+    despawn(id: string, opts?: {
+        cascade?: boolean;
+    }): void;
+    setLocked(id: string, locked: boolean): void;
+    /** The ops as they will be sent. */
+    readonly ops: readonly SceneOp[];
+}
+export interface LivePose {
+    id: string;
+    t: Vec3;
+    q: Quat;
+}
+export interface LiveJoints {
+    id: string;
+    j: Record<string, number>;
+}
+export interface LiveState {
+    id: string;
+    s: Record<string, unknown>;
+}
+/** One live batch: live entities (`layer: "live"`), lane overrides, removals; `lifetimeMs` makes the override rows it touches expire. */
+export interface LiveBatch {
+    upsert?: SceneEntity[];
+    poses?: LivePose[];
+    joints?: LiveJoints[];
+    state?: LiveState[];
+    remove?: string[];
+    lifetimeMs?: number;
+}
+/** A live row removed: the writer removed it, its lifetime ran out, or its writer left. */
+export interface LiveRemoved {
+    id: string;
+    by: "explicit" | "timeout" | "writer_gone";
+}
+/**
+ * The active project's scene as this node sees it (PLAN v0.24 §5): authored ⊕ live, kept current.
+ * Views and feeds read the handle's copy of the scene; every write goes to the runtime, which
+ * decides it, and resolves once the entities show it.
+ */
+export interface SceneHandle extends AsyncDisposable {
+    /** The entities now, authored with the live overrides applied; the same object while nothing changed. */
+    readonly entities: Readonly<Record<string, SceneEntity>>;
+    /**
+     * One entity as a view (`undefined` when it is not in the scene). `plane` reads one layer alone and
+     * the view changes only when that layer's value for the id does: `authored` is the entity as
+     * declared without the live lanes (the authored entity, or a live entity's upsert row); `live` is
+     * the id's live row (`SceneEntityLive`), `undefined` without one. Without `plane`: merged.
+     */
+    entity(id: string, opts?: {
+        plane?: "authored";
+    }): SceneView<SceneEntity | undefined>;
+    entity(id: string, opts: {
+        plane: "live";
+    }): SceneView<SceneEntityLive | undefined>;
+    entity(id: string, opts?: {
+        plane?: "authored" | "live";
+    }): SceneView<SceneEntity | SceneEntityLive | undefined>;
+    /** The hierarchy as a view. */
+    tree(): SceneView<SceneTree>;
+    /** The entities for which `where` holds (in id order), as a view. */
+    query(where: (e: SceneEntity) => boolean): SceneView<SceneEntity[]>;
+    readonly status: SceneStatus;
+    /** The authored changes, one batch per applied change. */
+    watchChanges(cb: (batch: SceneDiffOp[]) => void): () => void;
+    watchChanges(): AsyncIterableIterator<SceneDiffOp[]>;
+    /** The live rows removed, one batch per runtime tick that removed some. */
+    watchLiveRemovals(cb: (batch: LiveRemoved[]) => void): () => void;
+    watchLiveRemovals(): AsyncIterableIterator<LiveRemoved[]>;
+    /** The ids of this node's live writes the runtime dropped because another writer owns them, one batch per denied batch. */
+    watchLiveDenied(cb: (ids: string[]) => void): () => void;
+    watchLiveDenied(): AsyncIterableIterator<string[]>;
+    /** The handle's state at each change; ends after `closed`. */
+    watchState(cb: (state: SceneState) => void): () => void;
+    watchState(): AsyncIterableIterator<SceneState>;
+    /** One atomic batch; `base`: the version its structural ops assume. Resolves once the entities show it; a refusal is the runtime's error. Detached: `project_inactive`. */
+    apply(ops: SceneOp[], base?: number): Promise<void>;
+    /** The ops `build` makes, as one atomic batch. */
+    txn(build: (t: SceneTxn) => void): Promise<void>;
+    /** Spawns an entity; its id, once the entities show it. */
+    spawn(kind: string, opts: SceneSpawnOptions): Promise<string>;
+    patch(id: string, set: Partial<SceneEntity>): Promise<void>;
+    rename(id: string, name: string): Promise<void>;
+    reparent(id: string, parent: string | null, place?: ScenePlace): Promise<void>;
+    despawn(id: string, opts?: {
+        cascade?: boolean;
+    }): Promise<void>;
+    setLocked(id: string, locked: boolean): Promise<void>;
+    /** Writes one live batch on this node's live track; returns at once (like `publish`). Not attached: dropped and counted (`status.detachedDrops`). */
+    live(batch: LiveBatch): void;
+    /** The framework bridge (React): called on every change of the entities or the status. */
+    subscribe(listener: () => void): () => void;
+    /** Ends this handle: its verbs fail `not_connected`, its views and feeds end; the node's other scene handles go on. */
+    close(): void;
+}
+/**
+ * A declaration: what the runtime runs under an instance name (the robot's: a key of
+ * `tasks.declarations`; a project's: an entry of an entity's `tasks`). Whether it has a process to
+ * run is the catalog's: a task whose spec has nothing to run is passive (counted, never started).
+ */
+export interface TaskDeclaration {
+    /** The task's address, as the task tool lists it (`<workspace>:<pkg>:<task>`); never split. */
+    ref: string;
+    /** `false`: left out of the next run. */
+    enabled?: boolean;
+    /** Passed to the task: as flags, positionals or environment variables per its spec, and whole as `SYNAPSE_CONFIG` (JSON). */
+    config?: Record<string, unknown>;
+    /** The catalog's `schemaHash` this declaration was written against; another one fails the run. */
+    schema?: string;
+}
+/** How a task's last process ended: its exit code, the signal that ended it, or neither. Times are Unix ms. */
+export type TaskExit = {
+    code: number;
+    at: number;
+} | {
+    signal: number;
+    at: number;
+} | {
+    at: number;
+};
+/** One running task, as the runtime shows it. */
+export interface TaskStatus {
+    scope: "robot" | "project";
+    /** The task's address (its declaration's `ref`). */
+    addr: string;
+    instance: string;
+    /** Project tasks: the entity's id. */
+    entity?: string;
+    /** `down`: its process exited and its restart is pending. */
+    state: "up" | "down";
+    /** Unix ms of the last change between `up` and `down`. */
+    since: number;
+    /** How many times its process was started again after an exit. */
+    restarts: number;
+    /** How its last process ended. */
+    exit?: TaskExit;
+    /** The file its stdout and stderr go to. */
+    log: string;
+}
+/** A scope's run and its tasks. */
+export interface TasksRunStatus<T> {
+    /** `undefined`: the runtime has not said yet (not synced, or between sessions). */
+    state: "starting" | "running" | "stopping" | "stopped" | undefined;
+    /** Unix ms of the last change of `state`. */
+    since?: number;
+    /** Why it stopped or failed: `project_switch`, or an error code (`preflight_failed`, `launch_failed`, ...). */
+    reason?: string;
+    tasks: T;
+}
+/** What runs, both scopes: the robot's tasks by instance, the project's by entity id, then instance. */
+export interface TasksStatus {
+    robot: TasksRunStatus<Readonly<Record<string, TaskStatus>>>;
+    project: TasksRunStatus<Readonly<Record<string, Readonly<Record<string, TaskStatus>>>>>;
+}
+/** One task the runtime knows (from the task tool's workspaces). Fields the task's manifest lacks are absent. */
+export interface TaskCatalogEntry {
+    addr: string;
+    workspace: string;
+    pkg?: string;
+    name?: string;
+    kind?: string;
+    tags?: string[];
+    inputs?: JsonSchema;
+    schemaHash?: string;
+    definedBy?: string;
+}
+/** A value the runtime keeps current that this node only reads: it has no writes. */
+export interface ReadonlyStoreHandle<V> {
+    /** The value now; the same object while nothing changed, and an unchanged part keeps its object when another part changes. */
+    readonly value: V;
+    /** `true` while the value is current. */
+    readonly synced: boolean;
+    /** Resolves once the value is current (the first time). */
+    ready(): Promise<void>;
+    /** The whole value after each change. It is state, not history: a reader slower than the changes sees the latest value. */
+    watch(): AsyncIterable<V>;
+    /** The framework bridge (React): called on every change of the value or of `synced`. */
+    subscribe(listener: () => void): () => void;
+}
+/** The robot's task declarations, `instance` → declaration (operators write them). The node owns this handle: it has no `close` or `destroy`. */
+export interface TaskDeclarations extends Omit<StoreHandle, "name" | "value" | "get" | "set" | "watch" | "destroy" | "close" | typeof Symbol.asyncDispose> {
+    readonly value: Readonly<Record<string, TaskDeclaration>>;
+    get(instance: string): TaskDeclaration | undefined;
+    /** `set(instance, declaration)`, or `set({ ... })` for several as one atomic write; waits for the value to be current first, resolves once `value` shows the write. */
+    set(instance: string, declaration: TaskDeclaration): Promise<void>;
+    set(declarations: Record<string, TaskDeclaration>): Promise<void>;
+    /** The whole value after each change; with `instance`, that declaration each time it changes (`undefined` after a delete). */
+    watch(instance?: string): AsyncIterable<unknown>;
+    /** Resolves once the value is current (the first time). */
+    ready(): Promise<void>;
+}
+/**
+ * `node.tasks`: the robot's task declarations, what runs (`status`), what the runtime can run
+ * (`catalog`), and the verbs. Running and stopping need the operator role. A run's reply is the
+ * runtime's answer; what runs afterwards is `status`.
+ */
+export interface Tasks {
+    readonly declarations: TaskDeclarations;
+    readonly status: ReadonlyStoreHandle<TasksStatus>;
+    /** By address. */
+    readonly catalog: ReadonlyStoreHandle<Readonly<Record<string, TaskCatalogEntry>>>;
+    /**
+     * Starts the robot's tasks (the enabled declarations). Every declaration is checked first and nothing starts unless all
+     * pass: a failed check rejects `preflight_failed`, a process that could not start `launch_failed` (what had started is
+     * stopped); both carry the report ({@link isTasksRefusal}). `already_running` while they run. Robot tasks keep running
+     * across project switches.
+     */
+    runRobotTasks(): Promise<TasksRun>;
+    /** Stops every robot task (also when none ran). Project tasks are not touched. */
+    stopRobotTasks(): Promise<void>;
+    /** Starts the active project's tasks (the enabled `tasks` of its scene's entities), as {@link runRobotTasks}; `project_inactive` with no active project. A project switch stops them. */
+    runProjectTasks(): Promise<TasksRun>;
+    /** Stops every project task (also when none ran). Robot tasks are not touched. */
+    stopProjectTasks(): Promise<void>;
+}
+export interface Catalog {
+    readonly topics: Readonly<Record<string, {
+        desc?: TrackDesc;
+        publishers: Record<string, {
+            name: string;
+            bind: string;
+        }>;
+    }>>;
+    readonly services: Readonly<Record<string, {
+        name: string;
+        prefix: string;
+        card: Card;
+        builtin: boolean;
+    }>>;
+    /** The listed card of `service`, if any. */
+    describe(service: string): Card | undefined;
+}
+export interface Metrics {
+    sessions: number;
+    reconnects: number;
+    callsSent: number;
+    callsAnswered: number;
+}
+export type { JsonSchema };