@nanobpm/agentic 0.1.0

package/dist/blackboard/store.js

@@ -0,0 +1,216 @@
+/**
+ * The blackboard store — S7's durable layer over the app DataLayer.
+ *
+ * A per-scope advisory shared store. Agents READ it on dispatch and WRITE to it
+ * during their work ("I now also touch state.rs", "constraint X changed") so
+ * parallel siblings coordinate without a human relay. It is a faithful port of
+ * nano-workforce's `plan_blackboard` (issues #51 / #49 D4) — the same kinds,
+ * idempotent `dedupe_key` append, `file-claim` conflict reporting and
+ * `since`/cursor incremental reads — generalised from a hard-wired `plan_key` to
+ * a capability-derived `scope`, so any Urban app gets it for free.
+ *
+ * Design invariants (unchanged from the HTTP hook):
+ *  - ADVISORY ONLY. It never gates a sequence flow; it is shared *knowledge*,
+ *    read fresh, and is not part of deterministic replay.
+ *  - IDEMPOTENT append. A re-POST carrying a stable `dedupeKey` collapses to one
+ *    row (backed by a partial UNIQUE index; we also short-circuit here).
+ *  - SCOPE-BOUND. Every row carries the `scope` it was written under; reads and
+ *    conflict detection never cross scopes.
+ *
+ * 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 (identical to the S2 presence / S6 transcript
+ * stores' `SqliteDb`).
+ */
+import { BLACKBOARD_SCHEMA_SQL, BLACKBOARD_TABLE } from "./schema.js";
+/** The default clock: `Date.now()`. */
+export const systemClock = { now: () => Date.now() };
+/** The recognised blackboard entry kinds (verbatim from nano-workforce). */
+export const BLACKBOARD_KINDS = ["file-claim", "constraint-change", "scope-change", "learning", "note"];
+/** Coerce an arbitrary `kind` to a known value, defaulting to "note". */
+export function normalizeKind(kind) {
+    return BLACKBOARD_KINDS.find((k) => k === kind) ?? "note";
+}
+function decodeFiles(raw) {
+    if (!raw)
+        return [];
+    try {
+        const v = JSON.parse(raw);
+        return Array.isArray(v)
+            ? v.map((x) => String(x).trim()).filter((s) => s !== "")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+function normaliseFiles(files) {
+    return (files ?? []).map((f) => String(f).trim()).filter((s) => s !== "");
+}
+/**
+ * Canonical author identity for a write. A blank/omitted `authorTask` is a host
+ * write and normalises to "system". This is the single source of truth for the
+ * default so `append` (what gets stored) and `detectFileClaimConflicts` (whose
+ * claim to self-exclude) can never drift and falsely self-conflict.
+ */
+function normaliseAuthor(authorTask) {
+    return authorTask?.trim() || "system";
+}
+function toEntry(r) {
+    return {
+        id: r.id,
+        authorTask: r.author_task,
+        kind: r.kind,
+        files: decodeFiles(r.files),
+        body: r.body,
+        wave: r.wave,
+        createdAt: r.created_at,
+    };
+}
+/**
+ * True only for a UNIQUE / PRIMARY-KEY / duplicate violation — never a
+ * foreign-key or other constraint failure. We match the *specific* violation
+ * (extended SQLite codes, or the specific words) rather than the bare word
+ * "constraint", so a `FOREIGN KEY constraint failed` (real corruption, not a
+ * benign duplicate) is always rethrown rather than silently swallowed.
+ */
+export function isUniqueViolation(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const code = "code" in err ? err.code : undefined;
+    if (code === "SQLITE_CONSTRAINT_UNIQUE" || code === "SQLITE_CONSTRAINT_PRIMARYKEY")
+        return true;
+    const message = "message" in err ? err.message : undefined;
+    return typeof message === "string" && /(unique|primary key) constraint failed|duplicate/i.test(message);
+}
+export class BlackboardStore {
+    #db;
+    #clock;
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#clock = options.clock ?? systemClock;
+    }
+    /**
+     * Apply the canonical blackboard DDL (idempotent). Callers that let the app
+     * DataLayer migration runner apply `db/migrations/003_agentic_blackboard.sql`
+     * do not need this — the family module calls it so the store is usable against
+     * a bare source too. The DDL is identical to the migration (drift-guarded).
+     */
+    ensureSchema() {
+        this.#db.exec(BLACKBOARD_SCHEMA_SQL);
+    }
+    /**
+     * Append an entry to a board, idempotently. A blank `body` is rejected. When a
+     * `dedupeKey` is supplied and an entry already exists for it under this
+     * `scope`, the write is a no-op and the existing id is returned
+     * (`inserted: false`) — so an engine job retry re-appending the same fact
+     * never duplicates.
+     */
+    append(scope, input) {
+        const body = typeof input.body === "string" ? input.body.trim() : "";
+        if (!body)
+            throw new Error("blackboard entry requires a non-empty body");
+        const dedupeKey = input.dedupeKey?.trim() || undefined;
+        if (dedupeKey) {
+            const existing = this.#findByDedupe(scope, dedupeKey);
+            if (existing !== undefined)
+                return { inserted: false, id: existing };
+        }
+        const files = normaliseFiles(input.files);
+        try {
+            const { lastInsertRowid } = this.#db.run(`INSERT INTO ${BLACKBOARD_TABLE}
+           (scope, author_task, kind, files, body, wave, dedupe_key, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+                scope,
+                normaliseAuthor(input.authorTask),
+                normalizeKind(input.kind),
+                files.length ? JSON.stringify(files) : null,
+                body,
+                typeof input.wave === "number" ? input.wave : null,
+                dedupeKey ?? null,
+                new Date(this.#clock.now()).toISOString(),
+            ]);
+            return { inserted: true, id: Number(lastInsertRowid) };
+        }
+        catch (err) {
+            // Idempotent write-back under concurrency: two appends sharing a dedupeKey
+            // can both miss the pre-check above, then one loses the race on the UNIQUE
+            // (scope, dedupe_key) index. Convert that collision into a no-op by
+            // re-reading the winner's row, so a retry never throws.
+            if (dedupeKey && isUniqueViolation(err)) {
+                const existing = this.#findByDedupe(scope, dedupeKey);
+                if (existing !== undefined)
+                    return { inserted: false, id: existing };
+            }
+            throw err;
+        }
+    }
+    /**
+     * One incremental read of a board: entries with `id > since` in write order,
+     * plus the board's current head `cursor`. An agent polling mid-flight passes
+     * `cursor` back as the next `since`, so it pulls only what siblings added since
+     * its last read.
+     */
+    readPage(scope, opts = {}) {
+        const since = opts.since ?? 0;
+        // Read the head id independently so the cursor is the board's true head even
+        // when `since` filters every entry out (a caught-up poller learns it is
+        // caught up), and let SQL page with `id > since` against the (scope, id)
+        // index instead of loading the whole board to filter client-side.
+        const head = this.#db.all(`SELECT MAX(id) AS cursor FROM ${BLACKBOARD_TABLE} WHERE scope = ?`, [scope]);
+        const cursor = Number(head[0]?.cursor ?? 0);
+        const rows = this.#db.all(`SELECT * FROM ${BLACKBOARD_TABLE} WHERE scope = ? AND id > ? ORDER BY id`, [scope, since]);
+        const entries = rows.map(toEntry);
+        return { entries, cursor };
+    }
+    /** A board's entries in write order (id asc). `since` returns only `id > since`. */
+    read(scope, opts = {}) {
+        return this.readPage(scope, opts).entries;
+    }
+    /**
+     * Prior `file-claim` entries by OTHER authors under this `scope` that overlap
+     * `files`. A writer's own earlier claim is never a conflict with itself. Pass
+     * `beforeId` to restrict to strictly prior claims (`id < beforeId`) — the
+     * family computes conflicts AFTER inserting its own claim and sets `beforeId`
+     * to that new id, so first-writer-wins is decided by insertion order and a
+     * sibling claim that raced in concurrently is still surfaced without matching
+     * the writer's own just-written row.
+     */
+    detectFileClaimConflicts(scope, opts) {
+        const want = new Set(normaliseFiles(opts.files));
+        if (want.size === 0)
+            return [];
+        const me = normaliseAuthor(opts.authorTask);
+        const beforeId = opts.beforeId;
+        // Push `id < beforeId` into SQL (the common path per the docstring) so we
+        // scan only strictly-prior claims via the (scope, id) index rather than
+        // loading every file-claim for the scope and filtering client-side.
+        const clauses = ["scope = ?", "kind = 'file-claim'"];
+        const params = [scope];
+        if (beforeId != null) {
+            clauses.push("id < ?");
+            params.push(beforeId);
+        }
+        const rows = this.#db.all(`SELECT * FROM ${BLACKBOARD_TABLE} WHERE ${clauses.join(" AND ")} ORDER BY id`, params);
+        const out = [];
+        for (const r of rows) {
+            if ((r.author_task || "") === me)
+                continue;
+            for (const f of new Set(decodeFiles(r.files))) {
+                if (want.has(f)) {
+                    out.push({ file: f, authorTask: r.author_task, id: r.id, body: r.body, createdAt: r.created_at });
+                }
+            }
+        }
+        return out;
+    }
+    /** Number of entries under a scope. */
+    count(scope) {
+        const rows = this.#db.all(`SELECT COUNT(*) AS n FROM ${BLACKBOARD_TABLE} WHERE scope = ?`, [scope]);
+        return rows[0]?.n ?? 0;
+    }
+    #findByDedupe(scope, dedupeKey) {
+        const rows = this.#db.all(`SELECT id FROM ${BLACKBOARD_TABLE} WHERE scope = ? AND dedupe_key = ?`, [scope, dedupeKey]);
+        return rows[0]?.id;
+    }
+}

