@synapse-sdk/client 0.3.7 → 0.3.9

package/dist/channel.d.ts

@@ -1,6 +1,7 @@
 import { SynapseError, encode as encodeBody, type ErrorBody } from "@synapse-sdk/core";
 import type { Node } from "./node.ts";
 import type { Session } from "./session.ts";
+import type { Verdict } from "./types.ts";
 import { AsyncQueue, type Deferred } from "./util.ts";
 /** A fresh binding id (WP §8.1): 6 hex digits, the identity of one attempt to the runtime. */
 export declare function newBind(): string;
@@ -12,8 +13,10 @@ export declare const REFUSAL_PACE_MAX_MS = 5000;
 export declare function refusalPaceMs(n: number): number;
 /** The runtime is mid-change and says so: asked again shortly, silently. */
 export declare function isTransient(e: SynapseError): boolean;
-/** A refusal that is asked again, never a verdict: every code but the session going. */
-export declare function isReasked(e: SynapseError): boolean;
+/** A refusal for a fault of the caller's (PLAN v0.42): not asked again on this session; the verdict is `refused`. */
+export declare function isTerminal(e: SynapseError): boolean;
+/** A refusal that is asked again, paced and warned, never a verdict (contention: `already_registered`, `owner_taken`, `name_taken`, `unauthorized`, and every other code that is neither transient nor terminal); not the session going. */
+export declare function isContention(e: SynapseError): boolean;
 /** The holder a refusal names (`data.by`), if it does. */
 export declare function holderOf(e: SynapseError): string | undefined;
 export type Event = {
@@ -51,15 +54,7 @@ export interface Intent {
     /** Retracts what `install` installed, if anything is. */
     retract(): void;
     /** Where the intent stands on the current session. */
-    setVerdict(v: {
-        status: "unbound";
-    } | {
-        status: "pending";
-        epoch: number;
-    } | {
-        status: "admitted";
-        epoch: number;
-    }): void;
+    setVerdict(v: Verdict): void;
     /** The task is exiting (after the last retract). */
     exited?(): void;
     warn(msg: string): void;
@@ -72,7 +67,7 @@ export declare class Handle {
     readonly mailbox: AsyncQueue<Event>;
     readonly exited: Deferred<void>;
     constructor(node: Node, intent: Intent);
-    /** Resolves once the current attempt is admitted and announced; `not_connected` once the task is gone. */
+    /** Resolves once the current attempt is admitted and announced; rejects with a terminal refusal of the current session; `not_connected` once the task is gone. */
     ready(): Promise<void>;
     /** The intent is over: the task writes the `unregister` and exits. */
     unregister(): void;

package/dist/channel.js

@@ -9,10 +9,14 @@
 // - `ended`: the installed binding's reader ended (a provider's `calls` track): a renewal on the same session;
 // - `ready`: the application waits for the admission ([`Handle.ready`]), answered when it lands;
 // - `retry`: a paced re-ask is due; `unregister`: the application dropped the handle.
-// A transient reply (the runtime mid-change) is asked again on the same bind after `REFOLLOW_PACE`;
-// every refusal too (D 2026-10-06, R6, "phoenix style"), paced `refusalPace`, with a warning each
-// time. A refusal is no verdict: the verdict stays `pending`. Fast-lane invariant: the task never
-// sits between the application and a data track; it only installs and retracts what the fast lane uses.
+// A refusal is one of three kinds (PLAN v0.42): transient (the runtime mid-change), asked again on
+// the same bind after `REFOLLOW_PACE`, silently; contention (`already_registered`, `owner_taken`,
+// `name_taken`, `unauthorized`, and every code not named here: D 2026-10-06, R6, "phoenix style"),
+// asked again paced `refusalPace` with a warning each time, the verdict staying `pending`; terminal
+// (the caller's fault: `isTerminal`): the verdict `refused` with the error, one warning, nothing
+// asked again on the session, `ready()` rejects with it; the next session is a new attempt.
+// Fast-lane invariant: the task never sits between the application and a data track; it only
+// installs and retracts what the fast lane uses.
 import { SynapseError, encode as encodeBody } from "@synapse-sdk/core";
 import { startOn } from "./calls.js";
 import { AsyncQueue, deferred } from "./util.js";
@@ -26,8 +30,10 @@ export const REFUSAL_PACE_MAX_MS = 5000;
 export function refusalPaceMs(n) { return Math.min(REFOLLOW_PACE_MS * 2 ** Math.min(n - 1, 31), REFUSAL_PACE_MAX_MS); }
 /** The runtime is mid-change and says so: asked again shortly, silently. */
 export function isTransient(e) { return ["service_unavailable", "provider_unavailable", "overloaded", "project_settling", "timeout"].includes(e.code); }
-/** A refusal that is asked again, never a verdict: every code but the session going. */
-export function isReasked(e) { return e.code !== "not_connected" && e.code !== "connection_lost"; }
+/** A refusal for a fault of the caller's (PLAN v0.42): not asked again on this session; the verdict is `refused`. */
+export function isTerminal(e) { return ["schema_mismatch", "content_mismatch", "invalid_input", "mode_mismatch", "project_inactive"].includes(e.code); }
+/** A refusal that is asked again, paced and warned, never a verdict (contention: `already_registered`, `owner_taken`, `name_taken`, `unauthorized`, and every other code that is neither transient nor terminal); not the session going. */
+export function isContention(e) { return !isTerminal(e) && !isTransient(e) && e.code !== "not_connected" && e.code !== "connection_lost"; }
 /** The holder a refusal names (`data.by`), if it does. */
 export function holderOf(e) { const d = e.data; return d && typeof d.by === "string" ? d.by : undefined; }
 /** The application's side of a handle: its mailbox, and `ready()` as a request to the task. */
@@ -41,7 +47,7 @@ export class Handle {
         this.node = node;
         this.intent = intent;
     }
-    /** Resolves once the current attempt is admitted and announced; `not_connected` once the task is gone. */
+    /** Resolves once the current attempt is admitted and announced; rejects with a terminal refusal of the current session; `not_connected` once the task is gone. */
     ready() {
         const reply = deferred();
         if (!this.mailbox.push({ kind: "ready", reply }))
@@ -64,6 +70,8 @@ async function run(h) {
     let attempt = 0;
     let current;
     let admitted = false;
+    /** The current attempt's terminal refusal: nothing is asked again on its session. */
+    let refusedWith;
     let refusals = 0;
     let retryTimer;
     const ready = [];
@@ -110,6 +118,7 @@ async function run(h) {
         attempt += 1;
         clearRetry();
         admitted = false;
+        refusedWith = undefined;
         const a = current;
         current = undefined;
         if (!a)
@@ -141,6 +150,15 @@ async function run(h) {
         intent.warn(`${intent.registerSvc} ${intent.name}: ${what} (${e.code}${e.message ? `: ${e.message}` : ""}; holder ${holderOf(e) ?? "-"}; attempt ${refusals}; again in ${pace} ms)`);
         scheduleRetry(pace);
     };
+    /** A terminal refusal (PLAN v0.42): `refused`, one warning, no re-ask; the waiting `ready()`s reject with it. */
+    const refusedForGood = (e, epoch) => {
+        intent.warn(`${intent.registerSvc} ${intent.name}: refused by the runtime; not asked again on this session (${e.code}${e.message ? `: ${e.message}` : ""}; holder ${holderOf(e) ?? "-"})`);
+        clearRetry();
+        refusedWith = e;
+        intent.setVerdict({ status: "refused", epoch, error: e });
+        for (const r of ready.splice(0))
+            r.reject(e);
+    };
     const { session: first, unmonitor } = node.monitor(e => mailbox.push(e.kind === "started" ? { kind: "session", session: e.session } : e.kind === "ended" ? { kind: "sessionEnded" } : { kind: "nodeEnded" }));
     sessionChanged(first);
     try {
@@ -173,7 +191,9 @@ async function run(h) {
                     }
                     else if (isTransient(ev.result))
                         scheduleRetry(REFOLLOW_PACE_MS);
-                    else if (isReasked(ev.result))
+                    else if (isTerminal(ev.result))
+                        refusedForGood(ev.result, a.session.epoch);
+                    else if (isContention(ev.result))
                         refused(ev.result, "refused by the runtime; asking again");
                     // else: the session went; its end (a message on its way) begins the next attempt
                     break;
@@ -190,6 +210,8 @@ async function run(h) {
                 case "ready":
                     if (admitted)
                         ev.reply.resolve();
+                    else if (refusedWith)
+                        ev.reply.reject(refusedWith);
                     else
                         ready.push(ev.reply);
                     break;

package/dist/scene.d.ts

@@ -3,7 +3,7 @@ import { SynapseError, type ErrorBody, type ProjectSnapshot } from "@synapse-sdk
 import type { Node } from "./node.ts";
 import { StreamWriter, type Session } from "./session.ts";
 import type { Warn } from "./topics.ts";
-import type { LiveJoints, LivePose, LiveRemoved, LiveState, Quat, SceneAuthored, SceneDiffOp, SceneEntity, SceneEntityLive, SceneEntityRef, SceneEntityView, SceneHandle, SceneKind, SceneLive, SceneOp, ScenePlace, SceneSpawnOptions, SceneState, SceneStatus, SceneTree, SceneTxn, SceneView, Vec3 } from "./types.ts";
+import type { LiveJoints, LivePose, LiveRemoved, LiveState, Quat, SceneAuthored, SceneDiffOp, SceneEntity, SceneEntityLive, SceneEntityRef, SceneEntityView, SceneHandle, SceneKind, SceneLive, SceneOp, SceneSpawnOptions, SceneState, SceneStatus, SceneTree, SceneTxn, SceneView, Vec3 } from "./types.ts";
 import { AsyncQueue, type Deferred, type StateValue } from "./util.ts";
 /** How many batches a feed may fall behind before it is ended (the store's `STORE_FEED_CAP`). */
 export declare const SCENE_FEED_CAP = 256;
@@ -12,6 +12,9 @@ export declare const PATCH_PROTECTED: readonly string[];
 type Entities = Map<string, SceneEntity>;
 /** An entity named by its id or by a view of it (the id the view names now). */
 type EntityArg = string | SceneEntityView;
+/** A patch's `set` and `reparent`'s options, as the public interfaces take them. */
+type PatchSet = Parameters<SceneTxn["patch"]>[1];
+type ReparentOptions = NonNullable<Parameters<SceneTxn["reparent"]>[2]>;
 /**
  * A fresh entity id: a ULID (26 Crockford base-32 characters) made from a UUIDv7 (48-bit ms, version,
  * 74 random bits, variant), so ids sort by the time they were minted; within one millisecond the
@@ -30,6 +33,14 @@ export declare function orderBetween(left: string | null | undefined, right: str
  * prototype's rule). A cycle cannot come from the runtime; were one there, it is cut where it closes.
  */
 export declare function treeOf(entities: Readonly<Record<string, SceneEntity>>): SceneTree;
+/**
+ * The runtime's patch merge (`merge_set`): merges one level deep; a null deletes the key it names. A top-level null
+ * removes the component; an object merges into an object component key by key, a null sub-key removing that sub-key;
+ * an object given for a component that is absent or not an object replaces it without its null sub-keys, and nulls
+ * alone leave no component (an explicitly given `{}` is kept); any other value replaces. `undefined` is not given (the
+ * encoder skips it).
+ */
+export declare function mergeSet(into: Record<string, unknown>, set: Record<string, unknown>): Record<string, unknown>;
 /**
  * One authoring batch being built (`txn`): the ops it sends as one atomic `apply`. Ops on an entity
  * spawned in the same batch fold into its spawn: a patch (of keys a patch may set) or a rename merges
@@ -41,11 +52,15 @@ export declare class Txn implements SceneTxn {
     get ops(): readonly SceneOp[];
     /** Spawns an entity of `kind` under `opts.parent` (default the world root) with the components given (`layer` `authored` when not given, else `calibration`; a live entity is not spawned here, it comes from `scene.live.upsert`); its id is minted here (or `opts.id`, a known one) and returned. No `order` is sent: the runtime appends it after its siblings. */
     spawn(kind: SceneKind, opts: SceneSpawnOptions): string;
-    /** Sets components of the entity (one level deep: an object merges into an object). */
-    patch(entity: EntityArg, set: Partial<SceneEntity>): void;
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
+    patch(entity: EntityArg, set: PatchSet): void;
     rename(entity: EntityArg, name: string): void;
-    /** Moves the entity under `parent` (`null`: the world root), before or after a sibling (default: after the last). */
-    reparent(entity: EntityArg, parent: EntityArg | null, place?: ScenePlace): void;
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default it keeps its world pose (the runtime's default: nothing sent); `preserveWorld: false` sends
+     * `preserve_world: false`, and it keeps its local xform.
+     */
+    reparent(entity: EntityArg, parent: EntityArg | null, opts?: ReparentOptions): void;
     /** Despawns the entity (`cascade`: with its subtree). One spawned in this batch is cancelled instead, unless it has children spawned in the batch and `cascade` is off (then the runtime decides). */
     despawn(entity: EntityArg, opts?: {
         cascade?: boolean;

package/dist/scene.js

@@ -231,14 +231,45 @@ export function treeOf(entities) {
     return build(null);
 }
 // -------------------------------------------------------------------------------------------- txn
-/** One level of the runtime's patch merge: an object merges into an object key by key; anything else replaces. */
-function mergeSet(into, set) {
+/**
+ * The runtime's patch merge (`merge_set`): merges one level deep; a null deletes the key it names. A top-level null
+ * removes the component; an object merges into an object component key by key, a null sub-key removing that sub-key;
+ * an object given for a component that is absent or not an object replaces it without its null sub-keys, and nulls
+ * alone leave no component (an explicitly given `{}` is kept); any other value replaces. `undefined` is not given (the
+ * encoder skips it).
+ */
+export function mergeSet(into, set) {
     const out = { ...into };
     for (const [k, v] of Object.entries(set)) {
         if (v === undefined)
             continue;
+        if (v === null) {
+            delete out[k];
+            continue;
+        }
+        if (!isObject(v)) {
+            out[k] = v;
+            continue;
+        }
+        const given = Object.entries(v).filter(([, s]) => s !== undefined);
         const old = out[k];
-        out[k] = isObject(old) && isObject(v) ? { ...old, ...v } : v;
+        if (isObject(old)) {
+            const next = { ...old };
+            for (const [s, sv] of given) {
+                if (sv === null)
+                    delete next[s];
+                else
+                    next[s] = sv;
+            }
+            out[k] = next;
+        }
+        else {
+            const kept = given.filter(([, s]) => s !== null);
+            if (kept.length === 0 && given.length > 0)
+                delete out[k];
+            else
+                out[k] = Object.fromEntries(kept);
+        }
     }
     return out;
 }
@@ -264,7 +295,7 @@ export class Txn {
         this.#ops.push({ op: "spawn", entity });
         return id;
     }
-    /** Sets components of the entity (one level deep: an object merges into an object). */
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
     patch(entity, set) {
         const id = idOf(entity);
         // A protected key is the runtime's to refuse: such a patch is sent as it is.
@@ -287,13 +318,19 @@ export class Txn {
         }
         this.#ops.push({ op: "rename", id, name });
     }
-    /** Moves the entity under `parent` (`null`: the world root), before or after a sibling (default: after the last). */
-    reparent(entity, parent, place) {
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default it keeps its world pose (the runtime's default: nothing sent); `preserveWorld: false` sends
+     * `preserve_world: false`, and it keeps its local xform.
+     */
+    reparent(entity, parent, opts = {}) {
         const op = { op: "reparent", id: idOf(entity), parent: parent === null ? null : idOf(parent, "parent") };
-        if (place && "before" in place)
-            op.before = idOf(place.before, "before");
-        else if (place && "after" in place)
-            op.after = idOf(place.after, "after");
+        if (opts.before !== undefined)
+            op.before = idOf(opts.before, "before");
+        else if (opts.after !== undefined)
+            op.after = idOf(opts.after, "after");
+        if (opts.preserveWorld === false)
+            op.preserve_world = false;
         this.#ops.push(op);
     }
     /** Despawns the entity (`cascade`: with its subtree). One spawned in this batch is cancelled instead, unless it has children spawned in the batch and `cascade` is off (then the runtime decides). */
@@ -1972,7 +2009,7 @@ export class SceneHandleImpl {
             patch: (entity, set) => this.#txn(t => t.patch(entity, set)),
             upsert: (kind, opts) => this.#upsert(kind, opts),
             rename: (entity, name) => this.#txn(t => t.rename(entity, name)),
-            reparent: (entity, parent, place) => this.#txn(t => t.reparent(entity, parent, place)),
+            reparent: (entity, parent, opts) => this.#txn(t => t.reparent(entity, parent, opts)),
             despawn: (entity, opts) => this.#txn(t => t.despawn(entity, opts)),
             setLocked: (entity, locked) => this.#txn(t => t.setLocked(entity, locked)),
         });

package/dist/serve.d.ts

@@ -2,7 +2,7 @@ import { type Card, type ErrorBody, type ServiceContract } from "@synapse-sdk/co
 import { Handle, type Event as HandleEvent, type Intent } from "./channel.ts";
 import type { Node } from "./node.ts";
 import { type Session } from "./session.ts";
-import type { RegVerdict, Registration, ServeHandler } from "./types.ts";
+import type { RegVerdict, Registration, ServeHandler, Verdict } from "./types.ts";
 import type { Warn } from "./topics.ts";
 /** The reason `ctx.signal` carries when our track or session went (WP §8.4). */
 export declare const TRACK_LOST = "track_lost";
@@ -30,15 +30,7 @@ export declare class ServiceRegistration<I, U, R> implements Intent, Registratio
     /** Announces the card and `out`, installs the binding, then starts its `calls` reader. */
     install(s: Session, bind: string, mailbox: (e: HandleEvent) => void): void;
     retract(): void;
-    setVerdict(v: {
-        status: "unbound";
-    } | {
-        status: "pending";
-        epoch: number;
-    } | {
-        status: "admitted";
-        epoch: number;
-    }): void;
+    setVerdict(v: Verdict): void;
     /** The task is exiting: whatever handler still runs is this registration's to cancel. */
     exited(): void;
 }

package/dist/store.d.ts

@@ -30,6 +30,8 @@ export declare class State {
     gap: number | undefined;
     pending: number;
     ended: string | undefined;
+    /** The open's terminal refusal on the current session (PLAN v0.42). */
+    refused: SynapseError | undefined;
     subscribe(l: () => void): () => void;
     watch(): AsyncQueue<StoreChange[]>;
     /** A feed its reader has left: it is closed and gets nothing more. */
@@ -42,6 +44,8 @@ export declare class State {
     applyDiff(d: StoreDiff, warn: Warn): boolean;
     /** Nothing of the incarnation is known until the runtime answers the next open. */
     reset(): void;
+    /** The open was refused for good on this session: nothing of the incarnation is known, the error is the status's. */
+    refuse(e: SynapseError): void;
     opened(a: StoreAccess | undefined): void;
     end(reason: string): void;
     setPending(n: number): void;

package/dist/store.js

@@ -3,7 +3,9 @@
 // Its intent is the open (`synapse/store/open` with the handle's access mode); admitted, it follows the
 // incarnation the reply names (`runtime/store/<ns>/@<epoch>`, or `runtime/config/@<epoch>`), track
 // `data`: a snapshot, then diffs, then a final frame. The mirror is the runtime's: nothing is decided
-// here. A refusal is asked again, paced, with a warning (R6); a transient reply paced, silently; an
+// here. A contention refusal is asked again, paced, with a warning (R6); a terminal one (`mode_mismatch`,
+// `invalid_input`, ...: PLAN v0.42) is the status's `refused`, warned once, not asked again until the
+// next session; a transient reply paced, silently; an
 // incarnation that ends (writer gone, project switch, the owner restarted) replays the intent;
 // `destroyed` ends the handle. Writes name the epoch the mirror holds; the runtime checks ownership
 // (`not_owner`). Between incarnations (a session change, a replay) nothing is known: a write then is
@@ -11,7 +13,7 @@
 import * as Moq from "@moq/net";
 import { FLAGS, STORE_TRACK, SynapseError, decode as decodeBody, decodeHeader, moqPriority, storeBasePath, storeRobotScoped, } from "@synapse-sdk/core";
 import { startOn } from "./calls.js";
-import { REFOLLOW_PACE_MS, holderOf, isTransient, refusalPaceMs } from "./channel.js";
+import { REFOLLOW_PACE_MS, holderOf, isTerminal, isTransient, refusalPaceMs } from "./channel.js";
 import { latestSubscription, waitActive } from "./session.js";
 import { AsyncQueue, StatusCell, TIMEOUT, deferred, withTimeout } from "./util.js";
 export const ENDED_DESTROYED = "destroyed";
@@ -43,6 +45,8 @@ export class State {
     gap;
     pending = 0;
     ended;
+    /** The open's terminal refusal on the current session (PLAN v0.42). */
+    refused;
     #listeners = new Set();
     #watchers = new Set();
     subscribe(l) { this.#listeners.add(l); return () => { this.#listeners.delete(l); }; }
@@ -155,6 +159,15 @@ export class State {
         this.minRole = undefined;
         this.onDeath = undefined;
         this.absent = false;
+        this.refused = undefined;
+        this.#notify();
+    }
+    /** The open was refused for good on this session: nothing of the incarnation is known, the error is the status's. */
+    refuse(e) {
+        if (this.ended !== undefined)
+            return;
+        this.reset();
+        this.refused = e;
         this.#notify();
     }
     opened(a) {
@@ -189,7 +202,7 @@ export class State {
     status(nodeConnected, closed = false) {
         const ended = closed ? ENDED_CLIENT : this.ended;
         const connected = ended === undefined && nodeConnected;
-        return { synced: connected && this.pending === 0 && this.gap === undefined && (this.loaded || this.absent), connected, pending: this.pending, mode: this.mode, owner: this.owner, mine: this.mine, minRole: this.minRole, onDeath: this.onDeath, absent: this.absent, version: this.version, epoch: this.epoch, ended };
+        return { synced: connected && this.pending === 0 && this.gap === undefined && (this.loaded || this.absent), connected, pending: this.pending, mode: this.mode, owner: this.owner, mine: this.mine, minRole: this.minRole, onDeath: this.onDeath, absent: this.absent, version: this.version, epoch: this.epoch, ended, refused: this.refused };
     }
 }
 function sameValue(a, b) {
@@ -269,7 +282,7 @@ async function run(ns, registry) {
     const idle = () => { stopPhase(); phase = { kind: "idle" }; };
     /** Writes the open on the task's session, from `idle`, when nothing holds it back. */
     const open = () => {
-        if (phase.kind !== "idle" || destroying > 0 || state.ended !== undefined || !session)
+        if (phase.kind !== "idle" || destroying > 0 || state.ended !== undefined || state.refused !== undefined || !session)
             return;
         const s = session;
         leaveIncarnation();
@@ -395,6 +408,13 @@ async function run(ns, registry) {
             phase = { kind: "waitingProject", before: known };
             return;
         }
+        if (isTerminal(e)) {
+            warn(`store ${name}: open refused by the runtime; not asked again on this session (${e.code}${e.message ? `: ${e.message}` : ""}; holder ${holderOf(e) ?? "-"})`);
+            state.refuse(e);
+            for (const j of joining.splice(0))
+                j.reject(e);
+            return;
+        }
         refusals += 1;
         const pace = refusalPaceMs(refusals);
         warn(`store ${name}: open refused by the runtime (${e.code}${e.message ? `: ${e.message}` : ""}; holder ${holderOf(e) ?? "-"}; attempt ${refusals}; again in ${pace} ms)`);
@@ -418,6 +438,10 @@ async function run(ns, registry) {
             reply.reject(new SynapseError("project_inactive"));
             return;
         }
+        if (state.refused) {
+            reply.reject(state.refused);
+            return;
+        }
         if (state.absent || (state.loaded && state.version >= wanted))
             reply.resolve();
         else

package/dist/synapse.d.ts

@@ -2,7 +2,7 @@ import { type Age, type ErrorBody, type ProjectSnapshot, type ServiceContract, t
 import { Node } from "./node.ts";
 import { StoreHandleImpl } from "./store.ts";
 import { type Warn } from "./topics.ts";
-import type { CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Discovery, DiscoveryState, Envelope, FetchToken, Info, Metrics, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, Tasks, View, ViewOptions } from "./types.ts";
+import type { CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Discovery, DiscoveryState, Envelope, FetchToken, Info, Metrics, ProjectListing, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, Tasks, View, ViewOptions } from "./types.ts";
 import { type StateValue } from "./util.ts";
 export { FIRST_CONNECT_GIVE_UP_MS } from "./node.ts";
 export declare class Synapse implements AsyncDisposable {
@@ -83,7 +83,7 @@ export declare class Synapse implements AsyncDisposable {
         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). */
+    /** A publisher of `topic`; resolves once the runtime admitted it on the current session (a contention refusal is asked again, paced, warned; a terminal one, e.g. `schema_mismatch`, rejects it). */
     publisher<TIn, TOut>(topic: TopicContract<TIn, TOut>): Promise<Publisher<TIn>>;
     publisher<TIn = unknown>(topic: string): Promise<Publisher<TIn>>;
     /**
@@ -91,12 +91,15 @@ export declare class Synapse implements AsyncDisposable {
      * `for await`. Its follow task starts now. With `cb`, the callback form: the SDK runs the read loop and calls `cb` with
      * each batch `next()` returns (a throwing `cb` is rethrown later; the loop goes on); the same subscription comes back
      * (`unsubscribe()` ends it, `stats` counts it).
+     *
+     * A contract with a schema also tells the runtime the shape this node reads: the catalog lists the topic and this node
+     * under `subscribers` while the subscription lives, before anyone publishes. A subscription by bare name is not listed.
      */
     subscribe<TIn, TOut>(topic: TopicContract<TIn, TOut>, opts?: SubscribeOptions): Subscription<TOut>;
     subscribe<TIn, TOut>(topic: TopicContract<TIn, TOut>, cb: (batch: Envelope<TOut>[]) => void, opts?: SubscribeOptions): Subscription<TOut>;
     subscribe<TOut = unknown>(topic: string, opts?: SubscribeOptions): Subscription<TOut>;
     subscribe<TOut = unknown>(topic: string, cb: (batch: Envelope<TOut>[]) => void, opts?: SubscribeOptions): Subscription<TOut>;
-    /** The topic's latest value as a view (SDK §4.3); subscribed while someone listens. */
+    /** The topic's latest value as a view (SDK §4.3); subscribed from its creation until `close()`. */
     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, read its updates (`for await (const u of run)`, `await run.next()`), or pass `onUpdate`. With no session (before the first, between two) the Run is already failed `not_connected`: nothing was sent. */
@@ -133,6 +136,11 @@ export declare class Synapse implements AsyncDisposable {
      * resolves once the demoted session is connected.
      */
     leaveProject(): Promise<ProjectSnapshot>;
+    /**
+     * `synapse/project/list {}`: every project the runtime has, sorted by id: what each names (`name` when it has one,
+     * `scene_id`, `store_id`, whether it is the active one), or why it cannot be read (`error`). Changes nothing.
+     */
+    listProjects(): Promise<ProjectListing>;
     /**
      * 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).

package/dist/synapse.js

@@ -10,7 +10,7 @@ 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 { PublisherHandle, SubscriberClaim, TopicPublisher, TopicSubscription, wasmFor } from "./topics.js";
 import { TopicView } from "./view.js";
 import { watchState } from "./util.js";
 export { FIRST_CONNECT_GIVE_UP_MS } from "./node.js";
@@ -25,6 +25,10 @@ function wantedDesc(contract, n) {
 function descKey(d) {
     return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null, fec: d.fec ?? null });
 }
+/** The parts of a descriptor two typed subscriptions of one topic on one node must agree on (`fec` is a publisher's own), as text. */
+function shapeKey(d) {
+    return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null });
+}
 /**
  * A fact of the node as a state value (`node.status`, `node.catalog`, `node.project`, `node.discovery`): `read` is the fact
  * now, the same object while it is unchanged. It changes with the node's link, with the node's own values `kept` names,
@@ -82,6 +86,8 @@ const NO_SERVICES = Object.freeze({});
 export class Synapse {
     #node;
     #publishers = new Map();
+    /** The node's subscriber claims by topic name (PLAN v0.41): one per topic, held by its typed subscriptions. */
+    #subscriberClaims = new Map();
     #stores = new Map();
     warn;
     /**
@@ -259,15 +265,46 @@ export class Synapse {
     subscribe(topic, cbOrOpts, opts = {}) {
         const contract = resolveTopic(topic);
         if (typeof cbOrOpts !== "function")
-            return new TopicSubscription(this.node, contract, cbOrOpts ?? {}, this.warn);
-        const sub = new TopicSubscription(this.node, contract, opts, this.warn);
+            return new TopicSubscription(this.node, contract, cbOrOpts ?? {}, this.warn, this.#holdClaim(contract));
+        const sub = new TopicSubscription(this.node, contract, opts, this.warn, this.#holdClaim(contract));
         sub.deliverTo(cbOrOpts);
         return sub;
     }
     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, () => { });
+        return new TopicView(this.node, () => new TopicSubscription(this.node, contract, subOpts, this.warn, this.#holdClaim(contract)), opts, () => { });
+    }
+    /**
+     * The node's subscriber claim of `contract`'s topic, held once more (made with its task when none is live); returns its
+     * release, which the last holder's call turns into the `unregister`. A contract without a schema claims nothing; one whose
+     * shape differs from the live claim's throws `invalid_input`.
+     */
+    #holdClaim(contract) {
+        if (!contract.schema)
+            return undefined;
+        const name = contract.name;
+        let claim = this.#subscriberClaims.get(name);
+        if (!claim) {
+            claim = new SubscriberClaim(this.node, contract, this.warn);
+            this.#subscriberClaims.set(name, claim);
+        }
+        // One subscriber claim per topic per node: a typed subscription of another shape is not this node's claim, and its shape never reached the runtime.
+        else if (shapeKey(claim.contract.desc(this.node.dom)) !== shapeKey(contract.desc(this.node.dom)))
+            throw new SynapseError("invalid_input", `topic ${name}: this node already subscribes with a different descriptor`);
+        const c = claim;
+        c.holders++;
+        let held = true;
+        return () => {
+            if (!held)
+                return;
+            held = false;
+            if (--c.holders > 0)
+                return;
+            c.handle.unregister();
+            if (this.#subscriberClaims.get(name) === c)
+                this.#subscriberClaims.delete(name);
+        };
     }
     call(svc, args = {}, opts = {}) {
         const s = this.#session();
@@ -355,6 +392,11 @@ export class Synapse {
      * resolves once the demoted session is connected.
      */
     leaveProject() { return this.#projectCall("leave", {}); }
+    /**
+     * `synapse/project/list {}`: every project the runtime has, sorted by id: what each names (`name` when it has one,
+     * `scene_id`, `store_id`, whether it is the active one), or why it cannot be read (`error`). Changes nothing.
+     */
+    listProjects() { return this.call("synapse/project/list", {}).result; }
     // -------------------------------------------------------------------------------- tasks
     #tasks;
     /**

package/dist/topics.d.ts

@@ -14,8 +14,8 @@ export declare class TopicPublisher<TIn, TOut> implements Intent {
     private readonly wasm;
     readonly warn: Warn;
     readonly name: string;
-    readonly registerSvc = "synapse/topic/register";
-    readonly unregisterSvc = "synapse/topic/unregister";
+    readonly registerSvc = "synapse/publisher/register";
+    readonly unregisterSvc = "synapse/publisher/unregister";
     readonly desc: TrackDesc;
     readonly fecParams: FecParams | undefined;
     readonly fecStats: FecPubStats | undefined;
@@ -71,6 +71,32 @@ export declare class PublisherHandle<TIn, TOut> implements Publisher<TIn> {
     close(): void;
     [Symbol.asyncDispose](): Promise<void>;
 }
+/**
+ * A subscriber's claim of a topic (PLAN v0.41): the node's typed subscriptions of the topic tell the runtime the shape
+ * they read. One per topic per node (`Synapse` keeps them by name), held by those subscriptions; the last one ended
+ * writes the `unregister`. It installs nothing: the subscriptions read as they always do. A refusal (a shape that
+ * differs from the topic's established one) is warned once and not asked again on the session (PLAN v0.42).
+ */
+export declare class SubscriberClaim implements Intent {
+    #private;
+    readonly node: Node;
+    readonly contract: TopicContract<unknown, unknown>;
+    readonly warn: Warn;
+    readonly name: string;
+    readonly registerSvc = "synapse/subscriber/register";
+    readonly unregisterSvc = "synapse/subscriber/unregister";
+    /** The subscriptions holding it. */
+    holders: number;
+    readonly handle: Handle;
+    constructor(node: Node, contract: TopicContract<unknown, unknown>, warn: Warn);
+    get verdict(): Verdict;
+    /** The shape this node reads: the contract's descriptor in our time domain (final before the first session), without `fec` (a publisher's own transport setting). */
+    registerArgs(bind: string): unknown;
+    unregisterArgs(bind: string): unknown;
+    install(_s: Session, _bind: string, _mailbox: (e: HandleEvent) => void): void;
+    retract(): void;
+    setVerdict(v: Verdict): void;
+}
 /** Resolves the codec a `fec` topic needs (once per process). */
 export declare function wasmFor(contract: TopicContract<unknown, unknown>): Promise<FecWasm | undefined>;
 /** What a source gives when its track ended. */
@@ -114,10 +140,12 @@ export declare class TopicSubscription<T> implements Subscription<T> {
     readonly contract: TopicContract<unknown, T>;
     readonly opts: SubscribeOptions;
     readonly warn: Warn;
+    private readonly release?;
     readonly topic: string;
     readonly stats: SubStats;
     readonly latest: boolean;
-    constructor(node: Node, contract: TopicContract<unknown, T>, opts: SubscribeOptions, warn: Warn);
+    /** `release` lets go of what the subscription holds besides its tracks (the node's subscriber claim of a typed topic); called once, at `unsubscribe()`. */
+    constructor(node: Node, contract: TopicContract<unknown, T>, opts: SubscribeOptions, warn: Warn, release?: (() => void) | undefined);
     get signal(): AbortSignal;
     get ownDom(): string;
     /** The follow task hands a plain publisher here (a datagram source's reader starts); the waiting `next()` is woken. */

package/dist/topics.js

@@ -1,6 +1,6 @@
 // Topics (SDK §4, WP §6–§7), the JS spelling of the Rust client's `topics.rs`.
 //
-// A publisher is an intent (`channel.ts`): its handle task asks the runtime `synapse/topic/register`
+// A publisher is an intent (`channel.ts`): its handle task asks the runtime `synapse/publisher/register`
 // on every session and, admitted, installs the broadcast `<prefix>/topic/<bind>/<topic>` — `desc`
 // (one retained frame: the descriptor with our time domain) and `data` — which `publish()` writes to
 // on the fast lane, synchronously; while nothing is installed frames are dropped and counted.
@@ -11,6 +11,10 @@
 // (listed = alive): a publisher whose subscribe fails is left out until the catalog next changes,
 // when every listed publisher not held is tried again; no timer of our own. A datagram publisher
 // whose own `desc` has `fec` gets a follower (the video path: `FecReader` per publisher).
+//
+// A typed subscription (a contract with a schema) also holds the node's subscriber claim of its topic (PLAN v0.41), an
+// intent of the same shape that installs nothing: the runtime lists the topic and this node under `subscribers` with
+// the shape it reads, before anyone publishes.
 import * as Moq from "@moq/net";
 import { FLAGS, MSGPACK, SynapseError, TYPES, auParamSets, auSyncPoints, decode as decodeBody, decodeHeader, encode as encodeBody, fecSymbolSizeFor, frame, isVideo, mediaFlags, moqPriority, nowUs, stampSentUs, hasPendingSentUs, mediaHeader, topicPath, validateSync, } from "@synapse-sdk/core";
 import { Handle, start as startHandle } from "./channel.js";
@@ -32,8 +36,8 @@ export class TopicPublisher {
     wasm;
     warn;
     name;
-    registerSvc = "synapse/topic/register";
-    unregisterSvc = "synapse/topic/unregister";
+    registerSvc = "synapse/publisher/register";
+    unregisterSvc = "synapse/publisher/unregister";
     desc;
     fecParams;
     fecStats;
@@ -245,6 +249,38 @@ export class PublisherHandle {
     }
     async [Symbol.asyncDispose]() { this.close(); }
 }
+/**
+ * A subscriber's claim of a topic (PLAN v0.41): the node's typed subscriptions of the topic tell the runtime the shape
+ * they read. One per topic per node (`Synapse` keeps them by name), held by those subscriptions; the last one ended
+ * writes the `unregister`. It installs nothing: the subscriptions read as they always do. A refusal (a shape that
+ * differs from the topic's established one) is warned once and not asked again on the session (PLAN v0.42).
+ */
+export class SubscriberClaim {
+    node;
+    contract;
+    warn;
+    name;
+    registerSvc = "synapse/subscriber/register";
+    unregisterSvc = "synapse/subscriber/unregister";
+    #verdict = { status: "unbound" };
+    /** The subscriptions holding it. */
+    holders = 0;
+    handle;
+    constructor(node, contract, warn) {
+        this.node = node;
+        this.contract = contract;
+        this.warn = warn;
+        this.name = contract.name;
+        this.handle = startHandle(node, this);
+    }
+    get verdict() { return this.#verdict; }
+    /** The shape this node reads: the contract's descriptor in our time domain (final before the first session), without `fec` (a publisher's own transport setting). */
+    registerArgs(bind) { const { fec: _fec, ...desc } = this.contract.desc(this.node.dom); return { topic: this.name, desc, bind }; }
+    unregisterArgs(bind) { return { topic: this.name, bind }; }
+    install(_s, _bind, _mailbox) { }
+    retract() { }
+    setVerdict(v) { this.#verdict = v; }
+}
 /** Resolves the codec a `fec` topic needs (once per process). */
 export async function wasmFor(contract) {
     return contract.delivery === "datagram" && contract.fec ? requireFec(`topic ${contract.name}`) : undefined;
@@ -266,6 +302,7 @@ export class TopicSubscription {
     contract;
     opts;
     warn;
+    release;
     topic;
     stats = { read: 0, superseded: 0, staleDrops: 0, mismatch: 0, fecGiveup: 0, repaired: 0, coalesced: 0 };
     #sources = [];
@@ -279,11 +316,13 @@ export class TopicSubscription {
     #throttleUntil = 0;
     #throttled;
     #throttleTimer;
-    constructor(node, contract, opts, warn) {
+    /** `release` lets go of what the subscription holds besides its tracks (the node's subscriber claim of a typed topic); called once, at `unsubscribe()`. */
+    constructor(node, contract, opts, warn, release) {
         this.node = node;
         this.contract = contract;
         this.opts = opts;
         this.warn = warn;
+        this.release = release;
         this.topic = contract.name;
         this.latest = (opts.queueDepth ?? 1) !== 0;
         this.#deadlineUs = opts.deadlineMs !== undefined ? opts.deadlineMs * 1000 : undefined;
@@ -616,6 +655,7 @@ export class TopicSubscription {
             return;
         this.#ended = true;
         this.#stop.abort();
+        this.release?.();
         for (const s of this.#sources.splice(0))
             closeSource(s);
         this.#fec.length = 0;

package/dist/types.d.ts

@@ -163,7 +163,7 @@ export interface PublishOptions {
     tUs?: number;
     flags?: number;
 }
-/** Where a publisher stands with the runtime on the current session. */
+/** Where a publisher stands with the runtime on the current session; `refused`: refused for a fault of the caller's (`schema_mismatch`, `content_mismatch`, `invalid_input`, ...), not asked again until the next session. */
 export type Verdict = {
     status: "unbound";
 } | {
@@ -172,6 +172,10 @@ export type Verdict = {
 } | {
     status: "admitted";
     epoch: number;
+} | {
+    status: "refused";
+    epoch: number;
+    error: SynapseError;
 };
 export interface PublisherStats {
     published: number;
@@ -185,7 +189,7 @@ export interface PublisherStats {
 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. */
+    /** Resolves once admitted and announced on the current session; `not_connected` once the node ended. A contention refusal (`already_registered`, `unauthorized`, ...) is asked again, paced and warned about; a terminal one (`schema_mismatch`, ...) rejects with it. */
     ready(): Promise<void>;
     /**
      * Synchronous: writes to the installed track, or drops and counts while unbound (SDK §12.4). A
@@ -326,6 +330,10 @@ export type RegVerdict = {
 } | {
     status: "registered";
     epoch: number;
+} | {
+    status: "refused";
+    epoch: number;
+    error: SynapseError;
 };
 export interface Registration extends AsyncDisposable {
     readonly name: string;
@@ -355,6 +363,8 @@ export interface StoreStatus {
     epoch: string | undefined;
     /** `destroyed`, `connection_lost` or `client`. */
     ended: string | undefined;
+    /** The open refused on this session for a fault of the caller's (`mode_mismatch`, `invalid_input`, ...): not asked again until the next session. */
+    refused: SynapseError | undefined;
 }
 export type StoreChange = {
     kind: "put";
@@ -488,6 +498,8 @@ export interface Hardpoint {
 /**
  * An entity of the scene. The fields below are the ones the runtime and the early users read;
  * every other key passes through untouched.
+ * A component is absent (none), `{}` (there, nothing specified yet: every field at its default) or
+ * specified; a null component or sub-key is never stored (a patch deletes the key it names, a spawn drops it).
  */
 export interface SceneEntity {
     /** A ULID; never changes. */
@@ -620,8 +632,8 @@ export interface EntityAuthored {
      * 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>;
+    set<K extends keyof SceneEntity & string>(component: K, value: PatchSet[K]): Promise<void>;
+    set(components: PatchSet): 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 {
@@ -666,6 +678,12 @@ export interface SceneStatus {
     /** Lane rows dropped because their id's claim was refused (rows parked while it was asked, and rows written while refused). */
     unclaimedDrops: number;
 }
+type NullSubKeys<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [S in keyof T]?: T[S] | null;
+} : T;
+type PatchSet = {
+    [K in keyof SceneEntity]?: unknown extends SceneEntity[K] ? unknown : NullSubKeys<NonNullable<SceneEntity[K]>> | null;
+};
 /** An authored change as the runtime applied it (a diff op of the scene's `authored` track). */
 export type SceneDiffOp = {
     op: "spawn";
@@ -679,7 +697,7 @@ export type SceneDiffOp = {
 } | {
     op: "patch";
     id: string;
-    set: Partial<SceneEntity>;
+    set: PatchSet;
     rev: number;
 } | {
     op: "reparent";
@@ -710,7 +728,7 @@ export type SceneOp = {
 } | {
     op: "patch";
     id: string;
-    set: Partial<SceneEntity>;
+    set: PatchSet;
 } | {
     op: "reparent";
     id: string;
@@ -733,20 +751,22 @@ export type SceneSpawnOptions = {
     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): a sibling by its id or its view. */
-export type ScenePlace = {
-    before: string | SceneEntityView;
-} | {
-    after: string | SceneEntityView;
-};
 /** 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: 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;
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
+    patch(entity: string | SceneEntityView, set: PatchSet): void;
     rename(entity: string | SceneEntityView, name: string): void;
-    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, place?: ScenePlace): void;
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default it keeps its world pose (its local xform is recomputed); `preserveWorld: false` keeps its local xform.
+     */
+    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, opts?: {
+        before?: string | SceneEntityView;
+        after?: string | SceneEntityView;
+        preserveWorld?: boolean;
+    }): void;
     despawn(entity: string | SceneEntityView, opts?: {
         cascade?: boolean;
     }): void;
@@ -797,7 +817,8 @@ export interface SceneAuthored {
     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>;
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
+    patch(entity: string | SceneEntityView, set: PatchSet): 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. The id is the runtime's answer, never the copy's: `spawn(kind, { name, parent, ...components })` (a fresh id) is
@@ -813,7 +834,16 @@ export interface SceneAuthored {
         id?: never;
     }): Promise<SceneEntityView>;
     rename(entity: string | SceneEntityView, name: string): Promise<void>;
-    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, place?: ScenePlace): Promise<void>;
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default the entity keeps its world pose (its local xform is recomputed). With `preserveWorld: false` it keeps its
+     * local xform instead, so a tool moved to another flange snaps to it.
+     */
+    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, opts?: {
+        before?: string | SceneEntityView;
+        after?: string | SceneEntityView;
+        preserveWorld?: boolean;
+    }): Promise<void>;
     despawn(entity: string | SceneEntityView, opts?: {
         cascade?: boolean;
     }): Promise<void>;
@@ -1024,13 +1054,32 @@ export interface Tasks {
     /** Stops every project task (also when none ran). Robot tasks are not touched. */
     stopProjectTasks(): Promise<void>;
 }
+/** The answer of `node.listProjects()` (`synapse/project/list`): every project the runtime has, sorted by id. */
+export interface ProjectListing {
+    projects: ProjectEntry[];
+}
+/** One project of a {@link ProjectListing}: what its document names (`name` when it has one), or why it cannot be read (`error`). */
+export type ProjectEntry = {
+    id: string;
+    name?: string;
+    scene_id: string;
+    store_id: string;
+    active: boolean;
+} | {
+    id: string;
+    error: string;
+};
 export interface Catalog {
+    /** Every topic with a publisher or a typed subscriber: its established descriptor, its publishers and its typed subscribers, each by session prefix. */
     readonly topics: Readonly<Record<string, {
         desc?: TrackDesc;
         publishers: Record<string, {
             name: string;
             bind: string;
         }>;
+        subscribers: Record<string, {
+            name: string;
+        }>;
     }>>;
     readonly services: Readonly<Record<string, {
         name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/client",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Synapse SDK client: connect a node to the runtime; topics, services, calls, store, video.",
   "type": "module",
   "sideEffects": false,
@@ -14,7 +14,7 @@
     "dist"
   ],
   "dependencies": {
-    "@synapse-sdk/core": "0.3.7",
+    "@synapse-sdk/core": "0.3.9",
     "@moq/net": "0.4.2",
     "smol-toml": "1.9.0"
   },