@synapse-sdk/client 0.1.0 → 0.3.0

package/dist/scene_frames.d.ts

@@ -0,0 +1,51 @@
+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. */
+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;
+/** Which declared entry a derived frame materializes (its `props.materializes`); `null` when it carries none. */
+export declare function derivedFrameKey(frame: Record<string, unknown>): string | null;
+/** The checks a derived frame of `parentId` must pass: `flags.derived` set, `parent` is `parentId`, `props.materializes` present. Returns the failures (empty: it passes). */
+export declare function validateDerivedFrame(frame: Record<string, unknown>, parentId: string): string[];
+/**
+ * What a materializer queued. `frames`: every reconciled declared name → its frame's id (existing or
+ * spawned); `spawned`/`updated`/`removed`: the frame ids it spawned, renamed or patched, despawned;
+ * `vetoes`: retractions it refused because something is parented under the frame (listed); `errors`:
+ * what it could not reconcile (a missing rest pose, two frames for one name, a frame with no
+ * `props.materializes`, a name declared by both sources). `clean`: no vetoes and no errors.
+ */
+export interface MaterializeReport {
+    frames: Record<string, string>;
+    spawned: string[];
+    updated: string[];
+    removed: string[];
+    vetoes: string[];
+    errors: string[];
+    readonly clean: boolean;
+}
+/**
+ * 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
+ * (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.
+ *
+ * Per declared name: no frame → spawn one (`kind: "frame"`, the derived name, the pose,
+ * `flags.derived`, `props: {materializes, from}`); one frame → rename it if the robot was renamed,
+ * set a missing `from`, set the pose if one is given and differs. A frame whose name is no longer
+ * declared is despawned when nothing is parented under it, else vetoed. A derived child with no
+ * `props.materializes` stops the whole reconcile (an error, no ops): repair it by hand first.
+ */
+export declare function materializeFrames(txn: FrameTxn, robot: SceneEntity, entities: Entities, restPoses?: Record<string, Xform>, opts?: {
+    provenance?: string;
+}): MaterializeReport;
+/**
+ * Reconciles `entity`'s `hardpoints` with its derived frames of `props.from: "hardpoint"`, queueing
+ * the ops on `txn`, as `materializeFrames` does for `robot.frames`; the pose of each is the
+ * hardpoint's `xform` (identity when absent), so every declared name has one. Hardpoint frames are
+ * static: nothing animates them. Robot frames and hardpoint frames on one entity leave each other alone.
+ */
+export declare function materializeHardpoints(txn: FrameTxn, entity: SceneEntity, entities: Entities): MaterializeReport;
+export {};

package/dist/scene_frames.js

