@nanobpm/agentic 0.1.0

package/src/blackboard/family.test.ts

@@ -0,0 +1,280 @@
+import assert from "node:assert/strict";
+import { setImmediate as tick } from "node:timers/promises";
+import { test } from "node:test";
+import { decodeFrame, 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, CloseCode, HandshakeRequest } from "../channel/index.ts";
+import { attachBlackboardFamily, BlackboardPayloadError, BlackboardScopeError } from "./family.ts";
+import { BlackboardStore } from "./store.ts";
+import { openTestDb } from "./test-db.ts";
+
+/** In-memory connection the test drives directly, capturing frames sent back. */
+class FakeConnection implements ChannelConnection {
+  readonly id: string;
+  readonly handshake: HandshakeRequest;
+  readonly sent: Frame[] = [];
+  #onMessage: ((bytes: Uint8Array) => void) | undefined;
+  #onClose: ((code?: CloseCode, reason?: string) => void) | undefined;
+
+  constructor(id: string, handshake: HandshakeRequest) {
+    this.id = id;
+    this.handshake = handshake;
+  }
+  send(bytes: Uint8Array): void {
+    this.sent.push(decodeFrame(bytes));
+  }
+  close(code?: CloseCode, reason?: string): void {
+    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 frame(family: MessageFamily, payload: unknown, seq = 1): Uint8Array {
+  // Blackboard requests ride the `interactive` lane per the protocol conformance
+  // corpus; replies still come back on the `control`/facts lane (see `lastReply`).
+  const f: Frame = { lane: "interactive", family, seq, payload };
+  return encodeFrame(f);
+}
+
+const auth = sharedSecretAuthenticator({ secret: "s3cret" });
+
+/** Connect with a capability credential — the default board scope. */
+function connect(transport: FakeTransport, id: string, remote: string, credential = "board-cap"): FakeConnection {
+  const conn = new FakeConnection(id, { token: "s3cret", credential, remote });
+  transport.accept(conn);
+  return conn;
+}
+
+/** The single blackboard reply the connection received, decoded cast-free via JSON. */
+function lastReply(conn: FakeConnection) {
+  const f = conn.sent.at(-1);
+  assert.ok(f, "expected a reply frame");
+  assert.equal(f.family, "blackboard");
+  assert.equal(f.lane, "control", "replies ride the control/facts lane");
+  assert.ok(f.payload && typeof f.payload === "object");
+  return JSON.parse(JSON.stringify(f.payload));
+}
+
+test("append then read round-trips through the S1 seam", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  const store = new BlackboardStore(openTestDb());
+  attachBlackboardFamily(hub, store);
+
+  const conn = connect(transport, "c1", "peer-a");
+  await tick();
+
+  conn.receive(frame("blackboard", { op: "append", authorTask: "t1", kind: "note", body: "hello" }, 1));
+  await tick();
+  const appendReply = lastReply(conn);
+  assert.equal(appendReply.op, "append");
+  assert.equal(appendReply.inserted, true);
+  assert.equal(appendReply.scope, undefined, "reply must not echo the (secret) capability scope");
+  assert.deepEqual(appendReply.conflicts, []);
+
+  conn.receive(frame("blackboard", { op: "read" }, 2));
+  await tick();
+  const readReply = lastReply(conn);
+  assert.equal(readReply.op, "read");
+  assert.equal(readReply.scope, undefined, "reply must not echo the (secret) capability scope");
+  const entries = readReply.entries;
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0]?.body, "hello");
+  assert.equal(entries[0]?.authorTask, "t1");
+  assert.equal(readReply.cursor, entries[0]?.id);
+
+  await hub.close();
+});
+
+test("the read reply echoes the request seq for correlation", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  attachBlackboardFamily(hub, new BlackboardStore(openTestDb()));
+  const conn = connect(transport, "c1", "peer-a");
+  await tick();
+
+  conn.receive(frame("blackboard", { op: "read" }, 77));
+  await tick();
+  assert.equal(conn.sent.at(-1)?.seq, 77);
+
+  await hub.close();
+});
+
+test("a dedupeKey append is idempotent across a retry over the channel", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  const store = new BlackboardStore(openTestDb());
+  attachBlackboardFamily(hub, store);
+  const conn = connect(transport, "c1", "peer-a");
+  await tick();
+
+  conn.receive(frame("blackboard", { op: "append", body: "once", dedupeKey: "k1" }, 1));
+  await tick();
+  assert.equal(lastReply(conn).inserted, true);
+
+  conn.receive(frame("blackboard", { op: "append", body: "once (retry)", dedupeKey: "k1" }, 2));
+  await tick();
+  const retry = lastReply(conn);
+  assert.equal(retry.inserted, false);
+  assert.equal(store.count("board-cap"), 1);
+
+  await hub.close();
+});
+
+test("a file-claim append reports a conflict with a prior sibling claim", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  attachBlackboardFamily(hub, new BlackboardStore(openTestDb()));
+
+  // Both peers share the same capability → the same board.
+  const a = connect(transport, "c1", "peer-a");
+  const b = connect(transport, "c2", "peer-b");
+  await tick();
+
+  a.receive(frame("blackboard", { op: "append", authorTask: "t1", kind: "file-claim", files: ["state.rs"], body: "t1" }, 1));
+  await tick();
+  assert.deepEqual(lastReply(a).conflicts, [], "first claimer sees no conflict");
+
+  b.receive(frame("blackboard", { op: "append", authorTask: "t2", kind: "file-claim", files: ["state.rs"], body: "t2" }, 1));
+  await tick();
+  const conflicts = lastReply(b).conflicts;
+  assert.equal(conflicts.length, 1);
+  assert.equal(conflicts[0]?.file, "state.rs");
+  assert.equal(conflicts[0]?.authorTask, "t1");
+
+  await hub.close();
+});
+
+test("boards are isolated by capability scope", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  const store = new BlackboardStore(openTestDb());
+  attachBlackboardFamily(hub, store);
+
+  const a = connect(transport, "c1", "peer-a", "cap-A");
+  const b = connect(transport, "c2", "peer-b", "cap-B");
+  await tick();
+
+  a.receive(frame("blackboard", { op: "append", body: "a-only" }, 1));
+  b.receive(frame("blackboard", { op: "append", body: "b-only" }, 1));
+  await tick();
+
+  a.receive(frame("blackboard", { op: "read" }, 2));
+  await tick();
+  const aEntries = lastReply(a).entries;
+  assert.deepEqual(aEntries.map((e: { body: string }) => e.body), ["a-only"]);
+
+  b.receive(frame("blackboard", { op: "read" }, 2));
+  await tick();
+  const bEntries = lastReply(b).entries;
+  assert.deepEqual(bEntries.map((e: { body: string }) => e.body), ["b-only"]);
+
+  await hub.close();
+});
+
+test("a connection with no capability scope is rejected and never touches the store", async () => {
+  const transport = new FakeTransport();
+  const errors: unknown[] = [];
+  // Authenticator that grants without requiring a credential, so scope is absent.
+  const noCredAuth = sharedSecretAuthenticator({ secret: "s3cret", requireCredential: false });
+  const hub = new AgenticHub({ transport, authenticator: noCredAuth, sweepIntervalMs: 0 });
+  const store = new BlackboardStore(openTestDb());
+  attachBlackboardFamily(hub, store, { onError: (e) => errors.push(e) });
+
+  const conn = new FakeConnection("c1", { token: "s3cret", remote: "peer-a" });
+  transport.accept(conn);
+  await tick();
+  conn.receive(frame("blackboard", { op: "append", body: "x" }, 1));
+  await tick();
+
+  assert.equal(store.count(""), 0);
+  assert.equal(conn.sent.length, 0, "no reply for a scopeless connection");
+  assert.equal(errors.length, 1);
+  assert.ok(errors[0] instanceof BlackboardScopeError);
+
+  await hub.close();
+});
+
+test("a malformed blackboard payload 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 BlackboardStore(openTestDb());
+  attachBlackboardFamily(hub, store, { onError: (e) => errors.push(e) });
+  const conn = connect(transport, "c1", "peer-a");
+  await tick();
+
+  // Bad op.
+  conn.receive(frame("blackboard", { op: "delete" }, 1));
+  await tick();
+  // append with a blank body.
+  conn.receive(frame("blackboard", { op: "append", body: "   " }, 2));
+  await tick();
+
+  // file-claim whose files[] carries a non-string: must be rejected outright, not
+  // silently coerced to its string subset (which would store an incomplete claim
+  // and skew conflict detection).
+  conn.receive(
+    frame("blackboard", { op: "append", authorTask: "t1", kind: "file-claim", files: ["a.rs", 123], body: "t1" }, 3),
+  );
+  await tick();
+
+  assert.equal(store.count("board-cap"), 0);
+  assert.equal(errors.length, 3);
+  assert.ok(errors.every((e) => e instanceof BlackboardPayloadError));
+
+  await hub.close();
+});
+
+test("the blackboard family composes with a second family through the seam", async () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  attachBlackboardFamily(hub, new BlackboardStore(openTestDb()));
+  // A second, distinct family attaches through the same seam with no shared edit.
+  const heartbeats: string[] = [];
+  hub.registerFamilyHandler("heartbeat", (f) => {
+    heartbeats.push(JSON.stringify(f.payload));
+  });
+  assert.deepEqual(hub.router.families().sort(), ["blackboard", "heartbeat"]);
+
+  const conn = connect(transport, "c1", "peer-a");
+  await tick();
+  conn.receive(frame("blackboard", { op: "read" }, 1));
+  conn.receive(frame("heartbeat", { instance: "w-1" }, 2));
+  await tick();
+
+  assert.equal(conn.sent.at(-1)?.family, "blackboard", "the blackboard frame routed to the blackboard handler");
+  assert.deepEqual(heartbeats, ['{"instance":"w-1"}'], "the heartbeat frame routed to its own handler");
+
+  await hub.close();
+});
+
+test("attaching a second blackboard module to the same hub is rejected", () => {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({ transport, authenticator: auth, sweepIntervalMs: 0 });
+  attachBlackboardFamily(hub, new BlackboardStore(openTestDb()));
+  assert.throws(() => attachBlackboardFamily(hub, new BlackboardStore(openTestDb())), DuplicateFamilyHandlerError);
+});