package/dist/blackboard/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/blackboard/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(),
+    };
+}

package/dist/channel/auth.d.ts

@@ -0,0 +1,41 @@
+import type { HandshakeRequest } from "./connection.ts";
+/** What the authenticator grants a peer once it passes the gate. */
+export interface AuthGrant {
+    /** The authenticated principal (ADR 0028 identity). */
+    readonly identity: string;
+    /** Optional scope the identity is confined to (e.g. a plan/network). */
+    readonly scope?: string;
+    /** The capability credential the peer presented, if any. */
+    readonly capability?: string;
+}
+/** Application close code for a rejected identity token. */
+export declare const AUTH_UNAUTHORIZED = 4401;
+/** Application close code for a missing/rejected capability credential. */
+export declare const AUTH_FORBIDDEN = 4403;
+export type AuthResult = {
+    readonly ok: true;
+    readonly grant: AuthGrant;
+} | {
+    readonly ok: false;
+    readonly code: number;
+    readonly reason: string;
+};
+/** Verifies a handshake and either grants or rejects the connection. */
+export type Authenticator = (req: HandshakeRequest) => AuthResult | Promise<AuthResult>;
+export interface SharedSecretAuthOptions {
+    /** The shared identity-token secret every valid peer presents. */
+    readonly secret: string;
+    /** Require a capability credential too (default true). */
+    readonly requireCredential?: boolean;
+    /** Extra check on the credential; return false to reject. Default accept-any. */
+    readonly verifyCredential?: (credential: string, identity: string) => boolean;
+    /** Derive the identity from the handshake. Default: the connection's remote address (`req.remote`), or `anonymous`. */
+    readonly identityFor?: (req: HandshakeRequest) => string;
+}
+/**
+ * The default authenticator: a shared-secret identity token gate plus a required
+ * capability credential. Mirrors nano-workforce's blackboard-hook `?token=…`
+ * pattern; swap in a real ADR 0028 verifier by passing your own
+ * {@link Authenticator} to the hub.
+ */
+export declare function sharedSecretAuthenticator(options: SharedSecretAuthOptions): Authenticator;