@@ -0,0 +1,215 @@
+// Derived frames (scene spec A.4.4, §6): the frame entities an entity's declarations stand for, and
+// the one materializer every stack runs to keep them in step. Two declarations make derived frames:
+// a robot's `robot.frames` (names only; the rest pose is the caller's FK at the authored joints,
+// `props.from: "urdf"`) and an entity's `hardpoints` (the pose is in the data, `props.from:
+// "hardpoint"`). A derived frame is a `frame` child of the declaring entity with `flags.derived` and
+// `props.materializes` naming the declared entry; `(parent, materializes)` is its identity, its name
+// (`<parent name>_<frame>`) follows the parent's.
+//
+// The functions here only queue ops on a txn and say what they queued; they never call the runtime.
+// Nothing applies until the txn is sent, so a caller that wants all or nothing checks `clean` first.
+/** The presentation name of a materialized derived frame: `<parent name>_<frame>` (e.g. `ur5e_tool0`). */
+export function derivedFrameName(parentName, frame) { return `${parentName}_${frame}`; }
+/** Which declared entry a derived frame materializes (its `props.materializes`); `null` when it carries none. */
+export function derivedFrameKey(frame) {
+    const key = frame.props?.materializes;
+    return typeof key === "string" && key ? key : null;
+}
+/** The checks a derived frame of `parentId` must pass: `flags.derived` set, `parent` is `parentId`, `props.materializes` present. Returns the failures (empty: it passes). */
+export function validateDerivedFrame(frame, parentId) {
+    const errors = [];
+    if (!frame.flags?.derived)
+        errors.push("flags.derived must be true");
+    if (frame.parent !== parentId)
+        errors.push("parent must be the deriving entity id");
+    if (!(frame.props ?? {}).materializes)
+        errors.push("props.materializes is required");
+    return errors;
+}
+/**
+ * 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
+ * (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.
+ *
+ * Per declared name: no frame → spawn one (`kind: "frame"`, the derived name, the pose,
+ * `flags.derived`, `props: {materializes, from}`); one frame → rename it if the robot was renamed,
+ * set a missing `from`, set the pose if one is given and differs. A frame whose name is no longer
+ * declared is despawned when nothing is parented under it, else vetoed. A derived child with no
+ * `props.materializes` stops the whole reconcile (an error, no ops): repair it by hand first.
+ */
+export function materializeFrames(txn, robot, entities, restPoses = {}, opts = {}) {
+    const report = emptyReport();
+    const provenance = opts.provenance ?? "urdf";
+    if (typeof robot.id !== "string" || typeof robot.name !== "string") {
+        report.errors.push("robot entity needs an id and a name");
+        return report;
+    }
+    if (!isPlainObject(robot.robot)) {
+        report.errors.push("not a robot: entity carries no robot component");
+        return report;
+    }
+    const declared = (robot.robot.frames ?? []);
+    if (!Array.isArray(declared) || declared.some(n => typeof n !== "string" || !n)) {
+        report.errors.push("robot.frames must be a list of frame names");
+        return report;
+    }
+    for (const name of sourceCollisions(robot)) {
+        report.errors.push(`declared frame "${name}" collides with a hardpoint of the same name — robot.frames and hardpoints share one join-key space per entity`);
+    }
+    if (report.errors.length > 0)
+        return report;
+    const decl = new Map();
+    for (const name of declared)
+        decl.set(name, restPoses[name] ?? null);
+    reconcileDerived(txn, robot.id, robot.name, decl, provenance, "robot.frames", entities, report, name => `declared frame "${name}": no rest pose provided — FK at the canonical config is the caller's engine work`);
+    return report;
+}
+/**
+ * Reconciles `entity`'s `hardpoints` with its derived frames of `props.from: "hardpoint"`, queueing
+ * the ops on `txn`, as `materializeFrames` does for `robot.frames`; the pose of each is the
+ * hardpoint's `xform` (identity when absent), so every declared name has one. Hardpoint frames are
+ * static: nothing animates them. Robot frames and hardpoint frames on one entity leave each other alone.
+ */
+export function materializeHardpoints(txn, entity, entities) {
+    const report = emptyReport();
+    if (typeof entity.id !== "string" || typeof entity.name !== "string") {
+        report.errors.push("entity needs an id and a name");
+        return report;
+    }
+    const hardpoints = (entity.hardpoints ?? []);
+    if (!Array.isArray(hardpoints)) {
+        report.errors.push("hardpoints must be a list");
+        return report;
+    }
+    const decl = new Map();
+    for (const hp of hardpoints) {
+        const name = isPlainObject(hp) ? hp.name : undefined;
+        if (typeof name !== "string" || name === "") {
+            report.errors.push(`hardpoint without a usable name: ${JSON.stringify(hp)}`);
+            continue;
+        }
+        if (decl.has(name)) {
+            report.errors.push(`duplicate hardpoint name "${name}"`);
+            continue;
+        }
+        decl.set(name, hp.xform ?? { t: [0, 0, 0], q: [0, 0, 0, 1] });
+    }
+    for (const name of sourceCollisions(entity)) {
+        report.errors.push(`hardpoint "${name}" collides with a declared robot frame of the same name — robot.frames and hardpoints share one join-key space per entity`);
+    }
+    if (report.errors.length > 0)
+        return report;
+    // Every hardpoint has a pose (its own, or identity), so the missing-pose message is never used.
+    reconcileDerived(txn, entity.id, entity.name, decl, "hardpoint", "hardpoints", entities, report, name => `hardpoint "${name}" has no pose`);
+    return report;
+}
+function emptyReport() {
+    return {
+        frames: {}, spawned: [], updated: [], removed: [], vetoes: [], errors: [],
+        get clean() { return this.vetoes.length === 0 && this.errors.length === 0; },
+    };
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function listOf(entities) {
+    return Symbol.iterator in entities ? [...entities] : Object.values(entities);
+}
+// The names both `robot.frames` and `hardpoints` declare on one entity: two declarations would claim
+// one derived frame (its identity is (parent, materializes)), so both materializers refuse them.
+function sourceCollisions(entity) {
+    const frames = isPlainObject(entity.robot) && Array.isArray(entity.robot.frames) ? entity.robot.frames : [];
+    const hps = Array.isArray(entity.hardpoints) ? entity.hardpoints : [];
+    const hpNames = new Set(hps.map(h => (isPlainObject(h) ? h.name : undefined)).filter((n) => typeof n === "string"));
+    return frames.filter((n) => typeof n === "string" && hpNames.has(n)).sort();
+}
+// The reconcile both materializers share. `declared`: name → pose (`null`: the frame must already
+// exist). Only derived children whose `props.from` (absent: "urdf") is `provenance` are matched or
+// retracted; a derived child with no `props.materializes`, of either source, stops the reconcile.
+function reconcileDerived(txn, parentId, parentName, declared, provenance, sourceLabel, entities, report, missingPoseError) {
+    const ents = listOf(entities);
+    const byKey = new Map();
+    for (const ent of ents) {
+        if (ent.parent !== parentId || !ent.flags?.derived)
+            continue;
+        const key = derivedFrameKey(ent);
+        if (key === null) {
+            report.errors.push(`derived frame "${ent.id}" carries no props.materializes join key — repair it by hand before materializing`);
+            continue;
+        }
+        const from = (ent.props ?? {}).from ?? "urdf";
+        if (from !== provenance)
+            continue; // the other declaration's frame: left alone
+        const bucket = byKey.get(key);
+        if (bucket)
+            bucket.push(ent);
+        else
+            byKey.set(key, [ent]);
+    }
+    if (report.errors.length > 0)
+        return; // a frame no declaration can claim: no decision is safe until it is repaired
+    for (const [name, pose] of declared) {
+        const matches = byKey.get(name) ?? [];
+        if (matches.length > 1) {
+            report.errors.push(`declared frame "${name}" has ${matches.length} derived entities (${matches.map(e => e.id).join(", ")}) — resolve manually`);
+            continue;
+        }
+        if (matches.length === 0) {
+            if (pose === null) {
+                report.errors.push(missingPoseError(name));
+                continue;
+            }
+            const fid = txn.spawn("frame", {
+                parent: parentId,
+                name: derivedFrameName(parentName, name),
+                xform: pose,
+                flags: { derived: true },
+                props: { materializes: name, from: provenance },
+            });
+            report.spawned.push(fid);
+            report.frames[name] = fid;
+            continue;
+        }
+        const ent = matches[0];
+        const fid = ent.id;
+        report.frames[name] = fid;
+        let changed = false;
+        const expected = derivedFrameName(parentName, name);
+        if (ent.name !== expected) {
+            txn.rename(fid, expected);
+            changed = true;
+        }
+        if (!("from" in (ent.props ?? {}))) {
+            txn.patch(fid, { props: { from: provenance } });
+            changed = true;
+        }
+        if (pose !== null) {
+            const current = (ent.xform ?? {});
+            const drifted = Object.entries(pose).some(([k, v]) => JSON.stringify(current[k]) !== JSON.stringify(v));
+            if (drifted) {
+                txn.patch(fid, { xform: pose });
+                changed = true;
+            }
+        }
+        if (changed)
+            report.updated.push(fid);
+    }
+    for (const [key, matches] of byKey) {
+        if (declared.has(key))
+            continue;
+        for (const ent of matches) {
+            const dependents = ents.filter(e => e.parent === ent.id);
+            if (dependents.length > 0) {
+                const deps = dependents.map(d => d.name ?? d.id).join(", ");
+                report.vetoes.push(`frame "${key}" (${ent.name ?? ent.id}) was retracted from ${sourceLabel} but has ` +
+                    `${dependents.length} dependent(s) parented under it: ${deps} — reparent or remove them first`);
+            }
+            else {
+                txn.despawn(ent.id);
+                report.removed.push(ent.id);
+            }
+        }
+    }
+}

package/dist/serve.d.ts

@@ -0,0 +1,46 @@
+import { type Card, type ErrorBody, type ServiceContract } from "@synapse-sdk/core";
+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 { 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";
+export declare class ServiceRegistration<I, U, R> implements Intent, Registration {
+    #private;
+    readonly node: Node;
+    readonly name: string;
+    private readonly contract;
+    private readonly handler;
+    readonly warn: Warn;
+    readonly registerSvc = "synapse/service/register";
+    readonly unregisterSvc = "synapse/service/unregister";
+    readonly card: Card;
+    readonly handle: Handle;
+    /** How many times a `calls` track broke and the registration was renewed on the same session. */
+    callsTrackLost: number;
+    constructor(node: Node, name: string, card: Card, contract: ServiceContract<unknown, I, U, R> | undefined, handler: ServeHandler<I, U, R>, warn: Warn);
+    get verdict(): RegVerdict;
+    get bind(): string | undefined;
+    ready(): Promise<void>;
+    unregister(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+    registerArgs(bind: string): unknown;
+    unregisterArgs(bind: string): unknown;
+    /** 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;
+    /** The task is exiting: whatever handler still runs is this registration's to cancel. */
+    exited(): void;
+}
+/** What a handler's throw becomes on the wire: a `ServiceError` verbatim (`data.app = true` for an application code), anything else `provider_error`. */
+export declare function errorBodyOf(e: unknown): ErrorBody;

package/dist/serve.js

@@ -0,0 +1,281 @@
+// Serving (SDK §5.3, WP §8.1, §8.6), the JS spelling of the Rust client's `serve.rs`.
+//
+// A registration is an intent (`channel.ts`): its handle task asks `synapse/service/register` on
+// every session and, admitted, installs the broadcast `<prefix>/svc/<bind>/<service>` — `card` (one
+// retained frame) and `out` (our replies) — and starts the binding's `calls` reader on
+// `runtime/svc/<bind>/<service>`, the track the broker creates when our announce lands. A call
+// starts the handler; a cancel aborts the handler it names; the reader ending (the broker ended the
+// registration, the track broke) is told to the task, which renews the registration on the same
+// session with a fresh bind. Nothing resumes across sessions: a handler still running when its
+// binding is retracted is aborted (`track_lost`); its late result is dropped, never written to a
+// dead track — the broker has failed the caller already.
+import { ERROR_CODES, FLAGS, ServiceError, SynapseError, TYPES, decode as decodeBody, decodeHeader, encode as encodeBody, moqPriority, nowUs, servicePath, toHex, validateSync, } from "@synapse-sdk/core";
+import { Handle, start as startHandle } from "./channel.js";
+import * as Moq from "@moq/net";
+import { CallWriter, RETAINED_FRAME_MAX_AGE_MS, callTrackSubscription, frameTooLarge, readTrack, waitActive, writeLatest } from "./session.js";
+/** The reason `ctx.signal` carries when our track or session went (WP §8.4). */
+export const TRACK_LOST = "track_lost";
+export class ServiceRegistration {
+    node;
+    name;
+    contract;
+    handler;
+    warn;
+    registerSvc = "synapse/service/register";
+    unregisterSvc = "synapse/service/unregister";
+    card;
+    #bound;
+    #verdict = { status: "unbound" };
+    #running = new Map();
+    handle;
+    /** How many times a `calls` track broke and the registration was renewed on the same session. */
+    callsTrackLost = 0;
+    constructor(node, name, card, contract, handler, warn) {
+        this.node = node;
+        this.name = name;
+        this.contract = contract;
+        this.handler = handler;
+        this.warn = warn;
+        this.card = { ...card, name };
+        this.handle = startHandle(node, this);
+    }
+    get verdict() { return this.#verdict; }
+    get bind() { return this.#bound?.bind; }
+    ready() { return this.handle.ready(); }
+    unregister() { this.handle.unregister(); }
+    async [Symbol.asyncDispose]() { this.unregister(); }
+    registerArgs(bind) { return { service: this.name, card: this.card, bind }; }
+    unregisterArgs(bind) { return { service: this.name, bind }; }
+    /** Announces the card and `out`, installs the binding, then starts its `calls` reader. */
+    install(s, bind, mailbox) {
+        const bc = s.createBroadcast(servicePath(s.prefix, bind, this.name));
+        const card = bc.createTrack("card", { priority: moqPriority(1), maxAge: Moq.Time.Milli(RETAINED_FRAME_MAX_AGE_MS) });
+        writeLatest(card, { flags: FLAGS.KEY, type: TYPES.PUB, seq: 1, tUs: nowUs() }, encodeBody(this.card));
+        const out = CallWriter.create(bc, "out");
+        bc.announce();
+        const stop = new AbortController();
+        const old = this.#bound;
+        this.#bound = { bind, bc, card, out, stop };
+        if (old)
+            this.#finish(old);
+        void this.#serveOn(s, bind, out, stop.signal, mailbox);
+    }
+    retract() { const b = this.#bound; this.#bound = undefined; if (b)
+        this.#finish(b); }
+    setVerdict(v) {
+        this.#verdict = v.status === "admitted" ? { status: "registered", epoch: v.epoch } : v;
+    }
+    /** The task is exiting: whatever handler still runs is this registration's to cancel. */
+    exited() { this.#cancelHandlers(undefined); }
+    /** Cancels the binding's handlers (`track_lost`), closes `out` (late results are dropped) and ends the broadcast. */
+    #finish(b) {
+        b.stop.abort();
+        this.#cancelHandlers(b.bind);
+        try {
+            b.out.close();
+        }
+        catch { /* closed */ }
+        try {
+            b.card.close();
+        }
+        catch { /* closed */ }
+        try {
+            b.bc.close();
+        }
+        catch { /* closed */ }
+    }
+    #cancelHandlers(bind) {
+        for (const [k, r] of [...this.#running]) {
+            if (bind !== undefined && r.bind !== bind)
+                continue;
+            this.#running.delete(k);
+            r.reason ??= TRACK_LOST;
+            r.ac.abort(new SynapseError("canceled", r.reason));
+        }
+    }
+    /** Reads the binding's `calls` track until it ends or the binding is retracted; an end is told to the task (a renewal). */
+    async #serveOn(s, bind, out, stop, mailbox) {
+        const epoch = s.epoch;
+        let why;
+        try {
+            const req = s.request(`runtime/svc/${bind}/${this.name}`);
+            const bc = await waitActive(req, 10_000, stop);
+            const sub = bc.track("calls").subscribe(callTrackSubscription(moqPriority(0)));
+            const err = await readTrack(sub, payload => this.#onCallsFrame(payload, bind, out), stop);
+            req.close();
+            if (stop.aborted)
+                return;
+            if (err) {
+                this.callsTrackLost++;
+                why = `calls track lost: ${err instanceof Error ? err.message : String(err)}`;
+            }
+            else
+                why = "calls track ended: the broker ended the registration";
+        }
+        catch (e) {
+            if (stop.aborted)
+                return;
+            this.callsTrackLost++;
+            why = `calls track lost: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        this.warn(`service ${this.name} (epoch ${epoch}): ${why}; renewing the registration on this session`);
+        mailbox({ kind: "ended", bind });
+    }
+    #onCallsFrame(payload, bind, out) {
+        let header, hlen;
+        try {
+            ({ header, hlen } = decodeHeader(payload));
+        }
+        catch {
+            return;
+        }
+        let body;
+        try {
+            body = decodeBody(payload.subarray(hlen));
+        }
+        catch {
+            return;
+        }
+        if (header.type === TYPES.RPC_CALL) {
+            const call = body;
+            if (!call || !(call.call instanceof Uint8Array) || call.call.length !== 16) {
+                this.warn(`service ${this.name}: bad inbound call dropped`);
+                return;
+            }
+            const k = toHex(call.call);
+            // Only for the binding still installed: a reader stopped mid-frame after its binding's handlers were cancelled starts none behind that scan.
+            if (this.#bound?.bind !== bind)
+                return;
+            if (this.#running.has(k))
+                return;
+            const ac = new AbortController();
+            const running = { ac, bind, reason: undefined };
+            this.#running.set(k, running);
+            void this.#runCall(call, k, running, out);
+        }
+        else if (header.type === TYPES.RPC_CANCEL) {
+            const c = body;
+            if (!c || !(c.call instanceof Uint8Array))
+                return;
+            const r = this.#running.get(toHex(c.call));
+            if (r) {
+                r.reason = c.reason ?? "caller";
+                r.ac.abort(new SynapseError("canceled", r.reason));
+            }
+        }
+    }
+    /** Runs one call's handler and writes its terminal frame: the one place a call ends, whatever the handler does. */
+    async #runCall(call, k, running, out) {
+        const id = call.call;
+        // Frames are written only while the call is this registration's to answer (`running` installed): a
+        // late update or result, after a cancel or a retract, is dropped.
+        const header = (flags) => ({ flags, type: TYPES.RPC_RESP, seq: 0, tUs: nowUs() });
+        // The terminal frame always reaches the caller: a result that does not encode is written as
+        // `provider_error` instead (Rust serve.rs: `encode result`), and a result over moq's frame limit,
+        // refused before anything is written, as a `provider_error` naming the limit.
+        const finish = (flags, body) => {
+            if (this.#running.get(k) !== running)
+                return;
+            this.#running.delete(k);
+            const failed = (message) => encodeBody({ call: id, body: { code: "provider_error", message } });
+            let payload;
+            try {
+                payload = encodeBody({ call: id, body });
+            }
+            catch (e) {
+                flags = FLAGS.END | FLAGS.ERR;
+                payload = failed(`encode result: ${describe(e)}`);
+            }
+            try {
+                out.write(header(flags), payload);
+            }
+            catch (e) {
+                if (!(e instanceof SynapseError && e.code === "invalid_input")) {
+                    this.warn(`service ${this.name}: write result: ${describe(e)}`);
+                    return;
+                }
+                try {
+                    out.write(header(FLAGS.END | FLAGS.ERR), failed(frameTooLarge("result", payload.length).message));
+                }
+                catch (e2) {
+                    this.warn(`service ${this.name}: write result: ${describe(e2)}`);
+                }
+            }
+        };
+        const ctx = {
+            call: k, caller: call.caller, role: call.role, deadlineMs: call.deadline_ms, signal: running.ac.signal,
+            // An update's failure is the handler's to see (Rust `Ctx::update`): one that does not encode is
+            // `internal`, one over moq's frame limit `invalid_input`, refused before anything is written.
+            update: (u) => {
+                let v = u;
+                if (this.contract?.update) {
+                    const r = validateSync(this.contract.update, u);
+                    if (r.issues)
+                        throw new SynapseError("invalid_input", r.issues[0]?.message ?? "invalid update");
+                    v = r.value;
+                }
+                if (this.#running.get(k) !== running)
+                    return;
+                let payload;
+                try {
+                    payload = encodeBody({ call: id, body: v });
+                }
+                catch (e) {
+                    throw new SynapseError("internal", { message: `encode update: ${describe(e)}`, source: "sdk", cause: e });
+                }
+                try {
+                    out.write(header(0), payload);
+                }
+                catch (e) {
+                    if (e instanceof SynapseError && e.code === "invalid_input")
+                        throw frameTooLarge("update", payload.length);
+                    throw new SynapseError("internal", { message: `write update: ${describe(e)}`, source: "sdk", cause: e });
+                }
+            },
+        };
+        let result;
+        try {
+            let input = call.args;
+            if (this.contract?.input) {
+                const r = validateSync(this.contract.input, call.args);
+                if (r.issues)
+                    throw new SynapseError("invalid_input", { message: r.issues[0]?.message ?? "invalid input", data: { issues: r.issues } });
+                input = r.value;
+            }
+            let value = await this.handler(input, ctx);
+            if (this.contract?.output) {
+                const r = validateSync(this.contract.output, value);
+                if (r.issues)
+                    throw new SynapseError("provider_error", `invalid output: ${r.issues[0]?.message ?? ""}`);
+                value = r.value;
+            }
+            result = { value };
+        }
+        catch (e) {
+            result = { error: errorBodyOf(e) };
+        }
+        // Cancelled or retracted meanwhile: the broker has answered the caller; the late result is dropped by `write`.
+        if ("value" in result)
+            finish(FLAGS.END, result.value);
+        else
+            finish(FLAGS.END | FLAGS.ERR, result.error);
+    }
+}
+const describe = (e) => e instanceof Error ? e.message : String(e);
+/** What a handler's throw becomes on the wire: a `ServiceError` verbatim (`data.app = true` for an application code), anything else `provider_error`. */
+export function errorBodyOf(e) {
+    if (e instanceof SynapseError) {
+        const known = ERROR_CODES.has(e.code);
+        const b = { code: e.code };
+        if (e.message)
+            b.message = e.message;
+        if (e instanceof ServiceError && !known) {
+            const data = e.data !== undefined && e.data !== null && typeof e.data === "object" && !Array.isArray(e.data) ? { ...e.data } : e.data === undefined ? {} : { value: e.data };
+            b.data = { ...data, app: true };
+        }
+        else if (e.data !== undefined)
+            b.data = e.data;
+        return b;
+    }
+    return { code: "provider_error", message: e instanceof Error ? e.message : String(e) };
+}