@nanobpm/agentic 0.1.0

package/dist/channel/hub.d.ts

@@ -0,0 +1,78 @@
+import type { Frame } from "../protocol/index.ts";
+import type { Authenticator } from "./auth.ts";
+import type { Clock } from "./clock.ts";
+import type { ChannelTransport, CloseCode, HandshakeRequest } from "./connection.ts";
+import { FamilyRouter } from "./dispatch.ts";
+import { ConnectionRegistry } from "./registry.ts";
+/** Application close code used when a connection ages out on the liveness TTL. */
+export declare const LIVENESS_TIMEOUT = 4408;
+/**
+ * The per-connection context threaded to every family handler. A handler
+ * (S2/S5/S7) uses it to reply on the same connection and to attach presence in
+ * the shared {@link ConnectionRegistry}.
+ */
+export interface HubConnection {
+    /** The connection id. */
+    readonly id: string;
+    /** The authenticated principal (ADR 0028 identity). */
+    readonly identity: string;
+    /** What the transport captured at connect time. */
+    readonly handshake: HandshakeRequest;
+    /** The shared registry — handlers attach presence via `registry.setPresence(id, …)`. */
+    readonly registry: ConnectionRegistry;
+    /** Encode and send one frame back on this connection. */
+    send(frame: Frame): void;
+    /** Close this connection. */
+    close(code?: CloseCode, reason?: string): void;
+}
+export interface AgenticHubOptions {
+    /** The listening transport bound to the app's own port. */
+    transport: ChannelTransport;
+    /** How connections authenticate. */
+    authenticator: Authenticator;
+    /** A pre-populated router, or omit to let the hub create an empty one. */
+    router?: FamilyRouter<HubConnection>;
+    /** A shared registry, or omit to let the hub create one. */
+    registry?: ConnectionRegistry;
+    /**
+     * Injectable clock for the registry's liveness time. Ignored when a `registry`
+     * is supplied — that registry owns time (it is the single source of truth for
+     * liveness), so pass the clock to the {@link ConnectionRegistry} instead.
+     */
+    clock?: Clock;
+    /**
+     * How often to sweep for aged-out connections, in ms. Default: a third of the
+     * registry TTL. Pass 0 to disable the internal timer (tests call
+     * {@link AgenticHub.sweepNow} explicitly).
+     */
+    sweepIntervalMs?: number;
+    /** Notified of a decode/handler error; the offending connection is kept. */
+    onError?: (err: unknown, connectionId?: string) => void;
+}
+export declare class AgenticHub {
+    #private;
+    readonly router: FamilyRouter<HubConnection>;
+    readonly registry: ConnectionRegistry;
+    constructor(options: AgenticHubOptions);
+    /**
+     * Attach the handler that owns a message family. Convenience delegate to the
+     * router's registration seam — this is the canonical extension point every
+     * family module (S2/S5/S7) uses.
+     */
+    registerFamilyHandler(...args: Parameters<FamilyRouter<HubConnection>["registerFamilyHandler"]>): void;
+    /** The bound address of the underlying transport once listening. */
+    get address(): {
+        readonly port: number;
+    } | null;
+    /** The number of currently tracked connections. */
+    get connectionCount(): number;
+    /**
+     * Age out connections past the liveness TTL and close their sockets. Called
+     * automatically by the internal timer; exposed for deterministic tests. Reads
+     * "now" from the registry's own clock so liveness time has a single source of
+     * truth — the hub keeps no separate clock to drift against `lastSeen`.
+     */
+    sweepNow(): void;
+    /** Stop the liveness sweep and release the transport's port. */
+    close(): Promise<void>;
+}

package/dist/channel/hub.js