package/dist/channel/auth.js

@@ -0,0 +1,67 @@
+/**
+ * Connection authentication.
+ *
+ * A peer authenticates at the app-tier handshake with an ADR 0028 identity
+ * token PLUS a capability credential — the same pattern nano-workforce's
+ * blackboard hook already uses (`?token=…`). This is a connection-level gate:
+ * capability (cognition / weight / family / host) travels later on the
+ * `register` frame as an enrolment attribute and is NEVER a routing token.
+ *
+ * The hub takes any {@link Authenticator}; {@link sharedSecretAuthenticator} is
+ * the batteries-included default.
+ */
+import { timingSafeEqual } from "node:crypto";
+/** Application close code for a rejected identity token. */
+export const AUTH_UNAUTHORIZED = 4401;
+/** Application close code for a missing/rejected capability credential. */
+export const AUTH_FORBIDDEN = 4403;
+/**
+ * Constant-time string comparison. Unequal-length inputs short-circuit to
+ * `false` (length is not itself secret here); equal-length inputs are compared
+ * in constant time via {@link timingSafeEqual}.
+ */
+function safeEqual(a, b) {
+    const ab = new TextEncoder().encode(a);
+    const bb = new TextEncoder().encode(b);
+    if (ab.length !== bb.length) {
+        return false;
+    }
+    return timingSafeEqual(ab, bb);
+}
+/** Read the identity token from the handshake (explicit field or `token` query). */
+function tokenOf(req) {
+    return req.token ?? req.query?.token;
+}
+/**
+ * Read the capability credential from the handshake: explicit field, the
+ * `capability` query param, or the `x-capability-credential` header.
+ */
+function credentialOf(req) {
+    return req.credential ?? req.query?.capability ?? req.headers?.["x-capability-credential"];
+}
+/**
+ * The default authenticator: a shared-secret identity token gate plus a required
+ * capability credential. Mirrors nano-workforce's blackboard-hook `?token=…`
+ * pattern; swap in a real ADR 0028 verifier by passing your own
+ * {@link Authenticator} to the hub.
+ */
+export function sharedSecretAuthenticator(options) {
+    const requireCredential = options.requireCredential ?? true;
+    return (req) => {
+        const token = tokenOf(req);
+        if (token === undefined || !safeEqual(token, options.secret)) {
+            return { ok: false, code: AUTH_UNAUTHORIZED, reason: "invalid identity token" };
+        }
+        const identity = options.identityFor ? options.identityFor(req) : (req.remote ?? "anonymous");
+        const credential = credentialOf(req);
+        if (requireCredential) {
+            if (credential === undefined || credential.length === 0) {
+                return { ok: false, code: AUTH_FORBIDDEN, reason: "missing capability credential" };
+            }
+            if (options.verifyCredential && !options.verifyCredential(credential, identity)) {
+                return { ok: false, code: AUTH_FORBIDDEN, reason: "capability credential rejected" };
+            }
+        }
+        return { ok: true, grant: { identity, capability: credential } };
+    };
+}

