@nanobpm/agentic 0.1.0

package/dist/presence/family.d.ts

@@ -0,0 +1,40 @@
+import type { AgenticHub } from "../channel/index.ts";
+import type { PresenceRow, PresenceStore } 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 declare class PresencePayloadError extends Error {
+    readonly family: string;
+    constructor(family: string, detail: string);
+}
+/**
+ * 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 declare function attachPresenceFamily(hub: AgenticHub, store: PresenceStore, options?: PresenceFamilyOptions): PresenceFamilyHandle;

package/dist/presence/family.js

@@ -0,0 +1,166 @@
+/**
+ * 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.js";
+import { PresenceOwnershipError } from "./store.js";
+/** A malformed presence payload rejected before it touches the store. */
+export class PresencePayloadError extends Error {
+    family;
+    constructor(family, detail) {
+        super(`invalid ${family} payload: ${detail}`);
+        this.name = "PresencePayloadError";
+        this.family = family;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}
+function readNumber(record, key) {
+    const value = record[key];
+    return typeof value === "number" ? value : undefined;
+}
+/** Extract the enrolment capability from a validated `register` payload. */
+function readCapability(record) {
+    const raw = record.capability;
+    if (!isPlainObject(raw))
+        return {};
+    const cap = {};
+    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, store, options = {}) {
+    store.ensureSchema();
+    const onError = options.onError ?? (() => { });
+    const reject = (family, connectionId, detail) => {
+        onError(new PresencePayloadError(family, detail), connectionId);
+    };
+    hub.registerFamilyHandler("register", (frame, ctx) => {
+        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, ctx) => {
+        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, ctx) => {
+        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 = () => {
+        try {
+            return store.sweep();
+        }
+        catch (err) {
+            onError(err);
+            return [];
+        }
+    };
+    const interval = options.sweepIntervalMs ?? Math.max(1, Math.floor(store.ttlMs / 3));
+    let timer;
+    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/dist/presence/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @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/dist/presence/index.js

@@ -0,0 +1,17 @@
+/**
+ * @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.js";
+export { attachPresenceFamily, PresencePayloadError } from "./family.js";
+export { PRESENCE_TABLE, PRESENCE_SCHEMA_SQL } from "./schema.js";

package/dist/presence/schema.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare 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 declare const PRESENCE_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS agentic_presence (\n  instance      TEXT PRIMARY KEY,\n  connection_id TEXT NOT NULL,\n  identity      TEXT NOT NULL,\n  cognition     TEXT,\n  weight        REAL,\n  family        TEXT,\n  host          TEXT,\n  registered_at TEXT NOT NULL,\n  last_seen     INTEGER NOT NULL\n);\nCREATE INDEX IF NOT EXISTS idx_agentic_presence_last_seen ON agentic_presence (last_seen);\nCREATE INDEX IF NOT EXISTS idx_agentic_presence_connection ON agentic_presence (connection_id);";

package/dist/presence/schema.js

@@ -0,0 +1,32 @@
+/**
+ * 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/dist/presence/store.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The presence & registry store — S2's durable layer over the app DataLayer.
+ *
+ * S1 owns *connection* liveness in-memory (touch-on-frame + a TTL sweep that
+ * closes silent sockets). S2 layers a durable *presence* registry on top: one
+ * row per registered worker instance, carrying its declared capability
+ * (cognition/weight/family/host — an enrolment attribute, never a routing
+ * token), the connection it registered on, and its own `last_seen` liveness
+ * refreshed by heartbeats. Rows age out on the presence TTL via {@link sweep}.
+ *
+ * The store speaks only the tiny synchronous SQLite subset the runtime exposes
+ * ({@link SqliteDb}), so it works against any app DataLayer source without
+ * pulling in the whole runtime.
+ */
+import type { Capability } from "../protocol/index.ts";
+import type { Clock } from "../channel/index.ts";
+/**
+ * The minimal synchronous SQLite handle the store needs — structurally the same
+ * surface the Urban runtime's DataLayer exposes (`host.openSqlite`). Kept local
+ * so the store depends on a shape, not on the runtime package.
+ */
+export interface SqliteDb {
+    /** Execute one or more statements with no result (DDL, migrations). */
+    exec(sql: string): void;
+    /** Run a parameterised statement, returning the changed-row count. */
+    run(sql: string, params?: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /** Run a parameterised query, returning all rows as plain objects. */
+    all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+}
+/** A durable presence row for one registered worker instance. */
+export interface PresenceRow {
+    /** The worker instance id (`register.instance`) — the primary key. */
+    readonly instance: string;
+    /** The channel connection the instance last registered on. */
+    readonly connectionId: string;
+    /** The authenticated principal (ADR 0028 identity) of that connection. */
+    readonly identity: string;
+    /** The declared enrolment capability (never a routing token). */
+    readonly capability: Capability;
+    /** When the instance first registered, ISO-8601. */
+    readonly registeredAt: string;
+    /** Last liveness refresh (register/heartbeat), epoch ms. */
+    readonly lastSeen: number;
+}
+/** Input to {@link PresenceStore.register}. */
+export interface RegisterInput {
+    readonly instance: string;
+    readonly connectionId: string;
+    readonly identity: string;
+    readonly capability: Capability;
+}
+export interface PresenceStoreOptions {
+    /** Presence liveness TTL in ms; a row unseen for longer ages out. Default 30000. */
+    ttlMs?: number;
+    /** Injectable clock for deterministic tests. Default {@link systemClock}. */
+    clock?: Clock;
+}
+/**
+ * Raised when a `register` would overwrite an instance already owned by a
+ * different authenticated identity. Presence rows are bound to the identity
+ * that first registered them, so one authenticated peer can never take over
+ * (or change the identity of) another peer's instance.
+ */
+export declare class PresenceOwnershipError extends Error {
+    readonly instance: string;
+    constructor(instance: string);
+}
+export declare class PresenceStore {
+    #private;
+    constructor(db: SqliteDb, options?: PresenceStoreOptions);
+    /** The presence liveness TTL in ms. */
+    get ttlMs(): number;
+    /**
+     * Apply the canonical presence DDL (idempotent). Callers that let the app
+     * DataLayer migration runner apply `db/migrations/001_agentic_presence.sql`
+     * do not need this — but the family module calls it so the store is usable
+     * against a bare source too. The DDL is identical to the migration (guarded).
+     */
+    ensureSchema(): void;
+    /**
+     * Register (or re-register) an instance. A first registration stamps
+     * `registered_at`; a re-registration (e.g. after a reconnect on a new
+     * connection) keeps the original `registered_at` and refreshes everything
+     * else, including `last_seen`. Returns the stored row.
+     *
+     * Ownership is bound to the authenticated `identity` that first registered the
+     * instance: a re-register from the same identity (the reconnect case) is
+     * allowed, but one from a *different* identity is rejected with a
+     * {@link PresenceOwnershipError} and leaves the existing row untouched — no
+     * peer can take over another peer's instance or rewrite its identity.
+     */
+    register(input: RegisterInput): PresenceRow;
+    /**
+     * Refresh an instance's liveness to now. Returns `true` if the instance was
+     * registered, `false` if there is no such row (a heartbeat before register).
+     * When `identity` is given, the refresh is scoped to the owning identity, so a
+     * heartbeat from a foreign identity is a silent no-op (and cannot probe for
+     * the existence of another peer's instance).
+     */
+    heartbeat(instance: string, identity?: string): boolean;
+    /**
+     * Remove an instance's presence row. Returns `true` if a row was removed. When
+     * `identity` is given, the removal is scoped to the owning identity, so a
+     * deregister from a foreign identity is a silent no-op.
+     */
+    deregister(instance: string, identity?: string): boolean;
+    /**
+     * Remove every presence row registered on a now-dead connection (e.g. one S1
+     * closed on its own liveness sweep). Returns the removed instance ids so the
+     * caller can react. Presence also ages out via {@link sweep}; this is the
+     * eager path when a disconnect is observed.
+     */
+    removeByConnection(connectionId: string): string[];
+    /**
+     * Age out every presence row whose `last_seen` is older than the TTL and
+     * return the removed rows. `now` defaults to the clock; pass an explicit value
+     * for deterministic tests. Matches S1's liveness predicate (`now - lastSeen >
+     * ttl`).
+     */
+    sweep(now?: number): PresenceRow[];
+    /** Look up a single instance's presence row. */
+    get(instance: string): PresenceRow | undefined;
+    /** Every presence row, ordered by first registration then instance id. */
+    list(): PresenceRow[];
+    /** Number of registered instances. */
+    count(): number;
+}

package/dist/presence/store.js

@@ -0,0 +1,191 @@
+import { systemClock } from "../channel/index.js";
+import { PRESENCE_SCHEMA_SQL, PRESENCE_TABLE } from "./schema.js";
+const DEFAULT_TTL_MS = 30_000;
+/**
+ * Raised when a `register` would overwrite an instance already owned by a
+ * different authenticated identity. Presence rows are bound to the identity
+ * that first registered them, so one authenticated peer can never take over
+ * (or change the identity of) another peer's instance.
+ */
+export class PresenceOwnershipError extends Error {
+    instance;
+    constructor(instance) {
+        super(`instance "${instance}" is registered to a different identity`);
+        this.name = "PresenceOwnershipError";
+        this.instance = instance;
+    }
+}
+function buildCapability(row) {
+    const cap = {};
+    if (row.cognition !== null)
+        cap.cognition = row.cognition;
+    if (row.weight !== null)
+        cap.weight = row.weight;
+    if (row.family !== null)
+        cap.family = row.family;
+    if (row.host !== null)
+        cap.host = row.host;
+    return cap;
+}
+function toRow(row) {
+    return {
+        instance: row.instance,
+        connectionId: row.connection_id,
+        identity: row.identity,
+        capability: buildCapability(row),
+        registeredAt: row.registered_at,
+        lastSeen: row.last_seen,
+    };
+}
+export class PresenceStore {
+    #db;
+    #ttlMs;
+    #clock;
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.#clock = options.clock ?? systemClock;
+    }
+    /** The presence liveness TTL in ms. */
+    get ttlMs() {
+        return this.#ttlMs;
+    }
+    /**
+     * Apply the canonical presence DDL (idempotent). Callers that let the app
+     * DataLayer migration runner apply `db/migrations/001_agentic_presence.sql`
+     * do not need this — but the family module calls it so the store is usable
+     * against a bare source too. The DDL is identical to the migration (guarded).
+     */
+    ensureSchema() {
+        this.#db.exec(PRESENCE_SCHEMA_SQL);
+    }
+    /**
+     * Register (or re-register) an instance. A first registration stamps
+     * `registered_at`; a re-registration (e.g. after a reconnect on a new
+     * connection) keeps the original `registered_at` and refreshes everything
+     * else, including `last_seen`. Returns the stored row.
+     *
+     * Ownership is bound to the authenticated `identity` that first registered the
+     * instance: a re-register from the same identity (the reconnect case) is
+     * allowed, but one from a *different* identity is rejected with a
+     * {@link PresenceOwnershipError} and leaves the existing row untouched — no
+     * peer can take over another peer's instance or rewrite its identity.
+     */
+    register(input) {
+        const now = this.#clock.now();
+        const cap = input.capability;
+        this.#db.run(`INSERT INTO ${PRESENCE_TABLE}
+         (instance, connection_id, identity, cognition, weight, family, host, registered_at, last_seen)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(instance) DO UPDATE SET
+         connection_id = excluded.connection_id,
+         identity      = excluded.identity,
+         cognition     = excluded.cognition,
+         weight        = excluded.weight,
+         family        = excluded.family,
+         host          = excluded.host,
+         last_seen     = excluded.last_seen
+       WHERE ${PRESENCE_TABLE}.identity = excluded.identity`, [
+            input.instance,
+            input.connectionId,
+            input.identity,
+            cap.cognition ?? null,
+            cap.weight ?? null,
+            cap.family ?? null,
+            cap.host ?? null,
+            new Date(now).toISOString(),
+            now,
+        ]);
+        // Enforce ownership on the *persisted* row rather than the driver's
+        // changed-row count. The identity guard in the UPSERT's `WHERE` leaves a
+        // foreign-owned row untouched, so after the statement the stored identity
+        // is authoritative: if it differs from the caller's, this register was a
+        // rejected takeover. Reading it back keeps the invariant independent of how
+        // SQLite counts UPSERT changes (which counts WHERE-matched rows, not just
+        // value-changing ones), so a same-identity no-op re-register never trips it.
+        const row = this.get(input.instance);
+        if (row === undefined) {
+            throw new Error(`presence row vanished immediately after register: ${input.instance}`);
+        }
+        if (row.identity !== input.identity) {
+            throw new PresenceOwnershipError(input.instance);
+        }
+        return row;
+    }
+    /**
+     * Refresh an instance's liveness to now. Returns `true` if the instance was
+     * registered, `false` if there is no such row (a heartbeat before register).
+     * When `identity` is given, the refresh is scoped to the owning identity, so a
+     * heartbeat from a foreign identity is a silent no-op (and cannot probe for
+     * the existence of another peer's instance).
+     */
+    heartbeat(instance, identity) {
+        const { changes } = identity === undefined
+            ? this.#db.run(`UPDATE ${PRESENCE_TABLE} SET last_seen = ? WHERE instance = ?`, [this.#clock.now(), instance])
+            : this.#db.run(`UPDATE ${PRESENCE_TABLE} SET last_seen = ? WHERE instance = ? AND identity = ?`, [
+                this.#clock.now(),
+                instance,
+                identity,
+            ]);
+        return changes > 0;
+    }
+    /**
+     * Remove an instance's presence row. Returns `true` if a row was removed. When
+     * `identity` is given, the removal is scoped to the owning identity, so a
+     * deregister from a foreign identity is a silent no-op.
+     */
+    deregister(instance, identity) {
+        const { changes } = identity === undefined
+            ? this.#db.run(`DELETE FROM ${PRESENCE_TABLE} WHERE instance = ?`, [instance])
+            : this.#db.run(`DELETE FROM ${PRESENCE_TABLE} WHERE instance = ? AND identity = ?`, [instance, identity]);
+        return changes > 0;
+    }
+    /**
+     * Remove every presence row registered on a now-dead connection (e.g. one S1
+     * closed on its own liveness sweep). Returns the removed instance ids so the
+     * caller can react. Presence also ages out via {@link sweep}; this is the
+     * eager path when a disconnect is observed.
+     */
+    removeByConnection(connectionId) {
+        const removed = this.#db
+            .all(`SELECT instance FROM ${PRESENCE_TABLE} WHERE connection_id = ?`, [connectionId])
+            .map((r) => r.instance);
+        if (removed.length > 0) {
+            this.#db.run(`DELETE FROM ${PRESENCE_TABLE} WHERE connection_id = ?`, [connectionId]);
+        }
+        return removed;
+    }
+    /**
+     * Age out every presence row whose `last_seen` is older than the TTL and
+     * return the removed rows. `now` defaults to the clock; pass an explicit value
+     * for deterministic tests. Matches S1's liveness predicate (`now - lastSeen >
+     * ttl`).
+     */
+    sweep(now = this.#clock.now()) {
+        const cutoff = now - this.#ttlMs;
+        const stale = this.#db
+            .all(`SELECT * FROM ${PRESENCE_TABLE} WHERE last_seen < ?`, [cutoff])
+            .map(toRow);
+        if (stale.length > 0) {
+            this.#db.run(`DELETE FROM ${PRESENCE_TABLE} WHERE last_seen < ?`, [cutoff]);
+        }
+        return stale;
+    }
+    /** Look up a single instance's presence row. */
+    get(instance) {
+        const rows = this.#db.all(`SELECT * FROM ${PRESENCE_TABLE} WHERE instance = ?`, [instance]);
+        const row = rows[0];
+        return row === undefined ? undefined : toRow(row);
+    }
+    /** Every presence row, ordered by first registration then instance id. */
+    list() {
+        return this.#db
+            .all(`SELECT * FROM ${PRESENCE_TABLE} ORDER BY registered_at, instance`)
+            .map(toRow);
+    }
+    /** Number of registered instances. */
+    count() {
+        const rows = this.#db.all(`SELECT COUNT(*) AS n FROM ${PRESENCE_TABLE}`);
+        return rows[0]?.n ?? 0;
+    }
+}

package/dist/presence/test-db.d.ts

@@ -0,0 +1,5 @@
+import type { SqliteDb } from "./store.ts";
+export interface TestDb extends SqliteDb {
+    close(): void;
+}
+export declare function openTestDb(): TestDb;

package/dist/presence/test-db.js

@@ -0,0 +1,42 @@
+/**
+ * Test-only helper: a {@link SqliteDb} backed by an in-memory `node:sqlite`
+ * database, mirroring the Node host adapter's `wrapNodeSqlite`. Kept out of the
+ * published build (see `tsconfig.build.json` exclude) — it exists solely so the
+ * store/family tests exercise the store against a real SQLite engine, not a mock.
+ */
+import { DatabaseSync } from "node:sqlite";
+function toParams(params) {
+    return params.map((p) => {
+        if (p === null)
+            return null;
+        if (typeof p === "string" || typeof p === "number" || typeof p === "bigint" || p instanceof Uint8Array) {
+            return p;
+        }
+        if (typeof p === "boolean")
+            return p ? 1 : 0;
+        // Mirror wrapNodeSqlite's `sqliteParams`: unsupported types (including
+        // `undefined`) throw rather than coerce, so a test can never pass on a
+        // parameter production would reject.
+        throw new TypeError(`unsupported SQLite parameter type: ${typeof p}`);
+    });
+}
+export function openTestDb() {
+    const db = new DatabaseSync(":memory:");
+    return {
+        exec: (sql) => db.exec(sql),
+        run: (sql, params = []) => {
+            const stmt = db.prepare(sql);
+            const r = stmt.run(...toParams(params));
+            return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+        },
+        all: (sql, params = []) => {
+            const stmt = db.prepare(sql);
+            // Mirror wrapNodeSqlite exactly: return the driver's row objects directly.
+            // A JSON round-trip would throw on `bigint` values and mangle `Uint8Array`
+            // blobs, diverging from production and breaking test-only reads.
+            // biome-ignore lint/plugin: Node sqlite returns untyped row objects; SqliteDb.all<T> is the host adapter boundary.
+            return stmt.all(...toParams(params));
+        },
+        close: () => db.close(),
+    };
+}