@nanobpm/agentic 0.1.0

package/src/presence/family.ts

@@ -0,0 +1,205 @@
+/**
+ * The presence family module — S2's self-contained attachment to the S1 hub.
+ *
+ * This module owns the `register`, `heartbeat` and `deregister` message
+ * families. It attaches through the hub's canonical
+ * {@link AgenticHub.registerFamilyHandler} seam — it does NOT touch a shared
+ * frame→family dispatch switch — so it composes with the other wave-2 family
+ * modules (S5 relay, S7 blackboard) with no shared edit.
+ *
+ * On `register` it writes a durable presence row (via {@link PresenceStore}) and
+ * mirrors instance+capability onto S1's in-memory connection registry
+ * (`ctx.registry.setPresence`). `heartbeat` refreshes the row's liveness;
+ * `deregister` removes it. Rows the fleet stops heartbeating age out on the
+ * presence TTL via the sweep this module schedules.
+ */
+import { validatePayload } from "../protocol/index.ts";
+import type { Capability, Frame } from "../protocol/index.ts";
+import type { AgenticHub, HubConnection } from "../channel/index.ts";
+import type { PresenceRow, PresenceStore } from "./store.ts";
+import { PresenceOwnershipError } from "./store.ts";
+
+export interface PresenceFamilyOptions {
+  /**
+   * How often to age out stale presence rows, in ms. Default: a third of the
+   * store's TTL. Pass 0 to disable the internal timer (tests call
+   * {@link PresenceFamilyHandle.sweepNow} explicitly). The sweep reads "now"
+   * from the store's own clock, so liveness time has a single source of truth.
+   */
+  sweepIntervalMs?: number;
+  /**
+   * Notified of a fault this module handles while keeping the connection: a
+   * malformed presence payload ({@link PresencePayloadError}), a rejected
+   * ownership takeover ({@link PresenceOwnershipError}), or a presence-sweep
+   * error. Other handler exceptions are not routed here — they propagate to
+   * {@link AgenticHub} and surface via the hub's own error handling.
+   */
+  onError?: (err: unknown, connectionId?: string) => void;
+}
+
+/** Handle to the attached presence family — drives/stops the presence sweep. */
+export interface PresenceFamilyHandle {
+  /** Age out stale presence rows now and return the removed rows. */
+  sweepNow(): PresenceRow[];
+  /** Stop the presence sweep timer. */
+  stop(): void;
+}
+
+/** A malformed presence payload rejected before it touches the store. */
+export class PresencePayloadError extends Error {
+  readonly family: string;
+  constructor(family: string, detail: string) {
+    super(`invalid ${family} payload: ${detail}`);
+    this.name = "PresencePayloadError";
+    this.family = family;
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readString(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function readNumber(record: Record<string, unknown>, key: string): number | undefined {
+  const value = record[key];
+  return typeof value === "number" ? value : undefined;
+}
+
+/** Extract the enrolment capability from a validated `register` payload. */
+function readCapability(record: Record<string, unknown>): Capability {
+  const raw = record.capability;
+  if (!isPlainObject(raw)) return {};
+  const cap: { cognition?: string; weight?: number; family?: string; host?: string } = {};
+  const cognition = readString(raw, "cognition");
+  if (cognition !== undefined) cap.cognition = cognition;
+  const weight = readNumber(raw, "weight");
+  if (weight !== undefined) cap.weight = weight;
+  const family = readString(raw, "family");
+  if (family !== undefined) cap.family = family;
+  const host = readString(raw, "host");
+  if (host !== undefined) cap.host = host;
+  return cap;
+}
+
+/**
+ * Attach the presence family (`register`/`heartbeat`/`deregister`) to `hub`,
+ * backed by `store`. Registers three handlers via the S1 seam and schedules the
+ * presence-TTL sweep. Returns a handle to drive/stop the sweep.
+ *
+ * @throws DuplicateFamilyHandlerError if one of the three families already has
+ *   a handler on this hub (one family, one owning module).
+ */
+export function attachPresenceFamily(
+  hub: AgenticHub,
+  store: PresenceStore,
+  options: PresenceFamilyOptions = {},
+): PresenceFamilyHandle {
+  store.ensureSchema();
+  const onError = options.onError ?? (() => {});
+
+  const reject = (family: string, connectionId: string, detail: string): void => {
+    onError(new PresencePayloadError(family, detail), connectionId);
+  };
+
+  hub.registerFamilyHandler("register", (frame: Frame, ctx: HubConnection) => {
+    const payload = frame.payload;
+    const result = validatePayload("register", payload);
+    if (!result.ok) {
+      reject("register", ctx.id, result.errors.map((e) => e.message).join("; "));
+      return;
+    }
+    if (!isPlainObject(payload)) {
+      reject("register", ctx.id, "not an object");
+      return;
+    }
+    const instance = readString(payload, "instance");
+    if (instance === undefined) {
+      reject("register", ctx.id, "missing instance");
+      return;
+    }
+    const capability = readCapability(payload);
+    try {
+      store.register({ instance, connectionId: ctx.id, identity: ctx.identity, capability });
+    } catch (err) {
+      // An instance owned by another identity must not be hijacked: surface the
+      // rejection and leave S1's in-memory registry untouched.
+      if (err instanceof PresenceOwnershipError) {
+        onError(err, ctx.id);
+        return;
+      }
+      throw err;
+    }
+    // Mirror the enrolment onto S1's in-memory connection registry so a live
+    // connection carries its instance+capability without a DB read.
+    ctx.registry.setPresence(ctx.id, { instance, capability });
+  });
+
+  hub.registerFamilyHandler("heartbeat", (frame: Frame, ctx: HubConnection) => {
+    const payload = frame.payload;
+    const result = validatePayload("heartbeat", payload);
+    if (!result.ok) {
+      reject("heartbeat", ctx.id, result.errors.map((e) => e.message).join("; "));
+      return;
+    }
+    if (!isPlainObject(payload)) {
+      reject("heartbeat", ctx.id, "not an object");
+      return;
+    }
+    const instance = readString(payload, "instance");
+    if (instance === undefined) {
+      reject("heartbeat", ctx.id, "missing instance");
+      return;
+    }
+    store.heartbeat(instance, ctx.identity);
+  });
+
+  hub.registerFamilyHandler("deregister", (frame: Frame, ctx: HubConnection) => {
+    const payload = frame.payload;
+    const result = validatePayload("deregister", payload);
+    if (!result.ok) {
+      reject("deregister", ctx.id, result.errors.map((e) => e.message).join("; "));
+      return;
+    }
+    if (!isPlainObject(payload)) {
+      reject("deregister", ctx.id, "not an object");
+      return;
+    }
+    const instance = readString(payload, "instance");
+    if (instance === undefined) {
+      reject("deregister", ctx.id, "missing instance");
+      return;
+    }
+    store.deregister(instance, ctx.identity);
+  });
+
+  const sweepNow = (): PresenceRow[] => {
+    try {
+      return store.sweep();
+    } catch (err) {
+      onError(err);
+      return [];
+    }
+  };
+
+  const interval = options.sweepIntervalMs ?? Math.max(1, Math.floor(store.ttlMs / 3));
+  let timer: ReturnType<typeof setInterval> | undefined;
+  if (interval > 0) {
+    timer = setInterval(sweepNow, interval);
+    // Do not keep the process alive solely for the presence sweep.
+    timer.unref?.();
+  }
+
+  return {
+    sweepNow,
+    stop() {
+      if (timer !== undefined) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+    },
+  };
+}

package/src/presence/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @nanobpm/agentic-presence — the presence & registry family for the Nano
+ * agentic protocol (ADR 0056, slice S2).
+ *
+ * Owns the `register` / `heartbeat` / `deregister` message families: a durable
+ * presence registry over the app DataLayer/SQLite ({@link PresenceStore}) plus
+ * a self-contained family module ({@link attachPresenceFamily}) that attaches to
+ * the S1 hub through its `registerFamilyHandler(family, handler)` seam — never a
+ * shared dispatch switch. S1 owns connection liveness; this slice layers durable
+ * presence rows with their own heartbeat-refreshed TTL on top.
+ *
+ * The wire contract lives in `@nanobpm/agentic-protocol`; the hub in
+ * `@nanobpm/agentic-channel`. This package builds on both.
+ */
+export { PresenceOwnershipError, PresenceStore } from "./store.ts";
+export type {
+  PresenceRow,
+  PresenceStoreOptions,
+  RegisterInput,
+  SqliteDb,
+} from "./store.ts";
+
+export { attachPresenceFamily, PresencePayloadError } from "./family.ts";
+export type { PresenceFamilyOptions, PresenceFamilyHandle } from "./family.ts";
+
+export { PRESENCE_TABLE, PRESENCE_SCHEMA_SQL } from "./schema.ts";

package/src/presence/schema.test.ts

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { PRESENCE_SCHEMA_SQL, PRESENCE_TABLE } from "./schema.ts";
+import { PresenceStore } from "./store.ts";
+import { openTestDb } from "./test-db.ts";
+
+/**
+ * Normalise SQL for a drift comparison: drop `-- …` line comments, collapse all
+ * runs of whitespace to a single space, and trim. Two DDL scripts that create
+ * the same objects with the same columns normalise identically regardless of
+ * comments/indentation.
+ */
+function normaliseSql(sql: string): string {
+  return sql
+    .split("\n")
+    .map((line) => line.replace(/--.*$/, ""))
+    .join("\n")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const migrationPath = fileURLToPath(new URL("../../../../db/migrations/001_agentic_presence.sql", import.meta.url));
+
+test("the boot migration and PresenceStore's DDL do not drift", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.equal(
+    normaliseSql(migrationSql),
+    normaliseSql(PRESENCE_SCHEMA_SQL),
+    "db/migrations/001_agentic_presence.sql must match PRESENCE_SCHEMA_SQL — update both together",
+  );
+});
+
+test("the boot migration is forward-only and additive (IF NOT EXISTS, no drops)", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS agentic_presence/);
+  assert.doesNotMatch(migrationSql, /\bDROP\b/i);
+  assert.doesNotMatch(migrationSql, /\bALTER\b/i);
+});
+
+test("ensureSchema creates the presence table idempotently", () => {
+  const db = openTestDb();
+  const store = new PresenceStore(db);
+  store.ensureSchema();
+  store.ensureSchema();
+  const tables = db.all<{ name: string }>(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name = ?",
+    [PRESENCE_TABLE],
+  );
+  assert.equal(tables.length, 1);
+  db.close();
+});

package/src/presence/schema.ts

@@ -0,0 +1,34 @@
+/**
+ * The canonical presence-registry schema.
+ *
+ * The DDL here is the single source of truth the {@link PresenceStore} applies
+ * through {@link PresenceStore.ensureSchema}. The very same statements are
+ * mirrored in the app-boot migration `db/migrations/001_agentic_presence.sql`
+ * (applied by the DataLayer migration runner). To keep those two application
+ * paths from drifting, `schema.test.ts` normalises both and asserts they are
+ * statement-for-statement identical — divergence is a red test, not a silent
+ * production/boot mismatch.
+ */
+
+/** The presence & registry table name. */
+export const PRESENCE_TABLE = "agentic_presence";
+
+/**
+ * The canonical presence-registry DDL. Forward-only and additive; every column
+ * added here must also be added to the boot migration (the drift guard enforces
+ * it). Capability (cognition/weight/family/host) is stored as an ENROLMENT
+ * attribute — never a routing token.
+ */
+export const PRESENCE_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${PRESENCE_TABLE} (
+  instance      TEXT PRIMARY KEY,
+  connection_id TEXT NOT NULL,
+  identity      TEXT NOT NULL,
+  cognition     TEXT,
+  weight        REAL,
+  family        TEXT,
+  host          TEXT,
+  registered_at TEXT NOT NULL,
+  last_seen     INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_${PRESENCE_TABLE}_last_seen ON ${PRESENCE_TABLE} (last_seen);
+CREATE INDEX IF NOT EXISTS idx_${PRESENCE_TABLE}_connection ON ${PRESENCE_TABLE} (connection_id);`;

package/src/presence/store.test.ts

@@ -0,0 +1,190 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { Clock } from "../channel/index.ts";
+import { PresenceOwnershipError, PresenceStore } from "./store.ts";
+import { openTestDb } from "./test-db.ts";
+
+function fakeClock(start = 1000): Clock & { set(t: number): void } {
+  let t = start;
+  return { now: () => t, set: (v: number) => (t = v) };
+}
+
+function freshStore(opts: { ttlMs?: number; clock?: Clock } = {}): PresenceStore {
+  const db = openTestDb();
+  const store = new PresenceStore(db, opts);
+  store.ensureSchema();
+  return store;
+}
+
+test("register makes an instance appear with presence + host/family", () => {
+  const clock = fakeClock(5000);
+  const store = freshStore({ clock });
+
+  const row = store.register({
+    instance: "w-1",
+    connectionId: "c1",
+    identity: "peer-a",
+    capability: { cognition: "opus", weight: 4, family: "anthropic", host: "mac-1" },
+  });
+
+  assert.equal(row.instance, "w-1");
+  assert.equal(row.connectionId, "c1");
+  assert.equal(row.identity, "peer-a");
+  assert.deepEqual(row.capability, { cognition: "opus", weight: 4, family: "anthropic", host: "mac-1" });
+  assert.equal(row.registeredAt, new Date(5000).toISOString());
+  assert.equal(row.lastSeen, 5000);
+
+  assert.deepEqual(store.get("w-1"), row);
+  assert.equal(store.count(), 1);
+  assert.deepEqual(store.list().map((r) => r.instance), ["w-1"]);
+});
+
+test("a partial capability stores only the declared attributes", () => {
+  const store = freshStore();
+  const row = store.register({
+    instance: "w-2",
+    connectionId: "c2",
+    identity: "peer-b",
+    capability: { family: "openai" },
+  });
+  assert.deepEqual(row.capability, { family: "openai" });
+});
+
+test("re-register keeps registered_at but refreshes connection, capability and liveness", () => {
+  const clock = fakeClock(1000);
+  const store = freshStore({ clock });
+  store.register({ instance: "w-1", connectionId: "c1", identity: "peer-a", capability: { host: "h1" } });
+
+  clock.set(2000);
+  const again = store.register({
+    instance: "w-1",
+    connectionId: "c2",
+    identity: "peer-a",
+    capability: { host: "h2" },
+  });
+
+  assert.equal(again.registeredAt, new Date(1000).toISOString(), "registered_at is preserved");
+  assert.equal(again.connectionId, "c2");
+  assert.deepEqual(again.capability, { host: "h2" });
+  assert.equal(again.lastSeen, 2000);
+  assert.equal(store.count(), 1);
+});
+
+test("heartbeat refreshes liveness for a known instance and no-ops otherwise", () => {
+  const clock = fakeClock(1000);
+  const store = freshStore({ clock });
+  store.register({ instance: "w-1", connectionId: "c1", identity: "peer-a", capability: {} });
+
+  clock.set(9000);
+  assert.equal(store.heartbeat("w-1"), true);
+  assert.equal(store.get("w-1")?.lastSeen, 9000);
+
+  assert.equal(store.heartbeat("nope"), false);
+});
+
+test("deregister removes an instance", () => {
+  const store = freshStore();
+  store.register({ instance: "w-1", connectionId: "c1", identity: "peer-a", capability: {} });
+  assert.equal(store.deregister("w-1"), true);
+  assert.equal(store.get("w-1"), undefined);
+  assert.equal(store.deregister("w-1"), false);
+});
+
+test("re-register with identical values from the same identity is not a false ownership violation", () => {
+  const clock = fakeClock(1000);
+  const store = freshStore({ clock });
+  const input = {
+    instance: "w-1",
+    connectionId: "c1",
+    identity: "peer-a",
+    capability: { cognition: "opus", weight: 4, family: "anthropic", host: "h1" },
+  };
+  store.register(input);
+
+  // A byte-for-byte identical re-register (a no-op UPDATE) must still succeed:
+  // ownership is decided on the stored identity, not the driver's changed-row
+  // count, so a no-op UPSERT can never masquerade as a takeover.
+  assert.doesNotThrow(() => store.register(input));
+  const row = store.register(input);
+  assert.equal(row.identity, "peer-a");
+  assert.equal(store.count(), 1);
+});
+
+test("register refuses to hijack an instance owned by a different identity", () => {
+  const clock = fakeClock(1000);
+  const store = freshStore({ clock });
+  store.register({ instance: "w-1", connectionId: "c1", identity: "peer-a", capability: { host: "h1" } });
+
+  clock.set(2000);
+  assert.throws(
+    () =>
+      store.register({
+        instance: "w-1",
+        connectionId: "c2",
+        identity: "peer-b",
+        capability: { host: "evil" },
+      }),
+    PresenceOwnershipError,
+  );
+
+  // The original owner's row is untouched — no connection/identity/capability takeover.
+  const row = store.get("w-1");
+  assert.equal(row?.identity, "peer-a");
+  assert.equal(row?.connectionId, "c1");
+  assert.deepEqual(row?.capability, { host: "h1" });
+  assert.equal(row?.lastSeen, 1000, "a blocked re-register does not refresh liveness");
+});
+
+test("heartbeat scoped to an identity no-ops for a foreign identity", () => {
+  const clock = fakeClock(1000);
+  const store = freshStore({ clock });
+  store.register({ instance: "w-1", connectionId: "c1", identity: "peer-a", capability: {} });
+
+  clock.set(9000);
+  assert.equal(store.heartbeat("w-1", "peer-b"), false, "a foreign identity cannot refresh liveness");
+  assert.equal(store.get("w-1")?.lastSeen, 1000, "liveness unchanged by a foreign heartbeat");
+
+  assert.equal(store.heartbeat("w-1", "peer-a"), true, "the owning identity refreshes liveness");
+  assert.equal(store.get("w-1")?.lastSeen, 9000);
+});
+
+test("deregister scoped to an identity no-ops for a foreign identity", () => {
+  const store = freshStore();
+  store.register({ instance: "w-1", connectionId: "c1", identity: "peer-a", capability: {} });
+
+  assert.equal(store.deregister("w-1", "peer-b"), false, "a foreign identity cannot deregister");
+  assert.notEqual(store.get("w-1"), undefined, "row survives a foreign deregister");
+
+  assert.equal(store.deregister("w-1", "peer-a"), true, "the owning identity deregisters");
+  assert.equal(store.get("w-1"), undefined);
+});
+
+test("sweep ages out instances past the TTL and keeps live ones", () => {
+  const clock = fakeClock(1000);
+  const store = freshStore({ ttlMs: 100, clock });
+
+  store.register({ instance: "stale", connectionId: "c1", identity: "peer-a", capability: {} });
+  clock.set(1050);
+  store.register({ instance: "fresh", connectionId: "c2", identity: "peer-b", capability: {} });
+
+  // now=1200: stale last_seen=1000 (age 200 > 100) ages out; fresh last_seen=1050 (age 150 > 100) too.
+  // Bump fresh so only stale is old.
+  clock.set(1120);
+  store.heartbeat("fresh"); // fresh last_seen=1120
+  const removed = store.sweep(1160); // stale age 160>100; fresh age 40<100
+
+  assert.deepEqual(removed.map((r) => r.instance), ["stale"]);
+  assert.deepEqual(store.list().map((r) => r.instance), ["fresh"]);
+});
+
+test("removeByConnection drops every instance on a dead connection", () => {
+  const store = freshStore();
+  store.register({ instance: "a", connectionId: "c1", identity: "peer-a", capability: {} });
+  store.register({ instance: "b", connectionId: "c1", identity: "peer-a", capability: {} });
+  store.register({ instance: "c", connectionId: "c2", identity: "peer-b", capability: {} });
+
+  const removed = store.removeByConnection("c1").sort();
+  assert.deepEqual(removed, ["a", "b"]);
+  assert.deepEqual(store.list().map((r) => r.instance), ["c"]);
+  assert.deepEqual(store.removeByConnection("cX"), []);
+});