package/dist/channel/clock.d.ts

@@ -0,0 +1,11 @@
+/**
+ * An injectable monotonic-ish wall clock. The hub and connection registry read
+ * time only through a {@link Clock} so liveness/TTL behaviour is deterministic
+ * under test (pass a fake clock) without sleeping on the real timer.
+ */
+export interface Clock {
+    /** Current time in epoch milliseconds. */
+    now(): number;
+}
+/** The production clock, backed by {@link Date.now}. */
+export declare const systemClock: Clock;

package/dist/channel/clock.js

@@ -0,0 +1,4 @@
+/** The production clock, backed by {@link Date.now}. */
+export const systemClock = {
+    now: () => Date.now(),
+};

package/dist/channel/connection.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Transport-agnostic connection contracts.
+ *
+ * The hub owns connection lifecycle and framing; it speaks to the network only
+ * through {@link ChannelTransport} / {@link ChannelConnection}. That keeps the
+ * hub deterministically testable over an in-memory transport and lets the real
+ * {@link WebSocketChannelTransport} (or any future transport) be a thin adapter.
+ *
+ * A connection carries opaque, already-encoded protocol frames as bytes — the
+ * hub decodes them with the S0 codec (`@nanobpm/agentic-protocol`). This channel
+ * is served by the app on its OWN bound port; the Camunda-8 engine transport is
+ * a separate connection and is never touched here.
+ */
+/**
+ * Everything the transport learns about a peer at connect time, BEFORE any
+ * protocol frame is exchanged. The default authenticator reads the ADR 0028
+ * identity token and the capability credential from here (mirroring the
+ * `?token=…` pattern nano-workforce's blackboard hook already uses).
+ */
+export interface HandshakeRequest {
+    /** ADR 0028 identity token (typically the `token` query param or a header). */
+    readonly token?: string;
+    /** Capability credential authorising the peer to enrol. */
+    readonly credential?: string;
+    /** Remote address, for logging/diagnostics only. */
+    readonly remote?: string;
+    /** Lower-cased request headers. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Parsed query-string parameters. */
+    readonly query?: Readonly<Record<string, string>>;
+}
+/** Close-status code (WebSocket application range 3000–4999 for our own codes). */
+export type CloseCode = number;
+/**
+ * A single duplex connection to a peer. The hub registers exactly one message
+ * and one close listener; a transport may deliver `pong` for keepalive.
+ */
+export interface ChannelConnection {
+    /** Stable per-connection id (unique for the life of the process). */
+    readonly id: string;
+    /** What the transport captured about the peer at connect time. */
+    readonly handshake: HandshakeRequest;
+    /** Send one already-encoded frame as binary bytes. */
+    send(bytes: Uint8Array): void;
+    /** Close the connection with an optional application close code + reason. */
+    close(code?: CloseCode, reason?: string): void;
+    /** Register the (single) inbound-bytes listener. */
+    onMessage(listener: (bytes: Uint8Array) => void): void;
+    /** Register the (single) close listener. */
+    onClose(listener: (code?: CloseCode, reason?: string) => void): void;
+    /** Register a keepalive pong listener, if the transport supports ping/pong. */
+    onPong?(listener: () => void): void;
+    /**
+     * Register an inbound-ping listener, if the transport supports ping/pong. A
+     * peer-driven keepalive typically arrives as an inbound ping (the transport
+     * auto-replies with a pong), so an inbound ping is also proof of life.
+     */
+    onPing?(listener: () => void): void;
+    /** Send a keepalive ping, if the transport supports it. */
+    ping?(): void;
+}
+/**
+ * A listening transport, bound to the app's own port. It emits a
+ * {@link ChannelConnection} for every accepted, upgraded peer.
+ */
+export interface ChannelTransport {
+    /** Register the handler invoked for each newly accepted connection. */
+    onConnection(listener: (conn: ChannelConnection) => void): void;
+    /** The bound address once listening, or `null` before/after. */
+    readonly address: {
+        readonly port: number;
+    } | null;
+    /** Stop accepting and release the port. */
+    close(): Promise<void>;
+}