package/src/blackboard/family.ts

@@ -0,0 +1,208 @@
+/**
+ * The blackboard family module — S7's self-contained attachment to the S1 hub.
+ *
+ * This module owns the `blackboard` message family. 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 family
+ * modules (S2 presence, S5 relay) with no shared edit.
+ *
+ * It promotes nano-workforce's per-plan blackboard HTTP hook to a first-class,
+ * capability-scoped channel family. Two operations ride the one `blackboard`
+ * family, distinguished by `payload.op`:
+ *
+ *  - `append` — idempotently write an entry (kinds `file-claim`,
+ *    `constraint-change`, `scope-change`, `learning`, `note`). The reply carries
+ *    `{ inserted, id, conflicts }`; for a `file-claim`, `conflicts` lists prior
+ *    claims by OTHER authors on the same files (first-writer-wins, advisory).
+ *  - `read` — return the board's entries after `since` plus the head `cursor`
+ *    for incremental polling.
+ *
+ * The board `scope` is CAPABILITY-DERIVED: by default it is the connection's
+ * capability credential (the same credential the S1 handshake gated on — the
+ * per-board token nano-workforce's hook already uses as the credential). A
+ * connection can therefore only read/write the board its capability authorises,
+ * with no board id trusted from the payload. Override {@link BlackboardFamilyOptions.scopeOf}
+ * to derive the scope differently (e.g. from an ADR 0028 grant scope).
+ *
+ * Replies ride the control/facts lane so a blackboard write is never
+ * head-of-line-blocked behind a bulk-output storm (invariant 5).
+ */
+import { validatePayload } from "../protocol/index.ts";
+import type { Frame } from "../protocol/index.ts";
+import type { AgenticHub, HubConnection } from "../channel/index.ts";
+import type { BlackboardInput, BlackboardStore, ClaimConflict } from "./store.ts";
+
+export interface BlackboardFamilyOptions {
+  /**
+   * Resolve the board `scope` for a connection. Default: the capability
+   * credential presented at the handshake (`handshake.credential` or the
+   * `?capability=` query param) — so each distinct capability is its own board,
+   * exactly as nano-workforce's per-plan token is. Return `undefined` to reject
+   * the frame (the connection is not scoped to any board).
+   */
+  scopeOf?: (ctx: HubConnection) => string | undefined;
+  /**
+   * Notified of a fault this module handles while keeping the connection: a
+   * malformed blackboard payload ({@link BlackboardPayloadError}), a missing
+   * board scope, or a store error. Other exceptions propagate to {@link AgenticHub}.
+   */
+  onError?: (err: unknown, connectionId?: string) => void;
+}
+
+/** Handle to the attached blackboard family. */
+export interface BlackboardFamilyHandle {
+  /** Detach is a no-op today; present for symmetry with the other family modules. */
+  stop(): void;
+}
+
+/** A malformed blackboard payload rejected before it touches the store. */
+export class BlackboardPayloadError extends Error {
+  constructor(detail: string) {
+    super(`invalid blackboard payload: ${detail}`);
+    this.name = "BlackboardPayloadError";
+  }
+}
+
+/** Raised when a connection is not scoped to any board (no capability scope). */
+export class BlackboardScopeError extends Error {
+  constructor() {
+    super("connection is not scoped to any blackboard");
+    this.name = "BlackboardScopeError";
+  }
+}
+
+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 readStringArray(record: Record<string, unknown>, key: string): string[] | undefined {
+  const value = record[key];
+  if (!Array.isArray(value)) return undefined;
+  return value.filter((v): v is string => typeof v === "string");
+}
+
+/** The default scope resolver: the connection's capability credential. */
+function defaultScopeOf(ctx: HubConnection): string | undefined {
+  const credential = ctx.handshake.credential ?? ctx.handshake.query?.capability;
+  const scope = credential?.trim();
+  return scope !== undefined && scope !== "" ? scope : undefined;
+}
+
+/**
+ * Attach the blackboard family (`blackboard`) to `hub`, backed by `store`.
+ * Registers one handler via the S1 seam. Returns a handle for symmetry with the
+ * other family modules.
+ *
+ * @throws DuplicateFamilyHandlerError if the `blackboard` family already has a
+ *   handler on this hub (one family, one owning module).
+ */
+export function attachBlackboardFamily(
+  hub: AgenticHub,
+  store: BlackboardStore,
+  options: BlackboardFamilyOptions = {},
+): BlackboardFamilyHandle {
+  store.ensureSchema();
+  const onError = options.onError ?? (() => {});
+  const scopeOf = options.scopeOf ?? defaultScopeOf;
+
+  const reject = (connectionId: string, detail: string): void => {
+    onError(new BlackboardPayloadError(detail), connectionId);
+  };
+
+  hub.registerFamilyHandler("blackboard", (frame: Frame, ctx: HubConnection) => {
+    const payload = frame.payload;
+    const result = validatePayload("blackboard", payload);
+    if (!result.ok) {
+      reject(ctx.id, result.errors.map((e) => e.message).join("; "));
+      return;
+    }
+    if (!isPlainObject(payload)) {
+      reject(ctx.id, "not an object");
+      return;
+    }
+
+    const scope = scopeOf(ctx);
+    if (scope === undefined) {
+      onError(new BlackboardScopeError(), ctx.id);
+      return;
+    }
+
+    const op = payload.op;
+    try {
+      if (op === "read") {
+        handleRead(store, ctx, frame, scope, payload);
+        return;
+      }
+      // validatePayload already constrained op ∈ {append, read}.
+      handleAppend(store, ctx, frame, scope, payload, reject);
+    } catch (err) {
+      onError(err, ctx.id);
+    }
+  });
+
+  return {
+    stop() {},
+  };
+}
+
+function handleRead(
+  store: BlackboardStore,
+  ctx: HubConnection,
+  frame: Frame,
+  scope: string,
+  payload: Record<string, unknown>,
+): void {
+  const rawSince = payload.since;
+  const since = typeof rawSince === "number" ? rawSince : undefined;
+  const page = store.readPage(scope, { since });
+  // `scope` is NOT echoed: under the default resolver it is the connection's
+  // capability credential (a secret), and it is server-derived so the client
+  // never needs it back for routing. Echoing it would only widen its exposure
+  // to logs/recordings.
+  ctx.send(reply(frame, { op: "read", cursor: page.cursor, entries: page.entries }));
+}
+
+function handleAppend(
+  store: BlackboardStore,
+  ctx: HubConnection,
+  frame: Frame,
+  scope: string,
+  payload: Record<string, unknown>,
+  reject: (connectionId: string, detail: string) => void,
+): void {
+  const body = readString(payload, "body");
+  if (body === undefined || body.trim() === "") {
+    reject(ctx.id, "append requires a non-empty body");
+    return;
+  }
+  const files = readStringArray(payload, "files");
+  const wave = typeof payload.wave === "number" ? payload.wave : undefined;
+  const input: BlackboardInput = {
+    authorTask: readString(payload, "authorTask"),
+    kind: payload.kind,
+    files,
+    body,
+    wave,
+    dedupeKey: readString(payload, "dedupeKey"),
+  };
+  const { inserted, id } = store.append(scope, input);
+
+  // Conflict-of-intent is reported only for a file-claim carrying files: prior
+  // claims by OTHER authors on the same files, decided by insertion order
+  // (beforeId = this row's id), exactly as the HTTP hook did.
+  let conflicts: ClaimConflict[] = [];
+  if (input.kind === "file-claim" && files && files.length > 0) {
+    conflicts = store.detectFileClaimConflicts(scope, { authorTask: input.authorTask, files, beforeId: id });
+  }
+  ctx.send(reply(frame, { op: "append", inserted, id, conflicts }));
+}
+
+/** Build a control-lane blackboard reply that echoes the request `seq` for correlation. */
+function reply(request: Frame, payload: unknown): Frame {
+  return { lane: "control", family: "blackboard", seq: request.seq, payload };
+}

