@nanobpm/agentic 0.1.0

package/src/demand/model.ts

@@ -0,0 +1,183 @@
+/**
+ * The demand×supply model — S4.
+ *
+ * Given the demand (the routing tokens deployed models ask for, as
+ * `taskDefinition` leaves) and the supply (the live S2 registry, resolved to the
+ * SERVE tokens each worker fills through the S3 vocab), this computes, per
+ * network:
+ *
+ *  - **demand** — the distinct routing tokens the deployed models declare,
+ *    bucketed by the token's network prefix;
+ *  - **supply** — how many registered workers currently serve each token;
+ *  - **missing agent type** — `demand ∖ supply`: a demanded token no registered
+ *    worker can fill (the enrolment gap the cockpit lights up red);
+ *  - **the SLO state** — the worst of the missing-agent signal (a missing token
+ *    is RED) and the S3 diversity SLO (`family(#red) ≠ family(#blue)`).
+ *
+ * This is a **read-only mirror + enrolment gate**. It reads what the engine has
+ * deployed and what the registry reports and reconciles the two; it does NOT
+ * match-make — it never places work on, or holds a seat for, a worker. Active
+ * placement is explicitly out of scope for v1.
+ *
+ * Supply resolution reuses the S3 {@link VocabResolver}: a worker *serves* a token
+ * iff that token is in `resolver.resolve(worker.capability).tokens` — capability
+ * is the enrolment attribute the vocab's `requires` gate reads, never part of the
+ * token itself (design invariant 3).
+ */
+import { parseToken } from "../protocol/index.ts";
+import type { DemandPayload } from "../protocol/index.ts";
+import { correlateRegistry, type DiversityReport, type RegisteredWorker, type VocabResolver } from "../vocab/index.ts";
+
+import { distinctTaskTypes, type TaskDefinitionLeaf } from "./taskdef.ts";
+
+/** The SLO grade — same three-level scale as the S3 diversity SLO. */
+export type SloStatus = "green" | "amber" | "red";
+
+const SEVERITY: Record<SloStatus, number> = { green: 0, amber: 1, red: 2 };
+
+function worst(a: SloStatus, b: SloStatus): SloStatus {
+  return SEVERITY[a] >= SEVERITY[b] ? a : b;
+}
+
+/** One demanded routing token and the live supply against it. */
+export interface TokenDemand {
+  /** The demanded routing token (a `taskDefinition` leaf's type). */
+  readonly token: string;
+  /** How many registered workers currently serve this token. */
+  readonly supply: number;
+  /** The instances serving it, sorted — provenance for the cockpit drill-in. */
+  readonly instances: readonly string[];
+  /** False when no registered worker serves it — a missing agent type. */
+  readonly satisfied: boolean;
+}
+
+/** The demand×supply picture for one network prefix. */
+export interface NetworkDemand {
+  /** The network prefix bucket (`network` segment, or a bare token's own name). */
+  readonly network: string;
+  /** Every demanded token in the bucket, sorted by token. */
+  readonly tokens: readonly TokenDemand[];
+  /** The demanded tokens in this bucket with zero supply, sorted. */
+  readonly missing: readonly string[];
+}
+
+/** The full demand×supply report. */
+export interface DemandSupplyReport {
+  /** Per-network demand×supply, sorted by network. */
+  readonly networks: readonly NetworkDemand[];
+  /** Every missing agent type across all networks, sorted and de-duplicated. */
+  readonly missing: readonly string[];
+  /** The S3 diversity SLO over the correlated live registry. */
+  readonly diversity: DiversityReport;
+  /** The overall SLO state: worst of the missing-agent signal and diversity. */
+  readonly status: SloStatus;
+  /**
+   * Deployed `taskDefinition` types that are NOT valid routing tokens — ordinary
+   * (non-agentic) C8 jobs the engine also runs. Surfaced (not silently dropped)
+   * so an operator can spot a mistyped agentic token, but excluded from the
+   * agentic demand×supply accounting.
+   */
+  readonly nonAgentic: readonly string[];
+}
+
+/** Input to {@link computeDemandSupply}. */
+export interface DemandSupplyInput {
+  /** Demand: the deployed `taskDefinition` leaves (order-insensitive). */
+  readonly taskDefinitions: readonly TaskDefinitionLeaf[];
+  /** Supply: the live S2 registry rows. */
+  readonly workers: readonly RegisteredWorker[];
+  /** The S3 resolver over the resolved vocabulary artifact. */
+  readonly resolver: VocabResolver;
+}
+
+/** A demanded token's network-prefix bucket, or `undefined` if not a routing token. */
+function bucketOf(token: string): string | undefined {
+  try {
+    const parsed = parseToken(token);
+    // A bare (network-less) token like `decide` buckets under its own role name.
+    return parsed.network ?? parsed.role;
+  } catch {
+    return undefined;
+  }
+}
+
+function sortedUnique(values: Iterable<string>): string[] {
+  return [...new Set(values)].sort();
+}
+
+/**
+ * Compute the demand×supply model from deployed demand and live supply.
+ *
+ * Pure and deterministic: the same demand + registry + vocab always yields the
+ * same report, with every list sorted, so it is safe to diff frame-to-frame and
+ * to render straight into the cockpit.
+ */
+export function computeDemandSupply(input: DemandSupplyInput): DemandSupplyReport {
+  const { workers, resolver } = input;
+
+  // Supply index: each worker's SERVE token set, resolved once.
+  const supplyByToken = new Map<string, string[]>();
+  for (const worker of workers) {
+    const tokens = resolver.resolve(worker.capability).tokens;
+    for (const token of tokens) {
+      const instances = supplyByToken.get(token);
+      if (instances === undefined) supplyByToken.set(token, [worker.instance]);
+      else instances.push(worker.instance);
+    }
+  }
+
+  const demandTokens = distinctTaskTypes(input.taskDefinitions);
+  const byNetwork = new Map<string, Map<string, TokenDemand>>();
+  const nonAgentic: string[] = [];
+
+  for (const token of demandTokens) {
+    const network = bucketOf(token);
+    if (network === undefined) {
+      nonAgentic.push(token);
+      continue;
+    }
+    const instances = sortedUnique(supplyByToken.get(token) ?? []);
+    const demand: TokenDemand = {
+      token,
+      supply: instances.length,
+      instances,
+      satisfied: instances.length > 0,
+    };
+    const bucket = byNetwork.get(network) ?? new Map<string, TokenDemand>();
+    // A token can only appear once (distinctTaskTypes), so no merge is needed.
+    bucket.set(token, demand);
+    byNetwork.set(network, bucket);
+  }
+
+  const networks: NetworkDemand[] = [...byNetwork.entries()]
+    .map(([network, tokenMap]) => {
+      const tokens = [...tokenMap.values()].sort((a, b) => (a.token < b.token ? -1 : a.token > b.token ? 1 : 0));
+      const missing = tokens.filter((token) => !token.satisfied).map((token) => token.token);
+      return { network, tokens, missing };
+    })
+    .sort((a, b) => (a.network < b.network ? -1 : a.network > b.network ? 1 : 0));
+
+  const missing = sortedUnique(networks.flatMap((network) => network.missing));
+  const diversity = correlateRegistry(resolver, workers);
+  const missingStatus: SloStatus = missing.length > 0 ? "red" : "green";
+  const status = worst(missingStatus, diversity.status);
+
+  return {
+    networks,
+    missing,
+    diversity,
+    status,
+    nonAgentic: [...nonAgentic].sort(),
+  };
+}
+
+/**
+ * Project the report onto the S0 `demand` message family — one {@link DemandPayload}
+ * per network carrying its missing agent types, so the gap can cross the agentic
+ * channel's control/facts lane. Emits an entry for every network (missing may be
+ * empty), sorted by network, so a consumer sees a cleared network flip from a
+ * non-empty `missing` back to `[]`.
+ */
+export function toDemandPayloads(report: DemandSupplyReport): DemandPayload[] {
+  return report.networks.map((network) => ({ network: network.network, missing: network.missing }));
+}

