@synapse-sdk/client 0.3.4 → 0.3.6

package/dist/session.js

@@ -429,7 +429,7 @@ export async function withRoot(url, signal) {
         throw timeout.aborted ? new SynapseError("connection_lost", { message: `root helper at ${addr} did not answer`, source: "transport" }) : lost(describeError(e));
     }
     if (!isRuntimeRoot(root)) {
-        throw new SynapseError("invalid_input", { message: `${url} names no runtime (its /root helper returned ${JSON.stringify(root.slice(0, 80))}); give the full path, e.g. https://relay:4443/runtimes/<runtime_id>`, source: "sdk" });
+        throw new SynapseError("invalid_input", { message: `${url} names no runtime (its /root helper returned ${JSON.stringify(root.slice(0, 80))}); give the full path, e.g. https://<relay>/cluster/<cluster>/runtimes/<runtime_id>`, source: "sdk" });
     }
     u.pathname = `/${root}`;
     return u.toString();

package/dist/store.d.ts

@@ -9,6 +9,8 @@ export declare const ENDED_CONNECTION_LOST = "connection_lost";
 export declare const ENDED_CLIENT = "client";
 /** A watcher this many batches behind is ended, never grown. */
 export declare const STORE_FEED_CAP = 256;
+/** How long an incarnation the open's reply named has to show up on the announcement cursor (no "live" marker in @moq/net's JS cursor). */
+export declare const ANNOUNCE_WITHIN_MS = 1000;
 /** The mirror and what the runtime said about the namespace; written by the task and its reader only. */
 export declare class State {
     #private;
@@ -24,7 +26,8 @@ export declare class State {
     onDeath: StoreOnDeath | undefined;
     absent: boolean;
     loaded: boolean;
-    gap: boolean;
+    /** A diff skipped a version (not applied; the track is read again from its snapshot): the highest version seen then. Cleared once the copy is back at it (PLAN v0.34 §2.2). */
+    gap: number | undefined;
     pending: number;
     ended: string | undefined;
     subscribe(l: () => void): () => void;
@@ -32,7 +35,11 @@ export declare class State {
     /** A feed its reader has left: it is closed and gets nothing more. */
     unwatch(q: AsyncQueue<StoreChange[]>): void;
     applySnapshot(s: StoreSnapshot): void;
-    applyDiff(d: StoreDiff, warn: Warn): void;
+    /**
+     * One diff, applied when it is the next version. Otherwise it is not applied (`false`): a gap, `synced` false until the
+     * copy is back at the version seen; the reader reads the track again from its snapshot (PLAN v0.34 §2.2).
+     */
+    applyDiff(d: StoreDiff, warn: Warn): boolean;
     /** Nothing of the incarnation is known until the runtime answers the next open. */
     reset(): void;
     opened(a: StoreAccess | undefined): void;
@@ -140,11 +147,12 @@ export declare class StoreHandleImpl implements StoreHandle {
     destroy(): Promise<void>;
     /** `for await (const value of store.watch())`: the whole value after each change; `store.watch(key)`: that key's value each time it changes. Ends with the handle; leaving the loop removes the feed. */
     watch(key?: string): AsyncGenerator<unknown, void, undefined>;
-    /** The whole value after its next change (`store_gone` once this handle is closed). */
+    /** The whole value after its next change; `changed(key)`: that key's value after its next change (`undefined` after a delete), as `watch(key)` yields it. `store_gone` once this handle is closed. Armed at the call. */
     changed(): Promise<Record<string, unknown>>;
+    changed(key: string): Promise<unknown>;
     /** `cb` with the whole value on every change of the value or the status (the framework bridge, React's `useStore`); returns the remover. */
     onChange(cb: (value: Record<string, unknown>) => void): () => void;
-    /** Waits for the namespace to be in (the first snapshot applied, or absent). */
+    /** Waits for the namespace to be in: the value current as of the open (the version the runtime answered applied), or the namespace absent. */
     ready(): Promise<void>;
     close(): void;
     [Symbol.asyncDispose](): Promise<void>;

package/dist/store.js

@@ -21,7 +21,7 @@ const ENDED_STORE_GONE = "store_gone";
 /** A watcher this many batches behind is ended, never grown. */
 export const STORE_FEED_CAP = 256;
 /** How long an incarnation the open's reply named has to show up on the announcement cursor (no "live" marker in @moq/net's JS cursor). */
-const ANNOUNCE_WITHIN_MS = 1000;
+export const ANNOUNCE_WITHIN_MS = 1000;
 const isFinal = (reason) => reason === ENDED_DESTROYED;
 const gone = (name, why) => new SynapseError("store_gone", `store ${JSON.stringify(name)}: ${why}`);
 // ------------------------------------------------------------------------------------- state
@@ -39,7 +39,8 @@ export class State {
     onDeath;
     absent = false;
     loaded = false;
-    gap = false;
+    /** A diff skipped a version (not applied; the track is read again from its snapshot): the highest version seen then. Cleared once the copy is back at it (PLAN v0.34 §2.2). */
+    gap;
     pending = 0;
     ended;
     #listeners = new Set();
@@ -92,13 +93,22 @@ export class State {
         this.onDeath = s.on_death;
         this.absent = false;
         this.loaded = true;
-        this.gap = false;
+        this.#heal();
         this.#emit(records);
     }
+    /** A gap is over once the copy is back at the highest version seen when it opened. */
+    #heal() { if (this.gap !== undefined && this.version >= this.gap)
+        this.gap = undefined; }
+    /**
+     * One diff, applied when it is the next version. Otherwise it is not applied (`false`): a gap, `synced` false until the
+     * copy is back at the version seen; the reader reads the track again from its snapshot (PLAN v0.34 §2.2).
+     */
     applyDiff(d, warn) {
         if (d.version !== this.version + 1) {
-            warn(`store: diff out of sequence (have ${this.version}, got ${d.version}); not synced until the next snapshot`);
-            this.gap = true;
+            warn(`store: diff out of sequence (have ${this.version}, got ${d.version}): not applied; reading the track again from its snapshot`);
+            this.gap = Math.max(this.gap ?? d.version, d.version);
+            this.#notify();
+            return false;
         }
         const records = [];
         const flat = new Map(this.flat);
@@ -119,7 +129,9 @@ export class State {
         }
         this.flat = flat;
         this.version = d.version;
+        this.#heal();
         this.#emit(records);
+        return true;
     }
     #clear() {
         const records = [...this.rows].map(([key, r]) => ({ kind: "delete", key, previousValue: r.v, by: undefined }));
@@ -135,7 +147,7 @@ export class State {
         this.epoch = undefined;
         this.version = 0;
         this.loaded = false;
-        this.gap = false;
+        this.gap = undefined;
         this.mode = undefined;
         this.owner = undefined;
         this.mine = false;
@@ -151,7 +163,7 @@ export class State {
         this.epoch = undefined;
         this.version = 0;
         this.loaded = false;
-        this.gap = false;
+        this.gap = undefined;
         this.mode = a?.mode;
         this.owner = a?.owner ?? undefined;
         this.mine = a?.mine ?? false;
@@ -177,7 +189,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 && (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 };
     }
 }
 function sameValue(a, b) {
@@ -686,7 +698,8 @@ function announcedEpoch(base, prefix) {
 /**
  * Reads the incarnation the open bound (`want`; `undefined`: absent, the first one announced), writing
  * the mirror and telling the task of each frame applied; returns how the track ended (`undefined`:
- * no final frame — the session, or the broker, went; the task replays).
+ * no final frame — the session, or the broker, went; the task replays). A diff out of sequence is not applied: the
+ * subscription is let go and the track subscribed again, which delivers the open group from its snapshot (PLAN v0.34 §2.2).
  */
 async function follow(ns, session, announced, want, signal) {
     const { state, warn, name } = ns;
@@ -739,74 +752,86 @@ async function follow(ns, session, announced, want, signal) {
             return undefined;
         }
         announced.close();
-        sub = bc.track(STORE_TRACK).subscribe(latestSubscription(moqPriority(1)));
-        const s = sub;
+        const track = bc.track(STORE_TRACK);
         // Closing the subscriber ends `recvGroup`, not a read on the group it already handed us: that group is closed too.
         let g;
-        signal.addEventListener("abort", () => { s.close(); g?.close(); }, { once: true });
-        // The first group read is the open one, from its start: a snapshot, then the diffs.
-        for (;;) {
-            g = await s.recvGroup();
-            if (!g)
-                break;
+        signal.addEventListener("abort", () => { sub?.close(); g?.close(); }, { once: true });
+        // A gap: this subscription is let go and the track subscribed again, which delivers the open group from its
+        // snapshot (PLAN v0.34 §2.2; no counter, no timer).
+        subscribe: for (;;) {
+            if (signal.aborted)
+                return undefined;
+            try {
+                sub?.close();
+            }
+            catch { /* closed */ }
+            const s = sub = track.subscribe(latestSubscription(moqPriority(1)));
+            // The first group read is the open one, from its start: a snapshot, then the diffs.
             for (;;) {
-                let f;
-                try {
-                    f = await g.readFrame();
-                }
-                catch {
-                    break;
-                }
-                if (!f)
+                g = await s.recvGroup();
+                if (!g)
                     break;
-                let header, hlen;
-                try {
-                    ({ header, hlen } = decodeHeader(f.payload));
-                }
-                catch {
-                    warn(`store ${name}: frame not decodable`);
-                    continue;
-                }
-                let body;
-                try {
-                    body = decodeBody(f.payload.subarray(hlen));
-                }
-                catch {
-                    warn(`store ${name}: frame body not decodable`);
-                    continue;
-                }
-                if (header.flags & FLAGS.END) {
-                    const fin = body;
-                    return fin && typeof fin.reason === "string" ? fin.reason : ENDED_STORE_GONE;
-                }
-                // A stopped reader no longer writes the mirror: it belongs to the next incarnation (or to none).
-                if (header.flags & FLAGS.KEY) {
-                    const snap = body;
-                    if (!snap || snap.epoch !== epoch) {
-                        warn(`store ${name}: snapshot of another epoch dropped`);
-                        continue;
+                for (;;) {
+                    let f;
+                    try {
+                        f = await g.readFrame();
                     }
-                    if (signal.aborted)
-                        continue;
-                    if (state.ended === undefined)
-                        state.applySnapshot(snap);
-                    ns.post({ kind: "applied", epoch, version: snap.version });
-                }
-                else if (header.flags & FLAGS.DELTA) {
-                    const diff = body;
-                    if (!diff || typeof diff.version !== "number") {
-                        warn(`store ${name}: diff not decodable`);
+                    catch {
+                        break;
+                    }
+                    if (!f)
+                        break;
+                    let header, hlen;
+                    try {
+                        ({ header, hlen } = decodeHeader(f.payload));
+                    }
+                    catch {
+                        warn(`store ${name}: frame not decodable`);
                         continue;
                     }
-                    if (signal.aborted)
+                    let body;
+                    try {
+                        body = decodeBody(f.payload.subarray(hlen));
+                    }
+                    catch {
+                        warn(`store ${name}: frame body not decodable`);
                         continue;
-                    if (state.ended === undefined && state.loaded)
-                        state.applyDiff(diff, warn);
-                    ns.post({ kind: "applied", epoch, version: diff.version });
+                    }
+                    if (header.flags & FLAGS.END) {
+                        const fin = body;
+                        return fin && typeof fin.reason === "string" ? fin.reason : ENDED_STORE_GONE;
+                    }
+                    // A stopped reader no longer writes the mirror: it belongs to the next incarnation (or to none).
+                    if (header.flags & FLAGS.KEY) {
+                        const snap = body;
+                        if (!snap || snap.epoch !== epoch) {
+                            warn(`store ${name}: snapshot of another epoch dropped`);
+                            continue;
+                        }
+                        if (signal.aborted)
+                            continue;
+                        if (state.ended === undefined)
+                            state.applySnapshot(snap);
+                        ns.post({ kind: "applied", epoch, version: snap.version });
+                    }
+                    else if (header.flags & FLAGS.DELTA) {
+                        const diff = body;
+                        if (!diff || typeof diff.version !== "number") {
+                            warn(`store ${name}: diff not decodable`);
+                            continue;
+                        }
+                        if (signal.aborted)
+                            continue;
+                        if (state.ended === undefined && state.loaded && !state.applyDiff(diff, warn)) {
+                            g.close();
+                            continue subscribe;
+                        }
+                        ns.post({ kind: "applied", epoch, version: diff.version });
+                    }
                 }
             }
+            return undefined; // the track ended with no final frame: the session (or the broker) went
         }
-        return undefined; // the track ended with no final frame: the session (or the broker) went
     }
     catch {
         return undefined;
@@ -902,10 +927,15 @@ export class StoreHandleImpl {
             this.ns.state.unwatch(q);
         }
     }
-    /** The whole value after its next change (`store_gone` once this handle is closed). */
-    changed() {
+    changed(key) {
         if (this.#closed)
             return Promise.reject(this.#ended());
+        if (key !== undefined) {
+            // the first step of `watch(key)`, started now (its feed opens at the first `next()`), then left
+            const it = this.watch(key)[Symbol.asyncIterator]();
+            return it.next().then(r => { void it.return(undefined); if (r.done)
+                throw this.#ended(); return r.value; });
+        }
         const from = this.get();
         const d = deferred();
         const un = this.ns.state.subscribe(() => { const v = this.get(); if (v !== from) {
@@ -919,7 +949,7 @@ export class StoreHandleImpl {
     }
     /** `cb` with the whole value on every change of the value or the status (the framework bridge, React's `useStore`); returns the remover. */
     onChange(cb) { return this.ns.state.subscribe(() => cb(this.get())); }
-    /** Waits for the namespace to be in (the first snapshot applied, or absent). */
+    /** Waits for the namespace to be in: the value current as of the open (the version the runtime answered applied), or the namespace absent. */
     ready() { return this.ns.request(reply => ({ kind: "join", reply })); }
     close() {
         if (this.#closed)

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 { CallEvent, CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Envelope, 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, Envelope, Info, Metrics, 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 {
@@ -74,18 +74,15 @@ export declare class Synapse implements AsyncDisposable {
     /** The topic's latest value as a view (SDK §4.3); subscribed while someone listens. */
     view<TIn, TOut, S = TOut>(topic: TopicContract<TIn, TOut>, opts?: ViewOptions<TOut, S>): View<S>;
     view<TOut = unknown, S = TOut>(topic: string, opts?: ViewOptions<TOut, S>): View<S>;
-    /** Starts a call on the current session (SDK §5.2): `await` it for the result, or read `updates()` first. With no session (before the first, between two) the Run is already failed `not_connected`: nothing was sent. */
+    /** 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. */
     call<TArgs, TInput, U, R>(svc: ServiceContract<TArgs, TInput, U, R>, args: TArgs, opts?: CallOptions<U>): Run<U, R>;
     call<U = unknown, R = unknown>(svc: string, args?: unknown, opts?: CallOptions<U>): Run<U, R>;
-    /** The call's updates and result as one ordered stream; `break` cancels. */
-    callStream<TArgs, TInput, U, R>(svc: ServiceContract<TArgs, TInput, U, R>, args: TArgs, opts?: CallOptions<U>): AsyncGenerator<CallEvent<U, R>, void, undefined>;
-    callStream<U = unknown, R = unknown>(svc: string, args?: unknown, opts?: CallOptions<U>): AsyncGenerator<CallEvent<U, R>, void, undefined>;
     /** Registers `handler` as the provider of `svc`; resolves once the runtime lists us on the current session. One provider per service path per node. */
     serve<TArgs, TInput, U, R>(svc: ServiceContract<TArgs, TInput, U, R>, handler: ServeHandler<TInput, U, R>, opts?: ServeOptions): Promise<Registration>;
     serve<I = unknown, U = unknown, R = unknown>(svc: string, handler: ServeHandler<I, U, R>, opts?: ServeOptions): Promise<Registration>;
     /** Opens namespace `name` (SDK §9); resolves once the mirror is in (or the namespace is known absent). */
     store(name: string, opts?: StoreOptions): Promise<StoreHandle>;
-    /** The active project's scene (PLAN v0.24 §5); resolves attached, or at once `detached` when no project is active. */
+    /** The active project's scene (PLAN v0.24 §5); resolves attached (current as of the attach: at the version the runtime answered), or at once `detached` when no project is active. */
     scene(): Promise<SceneHandle>;
     /** The runtime's catalogs as the current session last read them (empty between sessions), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. */
     readonly catalog: StateValue<Catalog>;

package/dist/synapse.js

@@ -3,7 +3,7 @@
 // own tasks, told about sessions by the loop; every fact about the world is read from the current
 // `Session` (the runtime's statement) at the moment it is asked for, never copied here.
 import { SynapseError, ageOf, fecSymbolSizeFor, isServiceContract, nowUs, resolveTopic, serviceName, } from "@synapse-sdk/core";
-import { callStream, failedRun, startOn } from "./calls.js";
+import { failedRun, startOn } from "./calls.js";
 import { Node, createNode, endpointDial, resolveTarget } from "./node.js";
 import { ServiceRegistration } from "./serve.js";
 import { openScene } from "./scene.js";
@@ -240,9 +240,6 @@ export class Synapse {
         const contract = isServiceContract(svc) ? svc : undefined;
         return startOn(this.node, s, serviceName(svc), args, opts, contract);
     }
-    callStream(svc, args = {}, opts = {}) {
-        return callStream(this.call(svc, args, opts));
-    }
     async serve(svc, handler, opts = {}) {
         const n = this.node;
         const name = serviceName(svc);
@@ -273,7 +270,7 @@ export class Synapse {
     store(name, opts = {}) { return openStore(this.node, this.#stores, name, opts, this.warn); }
     // ---------------------------------------------------------------------------------- scene
     #scenes = { current: undefined };
-    /** The active project's scene (PLAN v0.24 §5); resolves attached, or at once `detached` when no project is active. */
+    /** The active project's scene (PLAN v0.24 §5); resolves attached (current as of the attach: at the version the runtime answered), or at once `detached` when no project is active. */
     scene() { return openScene(this.node, this.#scenes, this.warn); }
     // -------------------------------------------------------------------------------- catalog
     /** The runtime's catalogs as the current session last read them (empty between sessions), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. */

package/dist/types.d.ts

@@ -40,7 +40,7 @@ export interface ConnectOptions {
 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.
+     * the runtime's path, `https://<relay>/cluster/<cluster>/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. */
@@ -230,27 +230,32 @@ export interface CallOptions<U = unknown> {
     /** Local: fail `idle_timeout` (and cancel) when no frame arrives for this long. */
     idleTimeoutMs?: number;
     signal?: AbortSignal;
+    /** The callback form: the SDK reads the updates and calls `onUpdate(u)` for each (the run's loop then has none); a throwing `onUpdate` is rethrown later and the reading goes on. */
     onUpdate?: (u: U) => void;
 }
-/** A started call (WP §8.3): its updates, its result, and cancel. */
-/** `await run` is `await run.result`. */
-export interface Run<U, R> extends AsyncDisposable, PromiseLike<R> {
+/**
+ * A started call (WP §8.3). Its progress is a stream, the run itself a promise:
+ * `for await (const u of run)` the updates until the run ended, `await run.next()` one update
+ * (`undefined` once the run ended), or `onUpdate` in the call options (the SDK reads them);
+ * `await run` (or `.then`/`.catch`) the result, rejecting with the `SynapseError` of a
+ * `failed` or `canceled` run; `cancel()`.
+ */
+export interface Run<U, R> extends AsyncDisposable, PromiseLike<R>, AsyncIterable<U> {
     readonly id: string;
     readonly status: RunStatus;
-    /** The next progress update; `undefined` once the terminal frame arrived (then `result`). */
-    nextUpdate(): Promise<U | undefined>;
-    updates(): AsyncIterable<U>;
+    /** The next progress update; `undefined` once the run ended (then `await run` settles at once). */
+    next(): Promise<U | undefined>;
+    /** `await run` / `.then` as on a promise (returns a `Promise`, so `.then(...).catch(...)` chains). */
+    then<A = R, B = never>(onfulfilled?: ((value: R) => A | PromiseLike<A>) | null, onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    /** The result as a plain promise (what `await run` waits for). */
     readonly result: Promise<R>;
+    /** `.catch` as on a promise: `onRejected` gets the run's `SynapseError` when it failed or was canceled. */
+    catch<B = never>(onRejected?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<R | B>;
+    /** `.finally` as on a promise: `onFinally` runs once the run ended, whichever way. */
+    finally(onFinally?: (() => void) | null): Promise<R>;
     /** Cooperative cancel: tells the broker, resolves on its `canceled` frame. */
     cancel(reason?: string): Promise<void>;
 }
-export type CallEvent<U, R> = {
-    type: "update";
-    data: U;
-} | {
-    type: "result";
-    data: R;
-};
 export interface ServeContext<U> {
     readonly call: string;
     readonly caller: string;
@@ -332,7 +337,7 @@ export interface StoreHandle extends AsyncDisposable {
     readonly synced: boolean;
     /** 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). */
+    /** Resolves once the value is in: current as of the open (the version the runtime answered then 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>;
@@ -343,8 +348,9 @@ 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 whole value after its next change; `store_gone` once this handle is closed. */
+    /** The whole value after its next change; with `key`, that key's value after its next change (`undefined` after a delete). `store_gone` once this handle is closed. */
     changed(): Promise<Record<string, unknown>>;
+    changed(key: string): Promise<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;
@@ -441,7 +447,7 @@ export interface SceneEntity {
     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.
+     * holds is refused `name_taken`, its `data.holder` the id holding the name (`data.kind`, `data.layer`: the holder's).
      */
     name?: string;
     /** The parent's id; `null` is the world root. */
@@ -550,6 +556,9 @@ export interface SceneEntityView extends SceneView<SceneEntity | undefined> {
      */
     watch(): AsyncIterable<SceneEntity | undefined>;
     watch<K extends keyof SceneEntity & string>(component: K): AsyncIterable<SceneEntity[K] | undefined>;
+    /** The entity after its next change; with `component`, that component after its next change (`undefined` once gone). The value now once the handle ends. */
+    changed(): Promise<SceneEntity | undefined>;
+    changed<K extends keyof SceneEntity & string>(component: K): Promise<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 {
@@ -743,12 +752,14 @@ export interface SceneAuthored {
     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.
+     * it. The id is the runtime's answer, never the copy's: `spawn(kind, { name, parent, ...components })` (a fresh id) is
+     * sent first; the runtime refusing it `name_taken` names the holder and its kind (`data.holder`, `data.kind`,
+     * `data.layer`). A holder of this kind in the authored or calibration layer is patched with the components that differ
+     * from what the copy shows of it (one-level merge; live overrides never count; all of them when the copy does not show
+     * it yet; equal, nothing more is sent): the copy only trims the patch, it never decides. A holder of another kind, a
+     * live one, or an answer without them: the `name_taken` as it came. `parent` is used by the spawn only: an existing
+     * entity is not reparented. Any other refusal as it came (`not_found` on the patch: the entity went meanwhile; upsert
+     * again). An `id` component: `invalid_input` (`data: { component: "id" }`), nothing sent.
      */
     upsert(kind: SceneKind, opts: SceneSpawnOptions & {
         id?: never;
@@ -817,7 +828,7 @@ export interface SceneHandle extends AsyncDisposable {
     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. */
+    /** Resolves once the handle is attached (at once if it is): the copy current as of the attach, at the version the runtime answered when the scene was opened, or past it; `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>>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/client",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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.4",
+    "@synapse-sdk/core": "0.3.6",
     "@moq/net": "0.4.2"
   },
   "peerDependencies": {