package/src/blackboard/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @nanobpm/agentic-blackboard — the blackboard family for the Nano agentic
+ * protocol (ADR 0056, slice S7).
+ *
+ * Promotes nano-workforce's per-plan blackboard HTTP hook to a first-class,
+ * capability-scoped `blackboard` channel-message family: a durable per-scope
+ * coordination store ({@link BlackboardStore}) with idempotent `dedupeKey`
+ * append, `file-claim` conflict reporting and `since`/cursor incremental reads,
+ * plus a self-contained family module ({@link attachBlackboardFamily}) that
+ * attaches to the S1 hub through its `registerFamilyHandler(family, handler)`
+ * seam — never a shared dispatch switch. Any Urban app gets the blackboard for
+ * free by attaching this module.
+ *
+ * The wire contract lives in `@nanobpm/agentic-protocol`; the hub in
+ * `@nanobpm/agentic-channel`. This package builds on both.
+ */
+export {
+  BlackboardStore,
+  isUniqueViolation,
+  normalizeKind,
+  systemClock,
+  BLACKBOARD_KINDS,
+} from "./store.ts";
+export type {
+  BlackboardEntry,
+  BlackboardInput,
+  BlackboardKind,
+  BlackboardPage,
+  BlackboardStoreOptions,
+  ClaimConflict,
+  Clock,
+  SqliteDb,
+} from "./store.ts";
+
+export {
+  attachBlackboardFamily,
+  BlackboardPayloadError,
+  BlackboardScopeError,
+} from "./family.ts";
+export type { BlackboardFamilyOptions, BlackboardFamilyHandle } from "./family.ts";
+
+export { BLACKBOARD_TABLE, BLACKBOARD_SCHEMA_SQL } from "./schema.ts";

