@nanobpm/agentic 0.1.0

package/src/channel/hub.test.ts

@@ -0,0 +1,335 @@
+import assert from "node:assert/strict";
+import { setImmediate as tick } from "node:timers/promises";
+import { test } from "node:test";
+import { encodeFrame } from "../protocol/index.ts";
+import type { Frame } from "../protocol/index.ts";
+import { sharedSecretAuthenticator } from "./auth.ts";
+import type { AuthResult } from "./auth.ts";
+import type { Clock } from "./clock.ts";
+import type { ChannelConnection, ChannelTransport, CloseCode, HandshakeRequest } from "./connection.ts";
+import { AgenticHub, LIVENESS_TIMEOUT } from "./hub.ts";
+import { ConnectionRegistry } from "./registry.ts";
+
+/** An in-memory connection the test drives directly — no sockets, no timers. */
+class FakeConnection implements ChannelConnection {
+  readonly id: string;
+  readonly handshake: HandshakeRequest;
+  readonly sent: Uint8Array[] = [];
+  closed: { code?: CloseCode; reason?: string } | null = null;
+  #onMessage: ((bytes: Uint8Array) => void) | undefined;
+  #onClose: ((code?: CloseCode, reason?: string) => void) | undefined;
+  #onPong: (() => void) | undefined;
+  #onPing: (() => void) | undefined;
+
+  constructor(id: string, handshake: HandshakeRequest) {
+    this.id = id;
+    this.handshake = handshake;
+  }
+
+  send(bytes: Uint8Array): void {
+    this.sent.push(bytes);
+  }
+  close(code?: CloseCode, reason?: string): void {
+    this.closed = { code, reason };
+    this.#onClose?.(code, reason);
+  }
+  onMessage(listener: (bytes: Uint8Array) => void): void {
+    this.#onMessage = listener;
+  }
+  onClose(listener: (code?: CloseCode, reason?: string) => void): void {
+    this.#onClose = listener;
+  }
+  onPong(listener: () => void): void {
+    this.#onPong = listener;
+  }
+  onPing(listener: () => void): void {
+    this.#onPing = listener;
+  }
+
+  // Test drivers:
+  receive(bytes: Uint8Array): void {
+    this.#onMessage?.(bytes);
+  }
+  pong(): void {
+    this.#onPong?.();
+  }
+  ping(): void {
+    this.#onPing?.();
+  }
+}
+
+class FakeTransport implements ChannelTransport {
+  readonly address = { port: 0 };
+  #onConnection: ((conn: ChannelConnection) => void) | undefined;
+
+  onConnection(listener: (conn: ChannelConnection) => void): void {
+    this.#onConnection = listener;
+  }
+  close(): Promise<void> {
+    return Promise.resolve();
+  }
+  accept(conn: ChannelConnection): void {
+    this.#onConnection?.(conn);
+  }
+}
+
+function fakeClock(start = 1000): Clock & { set(t: number): void } {
+  let t = start;
+  return { now: () => t, set: (v: number) => (t = v) };
+}
+
+function registerFrame(instance: string): Uint8Array {
+  const frame: Frame = {
+    lane: "control",
+    family: "register",
+    seq: 1,
+    payload: { instance, capability: { cognition: "opus", family: "anthropic" } },
+  };
+  return encodeFrame(frame);
+}
+
+const goodAuth = sharedSecretAuthenticator({ secret: "s3cret" });
+
+test("authenticates a connection and tracks it with liveness", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, sweepIntervalMs: 0 });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+
+  assert.equal(hub.connectionCount, 1);
+  const entry = hub.registry.get("c1");
+  assert.equal(entry?.identity, "peer-a");
+  assert.equal(conn.closed, null);
+  await hub.close();
+});
+
+test("rejects an unauthenticated connection without tracking it", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, sweepIntervalMs: 0 });
+
+  const conn = new FakeConnection("bad", { token: "wrong", credential: "cap-1" });
+  transport.accept(conn);
+  await tick();
+
+  assert.equal(hub.connectionCount, 0);
+  assert.equal(conn.closed?.code, 4401);
+  await hub.close();
+});
+
+test("routes an inbound frame to the registered family handler", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, sweepIntervalMs: 0 });
+
+  const received: string[] = [];
+  hub.registerFamilyHandler("register", (frame, ctx) => {
+    const payload = frame.payload;
+    const instance = typeof payload === "object" && payload !== null && "instance" in payload ? payload.instance : "?";
+    ctx.registry.setPresence(ctx.id, { instance: String(instance) });
+    received.push(`register:${ctx.id}`);
+  });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+  conn.receive(registerFrame("w-1"));
+  await tick();
+
+  assert.deepEqual(received, ["register:c1"]);
+  assert.equal(hub.registry.get("c1")?.presence.instance, "w-1");
+  await hub.close();
+});
+
+test("keeps the connection alive on a malformed frame but reports the error", async () => {
+  const transport = new FakeTransport();
+  const errors: unknown[] = [];
+  const hub = new AgenticHub({
+    transport,
+    authenticator: goodAuth,
+    sweepIntervalMs: 0,
+    onError: (err) => errors.push(err),
+  });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+  conn.receive(new Uint8Array([0, 1, 2, 3])); // not a valid frame
+  await tick();
+
+  assert.equal(errors.length, 1);
+  assert.equal(hub.connectionCount, 1); // still tracked
+  assert.equal(conn.closed, null);
+  await hub.close();
+});
+
+test("liveness: a malformed frame still refreshes lastSeen so an active peer is not swept", async () => {
+  // A peer actively sending bytes is alive at the transport level even when the
+  // bytes fail to decode; sweeping it as "silent" would drop a live connection.
+  const clock = fakeClock(1000);
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, clock, sweepIntervalMs: 0 });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+
+  clock.set(1000 + 20_000);
+  conn.receive(new Uint8Array([0, 1, 2, 3])); // malformed, but proof of life
+  await tick();
+
+  clock.set(1000 + 40_000); // 40s since connect, but only 20s since last frame
+  hub.sweepNow();
+  assert.equal(hub.connectionCount, 1);
+  assert.equal(conn.closed, null);
+  await hub.close();
+});
+
+test("liveness: an inbound frame refreshes lastSeen so a live peer is not swept", async () => {
+  const clock = fakeClock(1000);
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, clock, sweepIntervalMs: 0 });
+  // registry TTL defaults to 30_000ms.
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+
+  clock.set(1000 + 20_000);
+  conn.receive(registerFrame("w-1")); // refresh liveness
+  await tick();
+
+  clock.set(1000 + 40_000); // 40s since connect, but only 20s since last frame
+  hub.sweepNow();
+  assert.equal(hub.connectionCount, 1);
+  assert.equal(conn.closed, null);
+  await hub.close();
+});
+
+test("liveness: a silent peer ages out on the TTL and its socket is closed", async () => {
+  const clock = fakeClock(1000);
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, clock, sweepIntervalMs: 0 });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+
+  clock.set(1000 + 40_000); // > 30s TTL with no frame
+  hub.sweepNow();
+
+  assert.equal(hub.connectionCount, 0);
+  assert.equal(conn.closed?.code, LIVENESS_TIMEOUT);
+  await hub.close();
+});
+
+test("a keepalive pong refreshes liveness", async () => {
+  const clock = fakeClock(1000);
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, clock, sweepIntervalMs: 0 });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+
+  clock.set(1000 + 20_000);
+  conn.pong();
+  clock.set(1000 + 40_000);
+  hub.sweepNow();
+
+  assert.equal(hub.connectionCount, 1);
+  await hub.close();
+});
+
+test("an inbound keepalive ping refreshes liveness", async () => {
+  const clock = fakeClock(1000);
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, clock, sweepIntervalMs: 0 });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+
+  clock.set(1000 + 20_000);
+  conn.ping();
+  clock.set(1000 + 40_000);
+  hub.sweepNow();
+
+  assert.equal(hub.connectionCount, 1);
+  await hub.close();
+});
+
+test("liveness sweep reads time from the registry, not a separate hub clock (no clock drift)", async () => {
+  // A pre-built registry stamps lastSeen with ITS clock; the hub must sweep
+  // against that same clock. If the hub kept a separate, faster clock it would
+  // spuriously age out a connection the registry still considers fresh — the
+  // registry is the single source of truth for liveness time.
+  const registryClock = fakeClock(1000);
+  const registry = new ConnectionRegistry({ clock: registryClock });
+  const hubClock = fakeClock(1000 + 100_000); // 100s ahead of the registry's clock
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, registry, clock: hubClock, sweepIntervalMs: 0 });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+
+  // Neither clock advances: the connection was just seen at registryClock=1000,
+  // well within the 30s TTL, so it must NOT be swept.
+  hub.sweepNow();
+
+  assert.equal(hub.connectionCount, 1);
+  assert.equal(conn.closed, null);
+  await hub.close();
+});
+test("a closed connection is removed from the registry", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, sweepIntervalMs: 0 });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+  assert.equal(hub.connectionCount, 1);
+
+  conn.close(1000, "bye");
+  assert.equal(hub.connectionCount, 0);
+  await hub.close();
+});
+
+test("a peer that disconnects while auth is in flight is never left tracked", async () => {
+  // The authenticator may be async (e.g. a network identity check). If the peer
+  // vanishes mid-auth, the close event must not be missed — otherwise the hub
+  // tracks a dead socket until a much later TTL sweep, inflating connectionCount.
+  const transport = new FakeTransport();
+  let release: ((r: AuthResult) => void) | undefined;
+  const pending = new Promise<AuthResult>((resolve) => {
+    release = resolve;
+  });
+  const hub = new AgenticHub({ transport, authenticator: () => pending, sweepIntervalMs: 0 });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn); // begins #accept, awaits the pending authenticator
+  await tick();
+
+  conn.close(1001, "gone"); // peer disconnects before auth resolves
+  release?.({ ok: true, grant: { identity: "peer-a" } });
+  await tick();
+
+  assert.equal(hub.connectionCount, 0);
+  await hub.close();
+});
+
+test("close() terminates tracked connections so shutdown is deterministic", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: goodAuth, sweepIntervalMs: 0 });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", credential: "cap-1", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+  assert.equal(hub.connectionCount, 1);
+
+  await hub.close();
+
+  assert.notEqual(conn.closed, null); // the socket was actively closed
+  assert.equal(hub.connectionCount, 0);
+});