@@ -0,0 +1,157 @@
+/**
+ * The app-tier agentic hub.
+ *
+ * Stands up over a {@link ChannelTransport} bound to the app's OWN port (the
+ * Camunda-8 engine transport is a separate connection and untouched). For each
+ * accepted connection it:
+ *   1. authenticates the handshake (ADR 0028 identity + capability credential),
+ *   2. tracks it in the {@link ConnectionRegistry} with liveness,
+ *   3. decodes inbound frames with the S0 codec and routes each to its family
+ *      handler via the {@link FamilyRouter} registration seam — never a switch,
+ *   4. ages out connections that stop sending (TTL sweep).
+ *
+ * Family behaviour (presence, relay, blackboard, …) is NOT baked in here: each
+ * wave-2 slice attaches its family as its own module through
+ * {@link AgenticHub.registerFamilyHandler}.
+ */
+import { decodeFrame, encodeFrame, FrameDecodeError } from "../protocol/index.js";
+import { FamilyRouter } from "./dispatch.js";
+import { ConnectionRegistry } from "./registry.js";
+/** Application close code used when a connection ages out on the liveness TTL. */
+export const LIVENESS_TIMEOUT = 4408;
+export class AgenticHub {
+    router;
+    registry;
+    #transport;
+    #authenticator;
+    #onError;
+    #conns = new Map();
+    #sweepTimer;
+    constructor(options) {
+        this.#transport = options.transport;
+        this.#authenticator = options.authenticator;
+        this.router = options.router ?? new FamilyRouter();
+        this.registry = options.registry ?? new ConnectionRegistry({ clock: options.clock });
+        this.#onError = options.onError ?? (() => { });
+        this.#transport.onConnection((conn) => {
+            void this.#accept(conn);
+        });
+        const sweepInterval = options.sweepIntervalMs ?? Math.max(1, Math.floor(this.registry.ttlMs / 3));
+        if (sweepInterval > 0) {
+            this.#sweepTimer = setInterval(() => this.sweepNow(), sweepInterval);
+            // Do not keep the process alive solely for the liveness sweep.
+            this.#sweepTimer.unref?.();
+        }
+    }
+    /**
+     * Attach the handler that owns a message family. Convenience delegate to the
+     * router's registration seam — this is the canonical extension point every
+     * family module (S2/S5/S7) uses.
+     */
+    registerFamilyHandler(...args) {
+        this.router.registerFamilyHandler(...args);
+    }
+    /** The bound address of the underlying transport once listening. */
+    get address() {
+        return this.#transport.address;
+    }
+    /** The number of currently tracked connections. */
+    get connectionCount() {
+        return this.registry.size;
+    }
+    async #accept(conn) {
+        // Register the close listener BEFORE awaiting auth. The authenticator may be
+        // async, and a peer can disconnect while it is in flight; the connection
+        // contract permits only a single close listener, so this one handler covers
+        // both the mid-auth race and the connection's normal post-registration life.
+        let closed = false;
+        conn.onClose(() => {
+            closed = true;
+            this.registry.remove(conn.id);
+            this.#conns.delete(conn.id);
+        });
+        let auth;
+        try {
+            auth = await this.#authenticator(conn.handshake);
+        }
+        catch (err) {
+            this.#onError(err, conn.id);
+            conn.close(AUTH_INTERNAL, "authentication error");
+            return;
+        }
+        if (!auth.ok) {
+            conn.close(auth.code, auth.reason);
+            return;
+        }
+        // The peer vanished while auth was in flight — never track a dead socket.
+        if (closed) {
+            return;
+        }
+        this.#conns.set(conn.id, conn);
+        this.registry.add(conn.id, auth.grant.identity);
+        const hubConn = {
+            id: conn.id,
+            identity: auth.grant.identity,
+            handshake: conn.handshake,
+            registry: this.registry,
+            send: (frame) => conn.send(encodeFrame(frame)),
+            close: (code, reason) => conn.close(code, reason),
+        };
+        conn.onMessage((bytes) => this.#onMessage(conn.id, hubConn, bytes));
+        conn.onPong?.(() => this.registry.touch(conn.id));
+        conn.onPing?.(() => this.registry.touch(conn.id));
+    }
+    #onMessage(id, hubConn, bytes) {
+        // Any inbound bytes are proof of life at the transport level — refresh
+        // liveness before decoding so an actively-transmitting peer is never swept
+        // as "silent", even if the bytes fail to decode into a well-formed frame.
+        this.registry.touch(id);
+        let frame;
+        try {
+            frame = decodeFrame(bytes);
+        }
+        catch (err) {
+            // A malformed frame is a per-message fault, not a connection fault: report
+            // it and keep the connection (and its liveness) intact.
+            if (err instanceof FrameDecodeError) {
+                this.#onError(err, id);
+                return;
+            }
+            throw err;
+        }
+        this.router.route(frame, hubConn).catch((err) => this.#onError(err, id));
+    }
+    /**
+     * Age out connections past the liveness TTL and close their sockets. Called
+     * automatically by the internal timer; exposed for deterministic tests. Reads
+     * "now" from the registry's own clock so liveness time has a single source of
+     * truth — the hub keeps no separate clock to drift against `lastSeen`.
+     */
+    sweepNow() {
+        const stale = this.registry.sweep();
+        for (const entry of stale) {
+            const conn = this.#conns.get(entry.id);
+            this.#conns.delete(entry.id);
+            conn?.close(LIVENESS_TIMEOUT, "liveness timeout");
+        }
+    }
+    /** Stop the liveness sweep and release the transport's port. */
+    async close() {
+        if (this.#sweepTimer !== undefined) {
+            clearInterval(this.#sweepTimer);
+            this.#sweepTimer = undefined;
+        }
+        // Actively close tracked connections so shutdown is deterministic across
+        // transports: ChannelTransport.close() is only specified to stop accepting
+        // and release the port, not to terminate live connections. Each close()
+        // fires the connection's onClose handler, which clears it from the registry
+        // and #conns; snapshot first to avoid mutating the map mid-iteration.
+        for (const conn of [...this.#conns.values()]) {
+            conn.close();
+        }
+        this.#conns.clear();
+        await this.#transport.close();
+    }
+}
+/** Application close code for an internal authentication error. */
+const AUTH_INTERNAL = 4500;

package/dist/channel/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @nanobpm/agentic-channel — the app-tier channel & hub for the Nano agentic
+ * protocol (ADR 0056, slice S1).
+ *
+ * Stands up a WebSocket server on the app's OWN bound port, authenticates each
+ * peer (ADR 0028 identity + capability credential), tracks it in a connection
+ * registry with liveness, and routes inbound frames to per-family handlers via
+ * the {@link FamilyRouter} registration seam — the canonical extension point
+ * every family module (S2 presence, S5 relay, S7 blackboard) attaches to.
+ *
+ * The wire contract itself lives in `@nanobpm/agentic-protocol`; this package
+ * builds on it. The Camunda-8 engine transport is a separate connection and is
+ * never touched.
+ */
+export { AgenticHub, LIVENESS_TIMEOUT } from "./hub.ts";
+export type { AgenticHubOptions, HubConnection } from "./hub.ts";
+export { FamilyRouter, UnknownFamilyError, DuplicateFamilyHandlerError, } from "./dispatch.ts";
+export type { FamilyHandler } from "./dispatch.ts";
+export { ConnectionRegistry } from "./registry.ts";
+export type { ConnectionRegistryOptions, Presence, RegisteredConnection, } from "./registry.ts";
+export { sharedSecretAuthenticator, AUTH_UNAUTHORIZED, AUTH_FORBIDDEN, } from "./auth.ts";
+export type { Authenticator, AuthGrant, AuthResult, SharedSecretAuthOptions, } from "./auth.ts";
+export { WebSocketChannelTransport } from "./ws-transport.ts";
+export type { WebSocketChannelTransportOptions } from "./ws-transport.ts";
+export { systemClock } from "./clock.ts";
+export type { Clock } from "./clock.ts";
+export type { ChannelConnection, ChannelTransport, CloseCode, HandshakeRequest, } from "./connection.ts";

package/dist/channel/index.js

@@ -0,0 +1,20 @@
+/**
+ * @nanobpm/agentic-channel — the app-tier channel & hub for the Nano agentic
+ * protocol (ADR 0056, slice S1).
+ *
+ * Stands up a WebSocket server on the app's OWN bound port, authenticates each
+ * peer (ADR 0028 identity + capability credential), tracks it in a connection
+ * registry with liveness, and routes inbound frames to per-family handlers via
+ * the {@link FamilyRouter} registration seam — the canonical extension point
+ * every family module (S2 presence, S5 relay, S7 blackboard) attaches to.
+ *
+ * The wire contract itself lives in `@nanobpm/agentic-protocol`; this package
+ * builds on it. The Camunda-8 engine transport is a separate connection and is
+ * never touched.
+ */
+export { AgenticHub, LIVENESS_TIMEOUT } from "./hub.js";
+export { FamilyRouter, UnknownFamilyError, DuplicateFamilyHandlerError, } from "./dispatch.js";
+export { ConnectionRegistry } from "./registry.js";
+export { sharedSecretAuthenticator, AUTH_UNAUTHORIZED, AUTH_FORBIDDEN, } from "./auth.js";
+export { WebSocketChannelTransport } from "./ws-transport.js";
+export { systemClock } from "./clock.js";

package/dist/channel/registry.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The connection registry with liveness.
+ *
+ * S1 tracks every authenticated connection and its last-seen time; a connection
+ * not seen within the liveness TTL ages out on {@link ConnectionRegistry.sweep}.
+ * Presence detail (instance / declared capability / host / family) is left blank
+ * by S1 and filled in by the S2 register/heartbeat family module through
+ * {@link ConnectionRegistry.setPresence} — S1 owns liveness, S2 owns presence.
+ */
+import type { Capability } from "../protocol/index.ts";
+import type { Clock } from "./clock.ts";
+/** Presence attributes a family module (S2) attaches to a live connection. */
+export interface Presence {
+    /** The worker instance id declared on `register`. */
+    instance?: string;
+    /** The enrolment capability declared on `register` (never a routing token). */
+    capability?: Capability;
+}
+/** A tracked, authenticated connection. */
+export interface RegisteredConnection {
+    /** The connection id (matches {@link ChannelConnection.id}). */
+    readonly id: string;
+    /** The authenticated principal (ADR 0028 identity) from the handshake. */
+    readonly identity: string;
+    /** When the connection was accepted, in epoch ms. */
+    readonly connectedAt: number;
+    /** Last time any inbound frame or keepalive pong was seen, in epoch ms. */
+    lastSeen: number;
+    /** Presence detail, populated by the S2 family module (blank until then). */
+    presence: Presence;
+}
+export interface ConnectionRegistryOptions {
+    /** Liveness TTL in ms; a connection unseen for longer ages out. Default 30000. */
+    ttlMs?: number;
+    /** Injectable clock (deterministic tests). Default {@link systemClock}. */
+    clock?: Clock;
+}
+export declare class ConnectionRegistry {
+    #private;
+    constructor(options?: ConnectionRegistryOptions);
+    /** The liveness TTL in ms. */
+    get ttlMs(): number;
+    /** Number of tracked connections. */
+    get size(): number;
+    /**
+     * Start tracking a newly authenticated connection. `connectedAt` and
+     * `lastSeen` are set to now; presence starts blank.
+     */
+    add(id: string, identity: string): RegisteredConnection;
+    /** Update a connection's liveness to now. No-op if unknown. */
+    touch(id: string): void;
+    /** Merge presence detail onto a tracked connection (used by S2). No-op if unknown. */
+    setPresence(id: string, patch: Presence): void;
+    /** Look up a tracked connection. */
+    get(id: string): RegisteredConnection | undefined;
+    /** Whether a connection is tracked. */
+    has(id: string): boolean;
+    /** Stop tracking a connection, returning the removed entry if present. */
+    remove(id: string): RegisteredConnection | undefined;
+    /** All tracked connections, in insertion order. */
+    list(): RegisteredConnection[];
+    /**
+     * Age out every connection whose last-seen time is older than the TTL and
+     * return the removed entries, so the hub can close their sockets. `now`
+     * defaults to the clock; pass an explicit value for deterministic tests.
+     */
+    sweep(now?: number): RegisteredConnection[];
+}

package/dist/channel/registry.js

@@ -0,0 +1,84 @@
+import { systemClock } from "./clock.js";
+const DEFAULT_TTL_MS = 30_000;
+export class ConnectionRegistry {
+    #byId = new Map();
+    #ttlMs;
+    #clock;
+    constructor(options = {}) {
+        this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.#clock = options.clock ?? systemClock;
+    }
+    /** The liveness TTL in ms. */
+    get ttlMs() {
+        return this.#ttlMs;
+    }
+    /** Number of tracked connections. */
+    get size() {
+        return this.#byId.size;
+    }
+    /**
+     * Start tracking a newly authenticated connection. `connectedAt` and
+     * `lastSeen` are set to now; presence starts blank.
+     */
+    add(id, identity) {
+        const now = this.#clock.now();
+        const entry = {
+            id,
+            identity,
+            connectedAt: now,
+            lastSeen: now,
+            presence: {},
+        };
+        this.#byId.set(id, entry);
+        return entry;
+    }
+    /** Update a connection's liveness to now. No-op if unknown. */
+    touch(id) {
+        const entry = this.#byId.get(id);
+        if (entry !== undefined) {
+            entry.lastSeen = this.#clock.now();
+        }
+    }
+    /** Merge presence detail onto a tracked connection (used by S2). No-op if unknown. */
+    setPresence(id, patch) {
+        const entry = this.#byId.get(id);
+        if (entry !== undefined) {
+            entry.presence = { ...entry.presence, ...patch };
+        }
+    }
+    /** Look up a tracked connection. */
+    get(id) {
+        return this.#byId.get(id);
+    }
+    /** Whether a connection is tracked. */
+    has(id) {
+        return this.#byId.has(id);
+    }
+    /** Stop tracking a connection, returning the removed entry if present. */
+    remove(id) {
+        const entry = this.#byId.get(id);
+        this.#byId.delete(id);
+        return entry;
+    }
+    /** All tracked connections, in insertion order. */
+    list() {
+        return [...this.#byId.values()];
+    }
+    /**
+     * Age out every connection whose last-seen time is older than the TTL and
+     * return the removed entries, so the hub can close their sockets. `now`
+     * defaults to the clock; pass an explicit value for deterministic tests.
+     */
+    sweep(now = this.#clock.now()) {
+        const stale = [];
+        for (const entry of this.#byId.values()) {
+            if (now - entry.lastSeen > this.#ttlMs) {
+                stale.push(entry);
+            }
+        }
+        for (const entry of stale) {
+            this.#byId.delete(entry.id);
+        }
+        return stale;
+    }
+}

package/dist/channel/ws-transport.d.ts

@@ -0,0 +1,23 @@
+import type { Server as HttpServer } from "node:http";
+import type { ChannelConnection, ChannelTransport } from "./connection.ts";
+export interface WebSocketChannelTransportOptions {
+    /** Port to bind (the app's own port). Use 0 for an ephemeral port. Ignored if `server` is set. */
+    port?: number;
+    /** Host/interface to bind. Ignored if `server` is set. */
+    host?: string;
+    /** Path the channel is served on. Default `/agentic`. */
+    path?: string;
+    /** Attach to an existing app HTTP server (share the app's port) instead of binding a new one. */
+    server?: HttpServer;
+}
+export declare class WebSocketChannelTransport implements ChannelTransport {
+    #private;
+    constructor(options?: WebSocketChannelTransportOptions);
+    onConnection(listener: (conn: ChannelConnection) => void): void;
+    /** Resolve once the server is listening on its port. */
+    ready(): Promise<void>;
+    get address(): {
+        readonly port: number;
+    } | null;
+    close(): Promise<void>;
+}

package/dist/channel/ws-transport.js

@@ -0,0 +1,178 @@
+/**
+ * The production WebSocket transport for the agentic hub.
+ *
+ * A thin adapter over the `ws` server that binds the app's OWN port (or attaches
+ * to an existing app HTTP server so it shares that port), captures the ADR 0028
+ * identity token + capability credential from the upgrade request, and hands the
+ * hub a transport-agnostic {@link ChannelConnection} per peer. The Camunda-8
+ * engine transport is a separate connection and is never touched here.
+ */
+import { randomUUID } from "node:crypto";
+import { WebSocketServer } from "ws";
+const DEFAULT_PATH = "/agentic";
+/** RFC 6455 close code for a frame whose type the endpoint cannot accept. */
+const CLOSE_UNSUPPORTED_DATA = 1003;
+/**
+ * Grace period for the shutdown close handshake before a still-open peer is
+ * force-terminated, so `close()` stays bounded even if a peer stalls.
+ */
+const GRACEFUL_CLOSE_TIMEOUT_MS = 250;
+/** Normalise Node's header map to a flat, lower-cased string record. */
+function flattenHeaders(req) {
+    const headers = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+        const name = key.toLowerCase();
+        if (typeof value === "string") {
+            headers[name] = value;
+        }
+        else if (Array.isArray(value)) {
+            headers[name] = value.join(", ");
+        }
+    }
+    return headers;
+}
+/** Parse the upgrade request into the handshake the authenticator reads. */
+function handshakeFrom(req) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const query = {};
+    for (const [key, value] of url.searchParams) {
+        query[key] = value;
+    }
+    const headers = flattenHeaders(req);
+    return {
+        token: query.token,
+        credential: query.capability ?? headers["x-capability-credential"],
+        remote: req.socket.remoteAddress ?? undefined,
+        headers,
+        query,
+    };
+}
+/** Coerce `ws` RawData into a single contiguous byte view for the codec. */
+function toBytes(data) {
+    if (Array.isArray(data)) {
+        return Buffer.concat(data);
+    }
+    if (data instanceof ArrayBuffer) {
+        return new Uint8Array(data);
+    }
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+/** One `ws` socket wrapped as a {@link ChannelConnection}. */
+class WsConnection {
+    id;
+    handshake;
+    #ws;
+    constructor(id, ws, handshake) {
+        this.id = id;
+        this.#ws = ws;
+        this.handshake = handshake;
+    }
+    send(bytes) {
+        if (this.#ws.readyState === this.#ws.OPEN) {
+            this.#ws.send(bytes, { binary: true });
+        }
+    }
+    close(code, reason) {
+        if (code === undefined) {
+            this.#ws.close();
+        }
+        else {
+            this.#ws.close(code, reason);
+        }
+    }
+    onMessage(listener) {
+        this.#ws.on("message", (data, isBinary) => {
+            // The channel protocol is binary-only. A text frame (`isBinary === false`,
+            // which `ws` may deliver as a `string` with no `.buffer`) is a protocol
+            // violation: reject it with 1003 rather than letting `toBytes` throw.
+            if (!isBinary) {
+                this.#ws.close(CLOSE_UNSUPPORTED_DATA, "binary frames only");
+                return;
+            }
+            listener(toBytes(data));
+        });
+    }
+    onClose(listener) {
+        this.#ws.on("close", (code, reason) => listener(code, reason.toString()));
+    }
+    onPong(listener) {
+        this.#ws.on("pong", () => listener());
+    }
+    onPing(listener) {
+        this.#ws.on("ping", () => listener());
+    }
+    ping() {
+        if (this.#ws.readyState === this.#ws.OPEN) {
+            this.#ws.ping();
+        }
+    }
+}
+export class WebSocketChannelTransport {
+    #wss;
+    #server;
+    #listener;
+    constructor(options = {}) {
+        const path = options.path ?? DEFAULT_PATH;
+        this.#server = options.server;
+        this.#wss = options.server
+            ? new WebSocketServer({ server: options.server, path })
+            : new WebSocketServer({ port: options.port ?? 0, host: options.host, path });
+        this.#wss.on("connection", (ws, req) => {
+            const conn = new WsConnection(randomUUID(), ws, handshakeFrom(req));
+            this.#listener?.(conn);
+        });
+    }
+    onConnection(listener) {
+        this.#listener = listener;
+    }
+    /** Resolve once the server is listening on its port. */
+    ready() {
+        // In shared-port mode the app owns the HTTP server: `ws` never emits
+        // `listening` on the WebSocketServer, so wait on the HTTP server instead
+        // (or resolve at once if it is already listening) to avoid hanging forever.
+        const source = this.#server ?? this.#wss;
+        if (this.#server ? this.#server.listening : this.#wss.address() !== null) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const onListening = () => {
+                source.off("error", onError);
+                resolve();
+            };
+            const onError = (err) => {
+                source.off("listening", onListening);
+                reject(err);
+            };
+            source.once("listening", onListening);
+            source.once("error", onError);
+        });
+    }
+    get address() {
+        const addr = this.#wss.address();
+        if (addr !== null && typeof addr === "object" && "port" in addr) {
+            return { port: addr.port };
+        }
+        return null;
+    }
+    close() {
+        return new Promise((resolve, reject) => {
+            // Prefer a graceful close handshake so peers observe a normal closure
+            // (with any application close code/reason) instead of an abnormal 1006.
+            // Fall back to terminate() for any peer that doesn't complete the
+            // handshake promptly, keeping shutdown bounded and deterministic.
+            for (const client of this.#wss.clients) {
+                client.close();
+            }
+            const fallback = setTimeout(() => {
+                for (const client of this.#wss.clients) {
+                    client.terminate();
+                }
+            }, GRACEFUL_CLOSE_TIMEOUT_MS);
+            fallback.unref?.();
+            this.#wss.close((err) => {
+                clearTimeout(fallback);
+                err ? reject(err) : resolve();
+            });
+        });
+    }
+}