package/src/demand/taskdef.test.ts

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { distinctTaskTypes, scanTaskDefinitions } from "./taskdef.ts";
+
+const MODEL = `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+                  xmlns:zeebe="http://camunda.org/schema/zeebe/1.0">
+  <bpmn:process id="plan-fanout" isExecutable="true">
+    <bpmn:serviceTask id="plan" name="Plan">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="planning.planner" retries="3" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="test" name="Test">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="qa.tester" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:userTask id="approve" name="Approve" />
+    <bpmn:serviceTask id="notype" name="No type">
+      <bpmn:extensionElements />
+    </bpmn:serviceTask>
+  </bpmn:process>
+</bpmn:definitions>`;
+
+test("scans taskDefinition leaves with process and element provenance", () => {
+  const leaves = scanTaskDefinitions(MODEL);
+  assert.deepEqual(leaves, [
+    { taskType: "planning.planner", process: "plan-fanout", elementId: "plan" },
+    { taskType: "qa.tester", process: "plan-fanout", elementId: "test" },
+  ]);
+});
+
+test("skips service tasks without a task definition", () => {
+  const leaves = scanTaskDefinitions(MODEL);
+  assert.ok(!leaves.some((l) => l.elementId === "notype"));
+  assert.ok(!leaves.some((l) => l.elementId === "approve"));
+});
+
+test("tolerates attribute ordering (type before id on the task-definition)", () => {
+  const xml = `<bpmn:definitions xmlns:bpmn="x" xmlns:zeebe="y">
+    <bpmn:process id="proc">
+      <bpmn:serviceTask id="t">
+        <zeebe:taskDefinition retries="1" type="ci.runner" />
+      </bpmn:serviceTask>
+    </bpmn:process>
+  </bpmn:definitions>`;
+  const leaves = scanTaskDefinitions(xml);
+  assert.equal(leaves.length, 1);
+  assert.equal(leaves[0].taskType, "ci.runner");
+});
+
+test("returns an empty process id when none is present", () => {
+  const xml = `<bpmn:definitions xmlns:bpmn="x" xmlns:zeebe="y">
+    <bpmn:serviceTask id="t"><zeebe:taskDefinition type="decide" /></bpmn:serviceTask>
+  </bpmn:definitions>`;
+  const leaves = scanTaskDefinitions(xml);
+  assert.equal(leaves[0].process, "");
+});
+
+test("tolerates whitespace around attribute equals signs (id / type / process id)", () => {
+  const xml = `<bpmn:definitions xmlns:bpmn="x" xmlns:zeebe="y">
+    <bpmn:process id = "spaced-proc">
+      <bpmn:serviceTask id = "t">
+        <zeebe:taskDefinition type = "ci.runner" retries="1" />
+      </bpmn:serviceTask>
+    </bpmn:process>
+  </bpmn:definitions>`;
+  const leaves = scanTaskDefinitions(xml);
+  assert.deepEqual(leaves, [
+    { taskType: "ci.runner", process: "spaced-proc", elementId: "t" },
+  ]);
+});
+
+test("distinctTaskTypes de-duplicates in first-occurrence order", () => {
+  assert.deepEqual(
+    distinctTaskTypes([
+      { taskType: "b", process: "p", elementId: "1" },
+      { taskType: "a", process: "p", elementId: "2" },
+      { taskType: "b", process: "p", elementId: "3" },
+    ]),
+    ["b", "a"],
+  );
+});