package/src/channel/hub.ts

@@ -0,0 +1,222 @@
+/**
+ * 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.ts";
+import type { Frame } from "../protocol/index.ts";
+import type { Authenticator } from "./auth.ts";
+import type { Clock } from "./clock.ts";
+import type { ChannelConnection, ChannelTransport, CloseCode, HandshakeRequest } from "./connection.ts";
+import { FamilyRouter } from "./dispatch.ts";
+import type { FamilyHandler } from "./dispatch.ts";
+import { ConnectionRegistry } from "./registry.ts";
+
+/** Application close code used when a connection ages out on the liveness TTL. */
+export 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 class AgenticHub {
+  readonly router: FamilyRouter<HubConnection>;
+  readonly registry: ConnectionRegistry;
+  readonly #transport: ChannelTransport;
+  readonly #authenticator: Authenticator;
+  readonly #onError: (err: unknown, connectionId?: string) => void;
+  readonly #conns = new Map<string, ChannelConnection>();
+  #sweepTimer: ReturnType<typeof setInterval> | undefined;
+
+  constructor(options: AgenticHubOptions) {
+    this.#transport = options.transport;
+    this.#authenticator = options.authenticator;
+    this.router = options.router ?? new FamilyRouter<HubConnection>();
+    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: Parameters<FamilyRouter<HubConnection>["registerFamilyHandler"]>): void {
+    this.router.registerFamilyHandler(...args);
+  }
+
+  /** The bound address of the underlying transport once listening. */
+  get address(): { readonly port: number } | null {
+    return this.#transport.address;
+  }
+
+  /** The number of currently tracked connections. */
+  get connectionCount(): number {
+    return this.registry.size;
+  }
+
+  async #accept(conn: ChannelConnection): Promise<void> {
+    // 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: Awaited<ReturnType<Authenticator>>;
+    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: HubConnection = {
+      id: conn.id,
+      identity: auth.grant.identity,
+      handshake: conn.handshake,
+      registry: this.registry,
+      send: (frame: Frame) => conn.send(encodeFrame(frame)),
+      close: (code?: CloseCode, reason?: string) => 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: string, hubConn: HubConnection, bytes: Uint8Array): void {
+    // 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: 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: unknown) => 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(): void {
+    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(): Promise<void> {
+    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/src/channel/index.ts

@@ -0,0 +1,55 @@
+/**
+ * @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/src/channel/registry.test.ts

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { Clock } from "./clock.ts";
+import { ConnectionRegistry } from "./registry.ts";
+
+function fakeClock(start = 1000): Clock & { set(t: number): void } {
+  let t = start;
+  return { now: () => t, set: (v: number) => (t = v) };
+}
+
+test("tracks a connection with connectedAt/lastSeen and reports size", () => {
+  const clock = fakeClock(1000);
+  const registry = new ConnectionRegistry({ ttlMs: 100, clock });
+
+  const entry = registry.add("c1", "alice");
+  assert.equal(registry.size, 1);
+  assert.equal(entry.identity, "alice");
+  assert.equal(entry.connectedAt, 1000);
+  assert.equal(entry.lastSeen, 1000);
+  assert.deepEqual(entry.presence, {});
+  assert.ok(registry.has("c1"));
+});
+
+test("touch advances liveness to now", () => {
+  const clock = fakeClock(1000);
+  const registry = new ConnectionRegistry({ ttlMs: 100, clock });
+  registry.add("c1", "alice");
+
+  clock.set(1050);
+  registry.touch("c1");
+  assert.equal(registry.get("c1")?.lastSeen, 1050);
+});
+
+test("setPresence merges S2's presence detail onto a live connection", () => {
+  const registry = new ConnectionRegistry({ ttlMs: 100, clock: fakeClock() });
+  registry.add("c1", "alice");
+
+  registry.setPresence("c1", { instance: "w-1" });
+  registry.setPresence("c1", { capability: { cognition: "opus", family: "anthropic" } });
+
+  const entry = registry.get("c1");
+  assert.equal(entry?.presence.instance, "w-1");
+  assert.equal(entry?.presence.capability?.cognition, "opus");
+});
+
+test("sweep ages out only connections past the TTL and returns them", () => {
+  const clock = fakeClock(1000);
+  const registry = new ConnectionRegistry({ ttlMs: 100, clock });
+  registry.add("stale", "alice");
+  registry.add("fresh", "bob");
+
+  clock.set(1080);
+  registry.touch("fresh"); // keep 'fresh' alive
+
+  clock.set(1150); // stale.lastSeen=1000 (age 150 > 100); fresh.lastSeen=1080 (age 70)
+  const removed = registry.sweep();
+
+  assert.deepEqual(
+    removed.map((r) => r.id),
+    ["stale"],
+  );
+  assert.ok(!registry.has("stale"));
+  assert.ok(registry.has("fresh"));
+  assert.equal(registry.size, 1);
+});
+
+test("touch/setPresence/remove on an unknown id are safe no-ops", () => {
+  const registry = new ConnectionRegistry({ clock: fakeClock() });
+  registry.touch("nope");
+  registry.setPresence("nope", { instance: "x" });
+  assert.equal(registry.remove("nope"), undefined);
+  assert.equal(registry.size, 0);
+});