@synapse-sdk/client 0.1.0 → 0.3.3

package/README.md

@@ -1,113 +1,3 @@
 # @synapse-sdk/client
 
-Isomorphic TypeScript SDK for the **Synapse** robotics bus (Phoenix Channels). Browser,
-Bun, Node, Deno, edge. The companion to `python_client` — same model (call / stream /
-subscribe / publish / provide, realm-prefixed addresses), idiomatic TypeScript.
-
-```sh
-# internal (git) for now:
-bun add github:<org>/<repo>        # or: pnpm add github:<org>/<repo>
-```
-
-Imports: `@synapse-sdk/client` (core) and `@synapse-sdk/client/react` (hooks; React is an
-optional peer dependency).
-
-> Built for robot control and HMIs, where a stale or still-open socket is a safety hazard.
-> So we **own the connection lifecycle** (a single, verified socket) and reuse the installed
-> `phoenix` package only for the wire serializer.
-
-## The safety invariant
-
-> **At most one socket is ever acted upon.** A new socket is never created until the previous
-> one's `close` is confirmed (healthy switch) or it's been fenced and abandoned (dead socket).
-
-Three mechanics enforce it (`src/connection.ts`):
-
-1. **Serialized reconcile** — `connect`/`disconnect` set a *desired target*; one queue
-   converges to it, latest wins. Mashing the connect button coalesces.
-2. **Generation + live-identity guards** — every socket event checks it belongs to the
-   current desired-epoch *and* the current socket, so a late message/close from a superseded
-   or replaced socket is inert.
-3. **Verified teardown** — switching awaits the real `close` (with a force-fence timeout)
-   before any new socket opens. Dead sockets (heartbeat timeout) are fenced and abandoned —
-   never awaited, never read from or written to again.
-
-No `window` coupling, so discarding a socket is clean. The fuzz test runs 100 random
-connect/disconnect/retarget ops and asserts simultaneously-open sockets never exceeds **1**.
-
-## Quick start
-
-```ts
-import { Synapse } from "@synapse-sdk/client"
-
-const synapse = new Synapse() // browser/Bun: uses the built-in WebSocket
-
-// declarative, idempotent target — the "connect button" calls this
-await synapse.connect({
-  url: "wss://robot-7.tail.ts.net/runtime/api/v1/socket",
-  params: { type: "web" },
-  token: () => auth.getToken(), // → Phoenix auth subprotocol, fresh on every (re)connect
-})
-await synapse.connect({ url: "wss://robot-9/…", token }) // retarget: same verb, safe switch
-await synapse.disconnect()
-
-synapse.subscribeState((s) => render(s.status)) // idle|connecting|connected|reconnecting|closing|error
-
-// consume — mirrors the Python node
-const sum = await synapse.call("rosbridge:/add_two_ints", { a: 2, b: 3 }, { onUpdate: show, signal })
-for await (const ev of synapse.callStream("planner/plan", req)) { /* ev.type: update|result */ }
-synapse.subscribe("telemetry/pose", (m) => render(m))
-await synapse.publish("teleop/cmd_vel", axes)
-
-// provide — from any node, including the browser (the robot calls in)
-synapse.service("teleop/joystick", (input, ctx) => drive(input))
-```
-
-### three.js / react-three-fiber (no React re-renders)
-
-High-frequency data bypasses React entirely via `latest()` — read `.get()` in the render loop:
-
-```ts
-const joints = synapse.latest("rosbridge:/joint_states", { opts: { type: "sensor_msgs/JointState" } })
-useFrame(() => {
-  const s = joints.get()              // non-reactive, latest-wins (no queue growth)
-  if (s) robotRef.current?.setJointValues(toMap(s.name, s.position))
-})
-```
-
-Connection *status* (low-frequency) drives UI through a selector hook; robot *data*
-(high-frequency) drives the scene imperatively. React stays quiet at 60 Hz.
-
-## Layout (single package)
-
-```
-src/
-  connection.ts   single-socket state machine — the safety core
-  channel.ts      one topic on the connection (join/push/request/on, auto-rejoin)
-  serializer.ts   wraps the installed `phoenix` Serializer (v2 text + binary frames)
-  node.ts         Synapse — the bus verbs (call/callStream/subscribe/publish/service/latest)
-  address.ts      realm-prefix parsing (`rosbridge:/x` → { realm, name })
-  errors.ts       ConnectionError / SupersededError / ChannelError / BusError
-  types.ts        public types
-  index.ts        barrel
-test/             bun:test — connection (fuzz/invariant), channel, node
-```
-
-## Develop
-
-```bash
-bun install
-bun test                     # invariant fuzz, channel, call/subscribe/publish/provider
-bun examples/live_demo.ts    # end-to-end against a running runtime on :9001
-bunx tsc --noEmit            # type-check
-```
-
-## Status & roadmap
-
-- [x] Single-socket connection core — fuzz-proven invariant
-- [x] Bus verbs: `call` / `callStream` / `subscribe` / `publish` / `service` / `latest`
-- [x] Wire frames reconciled against the live Elixir `ServiceChannel` / `PubSubChannel`
-- [ ] React adapter — `useConnectionStatus` / `useSubscription` / `useService` + zustand
-- [ ] System-channel handshake as the default `verify` (server role → verified `connected`)
-- [ ] State mirrors (`synapse:state:*`) + discovery (`synapse:catalog`)
-```
+Part of the Synapse SDK for JavaScript. Documentation: the repository.

package/dist/calls.d.ts

@@ -0,0 +1,37 @@
+import { type CallId, type ServiceContract } from "@synapse-sdk/core";
+import type { Node } from "./node.ts";
+import { type RespFrame, type Session } from "./session.ts";
+import type { CallEvent, CallOptions, Run, RunStatus } from "./types.ts";
+/** A fresh call id (WP §8.2): 16 random bytes. */
+export declare function newCallId(): CallId;
+export declare class RunImpl<U, R> implements Run<U, R> {
+    #private;
+    private readonly node;
+    readonly session: Session;
+    readonly callId: CallId;
+    private readonly svc;
+    private readonly opts;
+    private readonly contract;
+    readonly id: string;
+    constructor(node: Node, session: Session, callId: CallId, svc: string, opts: CallOptions<U>, contract: ServiceContract<unknown, unknown, U, R> | undefined);
+    get status(): RunStatus;
+    get result(): Promise<R>;
+    then<A = R, B = never>(onFulfilled?: ((v: R) => A | PromiseLike<A>) | null, onRejected?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    /** The session's demux hands frames here; `null` = the session ended with the call pending. */
+    deliver(f: RespFrame | null): void;
+    /** Starts the per-frame reader once the request is written (frames can arrive before `writeCall` returns). */
+    start(): void;
+    nextUpdate(): Promise<U | undefined>;
+    updates(): AsyncIterable<U>;
+    /** Cooperative cancel (WP §8.4): tells the broker, then waits for its `canceled` terminal frame. `connection_lost` without sending once the session ended. */
+    cancel(reason?: string): Promise<void>;
+    /** Dropped with the call in flight: the runtime is told (best effort). */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Starts a call on `session` — a specific session, not whichever is current: an attempt's requests
+ * go on the session the attempt is for (`channel.ts`). `connection_lost` once it ended.
+ */
+export declare function startOn<U, R>(node: Node, session: Session, svc: string, args: unknown, opts: CallOptions<U>, contract?: ServiceContract<unknown, unknown, U, R>): RunImpl<U, R>;
+/** `callStream`: the updates and the result as one ordered stream; `break` cancels. */
+export declare function callStream<U, R>(run: Run<U, R>): AsyncGenerator<CallEvent<U, R>, void, undefined>;

package/dist/calls.js

@@ -0,0 +1,192 @@
+// Calls (SDK §5.2, WP §8.3): a `Run` is one call on one session. It holds the session it was sent on
+// and acts only through it: its frames come from that session's `res` demux, a cancel goes on that
+// session's `req` track, and the session's end fails it (`connection_lost`, outcome unknown) — never
+// a frame on a later session (WP §8.4: ownership is checked, never inferred).
+import { FLAGS, SynapseError, TYPES, decode as decodeBody, encode as encodeBody, nowUs, toHex, validateSync } from "@synapse-sdk/core";
+import { outcomeUnknown } from "./session.js";
+import { AsyncQueue, deferred } from "./util.js";
+/** A fresh call id (WP §8.2): 16 random bytes. */
+export function newCallId() { const b = new Uint8Array(16); crypto.getRandomValues(b); return b; }
+export class RunImpl {
+    node;
+    session;
+    callId;
+    svc;
+    opts;
+    contract;
+    id;
+    #status = "pending";
+    #frames = new AsyncQueue(4096);
+    #result = deferred();
+    #done = false;
+    #idle;
+    #onAbort;
+    constructor(node, session, callId, svc, opts, contract) {
+        this.node = node;
+        this.session = session;
+        this.callId = callId;
+        this.svc = svc;
+        this.opts = opts;
+        this.contract = contract;
+        this.id = toHex(callId);
+        this.#result.promise.catch(() => { });
+        if (opts.signal) {
+            // The cancel's own failure (e.g. the session ended first) is already the call's result.
+            this.#onAbort = () => { this.cancel("aborted").catch(() => { }); };
+            if (opts.signal.aborted)
+                queueMicrotask(this.#onAbort);
+            else
+                opts.signal.addEventListener("abort", this.#onAbort, { once: true });
+        }
+    }
+    get status() { return this.#status; }
+    get result() { return this.#result.promise; }
+    then(onFulfilled, onRejected) { return this.#result.promise.then(onFulfilled, onRejected); }
+    /** The session's demux hands frames here; `null` = the session ended with the call pending. */
+    deliver(f) { this.#frames.push(f); }
+    /** Starts the per-frame reader once the request is written (frames can arrive before `writeCall` returns). */
+    start() { void this.#read(); }
+    async #read() {
+        this.#armIdle();
+        for (;;) {
+            const f = await this.#frames.next();
+            if (f === undefined)
+                return;
+            if (f === null) {
+                this.#finish({ error: outcomeUnknown(this.session.closingReason) });
+                return;
+            }
+            this.#armIdle();
+            if (f.header.type !== TYPES.RPC_RESP)
+                continue;
+            let reply;
+            try {
+                reply = decodeBody(f.body);
+            }
+            catch {
+                continue;
+            }
+            if (f.header.flags & FLAGS.END) {
+                if (f.header.flags & FLAGS.ERR) {
+                    const b = reply.body;
+                    this.#finish({ error: SynapseError.fromBody(b, { source: b.source ?? "broker" }) });
+                }
+                else {
+                    let out = reply.body;
+                    if (this.contract?.output) {
+                        const r = validateSync(this.contract.output, out);
+                        if (r.issues) {
+                            this.#finish({ error: new SynapseError("invalid_output", { message: r.issues[0]?.message ?? "invalid output", data: { issues: r.issues } }) });
+                            return;
+                        }
+                        out = r.value;
+                    }
+                    this.#finish({ value: out });
+                }
+                return;
+            }
+            this.#status = "running";
+            let u = reply.body;
+            if (this.contract?.update) {
+                const r = validateSync(this.contract.update, u);
+                if (r.issues)
+                    continue;
+                u = r.value;
+            }
+            this.#updates.push(u);
+            try {
+                this.opts.onUpdate?.(u);
+            }
+            catch { /* the caller's */ }
+        }
+    }
+    #updates = new AsyncQueue(4096);
+    #armIdle() {
+        if (this.opts.idleTimeoutMs === undefined)
+            return;
+        if (this.#idle !== undefined)
+            clearTimeout(this.#idle);
+        this.#idle = setTimeout(() => { void this.#sendCancel("idle_timeout"); this.#finish({ error: new SynapseError("idle_timeout", `no frame from ${this.svc} for ${this.opts.idleTimeoutMs} ms`) }); }, this.opts.idleTimeoutMs);
+    }
+    #finish(r) {
+        if (this.#done)
+            return;
+        this.#done = true;
+        if (this.#idle !== undefined)
+            clearTimeout(this.#idle);
+        if (this.#onAbort && this.opts.signal)
+            this.opts.signal.removeEventListener("abort", this.#onAbort);
+        this.session.forgetCall(this.callId);
+        this.node.callsAnswered++;
+        void this.#updates.close();
+        void this.#frames.close(true);
+        if ("error" in r) {
+            this.#status = r.error.code === "canceled" ? "canceled" : "failed";
+            this.#result.reject(r.error);
+        }
+        else {
+            this.#status = "succeeded";
+            this.#result.resolve(r.value);
+        }
+    }
+    async nextUpdate() { return this.#updates.next(); }
+    updates() { return this.#updates; }
+    #sendCancel(reason) {
+        if (!this.session.isLive)
+            return;
+        const body = { call: this.callId, reason };
+        try {
+            this.session.writeReq({ flags: 0, type: TYPES.RPC_CANCEL, seq: 0, tUs: nowUs() }, encodeBody(body));
+        }
+        catch { /* the session is going */ }
+    }
+    /** Cooperative cancel (WP §8.4): tells the broker, then waits for its `canceled` terminal frame. `connection_lost` without sending once the session ended. */
+    async cancel(reason = "caller") {
+        if (this.#done)
+            return;
+        if (!this.session.isLive) {
+            this.#finish({ error: new SynapseError("connection_lost", "cancel while disconnected") });
+            return;
+        }
+        this.#sendCancel(reason);
+        try {
+            await this.#result.promise;
+        }
+        catch (e) {
+            if (!(e instanceof SynapseError && e.code === "canceled"))
+                throw e;
+        }
+    }
+    /** Dropped with the call in flight: the runtime is told (best effort). */
+    async [Symbol.asyncDispose]() { if (!this.#done) {
+        this.#sendCancel("dropped");
+        this.#finish({ error: new SynapseError("canceled", "dropped") });
+    } }
+}
+/**
+ * Starts a call on `session` — a specific session, not whichever is current: an attempt's requests
+ * go on the session the attempt is for (`channel.ts`). `connection_lost` once it ended.
+ */
+export function startOn(node, session, svc, args, opts, contract) {
+    const id = newCallId();
+    const run = new RunImpl(node, session, id, svc, opts, contract);
+    const body = { call: id, svc, args };
+    if (opts.deadlineMs !== undefined)
+        body.deadline_ms = Math.max(1, Math.round(opts.deadlineMs));
+    session.writeCall({ flags: 0, type: TYPES.RPC_CALL, seq: 0, tUs: nowUs() }, encodeBody(body), id, f => run.deliver(f));
+    node.callsSent++;
+    run.start();
+    return run;
+}
+/** `callStream`: the updates and the result as one ordered stream; `break` cancels. */
+export async function* callStream(run) {
+    try {
+        for await (const u of run.updates())
+            yield { type: "update", data: u };
+        yield { type: "result", data: await run.result };
+    }
+    finally {
+        if (run.status === "pending" || run.status === "running")
+            run.cancel("caller").catch(() => { });
+    }
+}

package/dist/channel.d.ts

@@ -0,0 +1,84 @@
+import { SynapseError, encode as encodeBody, type ErrorBody } from "@synapse-sdk/core";
+import type { Node } from "./node.ts";
+import type { Session } from "./session.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;
+/** The pace of the first re-ask of a refused or transient request. */
+export declare const REFOLLOW_PACE_MS = 100;
+/** The longest pause between two re-asks of a refused intent. */
+export declare const REFUSAL_PACE_MAX_MS = 5000;
+/** The pause before re-ask number `n` (1-based): doubled per re-ask, capped. */
+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;
+/** The holder a refusal names (`data.by`), if it does. */
+export declare function holderOf(e: SynapseError): string | undefined;
+export type Event = {
+    kind: "session";
+    session: Session;
+} | {
+    kind: "sessionEnded";
+} | {
+    kind: "nodeEnded";
+} | {
+    kind: "reply";
+    attempt: number;
+    result: SynapseError | undefined;
+} | {
+    kind: "ended";
+    bind: string;
+} | {
+    kind: "ready";
+    reply: Deferred<void>;
+} | {
+    kind: "retry";
+    attempt: number;
+} | {
+    kind: "unregister";
+};
+/** One intent kind: what the task installs and retracts, and how it asks the runtime. */
+export interface Intent {
+    readonly name: string;
+    readonly registerSvc: string;
+    readonly unregisterSvc: string;
+    registerArgs(bind: string): unknown;
+    unregisterArgs(bind: string): unknown;
+    /** The runtime admitted attempt `bind` on `s`: announce and install what the fast lane uses. Throws when the announce failed (asked again like a refusal). */
+    install(s: Session, bind: string, mailbox: (e: Event) => void): void;
+    /** 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;
+    /** The task is exiting (after the last retract). */
+    exited?(): void;
+    warn(msg: string): void;
+}
+/** The application's side of a handle: its mailbox, and `ready()` as a request to the task. */
+export declare class Handle {
+    readonly node: Node;
+    readonly intent: Intent;
+    /** Unbounded, as the Rust task's control channel: no lifecycle message is ever dropped. */
+    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. */
+    ready(): Promise<void>;
+    /** The intent is over: the task writes the `unregister` and exits. */
+    unregister(): void;
+}
+/** Starts the task for `intent`; returns the handle. */
+export declare function start(node: Node, intent: Intent): Handle;
+/** Encodes a `register`'s args for the wire (msgpack map). */
+export declare const encodeArgs: typeof encodeBody;
+export type { ErrorBody };

package/dist/channel.js

@@ -0,0 +1,215 @@
+// One task per handle (SDK §2.1, PLAN v0.22 §5): Phoenix's `Channel` on the client, for the two
+// intents asked of the runtime by `register` — a publisher (`topics.ts`) and a service registration
+// (`serve.ts`). A handle is one task owning all of the handle's lifecycle state, driven by one
+// mailbox; its events, taken strictly in order:
+// - `session` / `sessionEnded` (told by the node's loop, `Node.monitor`): the attempt on the previous
+//   session ends (its `unregister` written if the session still takes it), a new one begins on the
+//   new session — a fresh bind, `register`, then the announce; `nodeEnded`: the task exits;
+// - `reply`: the answer to the `register` the task wrote (by attempt: an older one is dropped);
+// - `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.
+import { SynapseError, encode as encodeBody } from "@synapse-sdk/core";
+import { startOn } from "./calls.js";
+import { AsyncQueue, deferred } from "./util.js";
+/** A fresh binding id (WP §8.1): 6 hex digits, the identity of one attempt to the runtime. */
+export function newBind() { const b = new Uint8Array(3); crypto.getRandomValues(b); return Array.from(b, x => x.toString(16).padStart(2, "0")).join(""); }
+/** The pace of the first re-ask of a refused or transient request. */
+export const REFOLLOW_PACE_MS = 100;
+/** The longest pause between two re-asks of a refused intent. */
+export const REFUSAL_PACE_MAX_MS = 5000;
+/** The pause before re-ask number `n` (1-based): doubled per re-ask, capped. */
+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"; }
+/** 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. */
+export class Handle {
+    node;
+    intent;
+    /** Unbounded, as the Rust task's control channel: no lifecycle message is ever dropped. */
+    mailbox = new AsyncQueue(Infinity);
+    exited = deferred();
+    constructor(node, intent) {
+        this.node = node;
+        this.intent = intent;
+    }
+    /** Resolves once the current attempt is admitted and announced; `not_connected` once the task is gone. */
+    ready() {
+        const reply = deferred();
+        if (!this.mailbox.push({ kind: "ready", reply }))
+            return Promise.reject(new SynapseError("not_connected"));
+        return Promise.race([reply.promise, this.exited.promise.then(() => { throw new SynapseError("not_connected"); })]);
+    }
+    /** The intent is over: the task writes the `unregister` and exits. */
+    unregister() { this.mailbox.push({ kind: "unregister" }); }
+}
+/** Starts the task for `intent`; returns the handle. */
+export function start(node, intent) {
+    const h = new Handle(node, intent);
+    void run(h);
+    return h;
+}
+async function run(h) {
+    const { node, intent, mailbox } = h;
+    const post = (e) => { mailbox.push(e); };
+    let session;
+    let attempt = 0;
+    let current;
+    let admitted = false;
+    let refusals = 0;
+    let retryTimer;
+    const ready = [];
+    const clearRetry = () => { if (retryTimer !== undefined) {
+        clearTimeout(retryTimer);
+        retryTimer = undefined;
+    } };
+    const scheduleRetry = (ms) => { clearRetry(); const a = attempt; retryTimer = setTimeout(() => { retryTimer = undefined; post({ kind: "retry", attempt: a }); }, ms); };
+    /** Writes the current attempt's `register` (again, on a re-ask: the same bind); the reply comes back as an event. */
+    const ask = () => {
+        const a = current;
+        if (!a)
+            return;
+        const n = attempt;
+        try {
+            const run = startOn(node, a.session, intent.registerSvc, intent.registerArgs(a.bind), {});
+            void run.result.then(() => post({ kind: "reply", attempt: n, result: undefined }), (e) => post({ kind: "reply", attempt: n, result: e instanceof SynapseError ? e : new SynapseError("internal", String(e)) }));
+        }
+        catch (e) {
+            post({ kind: "reply", attempt: n, result: e instanceof SynapseError ? e : new SynapseError("internal", String(e)) });
+        }
+    };
+    /** `unregister {bind}` on the attempt's session; re-asked while transient, off the task. */
+    const unregister = (a) => {
+        const args = intent.unregisterArgs(a.bind);
+        void (async () => {
+            for (;;) {
+                try {
+                    await startOn(node, a.session, intent.unregisterSvc, args, {}).result;
+                    return;
+                }
+                catch (e) {
+                    if (e instanceof SynapseError && isTransient(e) && a.session.isLive) {
+                        await new Promise(r => setTimeout(r, REFOLLOW_PACE_MS));
+                        continue;
+                    }
+                    return;
+                }
+            }
+        })();
+    };
+    /** The current attempt is over: its `unregister` on its own session while that lives, then the retract. */
+    const endAttempt = () => {
+        attempt += 1;
+        clearRetry();
+        admitted = false;
+        const a = current;
+        current = undefined;
+        if (!a)
+            return;
+        if (a.session.isLive)
+            unregister(a);
+        intent.retract();
+    };
+    /** A new attempt on `s`: a fresh bind, `pending`, its `register`. */
+    const begin = (s) => {
+        attempt += 1;
+        refusals = 0;
+        current = { bind: newBind(), session: s };
+        intent.setVerdict({ status: "pending", epoch: s.epoch });
+        ask();
+    };
+    const sessionChanged = (s) => {
+        session = s;
+        endAttempt();
+        if (s)
+            begin(s);
+        else
+            intent.setVerdict({ status: "unbound" });
+    };
+    /** A refusal (R6): asked again on the same attempt and bind after `refusalPaceMs`, with a warning. */
+    const refused = (e, what) => {
+        refusals += 1;
+        const pace = refusalPaceMs(refusals);
+        intent.warn(`${intent.registerSvc} ${intent.name}: ${what} (${e.code}${e.message ? `: ${e.message}` : ""}; holder ${holderOf(e) ?? "-"}; attempt ${refusals}; again in ${pace} ms)`);
+        scheduleRetry(pace);
+    };
+    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 {
+        for (;;) {
+            const ev = await mailbox.next();
+            if (!ev || ev.kind === "unregister" || ev.kind === "nodeEnded")
+                break;
+            switch (ev.kind) {
+                case "session":
+                    sessionChanged(ev.session);
+                    break;
+                case "sessionEnded":
+                    sessionChanged(undefined);
+                    break;
+                case "reply": {
+                    if (ev.attempt !== attempt || !current)
+                        break; // an attempt no longer current
+                    const a = current;
+                    if (!ev.result) {
+                        try {
+                            intent.install(a.session, a.bind, post);
+                            admitted = true;
+                            intent.setVerdict({ status: "admitted", epoch: a.session.epoch });
+                            for (const r of ready.splice(0))
+                                r.resolve();
+                        }
+                        catch (e) {
+                            refused(e instanceof SynapseError ? e : new SynapseError("internal", String(e)), "announce failed; asking again");
+                        }
+                    }
+                    else if (isTransient(ev.result))
+                        scheduleRetry(REFOLLOW_PACE_MS);
+                    else if (isReasked(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;
+                }
+                case "ended": {
+                    // The installed binding's reader ended: a renewal on the same session.
+                    if (!current || current.bind !== ev.bind)
+                        break;
+                    const s = current.session;
+                    endAttempt();
+                    begin(s);
+                    break;
+                }
+                case "ready":
+                    if (admitted)
+                        ev.reply.resolve();
+                    else
+                        ready.push(ev.reply);
+                    break;
+                case "retry":
+                    if (ev.attempt === attempt)
+                        ask();
+                    break;
+            }
+        }
+    }
+    finally {
+        unmonitor();
+        endAttempt();
+        intent.setVerdict({ status: "unbound" });
+        intent.exited?.();
+        void mailbox.close(true);
+        h.exited.resolve();
+        for (const r of ready.splice(0))
+            r.reject(new SynapseError("not_connected"));
+    }
+}
+/** Encodes a `register`'s args for the wire (msgpack map). */
+export const encodeArgs = encodeBody;