package/dist/channel/connection.js

@@ -0,0 +1,14 @@
+/**
+ * Transport-agnostic connection contracts.
+ *
+ * The hub owns connection lifecycle and framing; it speaks to the network only
+ * through {@link ChannelTransport} / {@link ChannelConnection}. That keeps the
+ * hub deterministically testable over an in-memory transport and lets the real
+ * {@link WebSocketChannelTransport} (or any future transport) be a thin adapter.
+ *
+ * A connection carries opaque, already-encoded protocol frames as bytes — the
+ * hub decodes them with the S0 codec (`@nanobpm/agentic-protocol`). This channel
+ * is served by the app on its OWN bound port; the Camunda-8 engine transport is
+ * a separate connection and is never touched here.
+ */
+export {};

package/dist/channel/dispatch.d.ts

@@ -0,0 +1,46 @@
+import type { Frame, MessageFamily } from "../protocol/index.ts";
+/**
+ * A handler for one message family. `ctx` is whatever per-connection context
+ * the hub threads through (see {@link HubConnection}); the router itself is
+ * generic so it can be unit-tested without the hub.
+ */
+export type FamilyHandler<Ctx> = (frame: Frame, ctx: Ctx) => void | Promise<void>;
+/** Raised when a family key outside the S0 {@link MessageFamily} set is used. */
+export declare class UnknownFamilyError extends Error {
+    readonly family: string;
+    constructor(family: string);
+}
+/**
+ * Raised when a second handler is registered for a family that already has one.
+ * One family, one owning module — this guard is what stops two sibling slices
+ * silently clobbering each other's handler.
+ */
+export declare class DuplicateFamilyHandlerError extends Error {
+    readonly family: MessageFamily;
+    constructor(family: MessageFamily);
+}
+/**
+ * The derived frame→family routing table. The hub holds one of these; every
+ * family module attaches through {@link registerFamilyHandler}.
+ */
+export declare class FamilyRouter<Ctx> {
+    #private;
+    /**
+     * Attach the handler that owns `family`. This is the seam every family module
+     * calls; it keys off the S0 family set and refuses a duplicate so two slices
+     * cannot both claim one family.
+     */
+    registerFamilyHandler(family: MessageFamily, handler: FamilyHandler<Ctx>): void;
+    /** Set the fallback invoked for a frame whose family has no handler. */
+    onUnhandled(handler: FamilyHandler<Ctx>): void;
+    /** Whether a handler is registered for `family`. */
+    has(family: MessageFamily): boolean;
+    /** The families that currently have a handler (the derived table's keys). */
+    families(): MessageFamily[];
+    /**
+     * Route one decoded frame to its family handler by table lookup. Returns
+     * `true` if a family handler ran, `false` if it fell through to the unhandled
+     * fallback (or nowhere). Any handler rejection propagates to the caller.
+     */
+    route(frame: Frame, ctx: Ctx): Promise<boolean>;
+}