package/src/blackboard/schema.test.ts

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { BLACKBOARD_SCHEMA_SQL, BLACKBOARD_TABLE } from "./schema.ts";
+import { BlackboardStore } 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/003_agentic_blackboard.sql", import.meta.url));
+
+test("the boot migration and BlackboardStore's DDL do not drift", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.equal(
+    normaliseSql(migrationSql),
+    normaliseSql(BLACKBOARD_SCHEMA_SQL),
+    "db/migrations/003_agentic_blackboard.sql must match BLACKBOARD_SCHEMA_SQL — update both together",
+  );
+});
+
+test("the boot migration is forward-only and additive (IF NOT EXISTS, no drops/alters)", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS agentic_blackboard/);
+  assert.doesNotMatch(migrationSql, /\bDROP\b/i);
+  assert.doesNotMatch(migrationSql, /\bALTER\b/i);
+});
+
+test("the migration takes prefix 003, after S2's 001 and S6's 002", () => {
+  // Numbering is a shared epic surface (see migration header). Guard the prefix so
+  // a rebase that renumbers is caught here rather than at merge time.
+  // `fileURLToPath` yields OS-native separators (backslashes on Windows), so match
+  // either separator to keep this prefix guard portable.
+  assert.match(migrationPath, /[/\\]003_agentic_blackboard\.sql$/);
+});
+
+test("ensureSchema creates the blackboard table idempotently", () => {
+  const db = openTestDb();
+  const store = new BlackboardStore(db);
+  store.ensureSchema();
+  store.ensureSchema();
+  const tables = db.all<{ name: string }>("SELECT name FROM sqlite_master WHERE type='table' AND name = ?", [
+    BLACKBOARD_TABLE,
+  ]);
+  assert.equal(tables.length, 1);
+  db.close();
+});

