@synapse-sdk/client 0.3.0 → 0.3.4

package/dist/types.d.ts

@@ -1,5 +1,6 @@
-import type { Card, ClientType, Delivery, FecParams, MediaFrame, Role, ServiceRef, StoreMode, StoreOnDeath, StoreRow, TimeDomain, TopicRef, TrackDesc, Tlv, JsonSchema } from "@synapse-sdk/core";
-import type { SynapseError } from "@synapse-sdk/core";
+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";
+import type { StateValue } from "./util.ts";
 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 {
@@ -12,24 +13,21 @@ export interface ReconnectPolicy {
     nextRetryDelayMs(ctx: RetryContext): number | null;
 }
 export type Transport = "auto" | "webtransport" | "websocket";
+/** The node's own options (`new Synapse(opts)`): who it is and how it behaves. Where it connects is a `ConnectTarget`, given to `connect()`. */
 export interface ConnectOptions {
-    /** `https://host:port/<root>`. */
-    url: 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. */
+    /** Shared across one human's web clients so they are promoted and demoted together (WP §3.5; an hmi is never promoted or demoted); 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 (`&project=`, WP §3.5). */
+    /** 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. */
+    /** `null` = no reconnect: a dropped session leaves the node `failed` (resting; `connect()` dials again). Default: 100 ms → 10 s, ×2, jitter, unlimited. */
     reconnect?: ReconnectPolicy | null;
     transport?: Transport;
     connectTimeoutMs?: number;
@@ -38,16 +36,34 @@ export interface ConnectOptions {
     /** 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). */
+/** Where the node should be connected: the argument of `connect()` (identity fields left out keep the node's current ones). */
 export interface ConnectTarget {
+    /**
+     * 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.
+     */
     url: string;
+    /** The type to declare there; left out keeps the node's current one. */
     type?: ClientType;
+    /** The name to declare there; left out keeps the node's current one. */
     name?: string;
+    /** The user id to declare there; left out keeps the node's current one. */
     userId?: string;
+    /** The credential to present there; left out keeps the node's current one. Never printed. */
     credential?: string;
+    /** Pin of *this* broker's self-signed certificate (SHA-256 hex). Absent: `SYNAPSE_BROKER_CERT_SHA256`, then the broker's helper, then unpinned (per attempt). */
     brokerCertSha256?: string;
+    /** The relay token for *this* target; left out = no token (a token for another runtime would be refused). Never printed. */
+    token?: string;
 }
+/**
+ * Where the node stands. `idle`: no target (constructed and not yet `connect()`ed, or after `disconnect()`). `failed`:
+ * the dialing gave up (`unauthorized`, the bounded `connect()` timed out, the reconnect policy declined); the node rests
+ * there and a later `connect()` dials again. `closed`: after `close()`, for good.
+ */
 export type ConnectionState = {
+    status: "idle";
+} | {
     status: "connecting";
     attempt: number;
 } | {
@@ -79,7 +95,9 @@ export interface Info {
     dom: TimeDomain;
     brokerDom: string;
     brokerVersion: string; /** The robot the runtime serves (fixed for the runtime's life; empty between sessions). */
-    robot: string;
+    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). */
@@ -93,7 +111,7 @@ export type Notice = {
     project: string | null;
 };
 export interface PublishOptions {
-    /** The frame's `t_us` (this node's clock); default now. */
+    /** The frame's `t_us` (this node's clock): the capture time, if you have one; default now. */
     tUs?: number;
     flags?: number;
 }
@@ -121,12 +139,13 @@ export interface Publisher<TIn> extends AsyncDisposable {
     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). */
+    /**
+     * 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;
-    /** Raw topics: any frame type, flags and TLVs (WP §4.1); `MEDIA` frames via `publishMedia`. */
-    publishFrame(type: number, flags: number, tUs: number, tlvs: Tlv[], body: Uint8Array): void;
-    /** Raw topics: a media access unit (`MEDIA`, flags from the frame, `t_us` = capture time, `STAGES` when stamped; a `sentUs` of 0 is stamped at the write). */
-    publishMedia(frame: MediaFrame): void;
     stats(): PublisherStats;
     close(): void;
 }
@@ -141,6 +160,12 @@ export interface Envelope<T> {
     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`). */
@@ -187,12 +212,15 @@ export interface ViewOptions<T, S> extends SubscribeOptions {
     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()`. */
+/** A topic's value now, as a state value: `get()` any time, `onChange` for each change (the framework bridge), `changed()` for the next one, `watch()` for each one in a loop; subscribed from creation until `close()`. */
 export interface View<S> extends AsyncDisposable {
     get(): ViewState<S>;
-    subscribe(listener: () => void): () => void;
+    /** `cb` with the state on each change; returns the remover. */
+    onChange(cb: (state: ViewState<S>) => void): () => void;
     ready(): Promise<void>;
     changed(): Promise<ViewState<S>>;
+    /** The state after each change (state, not history: changes in between fold into the latest); ends when the view is closed or the node ends. */
+    watch(): AsyncIterable<ViewState<S>>;
     close(): void;
 }
 export type RunStatus = "pending" | "running" | "succeeded" | "failed" | "canceled";
@@ -288,18 +316,25 @@ export type StoreChange = {
     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`).
+ * A namespace as a value kept current (SDK §9): `get()` reads it, `set`/`delete` resolve once the
+ * value shows the write, `synced` says whether it is current, `onChange`/`watch()` follow changes. The runtime
+ * decides every write (`not_owner`, `unauthorized`, `store_gone`). A write made while the handle is
+ * between incarnations (its intent being replayed, e.g. after a project activation) waits for the
+ * handle to bind again and is decided then; it is refused `store_gone` only if the handle ends first.
  */
 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(): Record<string, unknown>;
+    /** One key's value (`undefined` when absent). */
     get(key: string): unknown;
+    /** The one boolean a node author checks: `status.get().synced`. */
     readonly synced: boolean;
-    readonly status: StoreStatus;
-    /** `set(key, value)`, or `set({ ... })` for several keys as one atomic write; resolves once `value` shows it. */
+    /** The handle's own state, a state value: `get()` now (the same object while unchanged), `onChange` for each change, `changed()` for the next. */
+    readonly status: StateValue<StoreStatus>;
+    /** Resolves once the first value is in (the first snapshot applied, or the namespace absent). */
+    ready(): Promise<void>;
+    /** `set(key, value)`, or `set({ ... })` for several keys as one atomic write; resolves once `get()` shows it. */
     set(key: string, value: unknown): Promise<void>;
     set(values: Record<string, unknown>): Promise<void>;
     delete(key: string): Promise<void>;
@@ -308,8 +343,10 @@ export interface StoreHandle extends AsyncDisposable {
     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;
+    /** The whole value after its next change; `store_gone` once this handle is closed. */
+    changed(): Promise<Record<string, unknown>>;
+    /** `cb` with the whole value on every change of the value or the status (the framework bridge); returns the remover. */
+    onChange(cb: (value: Record<string, unknown>) => void): () => void;
     close(): void;
 }
 export type Vec3 = [number, number, number];
@@ -323,6 +360,11 @@ export interface Xform {
 }
 /** Which plane an entity lives in: `authored` (the project's), `calibration` (the robot's), `live` (never persisted). */
 export type SceneLayer = "authored" | "calibration" | "live";
+/**
+ * What an entity is. Any string is a kind; these are offered for completion: `frame` and `robot` are the two the runtime
+ * gives meaning to, `model` and `scan` the common others.
+ */
+export type SceneKind = "frame" | "robot" | "model" | "scan" | (string & {});
 /** Each flag holds only when it is `true`. `locked` refuses patch/reparent/rename/despawn (a flags-only patch passes). */
 export interface SceneFlags {
     locked?: boolean;
@@ -396,8 +438,11 @@ export interface Hardpoint {
 export interface SceneEntity {
     /** A ULID; never changes. */
     id: string;
-    kind: string;
-    /** Unique across the authored and calibration planes. */
+    kind: SceneKind;
+    /**
+     * Unique across every plane (authored, calibration, live): a write that would give an entity a name another entity
+     * holds is refused `name_taken`, its `data.holder` the id holding the name.
+     */
     name?: string;
     /** The parent's id; `null` is the world root. */
     parent: string | null;
@@ -417,6 +462,9 @@ export interface SceneEntity {
     /** 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[];
@@ -429,7 +477,7 @@ export interface SceneEntity {
     [key: string]: unknown;
 }
 /**
- * An id's live row (`scene.entity(id, { plane: "live" })`), each key present only when the row has it:
+ * An id's live row (`view.live.get()`), 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).
  */
@@ -455,15 +503,96 @@ export interface SceneTreeNode {
 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.
+ * `onChange` for each change (the framework bridge), `changed()` for the next one, `watch()` for each one in a
+ * loop. 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). */
+    /** `cb` with the value on each change; returns the remover. */
+    onChange(cb: (value: T) => void): () => void;
+    /** The value after each change (state, not history: changes in between fold into the latest); ends with the handle. */
+    watch(): AsyncIterable<T>;
+    /** Resolves with the value after its next change relative to the value at the call: a change already readable when it is called is not its change (with the value as it is when the handle closes). */
     changed(): Promise<T>;
 }
+/** Which entity an entity view follows: an id (that entity only), or a name (whichever entity holds it now, on any plane). */
+export type SceneEntityRef = string | {
+    name: string;
+};
+/**
+ * One entity as a view (`scene.entity(id)`, `scene.entity({ name })`), shaped like a store handle: `get()` is the
+ * merged entity now (authored with its live overrides; `undefined` when there is none), `get(component)` one of its
+ * components; `watch()` follows it. It is a `SceneView` too (`onChange`, `changed()`), so it fits wherever a view
+ * does. The scene's two planes are its two namespaces: `authored` (`get`, `set`: the entity as declared, one patch)
+ * and `live` (`get`: the live row with its `stamp`; `set`: the lanes; `remove`: the row). They have no `watch`,
+ * `onChange` or `changed` of their own: the view's cover the entity, whichever plane changed.
+ *
+ * A view by name follows the name: when the entity holding it is despawned and another takes the name, the view
+ * reads the new one (a view by id reads `undefined` from then on).
+ */
+export interface SceneEntityView extends SceneView<SceneEntity | undefined> {
+    /**
+     * The id of the entity the view names now: a view by id (what `upsert` returns), its id; a view by name, the id
+     * holding the name now (none holds it: `not_found`, `data: { name }`).
+     */
+    readonly id: string;
+    /** The merged entity now; `undefined` when there is none (absent, or the handle detached or closed). */
+    get(): SceneEntity | undefined;
+    /** One component of the merged entity now (`get("xform")`); `undefined` when the entity or the component is absent. */
+    get<K extends keyof SceneEntity & string>(component: K): SceneEntity[K] | undefined;
+    /** The entity's authored plane: one object for the view's life. */
+    readonly authored: EntityAuthored;
+    /** The entity's live plane: one object for the view's life. */
+    readonly live: EntityLive;
+    /**
+     * The entity after each change (`undefined` once it is gone); with `component`, that component each time it
+     * changes. It is state, not history: changes in between are folded, the latest wins. Ends with the handle.
+     */
+    watch(): AsyncIterable<SceneEntity | undefined>;
+    watch<K extends keyof SceneEntity & string>(component: K): AsyncIterable<SceneEntity[K] | undefined>;
+}
+/** An entity view's authored plane (`view.authored`). Reads as the view does: nothing once the handle is detached or closed. */
+export interface EntityAuthored {
+    /** The entity as declared (the authored entity, or a live entity's upsert row), without the live lanes; its object changes only when that value does. */
+    get(): SceneEntity | undefined;
+    get<K extends keyof SceneEntity & string>(component: K): SceneEntity[K] | undefined;
+    /**
+     * `set(component, value)`, or `set({ ...components })` for several: one `patch` of the authored entity the view
+     * names now (by name: the id holding the name at the call), resolved once the entities show it; the runtime's
+     * refusal is the error. A view by id sends the patch as `scene.authored.patch(id, …)` does (an id the runtime does
+     * not have: its `not_found`). A view by name whose name no entity holds has no id to send to: `not_found`
+     * (`data: { name }`), nothing sent. Detached: `project_inactive`.
+     */
+    set<K extends keyof SceneEntity & string>(component: K, value: SceneEntity[K]): Promise<void>;
+    set(components: Partial<SceneEntity>): Promise<void>;
+}
+/** An entity view's live plane (`view.live`). Reads as the view does: nothing once the handle is detached or closed. */
+export interface EntityLive {
+    /** The entity's live row ({@link SceneEntityLive}, its `stamp` included); `undefined` without one. */
+    get(): SceneEntityLive | undefined;
+    get<K extends keyof SceneEntityLive & string>(component: K): SceneEntityLive[K] | undefined;
+    /**
+     * Writes the live lanes of the entity the view names now, as one `scene.live.batch` (synchronous, like `publish`):
+     * `xform: { t, q }` the pose lane (both required, nothing else), `joints` the joints lane, `state` the state lane; any
+     * other component is `invalid_input`. `lifetimeMs`: the override expires that long after its last write (the entity's
+     * authored values show again); a live entity keeps the lifetime it was upserted with. The first write for an id this
+     * node has not claimed asks the claim (see `scene.live.batch`), so a single write lands. A view by name whose name no
+     * entity holds: `not_found`. Not attached: dropped and counted (`status.get().detachedDrops`). Closed, or the node
+     * ended: `not_connected`.
+     */
+    set(components: {
+        xform?: {
+            t: Vec3;
+            q: Quat;
+        };
+        joints?: Record<string, number>;
+        state?: Record<string, unknown>;
+    }, opts?: {
+        lifetimeMs?: number;
+    }): void;
+    /** Releases this node's claim of the entity the view names now (`scene.live.remove(id)`, the call): the runtime retracts its live row. */
+    remove(): Promise<void>;
+}
 /** `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 {
@@ -475,10 +604,12 @@ export interface SceneStatus {
     /** 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. */
+    /** Live writes (`scene.live.batch`, `view.live.set`) dropped because the handle was not attached. */
     detachedDrops: number;
+    /** Lane rows dropped because their id's claim was refused (rows parked while it was asked, and rows written while refused). */
+    unclaimedDrops: number;
 }
-/** An authored change as the runtime applied it (the `watchChanges` feed). */
+/** An authored change as the runtime applied it (a diff op of the scene's `authored` track). */
 export type SceneDiffOp = {
     op: "spawn";
     entity: SceneEntity;
@@ -542,27 +673,27 @@ export type SceneOp = {
  */
 export type SceneSpawnOptions = {
     name: string;
-    parent?: string | null;
+    parent?: string | SceneEntityView | 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). */
+/** Where `reparent` puts the entity among its new siblings (default: after the last): a sibling by its id or its view. */
 export type ScenePlace = {
-    before: string;
+    before: string | SceneEntityView;
 } | {
-    after: string;
+    after: string | SceneEntityView;
 };
-/** One authoring batch being built (`txn`): sent as one atomic `apply`. */
+/** One authoring batch being built (`txn`): sent as one atomic `apply`. An entity is named by its id or by a view of it (`upsert`'s result). */
 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?: {
+    spawn(kind: SceneKind, opts: SceneSpawnOptions): string;
+    /** Sets components of the entity (an object merges into an object one level deep). */
+    patch(entity: string | SceneEntityView, set: Partial<SceneEntity>): void;
+    rename(entity: string | SceneEntityView, name: string): void;
+    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, place?: ScenePlace): void;
+    despawn(entity: string | SceneEntityView, opts?: {
         cascade?: boolean;
     }): void;
-    setLocked(id: string, locked: boolean): void;
+    setLocked(entity: string | SceneEntityView, locked: boolean): void;
     /** The ops as they will be sent. */
     readonly ops: readonly SceneOp[];
 }
@@ -579,80 +710,261 @@ 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. */
+/**
+ * One live batch: data only, the lanes (`poses`, `joints`, `state`). `lifetimeMs` makes the override rows the batch
+ * touches expire. Claims are calls, never rows: `scene.live.upsert` and `scene.live.remove`.
+ */
 export interface LiveBatch {
-    upsert?: SceneEntity[];
     poses?: LivePose[];
     joints?: LiveJoints[];
     state?: LiveState[];
-    remove?: string[];
     lifetimeMs?: number;
+    upsert?: never;
+    remove?: never;
 }
-/** A live row removed: the writer removed it, its lifetime ran out, or its writer left. */
+/** A live row removed: the writer removed it, its lifetime ran out, its writer left, or its entity (or a parent) was despawned (the claim is released). */
 export interface LiveRemoved {
     id: string;
-    by: "explicit" | "timeout" | "writer_gone";
+    by: "explicit" | "timeout" | "writer_gone" | "despawned";
+}
+/**
+ * The authored plane's verbs (`scene.authored`): the editor's (`spawn`, `patch`, `rename`, `reparent`, `despawn`,
+ * `setLocked`, `txn`, `apply`) and the node author's `upsert`. Every write goes to the runtime, which decides it, and
+ * resolves once the entities show it; a refusal is the runtime's error. Detached: `project_inactive`. An entity is
+ * named by its id or by a view of it.
+ */
+export interface SceneAuthored {
+    /** One atomic batch; `base`: the version its structural ops assume. */
+    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: SceneKind, opts: SceneSpawnOptions): Promise<string>;
+    patch(entity: string | SceneEntityView, set: Partial<SceneEntity>): Promise<void>;
+    /**
+     * A builder's one verb, keyed by `name`; resolves with the entity's view (by id: that entity) once the entities show
+     * it. No authored entity of that name: `spawn(kind, { name, parent, ...components })`. One of `kind`: its authored
+     * value is compared with what `patch(id, components)` would make of it (one-level merge; live overrides never
+     * count): equal, nothing is sent; else a patch of the components that differ. `parent` is used by the spawn only: an
+     * existing entity is not reparented. One of another kind, or a name a live entity holds: the spawn is sent and the
+     * runtime answers (`name_taken`, `data.holder`, while the name is held; the copy here may be stale). An `id`
+     * component: `invalid_input` (`data: { component: "id" }`), nothing sent.
+     */
+    upsert(kind: SceneKind, opts: SceneSpawnOptions & {
+        id?: never;
+    }): Promise<SceneEntityView>;
+    rename(entity: string | SceneEntityView, name: string): Promise<void>;
+    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, place?: ScenePlace): Promise<void>;
+    despawn(entity: string | SceneEntityView, opts?: {
+        cascade?: boolean;
+    }): Promise<void>;
+    setLocked(entity: string | SceneEntityView, locked: boolean): Promise<void>;
+}
+/**
+ * The live plane's verbs (`scene.live`). Decisions are calls, data is streams (PLAN v0.31): a claim is the call
+ * `synapse/scene/live/upsert` (`upsert`), a release the call `synapse/scene/live/remove` (`remove`); the lanes go on this
+ * node's live track (made on the first write of each session), synchronously like `publish` (`batch`, `view.live.set`).
+ * The runtime decides identity and ownership; nothing here reads the entities to decide what to send.
+ */
+export interface SceneLive {
+    /**
+     * One batch of lanes (the sim's one call per tick); returns at once. A row goes out only for an id this node claimed in
+     * the bound incarnation: a live entity of its `upsert`, or the override of an entity of the scene, which the first row
+     * of its id asks for (the call `upsert {id}`, once). Until the answer the latest row of each lane of that id is kept
+     * (latest wins) and sent once the claim is granted, so a single write lands; a refusal drops them (counted in
+     * `status.get().unclaimedDrops` with the rows written while refused), is a node notice (`node.notices`) and is asked
+     * again, paced, by a later row. The runtime stamps the rows; a row it does not apply comes back on `watchLiveDenied`.
+     * Not attached: dropped and counted (`status.get().detachedDrops`). Closed: `not_connected`. Never sent again.
+     */
+    batch(batch: LiveBatch): void;
+    /**
+     * A live entity of this node's: the call `synapse/scene/live/upsert {kind, name?, parent, lifetime_ms?, ...components}`;
+     * resolves with its view (by the id the runtime answered: minted for a new one; a name this node already claimed sends
+     * that claim's id). Rejects with the runtime's refusal as it came (`name_taken {name, id, holder}`, `not_owner`,
+     * `conflict`, `invalid_tree`, `project_inactive`, `unauthorized`, ...): nothing is kept. Granted, it is this node's claim:
+     * claimed again, same id, on every attach (a new session, a project switch, a scene restart; a refused re-claim is
+     * asked again, paced, with a warning), until `remove`. A session that goes before the answer: asked at the next
+     * attach. Detached: `project_inactive`; the node ending: `not_connected`. An `id` component: `invalid_input`
+     * (`data: { component: "id" }`), nothing sent.
+     */
+    upsert(kind: SceneKind, opts?: Omit<SceneSpawnOptions, "name" | "id"> & {
+        name?: string;
+        id?: never;
+    }, live?: {
+        lifetimeMs?: number;
+    }): Promise<SceneEntityView>;
+    /** Releases this node's claim of the entity: the call `synapse/scene/live/remove {id}` (the runtime retracts its row); the claim is not made again. Not held in the bound incarnation: resolves at once. */
+    remove(entity: string | SceneEntityView): Promise<void>;
 }
 /**
  * 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.
+ * Views and feeds read the handle's copy of the scene; the writes are in `authored` (the authored plane) and `live`
+ * (this node's live rows).
  */
 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>>;
+    get(): 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.
+     * One entity as a view ({@link SceneEntityView}), by id or by name (`entity({ name: "tool" })`: the entity holding
+     * the name now): merged, authored with its live overrides; one plane alone through the view (`view.authored`, `view.live`).
      */
-    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>;
+    entity(ref: SceneEntityRef): SceneEntityView;
     /** 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 handle's own state, a state value: `get()` now (the same object while unchanged), `onChange` for each change, `changed()` for the next. */
+    readonly status: StateValue<SceneStatus>;
+    /** The one boolean a node author checks: `status.get().synced`. */
+    readonly synced: boolean;
+    /** Resolves once the handle is attached (at once if it is); `not_connected` once the handle is closed. No timeout: pass an `AbortSignal` to what awaits it, or race it. */
+    ready(): Promise<void>;
+    /** The entities after their next change (state, not history); `not_connected` once the handle is closed. */
+    changed(): Promise<Readonly<Record<string, SceneEntity>>>;
+    /** The entities after each change (state, not history: changes in between fold into the latest); ends with the handle. */
+    watch(): AsyncIterable<Readonly<Record<string, SceneEntity>>>;
+    /** `cb` with the entities on every change of the entities or the status (the framework bridge); returns the remover. */
+    onChange(cb: (entities: Readonly<Record<string, SceneEntity>>) => void): () => void;
     /** 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;
+    /** The authored plane's verbs. */
+    readonly authored: SceneAuthored;
+    /** This node's live writes. */
+    readonly live: SceneLive;
     /** 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. */
+    get(): 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>;
+    /** `cb` with the value on every change of the value or of `synced` (the framework bridge); returns the remover. */
+    onChange(cb: (value: V) => 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" | "get" | "set" | "watch" | "destroy" | "close" | typeof Symbol.asyncDispose> {
+    /** Every declaration, `instance` → declaration. */
+    get(): Readonly<Record<string, TaskDeclaration>>;
+    get(instance: string): TaskDeclaration | undefined;
+    /**
+     * `set(declaration)`: a new declaration under an instance the SDK mints (a ulid), resolving with that instance;
+     * `set(instance, declaration)` writes the one named; `set({ ... })` several as one atomic write. One object is a
+     * declaration when its `ref` is a string, else a map `instance` → declaration. Each waits for the value to be current
+     * first and resolves once `get()` shows the write.
+     */
+    set(declaration: TaskDeclaration): Promise<string>;
+    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;