@synapse-sdk/client 0.3.3 → 0.3.6

package/dist/scene_frames.d.ts

@@ -1,7 +1,7 @@
 import type { SceneEntity, SceneTxn, Xform } from "./types.ts";
 /** The ops the materializers queue. */
 type FrameTxn = Pick<SceneTxn, "spawn" | "patch" | "rename" | "despawn">;
-/** The entities to reconcile against: `scene.entities` (id → entity) or a list of entities. */
+/** The entities to reconcile against: `scene.get()` (id → entity) or a list of entities. */
 type Entities = Iterable<SceneEntity> | Readonly<Record<string, SceneEntity>>;
 /** The presentation name of a materialized derived frame: `<parent name>_<frame>` (e.g. `ur5e_tool0`). */
 export declare function derivedFrameName(parentName: string, frame: string): string;
@@ -28,7 +28,7 @@ export interface MaterializeReport {
 /**
  * Reconciles `robot`'s `robot.frames` with its derived frames (those with `props.from` equal to
  * `provenance`, default `"urdf"`; a frame without `from` counts as `"urdf"`), queueing the ops on
- * `txn`. `entities` is the scene now (`scene.entities`). `restPoses` maps declared names to poses
+ * `txn`. `entities` is the scene now (`scene.get()`). `restPoses` maps declared names to poses
  * (FK at the authored joints, the caller's work); a name with no frame yet and no pose is an error,
  * never a spawn, so a call with no poses only renames, backfills `from` and retracts.
  *

package/dist/scene_frames.js

@@ -29,7 +29,7 @@ export function validateDerivedFrame(frame, parentId) {
 /**
  * Reconciles `robot`'s `robot.frames` with its derived frames (those with `props.from` equal to
  * `provenance`, default `"urdf"`; a frame without `from` counts as `"urdf"`), queueing the ops on
- * `txn`. `entities` is the scene now (`scene.entities`). `restPoses` maps declared names to poses
+ * `txn`. `entities` is the scene now (`scene.get()`). `restPoses` maps declared names to poses
  * (FK at the authored joints, the caller's work); a name with no frame yet and no pose is an error,
  * never a spawn, so a call with no poses only renames, backfills `from` and retracts.
  *

package/dist/session.d.ts

@@ -83,7 +83,7 @@ export declare function ensureWebTransport(): Promise<void>;
 export declare function describeError(e: unknown): string;
 /**
  * The error of a session's close (`classify_close`): `admission_refused` travels as the application
- * close code (retryable: a live session may hold this name, the project may be settling), another
+ * close code (retryable: a live session holds this name; a crashed one is released after the idle timeout), another
  * application code is a broker-side failure, `unauthorized` is the relay's own refusal, everything
  * else is the transport (`connection_lost`); a clean close is a drop too (in one-shot mode a broker
  * GOAWAY looks like one).
@@ -164,6 +164,8 @@ export declare class Session {
     readonly log: MoqLogScope;
     /** Counts *established* sessions of the node (SDK §2); set by the node when attached. */
     epoch: number;
+    /** The target generation this session was opened for (`Target.generation`); set by the node's loop when attached. */
+    generation: number;
     readonly startedMs: number;
     readonly transport: "webtransport" | "websocket";
     /** Datagrams travel only over WebTransport; the WebSocket fallback is stream-only. */

package/dist/session.js

@@ -313,7 +313,7 @@ const ADMISSION_REFUSED_SESSION_CODE = 64 + ADMISSION_REFUSED_CLOSE_CODE;
 const ADMISSION_REFUSED_REASON = new RegExp(`app code=${ADMISSION_REFUSED_CLOSE_CODE}(?!\\d)`);
 /**
  * The error of a session's close (`classify_close`): `admission_refused` travels as the application
- * close code (retryable: a live session may hold this name, the project may be settling), another
+ * close code (retryable: a live session holds this name; a crashed one is released after the idle timeout), another
  * application code is a broker-side failure, `unauthorized` is the relay's own refusal, everything
  * else is the transport (`connection_lost`); a clean close is a drop too (in one-shot mode a broker
  * GOAWAY looks like one).
@@ -323,7 +323,7 @@ export function closeError(err) {
         return new SynapseError("connection_lost", { message: "session closed by the broker", source: "transport" });
     const text = `${err.message} ${err.reason ?? ""}`;
     if ((err instanceof Moq.Error.Session && err.code === ADMISSION_REFUSED_SESSION_CODE) || ADMISSION_REFUSED_REASON.test(text)) {
-        return new SynapseError("admission_refused", { message: "the runtime refused this connection, retryable: a live session may hold this name, the project may be settling, or the runtime is overloaded; retry with backoff", source: "broker", cause: err });
+        return new SynapseError("admission_refused", { message: "the runtime refused this connection; retryable: a live session holds this name (a crashed one is released after the idle timeout); the SDK keeps retrying with backoff", source: "broker", cause: err });
     }
     if (err instanceof Moq.Error.Session && err.code === Moq.SessionCode.Unauthorized)
         return new SynapseError("unauthorized", { message: text.trim(), source: "broker", cause: err });
@@ -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();
@@ -446,6 +446,8 @@ export class Session {
     log;
     /** Counts *established* sessions of the node (SDK §2); set by the node when attached. */
     epoch = 0;
+    /** The target generation this session was opened for (`Target.generation`); set by the node's loop when attached. */
+    generation = 0;
     startedMs = performance.now();
     transport;
     /** Datagrams travel only over WebTransport; the WebSocket fallback is stream-only. */

package/dist/store.d.ts

@@ -3,12 +3,14 @@ import type { Node } from "./node.ts";
 import { type Session } from "./session.ts";
 import type { Warn } from "./topics.ts";
 import type { StoreChange, StoreHandle, StoreOptions, StoreStatus } from "./types.ts";
-import { AsyncQueue, type Deferred } from "./util.ts";
+import { AsyncQueue, type Deferred, type StateValue } from "./util.ts";
 export declare const ENDED_DESTROYED = "destroyed";
 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;
@@ -78,11 +85,19 @@ type Event = {
     epoch: string;
     version: number;
     reply: Deferred<void>;
-} | {
+}
+/** A write of handle `handle` (its parked writes are refused when it leaves). */
+ | {
     kind: "write";
+    handle: number;
     op: string;
     args: WriteOp;
     reply: Deferred<unknown>;
+}
+/** Handle `handle` was closed, others remain: its parked writes are refused. */
+ | {
+    kind: "leave";
+    handle: number;
 } | {
     kind: "writeDone";
     op: string;
@@ -107,6 +122,7 @@ export declare class Namespace {
     readonly mailbox: AsyncQueue<Event>;
     readonly exited: Deferred<void>;
     handles: number;
+    nextHandle: number;
     constructor(name: string, opts: StoreOptions, node: Node, warn: Warn);
     post(e: Event): boolean;
     request<T>(make: (reply: Deferred<T>) => Event): Promise<T>;
@@ -116,32 +132,35 @@ export declare function startNamespace(ns: Namespace, registry: Map<string, Name
 export declare class StoreHandleImpl implements StoreHandle {
     #private;
     private readonly ns;
+    /** The handle's own state, a state value: `get()` (the same object while unchanged), `onChange`, `changed()`, `watch()`. */
+    readonly status: StateValue<StoreStatus>;
     constructor(ns: Namespace);
     get name(): string;
-    /** The whole value, what the runtime has; the same object while nothing changed (reference-stable for React). */
-    get value(): Record<string, unknown>;
+    /** `get()`: the whole value, what the runtime has; the same object while nothing changed (reference-stable for React). `get(key)`: that key's value, `undefined` when absent. */
+    get(): Record<string, unknown>;
     get(key: string): unknown;
     get synced(): boolean;
-    get status(): StoreStatus;
-    /** `set(key, value)` or `set({ ...several keys })` (one atomic write); resolves once `value` shows it. */
+    /** `set(key, value)` or `set({ ...several keys })` (one atomic write); resolves once `get()` shows it. */
     set(keyOrValues: string | Record<string, unknown>, value?: unknown): Promise<void>;
     delete(key: string): Promise<void>;
     clear(): Promise<void>;
     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 framework bridge (React's `useStore`): called on every change of the value or the status. */
-    subscribe(listener: () => void): () => void;
-    /** Waits for the namespace to be in (the first snapshot applied, or absent). */
-    join(): Promise<void>;
-    /** `join()` under the SDK's word (Publisher and Registration have `ready()` too). */
+    /** 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 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>;
 }
 /**
  * `store(name, opts)`: one task per namespace per node; a second `store` with the same options joins
- * it (no open written), with other options `invalid_input`; one exiting is waited out.
+ * it (no open written), with other options `invalid_input`; one exiting is waited out. Without a session
+ * (before the first, between two) the task waits for the next one, like after a drop; it resolves once in.
  */
 export declare function openStore(node: Node, registry: Map<string, Namespace>, name: string, opts: StoreOptions, warn: Warn): Promise<StoreHandleImpl>;
 /**