package/src/blackboard/schema.ts

@@ -0,0 +1,44 @@
+/**
+ * The canonical blackboard schema.
+ *
+ * The DDL here is the single source of truth the {@link BlackboardStore} applies
+ * through {@link BlackboardStore.ensureSchema}. The very same statements are
+ * mirrored in the app-boot migration `db/migrations/003_agentic_blackboard.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 table promotes nano-workforce's per-plan `plan_blackboard` HTTP hook to a
+ * first-class channel-family store: the same idempotent-append (`dedupe_key`),
+ * conflict-of-intent (`file-claim`) and incremental-read (`id`/cursor) semantics,
+ * generalised from a hard-wired `plan_key` to a capability-derived `scope` so any
+ * Urban app gets it for free.
+ */
+
+/** The blackboard table name. */
+export const BLACKBOARD_TABLE = "agentic_blackboard";
+
+/**
+ * The canonical blackboard DDL. Forward-only and additive; every column added
+ * here must also be added to the boot migration (the drift guard enforces it).
+ *
+ * Idempotency: the partial UNIQUE index over `(scope, dedupe_key)` (NULLs
+ * excluded, so a dedupe-less note always appends) collapses a re-POST carrying a
+ * stable `dedupe_key` to one row — the engine may re-activate a job on retry, so
+ * a repeated append must be a no-op. `(scope, id)` lists a board's entries in
+ * write order and drives the `since`/cursor incremental read.
+ */
+export const BLACKBOARD_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${BLACKBOARD_TABLE} (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  scope       TEXT NOT NULL,
+  author_task TEXT NOT NULL DEFAULT 'system',
+  kind        TEXT NOT NULL DEFAULT 'note',
+  files       TEXT,
+  body        TEXT NOT NULL,
+  wave        INTEGER,
+  dedupe_key  TEXT,
+  created_at  TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS ux_${BLACKBOARD_TABLE}_dedupe ON ${BLACKBOARD_TABLE} (scope, dedupe_key) WHERE dedupe_key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_${BLACKBOARD_TABLE}_scope ON ${BLACKBOARD_TABLE} (scope, id);`;