package/src/demand/taskdef.ts

@@ -0,0 +1,78 @@
+/**
+ * Parse `taskDefinition` leaves out of a deployed BPMN model.
+ *
+ * The demand side of the demand×supply model (S4) is the set of routing tokens
+ * the deployed processes ask for. In a Nano/Camunda-8 model each demand is a
+ * service task's `<zeebe:taskDefinition type="…">` — the job type the engine
+ * matches 1:1 against a worker's routing token. This scanner reads those leaves
+ * out of the raw BPMN XML so the model can bucket them by network prefix and
+ * diff them against live supply.
+ *
+ * It is deliberately a small, dependency-free regex scan over the same surface
+ * the Urban toolkit's worker-io deriver reads, so it stays app-tier and never
+ * touches the engine internals — the XML arrives from the C8 REST API
+ * ({@link ./c8-rest.ts}).
+ */
+
+/** One deployed `taskDefinition` leaf: a job type demanded by a model element. */
+export interface TaskDefinitionLeaf {
+  /** The `zeebe:taskDefinition` `type` — the routing token the engine matches. */
+  readonly taskType: string;
+  /** The `bpmn:process` id the leaf was declared in (best-effort, may be empty). */
+  readonly process: string;
+  /** The service-task element id carrying the leaf (best-effort, may be empty). */
+  readonly elementId: string;
+}
+
+function attr(tag: string, name: string): string {
+  const match = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+  return match ? match[1] : "";
+}
+
+function processId(xml: string): string {
+  const match = xml.match(/<bpmn:process\b[^>]*\bid\s*=\s*"([^"]*)"/);
+  return match ? match[1] : "";
+}
+
+/**
+ * Scan one BPMN document for its service-task `taskDefinition` leaves.
+ *
+ * Every `<bpmn:serviceTask>` carrying a `<zeebe:taskDefinition type="…">` with a
+ * non-empty type yields a leaf; tasks without a task definition (or with an empty
+ * type) are skipped. The scan is order-preserving and tolerant of attribute
+ * ordering and self-closing task-definition tags.
+ */
+export function scanTaskDefinitions(xml: string): TaskDefinitionLeaf[] {
+  const proc = processId(xml);
+  const out: TaskDefinitionLeaf[] = [];
+  const blockRe = /<bpmn:serviceTask\b([^>]*)>([\s\S]*?)<\/bpmn:serviceTask>/g;
+  let block: RegExpExecArray | null;
+  while ((block = blockRe.exec(xml)) !== null) {
+    const openAttrs = block[1];
+    const body = block[2];
+    const elementId = attr(`<x ${openAttrs}>`, "id");
+    const tdMatch = body.match(/<zeebe:taskDefinition\b[^>]*>/);
+    if (!tdMatch) continue;
+    const taskType = attr(tdMatch[0], "type");
+    if (!taskType) continue;
+    out.push({ taskType, elementId, process: proc });
+  }
+  return out;
+}
+
+/**
+ * Scan many BPMN documents and return the distinct demanded job types, in first
+ * occurrence order. The demand×supply model only needs the distinct set of
+ * routing tokens; {@link scanTaskDefinitions} keeps the full leaves for callers
+ * that want element provenance.
+ */
+export function distinctTaskTypes(leaves: readonly TaskDefinitionLeaf[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const leaf of leaves) {
+    if (seen.has(leaf.taskType)) continue;
+    seen.add(leaf.taskType);
+    out.push(leaf.taskType);
+  }
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @nanobpm/agentic — the Nano agentic protocol (ADR 0056).
+ *
+ * One app-tier channel carrying agent presence/registry, demand×supply, a shared
+ * blackboard and a live terminal relay. This barrel re-exports every family as a
+ * namespace; most consumers import the specific subpath they need instead, e.g.
+ * `@nanobpm/agentic/channel`, `@nanobpm/agentic/relay`, `@nanobpm/agentic/cockpit`.
+ */
+export * as protocol from "./protocol/index.ts";
+export * as channel from "./channel/index.ts";
+export * as presence from "./presence/index.ts";
+export * as vocab from "./vocab/index.ts";
+export * as demand from "./demand/index.ts";
+export * as relay from "./relay/index.ts";
+export * as transcript from "./transcript/index.ts";
+export * as blackboard from "./blackboard/index.ts";
+export * as cockpit from "./cockpit/index.ts";

package/src/presence/family.test.ts

@@ -0,0 +1,252 @@
+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, MessageFamily } from "../protocol/index.ts";
+import {
+  AgenticHub,
+  DuplicateFamilyHandlerError,
+  sharedSecretAuthenticator,
+} from "../channel/index.ts";
+import type {
+  ChannelConnection,
+  ChannelTransport,
+  Clock,
+  CloseCode,
+  HandshakeRequest,
+} from "../channel/index.ts";
+import { attachPresenceFamily, PresencePayloadError } from "./family.ts";
+import { PresenceStore } from "./store.ts";
+import { openTestDb } from "./test-db.ts";
+
+/** In-memory connection the test drives directly — public-API fakes only. */
+class FakeConnection implements ChannelConnection {
+  readonly id: string;
+  readonly handshake: HandshakeRequest;
+  closed: { code?: CloseCode; reason?: string } | null = null;
+  #onMessage: ((bytes: Uint8Array) => void) | undefined;
+  #onClose: ((code?: CloseCode, reason?: string) => void) | undefined;
+
+  constructor(id: string, handshake: HandshakeRequest) {
+    this.id = id;
+    this.handshake = handshake;
+  }
+  send(): void {}
+  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;
+  }
+  receive(bytes: Uint8Array): void {
+    this.#onMessage?.(bytes);
+  }
+}
+
+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 frame(family: MessageFamily, payload: unknown, seq = 1): Uint8Array {
+  const f: Frame = { lane: "control", family, seq, payload };
+  return encodeFrame(f);
+}
+
+const auth = sharedSecretAuthenticator({ secret: "s3cret" });
+
+function connect(transport: FakeTransport, id: string, remote: string): FakeConnection {
+  const conn = new FakeConnection(id, { token: "s3cret", credential: "cap-1", remote });
+  transport.accept(conn);
+  return conn;
+}
+
+test("a registering worker appears in the registry with presence + host/family via the S1 seam", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  const store = new PresenceStore(openTestDb(), { clock: fakeClock(5000) });
+  attachPresenceFamily(hub, store, { sweepIntervalMs: 0 });
+
+  const conn = connect(transport, "c1", "peer-a");
+  await tick();
+  conn.receive(frame("register", { instance: "w-1", capability: { family: "anthropic", host: "mac-1" } }));
+  await tick();
+
+  const row = store.get("w-1");
+  assert.equal(row?.connectionId, "c1");
+  assert.equal(row?.identity, "peer-a");
+  assert.deepEqual(row?.capability, { family: "anthropic", host: "mac-1" });
+  // The enrolment is mirrored onto S1's in-memory connection registry too.
+  assert.deepEqual(hub.registry.get("c1")?.presence, { instance: "w-1", capability: { family: "anthropic", host: "mac-1" } });
+
+  await hub.close();
+});
+
+test("attaches three distinct families through the seam and routes each to the store", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  const clock = fakeClock(1000);
+  const store = new PresenceStore(openTestDb(), { clock });
+  attachPresenceFamily(hub, store, { sweepIntervalMs: 0 });
+
+  assert.deepEqual(hub.router.families().sort(), ["deregister", "heartbeat", "register"]);
+
+  const conn = connect(transport, "c1", "peer-a");
+  await tick();
+
+  conn.receive(frame("register", { instance: "w-1", capability: { cognition: "opus" } }));
+  await tick();
+  assert.equal(store.get("w-1")?.lastSeen, 1000);
+
+  clock.set(2500);
+  conn.receive(frame("heartbeat", { instance: "w-1" }, 2));
+  await tick();
+  assert.equal(store.get("w-1")?.lastSeen, 2500, "heartbeat refreshed liveness");
+
+  conn.receive(frame("deregister", { instance: "w-1" }, 3));
+  await tick();
+  assert.equal(store.get("w-1"), undefined, "deregister removed the row");
+
+  await hub.close();
+});
+
+test("a foreign peer cannot hijack, heartbeat, or deregister another peer's instance", async () => {
+  const transport = new FakeTransport();
+  const errors: unknown[] = [];
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  const clock = fakeClock(1000);
+  const store = new PresenceStore(openTestDb(), { clock });
+  attachPresenceFamily(hub, store, { sweepIntervalMs: 0, onError: (e) => errors.push(e) });
+
+  const owner = connect(transport, "c1", "peer-a");
+  const attacker = connect(transport, "c2", "peer-b");
+  await tick();
+
+  owner.receive(frame("register", { instance: "w-1", capability: { host: "owned" } }));
+  await tick();
+  assert.equal(store.get("w-1")?.identity, "peer-a");
+
+  // Attacker (a different authenticated identity) tries to take over the instance.
+  clock.set(2000);
+  attacker.receive(frame("register", { instance: "w-1", capability: { host: "evil" } }, 2));
+  await tick();
+  let row = store.get("w-1");
+  assert.equal(row?.identity, "peer-a", "register takeover blocked — owner keeps the row");
+  assert.equal(row?.connectionId, "c1");
+  assert.deepEqual(row?.capability, { host: "owned" });
+  assert.equal(row?.lastSeen, 1000, "blocked register does not refresh liveness");
+  assert.equal(errors.length, 1, "the blocked takeover is surfaced via onError");
+
+  // Attacker cannot keep the instance alive on the owner's behalf.
+  clock.set(5000);
+  attacker.receive(frame("heartbeat", { instance: "w-1" }, 3));
+  await tick();
+  assert.equal(store.get("w-1")?.lastSeen, 1000, "foreign heartbeat is a no-op");
+
+  // Attacker cannot deregister the owner's instance.
+  attacker.receive(frame("deregister", { instance: "w-1" }, 4));
+  await tick();
+  assert.notEqual(store.get("w-1"), undefined, "foreign deregister is a no-op");
+
+  // The genuine owner still controls its own instance.
+  owner.receive(frame("heartbeat", { instance: "w-1" }, 2));
+  await tick();
+  assert.equal(store.get("w-1")?.lastSeen, 5000, "owner heartbeat refreshes liveness");
+  owner.receive(frame("deregister", { instance: "w-1" }, 3));
+  await tick();
+  assert.equal(store.get("w-1"), undefined, "owner deregisters its own instance");
+
+  await hub.close();
+});
+
+test("a malformed register frame is rejected and never touches the store", async () => {
+  const transport = new FakeTransport();
+  const errors: unknown[] = [];
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  const store = new PresenceStore(openTestDb());
+  attachPresenceFamily(hub, store, { sweepIntervalMs: 0, onError: (e) => errors.push(e) });
+
+  const conn = connect(transport, "c1", "peer-a");
+  await tick();
+  // Missing the required `instance` field.
+  conn.receive(frame("register", { capability: { host: "h" } }));
+  await tick();
+
+  assert.equal(store.count(), 0);
+  assert.equal(errors.length, 1);
+
+  await hub.close();
+});
+
+test("a non-object register payload is rejected with a payload error and never touches the store", async () => {
+  const transport = new FakeTransport();
+  const errors: unknown[] = [];
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  const store = new PresenceStore(openTestDb());
+  attachPresenceFamily(hub, store, { sweepIntervalMs: 0, onError: (e) => errors.push(e) });
+
+  const conn = connect(transport, "c1", "peer-a");
+  await tick();
+  // A non-object payload (array) — validatePayload rejects it before it can
+  // narrow to a record, so the store is never reached.
+  conn.receive(frame("register", ["not", "an", "object"]));
+  await tick();
+
+  assert.equal(store.count(), 0);
+  assert.equal(errors.length, 1);
+  const err = errors[0];
+  assert(err instanceof PresencePayloadError);
+  assert.match(err.message, /must be an object/);
+
+  await hub.close();
+});
+
+test("presence ages out on the TTL via the family sweep", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  const clock = fakeClock(1000);
+  const store = new PresenceStore(openTestDb(), { ttlMs: 100, clock });
+  const presence = attachPresenceFamily(hub, store, { sweepIntervalMs: 0 });
+
+  const conn = connect(transport, "c1", "peer-a");
+  await tick();
+  conn.receive(frame("register", { instance: "w-1", capability: {} }));
+  await tick();
+  assert.equal(store.count(), 1);
+
+  clock.set(1200); // age 200 > ttl 100
+  const removed = presence.sweepNow();
+  assert.deepEqual(removed.map((r) => r.instance), ["w-1"]);
+  assert.equal(store.count(), 0);
+
+  presence.stop();
+  await hub.close();
+});
+
+test("attaching a second presence module to the same hub is rejected", () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  attachPresenceFamily(hub, new PresenceStore(openTestDb()), { sweepIntervalMs: 0 });
+  assert.throws(
+    () => attachPresenceFamily(hub, new PresenceStore(openTestDb()), { sweepIntervalMs: 0 }),
+    DuplicateFamilyHandlerError,
+  );
+});