@synapse-sdk/client 0.3.3 → 0.3.4

package/dist/calls.d.ts

@@ -1,4 +1,4 @@
-import { type CallId, type ServiceContract } from "@synapse-sdk/core";
+import { SynapseError, 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";
@@ -33,5 +33,11 @@ export declare class RunImpl<U, R> implements Run<U, R> {
  * 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>;
+/**
+ * A call that was never sent (no session): a `Run` already `failed` with `error`. Its result is the
+ * error; it has no updates; `cancel()` has nothing to do. Like every Run, an unread result is no
+ * unhandled rejection.
+ */
+export declare function failedRun<U, R>(error: SynapseError): Run<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

@@ -178,6 +178,25 @@ export function startOn(node, session, svc, args, opts, contract) {
     run.start();
     return run;
 }
+/**
+ * A call that was never sent (no session): a `Run` already `failed` with `error`. Its result is the
+ * error; it has no updates; `cancel()` has nothing to do. Like every Run, an unread result is no
+ * unhandled rejection.
+ */
+export function failedRun(error) {
+    const result = Promise.reject(error);
+    result.catch(() => { });
+    return {
+        id: "",
+        status: "failed",
+        result,
+        then: (onFulfilled, onRejected) => result.then(onFulfilled, onRejected),
+        nextUpdate: async () => undefined,
+        updates: async function* () { },
+        cancel: async () => { },
+        [Symbol.asyncDispose]: async () => { },
+    };
+}
 /** `callStream`: the updates and the result as one ordered stream; `break` cancels. */
 export async function* callStream(run) {
     try {

package/dist/node.d.ts

@@ -9,14 +9,16 @@ export declare function fixedPolicy(ms: number): ReconnectPolicy;
 /** Stops after `maxAttempts` attempts in one phase. */
 export declare function withMaxAttempts(p: ReconnectPolicy, maxAttempts: number): ReconnectPolicy;
 export declare const defaultReconnectPolicy: ReconnectPolicy;
-/** The node's declared target: bumped `generation` per change; `dial` undefined = deliberately disconnected. */
+/** The node's declared target: bumped `generation` per change; `dial` undefined = no target (the node is `idle`). */
 export interface Target {
     generation: number;
     dial: Dial | undefined;
     identity: Identity;
 }
-/** The one lifecycle cell: `ConnectionState` with the session on `connected`. State, not history. */
+/** The one lifecycle value (held in a `Cell`): `ConnectionState` with the session on `connected`. State, not history. */
 export type Link = {
+    status: "idle";
+} | {
     status: "connecting";
     attempt: number;
 } | {
@@ -36,6 +38,7 @@ export type Link = {
 } | {
     status: "failed";
     error: SynapseError;
+    generation: number;
 };
 export declare function stateOf(l: Link): ConnectionState;
 /** What a handle task is told about the node's session, in its own mailbox, in order with its other events. */
@@ -47,16 +50,20 @@ export type SessionEvent = {
 } | {
     kind: "nodeEnded";
 };
-/** Where the loop replies to a `connect`/`setTarget` call waiting for a target generation. */
+/** How long the first pursuit of a declared target (`connect()`) keeps trying a retryable failure before `failed` (SDK §2: a hard bound; the same value in every SDK). */
+export declare const FIRST_CONNECT_GIVE_UP_MS = 30000;
+/** Where the loop replies to a `connect`/`disconnect` call waiting for a target generation. */
 type Reply = Deferred<void>;
-/** Why the loop is dialing. */
+/**
+ * Why the loop is dialing: the first pursuit of a declared target (`connect()`), every attempt (its pause included) cut
+ * at `deadlineMs` (`boundMs` after the first attempt), or a dropped session (paced by the policy).
+ */
 type Pursuit = {
     kind: "first";
     deadlineMs: number;
+    boundMs: number;
 } | {
     kind: "reconnect";
-} | {
-    kind: "target";
 };
 type Stand = {
     kind: "live";
@@ -76,30 +83,44 @@ type Next = {
     delayMs: number;
 } | {
     kind: "failed";
-} | {
-    kind: "closed";
 };
-/** The rules (SDK §2, WP §10.4) for the delay before attempt `attempt`. */
+/**
+ * The rules (SDK §2, WP §10.4) for the delay before attempt `attempt`. `unauthorized` gives up in every pursuit. The first
+ * connect retries only retryable errors and only until its deadline (the loop cuts the pause and the attempt at it; the
+ * delay is not cut here); with no policy it uses the default. Giving up is `failed` in every pursuit: the node rests
+ * until a new target.
+ */
 export declare function decide(pursuit: Pursuit, policy: ReconnectPolicy | null, err: SynapseError, attempt: number, nowMs: number): Next;
 export declare class Node {
     #private;
     readonly link: Cell<Link>;
     readonly target: Cell<Target>;
-    readonly dom: TimeDomain;
+    /** The node's time domain; final once `prepared` resolved (the loop dials, and publishers describe themselves, only after). */
+    dom: TimeDomain;
+    /** Resolves once the time domain is final (the host's monotonic clock read, its domain id derived). */
+    readonly prepared: Promise<void>;
     readonly knobs: SessionKnobs;
     readonly policy: ReconnectPolicy | null;
+    /** Bun/Node: close on SIGINT/SIGTERM once a target is declared (not at construction: constructing opens nothing). */
+    readonly signals: boolean;
     /** Broker notices addressed to this node, across its sessions (fed by the loop from the current session's). */
     readonly notices: Set<(n: ErrorBody) => void>;
     readonly projectNotices: Set<(n: Notice) => void>;
-    /** Resolves once the node has ended for good (`close()`, the first connect failing, the policy giving up). */
+    /** Resolves once the node has ended for good: `close()`, and nothing else. */
     readonly ended: Deferred<void>;
     epochs: number;
     reconnects: number;
     callsSent: number;
     callsAnswered: number;
-    constructor(target: Target, dom: TimeDomain, knobs: SessionKnobs, policy: ReconnectPolicy | null);
+    /** `finalDom`: the time domain once known, when `dom` is only provisional (see `createNode`). */
+    constructor(target: Target, dom: TimeDomain, knobs: SessionKnobs, policy: ReconnectPolicy | null, opts?: {
+        signals?: boolean;
+        finalDom?: Promise<TimeDomain>;
+    });
     get isEnded(): boolean;
     get isConnected(): boolean;
+    /** Whether the node rests `failed` on target `generation` (a `failed` of an older target, not yet replaced by the loop, is not this target's). */
+    failedOn(generation: number): boolean;
     currentSession(): Session | undefined;
     state(): ConnectionState;
     /** The loop's one write. A write that names a session or withdraws one tells every monitoring handle, in the same step. */
@@ -115,13 +136,29 @@ export declare class Node {
     };
     /** The node ends for good in `link`: handles are told, feeds end. */
     end(link: Link): void;
-    /** Builds the freshly opened session completely (its epoch, its tasks running), then names it. */
-    attach(session: Session): Session;
+    /** Builds the freshly opened session completely (its epoch, the target generation it was opened for, its tasks running), then names it. */
+    attach(session: Session, generation: number): Session;
     /** `close()`: posts the command; resolves once the node has ended. */
     close(): Promise<void>;
-    /** `setTarget()`: declares the target under the cell's write, posts the command with its reply, and awaits it. */
-    setTarget(dial: Dial | undefined): Promise<void>;
-    /** Starts the loop. `first` is the `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
+    /**
+     * The one path of every target change (`connect()`, `disconnect()`): declares `dial` (`undefined`: no target) under the
+     * `target` `Cell`'s write, posts the command with its reply, and awaits it (the loop answers once the target is reached, given up
+     * on, applied as none, or superseded by a newer one: quietly). The target already declared declares nothing (except
+     * from `failed` on it, where it is dialed again) and settles with the node's state (`settled`); no target again is done at
+     * once. `giveUpAfterMs`: the bound of the dial's first pursuit.
+     */
+    declare(dial: Dial | undefined, giveUpAfterMs?: number): Promise<void>;
+    /**
+     * Settles with target `generation` by reading the node's state: resolves once connected on a session opened for it (a
+     * session of an earlier target still connected does not count) or once a newer target superseded it (quietly, as the
+     * loop answers a superseded call); rejects once `failed` on it (its error; a `failed` of an older target keeps it waiting) or ended (`not_connected`).
+     */
+    settled(generation: number): Promise<void>;
+    /** `disconnect()` again while the first is still being acted on: resolves once the node rests `idle` (or a newer target superseded it); `not_connected` once it ended. */
+    idle(generation: number): Promise<void>;
+    /** Resolves once a session other than `asked` is connected; rejects with the error once the node rests `failed`, `not_connected` once it ended or rests `idle` (disconnected meanwhile: no session will follow). */
+    switchedFrom(asked: Session): Promise<void>;
+    /** Starts the loop (once the time domain is final). `first` is a `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
     run(stand: Stand, first: Reply | undefined, signals: boolean): void;
 }
 /** Resolves the identity a node declares (`resolve_identity`): a missing name is minted, a `web`/`hmi` node without a `user_id` mints one. */
@@ -133,13 +170,14 @@ export declare function resolveIdentity(o: {
 }): Identity;
 /** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
 export declare function resolveTarget(node: Node, t: ConnectTarget): Dial;
+/** A given broker url that is not a URL is the caller's mistake: `invalid_input`. */
+export declare function checkUrl(url: string): void;
 /**
- * Builds the node and starts its loop in the first pursuit. Resolves as soon as the loop runs, with
- * the node (so a `close()` can reach it during the first dial) and `connected`: the loop's reply to
- * the first connect, a session established or why there is none (`not_connected` after a `close()`).
+ * Builds the node, synchronously, with no target (`idle`), and starts its loop resting; nothing is
+ * dialed until `connect()` declares a target. Throws `invalid_input` for options that can never work
+ * (a bad name). The time domain is read in the background; the loop starts once it is final.
  */
-export declare function startNode(opts: ConnectOptions, giveUpAfterMs: number): Promise<{
-    node: Node;
-    connected: Promise<void>;
-}>;
+export declare function createNode(opts: ConnectOptions): Node;
+/** The dial `connect()` with no target declares when none is declared: `SYNAPSE_ENDPOINT` (Bun/Node; unset, or a browser: `invalid_input`) with the node's current identity. */
+export declare function endpointDial(node: Node): Dial;
 export {};

package/dist/node.js

@@ -1,9 +1,9 @@
 // The node (SDK §2, WP §10): the permanent thing. It owns this node's intents (the handle registries
-// live on the handles' modules), its declared target, and ONE lifecycle cell (`Link`) that says where
+// live on the handles' modules), its declared target, and ONE lifecycle `Cell` (`Link`) that says where
 // the node stands and, when connected, names the session. It holds no fact the broker told us: those
 // are the current `Session`'s. One loop (`run`) is the only driver: it dials, attaches, waits, tears
-// down, and answers `close()` and `setTarget()` by reply. Handles are told about sessions as a
-// message in their own mailbox (`monitor`), never by watching a cell. Nothing on the wire is
+// down, and answers `close()` and every target change (`declare`) by reply. Handles are told about sessions as a
+// message in their own mailbox (`monitor`), never by watching a `Cell`. Nothing on the wire is
 // resumable: a new session means a fresh `req` track, fresh announces, fresh subscriptions, which
 // the handles replay when told.
 import { ClockSync, SynapseError, calibrateMonotonicClock, defaultDomId, isValidClientName, mintName, mintUserId, nowUs } from "@synapse-sdk/core";
@@ -27,6 +27,7 @@ export function withMaxAttempts(p, maxAttempts) {
 export const defaultReconnectPolicy = exponentialPolicy(100, 10_000);
 export function stateOf(l) {
     switch (l.status) {
+        case "idle": return { status: "idle" };
         case "connected": return { status: "connected", url: l.session.url, sinceMs: l.session.startedMs };
         case "connecting": return { status: "connecting", attempt: l.attempt };
         case "reconnecting": return { status: "reconnecting", attempt: l.attempt, reason: l.reason, error: l.error, nextRetryAtMs: l.nextRetryAtMs };
@@ -35,7 +36,14 @@ export function stateOf(l) {
         case "failed": return { status: "failed", error: l.error };
     }
 }
-/** The rules (SDK §2, WP §10.4) for the delay before attempt `attempt`. */
+/** How long the first pursuit of a declared target (`connect()`) keeps trying a retryable failure before `failed` (SDK §2: a hard bound; the same value in every SDK). */
+export const FIRST_CONNECT_GIVE_UP_MS = 30_000;
+/**
+ * The rules (SDK §2, WP §10.4) for the delay before attempt `attempt`. `unauthorized` gives up in every pursuit. The first
+ * connect retries only retryable errors and only until its deadline (the loop cuts the pause and the attempt at it; the
+ * delay is not cut here); with no policy it uses the default. Giving up is `failed` in every pursuit: the node rests
+ * until a new target.
+ */
 export function decide(pursuit, policy, err, attempt, nowMs) {
     if (err.code === "unauthorized")
         return { kind: "failed" };
@@ -43,43 +51,56 @@ export function decide(pursuit, policy, err, attempt, nowMs) {
     if (pursuit.kind === "first") {
         if (!err.retryable || nowMs >= pursuit.deadlineMs)
             return { kind: "failed" };
-        const d = (policy ?? defaultReconnectPolicy).nextRetryDelayMs({ attempt });
-        delay = d === null ? null : Math.min(d, pursuit.deadlineMs - nowMs);
+        delay = (policy ?? defaultReconnectPolicy).nextRetryDelayMs({ attempt });
     }
     else
         delay = policy ? policy.nextRetryDelayMs({ attempt }) : null;
     if (delay !== null)
         return { kind: "retry", delayMs: delay };
-    return pursuit.kind === "reconnect" ? { kind: "closed" } : { kind: "failed" };
+    return { kind: "failed" };
+}
+/** The first connect's give-up when its bound cut an attempt: `last`, the previous attempt's error (when there was one), is its cause. */
+function gaveUp(boundMs, last) {
+    return new SynapseError(last?.code ?? "connection_lost", { message: `the first connect gave up after ${boundMs} ms${last ? ` (last attempt: ${last.message})` : ""}`, ...(last ? { cause: last } : {}) });
 }
 // ---------------------------------------------------------------------------------------- node
 export class Node {
-    link = new Cell({ status: "connecting", attempt: 1 });
+    link = new Cell({ status: "idle" });
     target;
+    /** The node's time domain; final once `prepared` resolved (the loop dials, and publishers describe themselves, only after). */
     dom;
+    /** Resolves once the time domain is final (the host's monotonic clock read, its domain id derived). */
+    prepared;
     knobs;
     policy;
+    /** Bun/Node: close on SIGINT/SIGTERM once a target is declared (not at construction: constructing opens nothing). */
+    signals;
     /** Broker notices addressed to this node, across its sessions (fed by the loop from the current session's). */
     notices = new Set();
     projectNotices = new Set();
-    /** Resolves once the node has ended for good (`close()`, the first connect failing, the policy giving up). */
+    /** Resolves once the node has ended for good: `close()`, and nothing else. */
     ended = deferred();
     #endedFlag = false;
-    /** The loop's mailbox: unbounded, so no `close()` or `setTarget()` is ever dropped. */
+    /** The loop's mailbox: unbounded, so no `close()` or target change is ever dropped. */
     #commands = new AsyncQueue(Infinity);
     #monitors = new Set();
     epochs = 0;
     reconnects = 0;
     callsSent = 0;
     callsAnswered = 0;
-    constructor(target, dom, knobs, policy) {
+    /** `finalDom`: the time domain once known, when `dom` is only provisional (see `createNode`). */
+    constructor(target, dom, knobs, policy, opts = {}) {
         this.target = new Cell(target);
         this.dom = dom;
         this.knobs = knobs;
         this.policy = policy;
+        this.signals = opts.signals ?? false;
+        this.prepared = opts.finalDom ? opts.finalDom.then(d => { this.dom = d; }) : Promise.resolve();
     }
     get isEnded() { return this.#endedFlag; }
     get isConnected() { return this.link.get().status === "connected"; }
+    /** Whether the node rests `failed` on target `generation` (a `failed` of an older target, not yet replaced by the loop, is not this target's). */
+    failedOn(generation) { const l = this.link.get(); return l.status === "failed" && l.generation === generation; }
     currentSession() { const l = this.link.get(); return l.status === "connected" ? l.session : undefined; }
     state() { return stateOf(this.link.get()); }
     /** The loop's one write. A write that names a session or withdraws one tells every monitoring handle, in the same step. */
@@ -119,9 +140,10 @@ export class Node {
         forgetOnSignals(this.#closable);
     }
     #closable = { close: () => this.close() };
-    /** Builds the freshly opened session completely (its epoch, its tasks running), then names it. */
-    attach(session) {
+    /** Builds the freshly opened session completely (its epoch, the target generation it was opened for, its tasks running), then names it. */
+    attach(session, generation) {
         session.epoch = ++this.epochs;
+        session.generation = generation;
         const sync = new ClockSync(this.dom.id, session.hello.dom, nowUs());
         session.clock.set(sync.info());
         session.onNotice = (n) => {
@@ -141,24 +163,124 @@ export class Node {
         this.#commands.push({ kind: "close" });
         await this.ended.promise;
     }
-    /** `setTarget()`: declares the target under the cell's write, posts the command with its reply, and awaits it. */
-    setTarget(dial) {
+    /**
+     * The one path of every target change (`connect()`, `disconnect()`): declares `dial` (`undefined`: no target) under the
+     * `target` `Cell`'s write, posts the command with its reply, and awaits it (the loop answers once the target is reached, given up
+     * on, applied as none, or superseded by a newer one: quietly). The target already declared declares nothing (except
+     * from `failed` on it, where it is dialed again) and settles with the node's state (`settled`); no target again is done at
+     * once. `giveUpAfterMs`: the bound of the dial's first pursuit.
+     */
+    declare(dial, giveUpAfterMs = FIRST_CONNECT_GIVE_UP_MS) {
         if (this.#endedFlag)
-            return Promise.reject(new SynapseError("not_connected", "node closed"));
+            return Promise.reject(notConnected());
         const t = this.target.get();
-        if (sameDial(t.dial, dial))
-            return Promise.resolve();
+        if (sameDial(t.dial, dial) && !this.failedOn(t.generation))
+            return dial ? this.settled(t.generation) : this.idle(t.generation);
+        if (dial && this.signals)
+            closeOnSignals(this.#closable);
         const next = { generation: t.generation + 1, dial, identity: dial ? dial.identity : t.identity };
         this.target.set(next);
         const reply = deferred();
-        this.#commands.push({ kind: "setTarget", target: next, reply });
+        this.#commands.push({ kind: "declare", target: next, reply, giveUpAfterMs });
         return reply.promise;
     }
-    /** Starts the loop. `first` is the `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
+    /**
+     * Settles with target `generation` by reading the node's state: resolves once connected on a session opened for it (a
+     * session of an earlier target still connected does not count) or once a newer target superseded it (quietly, as the
+     * loop answers a superseded call); rejects once `failed` on it (its error; a `failed` of an older target keeps it waiting) or ended (`not_connected`).
+     */
+    settled(generation) {
+        return new Promise((resolve, reject) => {
+            const check = () => {
+                const l = this.link.get();
+                if ((l.status === "connected" && l.session.generation === generation) || this.target.get().generation !== generation) {
+                    resolve();
+                    return true;
+                }
+                if (l.status === "failed" && l.generation === generation) {
+                    reject(l.error);
+                    return true;
+                }
+                if (l.status === "closed") {
+                    reject(notConnected());
+                    return true;
+                }
+                return false;
+            };
+            if (check())
+                return;
+            const unLink = this.link.subscribe(() => { if (check()) {
+                unLink();
+                unTarget();
+            } });
+            const unTarget = this.target.subscribe(() => { if (check()) {
+                unLink();
+                unTarget();
+            } });
+        });
+    }
+    /** `disconnect()` again while the first is still being acted on: resolves once the node rests `idle` (or a newer target superseded it); `not_connected` once it ended. */
+    idle(generation) {
+        return new Promise((resolve, reject) => {
+            const check = () => {
+                const l = this.link.get();
+                if (l.status === "idle" || this.target.get().generation !== generation) {
+                    resolve();
+                    return true;
+                }
+                if (l.status === "closed") {
+                    reject(notConnected());
+                    return true;
+                }
+                return false;
+            };
+            if (check())
+                return;
+            const unLink = this.link.subscribe(() => { if (check()) {
+                unLink();
+                unTarget();
+            } });
+            const unTarget = this.target.subscribe(() => { if (check()) {
+                unLink();
+                unTarget();
+            } });
+        });
+    }
+    /** Resolves once a session other than `asked` is connected; rejects with the error once the node rests `failed`, `not_connected` once it ended or rests `idle` (disconnected meanwhile: no session will follow). */
+    switchedFrom(asked) {
+        return new Promise((resolve, reject) => {
+            const check = () => {
+                const l = this.link.get();
+                if (l.status === "connected" && l.session !== asked) {
+                    resolve();
+                    return true;
+                }
+                if (l.status === "failed") {
+                    reject(l.error);
+                    return true;
+                }
+                if (l.status === "closed") {
+                    reject(notConnected());
+                    return true;
+                }
+                // A `disconnect()` during the switch: no session will follow.
+                if (l.status === "idle") {
+                    reject(new SynapseError("not_connected", "disconnected before the promoted session was up"));
+                    return true;
+                }
+                return false;
+            };
+            if (check())
+                return;
+            const un = this.link.subscribe(() => { if (check())
+                un(); });
+        });
+    }
+    /** Starts the loop (once the time domain is final). `first` is a `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
     run(stand, first, signals) {
         if (signals)
             closeOnSignals(this.#closable);
-        void runLoop(this, this.#commands, stand, first);
+        void this.prepared.then(() => runLoop(this, this.#commands, stand, first));
     }
 }
 function sameDial(a, b) {
@@ -174,7 +296,7 @@ const notConnected = () => new SynapseError("not_connected", "node closed");
  */
 async function runLoop(node, commands, stand, first) {
     let target = node.target.get();
-    /** The `setTarget`/`connect` calls waiting for the current target. */
+    /** The `connect`/`disconnect` calls waiting for the current target. */
     let waiting = first ? [first] : [];
     const replyAll = (r) => { for (const w of waiting)
         r ? w.reject(r) : w.resolve(); waiting = []; };
@@ -198,7 +320,7 @@ async function runLoop(node, commands, stand, first) {
                 stand = { kind: "resting" };
                 continue;
             }
-            const { delayMs } = stand;
+            const { delayMs, pursuit } = stand;
             const ac = new AbortController();
             const opened = (async () => {
                 if (delayMs > 0)
@@ -214,9 +336,18 @@ async function runLoop(node, commands, stand, first) {
                     return { kind: "opened", result: e instanceof SynapseError ? e : new SynapseError("connection_lost", { message: String(e), cause: e }) };
                 }
             })();
-            wake = await Promise.race([nextCommand(), opened]);
-            // The dial is abandoned: its pause ends now; a session it still opens is closed when it arrives.
-            if (wake.kind === "command") {
+            // The first connect's bound cuts the pause and the attempt at its deadline: its give-up, with the previous
+            // attempt's error (attempt 1 has none) as the cause.
+            let cutTimer;
+            const racers = [nextCommand(), opened];
+            if (pursuit.kind === "first") {
+                const cut = { kind: "cut", error: gaveUp(pursuit.boundMs, stand.attempt > 1 ? stand.error : undefined) };
+                racers.push(new Promise(r => { cutTimer = setTimeout(() => r(cut), Math.max(0, pursuit.deadlineMs - performance.now())); }));
+            }
+            wake = await Promise.race(racers);
+            clearTimeout(cutTimer);
+            // The dial is abandoned (a command, or the bound): its pause ends now; a session it still opens is closed when it arrives.
+            if (wake.kind === "command" || wake.kind === "cut") {
                 ac.abort();
                 void opened.then(w => { if (w.kind === "opened" && w.result instanceof Session)
                     w.result.close(); });
@@ -243,7 +374,7 @@ async function runLoop(node, commands, stand, first) {
         const close = queued.some(c => c.kind === "close");
         let newest;
         for (const c of queued) {
-            if (c.kind !== "setTarget")
+            if (c.kind !== "declare")
                 continue;
             if (close) {
                 waiting.push(c.reply);
@@ -252,7 +383,7 @@ async function runLoop(node, commands, stand, first) {
             if (!newest || c.target.generation > newest.target.generation) {
                 if (newest)
                     newest.reply.resolve();
-                newest = { target: c.target, reply: c.reply };
+                newest = { target: c.target, reply: c.reply, giveUpAfterMs: c.giveUpAfterMs };
             }
             else
                 c.reply.resolve(); // superseded: quietly done
@@ -272,11 +403,13 @@ async function runLoop(node, commands, stand, first) {
             target = newest.target;
             attempts = 0;
             if (target.dial) {
+                // Every dial is first pursued within its bound.
+                const pursuit = { kind: "first", deadlineMs: performance.now() + newest.giveUpAfterMs, boundMs: newest.giveUpAfterMs };
                 node.setLink({ status: "connecting", attempt: 1 });
-                stand = { kind: "dialing", pursuit: { kind: "target" }, attempt: 1, delayMs: 0, reason: "client", error: new SynapseError("connection_lost", "target changed") };
+                stand = { kind: "dialing", pursuit, attempt: 1, delayMs: 0, reason: "client", error: new SynapseError("connection_lost", "target changed") };
             }
             else {
-                node.setLink({ status: "closed", reason: "client" });
+                node.setLink({ status: "idle" });
                 replyAll(undefined);
                 stand = { kind: "resting" };
             }
@@ -302,18 +435,24 @@ async function runLoop(node, commands, stand, first) {
                 stand = { kind: "dialing", pursuit: { kind: "reconnect" }, attempt: attempts, delayMs: delay, reason, error: err };
             }
             else {
-                await teardown(node, s, { status: "closing" });
-                node.end({ status: "closed", reason });
-                replyAll(notConnected());
-                return;
+                // The policy declined: the node rests `failed` with the drop's error until a new target (or `close()`).
+                await teardown(node, s, { status: "failed", error: err, generation: target.generation });
+                stand = { kind: "resting" };
             }
             continue;
         }
-        // opened
         if (stand.kind !== "dialing")
             continue;
+        // the first connect's bound cut the attempt: given up
+        if (wake.kind === "cut") {
+            node.setLink({ status: "failed", error: wake.error, generation: target.generation });
+            replyAll(wake.error);
+            stand = { kind: "resting" };
+            continue;
+        }
+        // opened
         if (wake.result instanceof Session) {
-            node.attach(wake.result);
+            node.attach(wake.result, target.generation);
             replyAll(undefined); // the target is reached
             stand = { kind: "live", session: wake.result };
             continue;
@@ -329,21 +468,12 @@ async function runLoop(node, commands, stand, first) {
             stand.error = e;
             node.setLink(pursuit.kind === "first" ? { status: "connecting", attempt: stand.attempt } : { status: "reconnecting", attempt: stand.attempt, reason: stand.reason, error: e, nextRetryAtMs: performance.now() + next.delayMs });
         }
-        else if (next.kind === "failed" && pursuit.kind === "target") {
-            node.setLink({ status: "failed", error: e });
+        else {
+            // Given up (any pursuit): `failed` is a resting state; a later `connect()` dials again.
+            node.setLink({ status: "failed", error: e, generation: target.generation });
             replyAll(e);
             stand = { kind: "resting" };
         }
-        else if (next.kind === "failed") {
-            node.end({ status: "failed", error: e });
-            replyAll(e);
-            return;
-        }
-        else {
-            node.end({ status: "closed", reason: stand.reason });
-            replyAll(notConnected());
-            return;
-        }
     }
 }
 /** Ends session `s`: the node stops naming it (handles are told, the status is true from that instant), then the session is torn down (calls failed, tasks awaited, close sent). */
@@ -367,12 +497,7 @@ export function resolveIdentity(o) {
 }
 /** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
 export function resolveTarget(node, t) {
-    try {
-        new URL(t.url);
-    }
-    catch (e) {
-        throw new SynapseError("invalid_input", { message: `broker url ${JSON.stringify(t.url)}: ${e instanceof Error ? e.message : String(e)}` });
-    }
+    checkUrl(t.url);
     const cur = node.target.get().identity;
     if (t.name !== undefined && !isValidClientName(t.name))
         throw new SynapseError("invalid_input", `name ${JSON.stringify(t.name)} is not [a-z0-9_-]{1,64}`);
@@ -386,23 +511,37 @@ export function resolveTarget(node, t) {
         identity.credential = cred;
     return makeDial(t.url, identity, t.brokerCertSha256, t.token);
 }
+/** A given broker url that is not a URL is the caller's mistake: `invalid_input`. */
+export function checkUrl(url) {
+    try {
+        new URL(url);
+    }
+    catch (e) {
+        throw new SynapseError("invalid_input", { message: `broker url ${JSON.stringify(url)}: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
 /**
- * Builds the node and starts its loop in the first pursuit. Resolves as soon as the loop runs, with
- * the node (so a `close()` can reach it during the first dial) and `connected`: the loop's reply to
- * the first connect, a session established or why there is none (`not_connected` after a `close()`).
+ * Builds the node, synchronously, with no target (`idle`), and starts its loop resting; nothing is
+ * dialed until `connect()` declares a target. Throws `invalid_input` for options that can never work
+ * (a bad name). The time domain is read in the background; the loop starts once it is final.
  */
-export async function startNode(opts, giveUpAfterMs) {
-    const url = urlOrEndpoint(opts.url);
+export function createNode(opts) {
     const identity = resolveIdentity(opts);
     // In the host's domain (Bun/Node) `nowUs()` must be the kernel's monotonic clock, like every other process on the host (WP §7.3).
-    if (!opts.domId)
+    const provisional = { id: opts.domId ?? identity.name };
+    const finalDom = opts.domId ? undefined : (async () => {
         await calibrateMonotonicClock();
-    const domId = opts.domId ?? (await defaultDomId()) ?? identity.name;
+        return { id: (await defaultDomId()) ?? identity.name };
+    })();
     const knobs = { transport: opts.transport ?? "auto", connectTimeoutMs: opts.connectTimeoutMs ?? 10_000, maxDatagram: opts.maxDatagram ?? defaultMaxDatagram(), project: opts.project };
     const policy = opts.reconnect === undefined ? defaultReconnectPolicy : opts.reconnect;
-    const dial = makeDial(url, identity, opts.brokerCertSha256, opts.token);
-    const node = new Node({ generation: 0, dial, identity }, { id: domId }, knobs, policy);
-    const first = deferred();
-    node.run({ kind: "dialing", pursuit: { kind: "first", deadlineMs: performance.now() + giveUpAfterMs }, attempt: 1, delayMs: 0, reason: "", error: new SynapseError("connection_lost") }, first, opts.signals ?? true);
-    return { node, connected: first.promise };
+    const node = new Node({ generation: 0, dial: undefined, identity }, provisional, knobs, policy, { signals: opts.signals ?? true, finalDom });
+    node.run({ kind: "resting" }, undefined, false);
+    return node;
+}
+/** The dial `connect()` with no target declares when none is declared: `SYNAPSE_ENDPOINT` (Bun/Node; unset, or a browser: `invalid_input`) with the node's current identity. */
+export function endpointDial(node) {
+    const url = urlOrEndpoint(undefined);
+    checkUrl(url);
+    return makeDial(url, node.target.get().identity, undefined, undefined);
 }