package/dist/channel/dispatch.js

@@ -0,0 +1,86 @@
+/**
+ * The family-handler registration seam — S1's canonical extension point.
+ *
+ * Multiple wave-2 slices (S2 presence/registry, S5 relay, S7 blackboard) each
+ * attach a NEW inbound message-family handler to the single hub. To stop them
+ * colliding on a central `switch (frame.family)`, the hub's frame→family routing
+ * is DERIVED from this registration table: each family is a self-contained
+ * module that attaches itself with {@link FamilyRouter.registerFamilyHandler}
+ * and the router dispatches by table lookup — never a hand-edited switch.
+ *
+ * Family keys are the S0 {@link MessageFamily} set (`@nanobpm/agentic-protocol`),
+ * the one source of truth; registering a key outside that set is rejected.
+ */
+import { isMessageFamily } from "../protocol/index.js";
+/** Raised when a family key outside the S0 {@link MessageFamily} set is used. */
+export class UnknownFamilyError extends Error {
+    family;
+    constructor(family) {
+        super(`unknown message family: ${family}`);
+        this.name = "UnknownFamilyError";
+        this.family = family;
+    }
+}
+/**
+ * Raised when a second handler is registered for a family that already has one.
+ * One family, one owning module — this guard is what stops two sibling slices
+ * silently clobbering each other's handler.
+ */
+export class DuplicateFamilyHandlerError extends Error {
+    family;
+    constructor(family) {
+        super(`a handler is already registered for family: ${family}`);
+        this.name = "DuplicateFamilyHandlerError";
+        this.family = family;
+    }
+}
+/**
+ * The derived frame→family routing table. The hub holds one of these; every
+ * family module attaches through {@link registerFamilyHandler}.
+ */
+export class FamilyRouter {
+    #handlers = new Map();
+    #onUnhandled;
+    /**
+     * Attach the handler that owns `family`. This is the seam every family module
+     * calls; it keys off the S0 family set and refuses a duplicate so two slices
+     * cannot both claim one family.
+     */
+    registerFamilyHandler(family, handler) {
+        if (!isMessageFamily(family)) {
+            throw new UnknownFamilyError(family);
+        }
+        if (this.#handlers.has(family)) {
+            throw new DuplicateFamilyHandlerError(family);
+        }
+        this.#handlers.set(family, handler);
+    }
+    /** Set the fallback invoked for a frame whose family has no handler. */
+    onUnhandled(handler) {
+        this.#onUnhandled = handler;
+    }
+    /** Whether a handler is registered for `family`. */
+    has(family) {
+        return this.#handlers.has(family);
+    }
+    /** The families that currently have a handler (the derived table's keys). */
+    families() {
+        return [...this.#handlers.keys()];
+    }
+    /**
+     * Route one decoded frame to its family handler by table lookup. Returns
+     * `true` if a family handler ran, `false` if it fell through to the unhandled
+     * fallback (or nowhere). Any handler rejection propagates to the caller.
+     */
+    async route(frame, ctx) {
+        const handler = this.#handlers.get(frame.family);
+        if (handler === undefined) {
+            if (this.#onUnhandled !== undefined) {
+                await this.#onUnhandled(frame, ctx);
+            }
+            return false;
+        }
+        await handler(frame, ctx);
+        return true;
+    }
+}