@nanobpm/nano-workforce 0.53.0 → 0.54.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.54.0](https://github.com/nanobpm/nano-workforce/compare/v0.53.0...v0.54.0) (2026-08-13)
+
+
+### Features
+
+* generalize the advisory blackboard onto the agentic channel (H4) ([#166](https://github.com/nanobpm/nano-workforce/issues/166)) ([450a4fa](https://github.com/nanobpm/nano-workforce/commit/450a4fa4a75ad1cdc2a78eef6f95aa2f45bebb9f)), closes [#147](https://github.com/nanobpm/nano-workforce/issues/147) [#147](https://github.com/nanobpm/nano-workforce/issues/147) [#143](https://github.com/nanobpm/nano-workforce/issues/143)
+
 # [0.53.0](https://github.com/nanobpm/nano-workforce/compare/v0.52.0...v0.53.0) (2026-08-13)
 
 

package/app/agentic/families/blackboard.family.test.ts

@@ -0,0 +1,189 @@
+// Tests for H4's channel-side `blackboard` family module (#147). These prove the generalized
+// agentic-channel path is a faithful bridge to the SAME per-plan board the HTTP hook serves:
+//   - a channel `append` frame writes the very rows `readBlackboard(data, planKey)` (the HTTP path)
+//     reads back — one canonical store, no drift surface;
+//   - `file-claim` conflict-of-intent is reported on the channel exactly as over HTTP;
+//   - board scope is capability-derived (the plan's blackboard token → plan_key), so a connection
+//     only ever touches the board its credential authorises;
+//   - an unknown/absent credential is rejected (advisory — the frame is dropped, never a hard-lock).
+import test from "node:test";
+import { AgenticHub, type HubConnection, sharedSecretAuthenticator } from "@nanobpm/agentic/channel";
+import type { ChannelTransport, HandshakeRequest } from "@nanobpm/agentic/channel";
+import type { Frame } from "@nanobpm/agentic/protocol";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../../test/log.ts";
+import { memBlackboardData } from "../../../test/blackboardDb.ts";
+import { readBlackboard } from "../../blackboard.ts";
+import type { AgenticContext } from "../registry.ts";
+import { family } from "./blackboard.family.ts";
+
+/** A do-nothing transport just to satisfy the hub constructor; the tests drive the router directly. */
+function fakeTransport(): ChannelTransport {
+  return {
+    onConnection() {},
+    address: null,
+    async close() {},
+  };
+}
+
+/** Build a hub + mount the blackboard family over a real in-memory DataLayer. */
+function mountFamily() {
+  const { data, db, close } = memBlackboardData();
+  const hub = new AgenticHub({
+    transport: fakeTransport(),
+    authenticator: sharedSecretAuthenticator({ secret: "s3cr3t" }),
+    sweepIntervalMs: 0,
+  });
+  const ctx: AgenticContext = {
+    hub,
+    registry: hub.registry,
+    // The blackboard family never touches the transport; a minimal stand-in is enough.
+    transport: undefined as unknown as AgenticContext["transport"],
+    data,
+    log: noopLog(),
+  };
+  family.mount(ctx);
+  return { hub, data, db, close };
+}
+
+/** A HubConnection whose sends are captured, presenting `credential` at the handshake. */
+function conn(hub: AgenticHub, credential: string | undefined, sent: Frame[]): HubConnection {
+  const handshake: HandshakeRequest = credential === undefined ? {} : { credential };
+  return {
+    id: `c-${credential ?? "anon"}`,
+    identity: "peer",
+    handshake,
+    registry: hub.registry,
+    send: (frame) => sent.push(frame),
+    close() {},
+  };
+}
+
+function seedToken(db: { run(sql: string, params?: unknown[]): unknown }, planKey: string, token: string): void {
+  db.run("INSERT INTO plans (plan_key, blackboard_token) VALUES (?, ?)", [planKey, token]);
+}
+
+function appendFrame(seq: number, payload: Record<string, unknown>): Frame {
+  return { lane: "control", family: "blackboard", seq, payload: { op: "append", ...payload } };
+}
+
+function readFrame(seq: number, since?: number): Frame {
+  return { lane: "control", family: "blackboard", seq, payload: since === undefined ? { op: "read" } : { op: "read", since } };
+}
+
+test("channel append writes the SAME board the HTTP readBlackboard path reads", async () => {
+  const { hub, data, db, close } = mountFamily();
+  try {
+    seedToken(db, "o/r#1", "tok-1");
+    const sent: Frame[] = [];
+    const c = conn(hub, "tok-1", sent);
+
+    const ran = await hub.router.route(
+      appendFrame(1, { authorTask: "gap-2", kind: "note", body: "hello board" }),
+      c,
+    );
+    assertEquals(ran, true);
+    assertEquals(sent.length, 1);
+    const reply = sent[0].payload as { op: string; inserted: boolean; id: number };
+    assertEquals(reply.op, "append");
+    assertEquals(reply.inserted, true);
+    assert(reply.id > 0);
+
+    // Parity: the HTTP-side reader sees exactly what the channel wrote, under the same plan scope.
+    const entries = await readBlackboard(data, "o/r#1");
+    assertEquals(entries.length, 1);
+    assertEquals(entries[0].author_task, "gap-2");
+    assertEquals(entries[0].body, "hello board");
+    assertEquals(entries[0].kind, "note");
+  } finally {
+    await hub.close();
+    close();
+  }
+});
+
+test("channel file-claim reports conflicts with a prior claim by another author", async () => {
+  const { hub, data, db, close } = mountFamily();
+  try {
+    seedToken(db, "o/r#1", "tok-1");
+    const sent: Frame[] = [];
+    const c = conn(hub, "tok-1", sent);
+
+    await hub.router.route(
+      appendFrame(1, { authorTask: "gap-1", kind: "file-claim", files: ["engine/state.rs"], body: "own state.rs" }),
+      c,
+    );
+    await hub.router.route(
+      appendFrame(2, { authorTask: "gap-2", kind: "file-claim", files: ["engine/state.rs"], body: "also want state.rs" }),
+      c,
+    );
+
+    const second = sent[1].payload as { conflicts: { authorTask: string; file: string }[] };
+    assertEquals(second.conflicts.length, 1);
+    assertEquals(second.conflicts[0].authorTask, "gap-1");
+    assertEquals(second.conflicts[0].file, "engine/state.rs");
+
+    // And both rows landed on the shared board.
+    const entries = await readBlackboard(data, "o/r#1");
+    assertEquals(entries.length, 2);
+  } finally {
+    await hub.close();
+    close();
+  }
+});
+
+test("channel read returns entries appended over HTTP (bidirectional bridge parity)", async () => {
+  const { hub, data, db, close } = mountFamily();
+  try {
+    seedToken(db, "o/r#1", "tok-1");
+    // Write via the HTTP-path adapter…
+    const { appendEntry } = await import("../../blackboard.ts");
+    await appendEntry(data, "o/r#1", { author_task: "gap-3", kind: "note", body: "via http" });
+
+    // …and read it back over the channel.
+    const sent: Frame[] = [];
+    const ran = await hub.router.route(readFrame(9), conn(hub, "tok-1", sent));
+    assertEquals(ran, true);
+    const reply = sent[0].payload as { op: string; entries: { authorTask: string; body: string }[] };
+    assertEquals(reply.op, "read");
+    assertEquals(reply.entries.length, 1);
+    assertEquals(reply.entries[0].authorTask, "gap-3");
+    assertEquals(reply.entries[0].body, "via http");
+  } finally {
+    await hub.close();
+    close();
+  }
+});
+
+test("an unknown credential is rejected — no board is touched, no reply sent", async () => {
+  const { hub, data, db, close } = mountFamily();
+  try {
+    seedToken(db, "o/r#1", "tok-1");
+    const sent: Frame[] = [];
+    const ran = await hub.router.route(
+      appendFrame(1, { authorTask: "gap-2", kind: "note", body: "should not land" }),
+      conn(hub, "bogus-token", sent),
+    );
+    assertEquals(ran, true); // the handler ran (and rejected) — the family owns the frame
+    assertEquals(sent.length, 0); // no reply: scope could not be resolved
+    // Nothing was written under any scope.
+    const [{ n }] = db.all<{ n: number }>("SELECT COUNT(*) AS n FROM agentic_blackboard");
+    assertEquals(n, 0);
+    assertEquals((await readBlackboard(data, "o/r#1")).length, 0);
+  } finally {
+    await hub.close();
+    close();
+  }
+});
+
+test("an absent credential is rejected too", async () => {
+  const { hub, db, close } = mountFamily();
+  try {
+    seedToken(db, "o/r#1", "tok-1");
+    const sent: Frame[] = [];
+    await hub.router.route(appendFrame(1, { kind: "note", body: "x" }), conn(hub, undefined, sent));
+    assertEquals(sent.length, 0);
+  } finally {
+    await hub.close();
+    close();
+  }
+});

package/app/agentic/families/blackboard.family.ts

@@ -0,0 +1,69 @@
+// nano-workforce — the agentic-channel `blackboard` family (ADR 0056, H4 / #147).
+//
+// This is H4's ONE new file plugged into the H0 (#143) family-registration seam. It mounts
+// `@nanobpm/agentic/blackboard`'s `blackboard` message family on the app-tier hub, backed by the
+// SAME `BlackboardStore` — over the SAME app SQLite DataLayer (`ctx.data.source().db`) — that the
+// legacy `/app/api/hooks/blackboard` HTTP hook now uses (see `app/blackboard.ts`). One canonical
+// store, one table (`agentic_blackboard`), reached two ways: the HTTP side-channel and the agentic
+// channel serve the identical per-plan board with no drift surface.
+//
+// Board scope parity: the family derives each connection's board `scope` from its capability
+// credential — the per-plan blackboard token — resolved back to its `plan_key` via
+// `planKeyForTokenSync`, EXACTLY as the HTTP hook resolves `?token=` to a plan. So a channel client
+// and an HTTP caller holding the same plan token read/write the very same rows. An unknown/absent
+// credential yields no scope and the frame is rejected (advisory — never a hard-lock, never gates a
+// BPMN sequence flow).
+//
+// Adds NO migration of its own: H4's reserved `db/migrations/025_agentic_blackboard.sql` (owned by
+// the app-side adapter) creates `agentic_blackboard`; `store.ensureSchema()` here is the idempotent
+// belt-and-braces the store's own contract expects.
+import { attachBlackboardFamily, BlackboardStore } from "@nanobpm/agentic/blackboard";
+import type { HubConnection } from "@nanobpm/agentic/channel";
+import { planKeyForTokenSync } from "../../blackboard.ts";
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+
+/** The capability-credential a connection presents at the handshake (the blackboard token). */
+function credentialOf(conn: HubConnection): string {
+  return (conn.handshake.credential ?? conn.handshake.query?.capability ?? "").trim();
+}
+
+let handle: { stop(): void } | undefined;
+
+/**
+ * The `blackboard` family module. `mount` attaches the family to the hub when the app has a data
+ * layer; without one (data isn't mounted) it is a no-op — the channel simply serves no blackboard,
+ * exactly as the HTTP hook would 404. `teardown` detaches it.
+ */
+export const family: AgenticFamily = {
+  name: "blackboard",
+  mount(ctx: AgenticContext): void {
+    // Stop any previously-attached family before (re)mounting, so a repeat mount() (tests or a
+    // future remount path) can't leave stale handlers attached and double-handle frames / leak
+    // resources. Done unconditionally — before the data check — so even a no-data remount detaches
+    // the prior handle instead of silently leaving it live.
+    handle?.stop();
+    handle = undefined;
+    const data = ctx.data;
+    if (!data) {
+      ctx.log.warn("agentic blackboard family: no data layer; not mounting");
+      return;
+    }
+    const db = data.source().db;
+    const store = new BlackboardStore(db);
+    store.ensureSchema();
+    handle = attachBlackboardFamily(ctx.hub, store, {
+      // Scope every board to the plan the credential's token maps to — the same plan the HTTP hook
+      // scopes to — so the two paths share one board. Returning undefined rejects the frame.
+      scopeOf: (conn) => planKeyForTokenSync(db, credentialOf(conn)),
+      onError: (err, connectionId) =>
+        ctx.log.warn("agentic blackboard family error", { connectionId, err: String(err) }),
+    });
+    ctx.log.info("agentic blackboard family mounted");
+  },
+  teardown(): void {
+    handle?.stop();
+    handle = undefined;
+  },
+};
+
+export default family;

package/app/blackboard.schema.test.ts

@@ -0,0 +1,21 @@
+// Schema-drift guard (#147). The `db/migrations/025_agentic_blackboard.sql` CREATE statements MUST be
+// the canonical `BLACKBOARD_SCHEMA_SQL` verbatim — the exact DDL `@nanobpm/agentic/blackboard`'s
+// `BlackboardStore.ensureSchema()` (and the agentic-channel family) apply. If the two ever drift, a
+// board created by a migration on one host and by `ensureSchema()` on another would disagree — this
+// test fails the build before that can ship.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+import { BLACKBOARD_SCHEMA_SQL } from "@nanobpm/agentic/blackboard";
+import { assert, assertEquals } from "#test-assert";
+
+test("migration 025 CREATE statements equal BLACKBOARD_SCHEMA_SQL verbatim", () => {
+  const path = fileURLToPath(new URL("../db/migrations/025_agentic_blackboard.sql", import.meta.url));
+  const sql = readFileSync(path, "utf8");
+  const start = sql.indexOf("CREATE TABLE IF NOT EXISTS agentic_blackboard");
+  const end = sql.indexOf("(scope, id);");
+  assert(start !== -1, "migration 025 is missing the `CREATE TABLE IF NOT EXISTS agentic_blackboard` marker");
+  assert(end !== -1, "migration 025 is missing the `(scope, id);` index marker");
+  const createBlock = sql.slice(start, end + "(scope, id);".length).trim();
+  assertEquals(createBlock, BLACKBOARD_SCHEMA_SQL.trim());
+});

package/app/blackboard.test.ts

@@ -1,7 +1,12 @@
 // Unit tests for the epic coordination blackboard (Tier 1, issues #51 / #49 D4).
+//
+// H4 (#147) migrated the storage onto `@nanobpm/agentic/blackboard`'s shared `BlackboardStore`
+// (table `agentic_blackboard`), reached over the app DataLayer's raw SQLite handle. These tests run
+// the adapter against a REAL in-memory SQLite engine (see `test/blackboardDb.ts`), so the
+// idempotency, conflict, and incremental-read behaviour is verified end-to-end, not against a mock.
 import { test } from "node:test";
 import { assert, assertEquals, assertStringIncludes } from "#test-assert";
-import type { DataLayer } from "@nanobpm/urban";
+import { memBlackboardData } from "../test/blackboardDb.ts";
 import {
   appendEntry,
   blackboardUrl,
@@ -10,41 +15,13 @@ import {
   mintBlackboardToken,
   normalizeKind,
   planKeyForToken,
+  planKeyForTokenSync,
   publicBaseUrl,
   readBlackboard,
   readBlackboardPage,
   renderCoordinationBrief,
 } from "./blackboard.ts";
 
-// A tiny in-memory stand-in for the record gateway, matching the subset of the Table<T> API the
-// blackboard uses (insert/find/findOne). Mirrors the fake-app style used across the app tests.
-function memData(): { data: DataLayer; stores: Record<string, any[]> } {
-  const stores: Record<string, any[]> = {};
-  const seq: Record<string, number> = {};
-  function tbl(name: string, pk = "id") {
-    const rows = (stores[name] ??= [] as any[]);
-    return {
-      async insert(row: any) {
-        if (pk === "id") {
-          const id = (seq[name] = (seq[name] ?? 0) + 1);
-          rows.push({ id, ...row });
-          return id;
-        }
-        rows.push({ ...row });
-        return row[pk];
-      },
-      async find(where: any = {}) {
-        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
-      },
-      async findOne(where: any = {}) {
-        return rows.find((r) => Object.entries(where).every(([k, v]) => r[k] === v));
-      },
-    };
-  }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
-  return { data, stores };
-}
-
 test("mintBlackboardToken: URL-safe, unguessable, unique", () => {
   const a = mintBlackboardToken();
   const b = mintBlackboardToken();
@@ -106,16 +83,21 @@ test("renderCoordinationBrief: leads with a separator and teaches the protocol +
   assertStringIncludes(brief, "Share what you learn");
 });
 
-test("planKeyForToken: resolves a token to its plan, undefined otherwise", async () => {
-  const { data } = memData();
+test("planKeyForToken: resolves a token to its plan, undefined otherwise (async + sync agree)", async () => {
+  const { data, db } = memBlackboardData();
   await data.table("plans", "plan_key").insert({ plan_key: "o/r#7", blackboard_token: "tok7" });
   assertEquals(await planKeyForToken(data, "tok7"), "o/r#7");
   assertEquals(await planKeyForToken(data, "nope"), undefined);
   assertEquals(await planKeyForToken(data, ""), undefined);
+  // The sync resolver (used by the agentic channel's scopeOf) resolves the identical mapping, so the
+  // HTTP hook and the channel scope a plan's board to the same plan_key.
+  assertEquals(planKeyForTokenSync(db, "tok7"), "o/r#7");
+  assertEquals(planKeyForTokenSync(db, "nope"), undefined);
+  assertEquals(planKeyForTokenSync(db, ""), undefined);
 });
 
 test("appendEntry + readBlackboard: append, encode files, read back in write order", async () => {
-  const { data } = memData();
+  const { data } = memBlackboardData();
   await appendEntry(data, "o/r#1", { author_task: "gap-2", kind: "file-claim", files: ["a.rs"], body: "touches a.rs" });
   await appendEntry(data, "o/r#1", { author_task: "gap-8", kind: "note", body: "heads up" });
   await appendEntry(data, "o/r#2", { body: "other plan" }); // must not leak across plans
@@ -128,14 +110,14 @@ test("appendEntry + readBlackboard: append, encode files, read back in write ord
 });
 
 test("appendEntry: trims whitespace-padded file paths so stored/read values are clean", async () => {
-  const { data } = memData();
+  const { data } = memBlackboardData();
   await appendEntry(data, "p", { kind: "file-claim", files: ["  engine/state.rs  ", "\tengine/mine.rs\n"], body: "claims" });
   const [e] = await readBlackboard(data, "p");
   assertEquals(e.files, ["engine/state.rs", "engine/mine.rs"], "paths stored trimmed, not whitespace-padded");
 });
 
 test("appendEntry: a missing author defaults to 'system' and kind is normalised", async () => {
-  const { data } = memData();
+  const { data } = memBlackboardData();
   await appendEntry(data, "p", { body: "x", kind: "weird" as unknown });
   const [e] = await readBlackboard(data, "p");
   assertEquals(e.author_task, "system");
@@ -143,44 +125,30 @@ test("appendEntry: a missing author defaults to 'system' and kind is normalised"
 });
 
 test("appendEntry: idempotent on dedupe_key (a job retry re-POST is a no-op)", async () => {
-  const { data, stores } = memData();
+  const { data, db } = memBlackboardData();
   const first = await appendEntry(data, "p", { author_task: "t", body: "claim", dedupe_key: "t:claim:1" });
   const again = await appendEntry(data, "p", { author_task: "t", body: "claim", dedupe_key: "t:claim:1" });
   assertEquals(first.inserted, true);
   assertEquals(again.inserted, false, "second write with same dedupe_key is a no-op");
   assertEquals(again.id, first.id, "returns the existing id");
-  assertEquals(stores["plan_blackboard"].length, 1, "exactly one row persisted");
+  const [{ n }] = db.all<{ n: number }>("SELECT COUNT(*) AS n FROM agentic_blackboard WHERE scope = ?", ["p"]);
+  assertEquals(n, 1, "exactly one row persisted");
 });
 
-test("appendEntry: a lost UNIQUE race collapses to a no-op instead of a 500", async () => {
-  // Simulate the concurrency window: two POSTs share a dedupe_key, both miss the findOne
-  // pre-check, then insert loses the race on the UNIQUE (plan_key, dedupe_key) index. The
-  // catch branch must re-read the winner's row and return it rather than propagate the throw.
-  const winner = { id: 42, plan_key: "p", dedupe_key: "t:claim:1", author_task: "t", body: "claim" };
-  let preCheckDone = false;
-  const table: any = {
-    async findOne() {
-      // Pre-check misses (row not yet visible); the recovery read after the collision hits.
-      if (!preCheckDone) {
-        preCheckDone = true;
-        return undefined;
-      }
-      return winner;
-    },
-    async insert() {
-      throw Object.assign(new Error("UNIQUE constraint failed: plan_blackboard.dedupe_key"), {
-        code: "SQLITE_CONSTRAINT_UNIQUE",
-      });
-    },
-  };
-  const data = { table: () => table } as any as DataLayer;
-  const res = await appendEntry(data, "p", { author_task: "t", body: "claim", dedupe_key: "t:claim:1" });
-  assertEquals(res.inserted, false, "a lost race is not a fresh insert");
-  assertEquals(res.id, 42, "returns the winning row's id");
+test("appendEntry: a repeat dedupe_key collapses to the existing row instead of a fresh insert", async () => {
+  // The store's idempotent short-circuit (and its lost-UNIQUE-race recovery) means re-appending a
+  // fact under a stable dedupe_key returns the winning row as inserted:false rather than throwing —
+  // an engine job retry never duplicates or 500s.
+  const { data } = memBlackboardData();
+  const winner = await appendEntry(data, "p", { author_task: "t", body: "claim", dedupe_key: "t:claim:1" });
+  assertEquals(winner.inserted, true);
+  const retry = await appendEntry(data, "p", { author_task: "t", body: "claim", dedupe_key: "t:claim:1" });
+  assertEquals(retry.inserted, false, "a repeat is not a fresh insert");
+  assertEquals(retry.id, winner.id, "returns the winning row's id");
 });
 
 test("appendEntry: a blank body is rejected", async () => {
-  const { data } = memData();
+  const { data } = memBlackboardData();
   let threw = false;
   try {
     await appendEntry(data, "p", { body: "   " });
@@ -191,7 +159,7 @@ test("appendEntry: a blank body is rejected", async () => {
 });
 
 test("readBlackboard: since returns only newer entries (incremental poll)", async () => {
-  const { data } = memData();
+  const { data } = memBlackboardData();
   await appendEntry(data, "p", { body: "one" });
   await appendEntry(data, "p", { body: "two" });
   await appendEntry(data, "p", { body: "three" });
@@ -201,7 +169,7 @@ test("readBlackboard: since returns only newer entries (incremental poll)", asyn
 });
 
 test("readBlackboardPage: cursor is the plan head and lets an agent poll to caught-up (Tier 2)", async () => {
-  const { data } = memData();
+  const { data } = memBlackboardData();
   await appendEntry(data, "p", { body: "one" });
   await appendEntry(data, "p", { body: "two" });
 
@@ -222,14 +190,14 @@ test("readBlackboardPage: cursor is the plan head and lets an agent poll to caug
 });
 
 test("readBlackboardPage: an empty plan yields no entries and a zero cursor", async () => {
-  const { data } = memData();
+  const { data } = memBlackboardData();
   const page = await readBlackboardPage(data, "empty");
   assertEquals(page.entries, []);
   assertEquals(page.cursor, 0);
 });
 
 test("detectFileClaimConflicts: a sibling's prior claim on the same file is surfaced", async () => {
-  const { data } = memData();
+  const { data } = memBlackboardData();
   await appendEntry(data, "p", { author_task: "gap-2", kind: "file-claim", files: ["engine/state.rs"], body: "owns state.rs" });
 
   const conflicts = await detectFileClaimConflicts(data, "p", {
@@ -242,7 +210,7 @@ test("detectFileClaimConflicts: a sibling's prior claim on the same file is surf
 });
 
 test("detectFileClaimConflicts: your own prior claim and non-file-claim entries are not conflicts", async () => {
-  const { data } = memData();
+  const { data } = memBlackboardData();
   await appendEntry(data, "p", { author_task: "gap-2", kind: "file-claim", files: ["a.rs"], body: "my earlier claim" });
   await appendEntry(data, "p", { author_task: "gap-8", kind: "note", files: ["a.rs"], body: "just a note about a.rs" });
 
@@ -256,7 +224,7 @@ test("detectFileClaimConflicts: your own prior claim and non-file-claim entries
 });
 
 test("detectFileClaimConflicts: beforeId restricts to strictly prior claims (insertion order wins)", async () => {
-  const { data } = memData();
+  const { data } = memBlackboardData();
   const prior = await appendEntry(data, "p", {
     author_task: "gap-2",
     kind: "file-claim",

package/app/blackboard.ts

@@ -2,42 +2,43 @@
 //
 // A per-plan advisory shared store. Implementer agents (`senior:feature`) READ it on dispatch and
 // WRITE to it during/after their work — "I now also touch state.rs", "constraint X changed
-// direction Y" — so parallel siblings in a wave can coordinate without a human relay. It is the
-// machine-actionable substrate the #614 retro's "structured coordination channel" asked for.
+// direction Y" — so parallel siblings in a wave can coordinate without a human relay.
 //
-// Design invariants:
+// H4 (#147, ADR 0056) GENERALISED the storage onto `@nanobpm/agentic/blackboard`'s first-class,
+// capability-scoped `BlackboardStore` (table `agentic_blackboard`) — the SAME store the new
+// agentic-channel `blackboard` family serves, over the SAME app SQLite DataLayer. This module is now
+// the app-side ADAPTER: it keeps the exact HTTP-hook surface (snake_case entries, `plan_key` scope,
+// token→plan resolution) callers already depend on — `operations/{appendBlackboard,readBlackboard}`,
+// `app/retro.ts`, `app/plan.ts`, `workers/record-wave` — while the append/read/dedupe/conflict
+// SEMANTICS live once in the shared store (no drift surface). The idempotency, `file-claim`
+// conflict reporting, and `since`/cursor incremental-read behaviour are identical to before because
+// the store is a faithful port of the original `plan_blackboard` logic.
+//
+// Design invariants (unchanged):
 //   - ADVISORY ONLY. Never gate a sequence flow on a blackboard read; the BPMN stays the
 //     control-flow source of truth. This store is shared *knowledge*, read fresh, and is not part
 //     of deterministic replay.
 //   - IDEMPOTENT write-back. The engine may re-activate a job on retry, so a re-POST carrying a
-//     stable `dedupe_key` is a no-op (backed by a unique index; we also short-circuit here).
+//     stable `dedupe_key` is a no-op (backed by a unique index; the store also short-circuits).
 //   - CAPABILITY URL. The per-plan token IS the credential; the agent curls the exact URL it was
 //     handed (delivered in `appendPrompt`). Delivery is in-band (rides the prompt the harness
 //     already forwards); use is out-of-band (a direct side-channel to `/app/api/hooks/blackboard`).
 //
-// Data access goes through the record gateway (`data.table`), never hand-written SQL — matching
-// app/service.ts and app/plan.ts.
-import type { DataLayer } from "@nanobpm/urban";
+// Storage goes through the shared `BlackboardStore` over the app DataLayer's raw synchronous SQLite
+// handle (`data.source().db`) — the same physical database the record gateway (`data.table`) uses,
+// so the HTTP hook and the agentic channel share one connection and one table.
 
-const now = () => new Date().toISOString();
+import { BlackboardStore, type SqliteDb } from "@nanobpm/agentic/blackboard";
+import type { DataLayer } from "@nanobpm/urban";
 
-export const BLACKBOARD_KINDS = ["file-claim", "constraint-change", "scope-change", "learning", "note"] as const;
-export type BlackboardKind = (typeof BLACKBOARD_KINDS)[number];
+// Re-export the storage vocabulary from the shared package so there is ONE canonical definition of
+// the kinds, the kind-normaliser, and the unique-violation predicate — the app never keeps a
+// parallel copy that could drift from the store's own semantics.
+export type { BlackboardKind } from "@nanobpm/agentic/blackboard";
+export { BLACKBOARD_KINDS, isUniqueViolation, normalizeKind } from "@nanobpm/agentic/blackboard";
 
-/** The stored row shape (files is a JSON-encoded string of paths, or NULL). */
-export interface BlackboardRow {
-  id: number;
-  plan_key: string;
-  author_task: string;
-  kind: string;
-  files: string | null;
-  body: string;
-  wave: number | null;
-  dedupe_key: string | null;
-  created_at: string;
-}
-
-/** The parsed, agent-facing view of an entry (files decoded to an array). */
+/** The parsed, agent-facing view of an entry (files decoded to an array). Snake_case is the
+ * app/HTTP-hook boundary contract every existing caller and agent already consumes. */
 export interface BlackboardEntry {
   id: number;
   author_task: string;
@@ -58,11 +59,6 @@ export interface BlackboardInput {
   dedupe_key?: string;
 }
 
-/** Coerce an arbitrary `kind` to a known value, defaulting to "note" for anything unrecognised. */
-export function normalizeKind(kind: unknown): BlackboardKind {
-  return BLACKBOARD_KINDS.find((k) => k === kind) ?? "note";
-}
-
 /** A URL-safe, unguessable capability token (192 bits of randomness, base64url, no padding). */
 export function mintBlackboardToken(): string {
   const bytes = new Uint8Array(24);
@@ -157,9 +153,45 @@ coordinate, or if it genuinely blocks you, escalate a \`question\` per your norm
 here is a hard lock; the merge step is the real safety net.`;
 }
 
-const blackboardTable = (data: DataLayer) => data.table<BlackboardRow>("plan_blackboard", "id");
+// The store is a thin wrapper over the DataLayer's raw synchronous SQLite handle; construct it per
+// call (cheap — it just holds the handle). The schema is applied by boot migration
+// `025_agentic_blackboard.sql`; we also `ensureSchema()` once per handle (idempotent
+// `CREATE TABLE IF NOT EXISTS`) so the adapter works against a bare source too (e.g. unit tests over
+// an in-memory DataLayer that hasn't run migrations).
+const schemaReady = new WeakSet<object>();
+function storeFor(data: DataLayer): BlackboardStore {
+  const db = data.source().db;
+  const store = new BlackboardStore(db);
+  if (!schemaReady.has(db)) {
+    store.ensureSchema();
+    schemaReady.add(db);
+  }
+  return store;
+}
+
+/** Map the store's camelCase entry to the app/HTTP snake_case boundary shape. */
+function toEntry(e: {
+  id: number;
+  authorTask: string;
+  kind: string;
+  files: string[];
+  body: string;
+  wave: number | null;
+  createdAt: string;
+}): BlackboardEntry {
+  return {
+    id: e.id,
+    author_task: e.authorTask,
+    kind: e.kind,
+    files: e.files,
+    body: e.body,
+    wave: e.wave,
+    created_at: e.createdAt,
+  };
+}
 
-/** Resolve a capability token back to its plan, or undefined when the token is unknown. */
+/** Resolve a capability token back to its plan, or undefined when the token is unknown. Async
+ * variant over the record gateway, used by the HTTP-hook operations. */
 export async function planKeyForToken(data: DataLayer, token: string): Promise<string | undefined> {
   if (!token) return undefined;
   const row = await data
@@ -168,32 +200,24 @@ export async function planKeyForToken(data: DataLayer, token: string): Promise<s
   return row?.plan_key;
 }
 
-function decodeFiles(raw: string | null): string[] {
-  if (!raw) return [];
-  try {
-    const v = JSON.parse(raw);
-    return Array.isArray(v) ? v.map(String).map((s) => s.trim()).filter((s) => s !== "") : [];
-  } catch {
-    return [];
-  }
-}
-
-function toEntry(r: BlackboardRow): BlackboardEntry {
-  return {
-    id: r.id,
-    author_task: r.author_task,
-    kind: r.kind,
-    files: decodeFiles(r.files).map((x) => x.trim()).filter((x) => x !== ""),
-    body: r.body,
-    wave: r.wave,
-    created_at: r.created_at,
-  };
+/** Resolve a capability token back to its plan over a raw synchronous SQLite handle. The agentic
+ * channel's `blackboard` family derives its board `scope` synchronously from the connection's
+ * capability credential, so it needs this sync path (the async {@link planKeyForToken} can't be
+ * awaited in a synchronous `scopeOf`). Both resolve the SAME `plans.blackboard_token` mapping, so
+ * the channel and the HTTP hook scope every plan's board to the identical `plan_key`. */
+export function planKeyForTokenSync(db: SqliteDb, token: string): string | undefined {
+  if (!token) return undefined;
+  const rows = db.all<{ plan_key: string }>(
+    "SELECT plan_key FROM plans WHERE blackboard_token = ? LIMIT 1",
+    [token],
+  );
+  return rows[0]?.plan_key;
 }
 
 /** One incremental read: the entries after `since` (write order) plus `cursor` — the plan's current
- * head id. An agent polling midflight (Tier 2) passes `cursor` back as the next `since`, so it pulls
- * only what siblings added since its last read. `cursor` is the true head even when `since` filters
- * every entry out, so a caller that is fully caught up learns it is caught up (cursor unchanged). */
+ * head id. An agent polling midflight passes `cursor` back as the next `since`, so it pulls only
+ * what siblings added since its last read. `cursor` is the true head even when `since` filters every
+ * entry out, so a caller that is fully caught up learns it is caught up (cursor unchanged). */
 export interface BlackboardPage {
   entries: BlackboardEntry[];
   cursor: number;
@@ -204,14 +228,8 @@ export async function readBlackboardPage(
   planKey: string,
   opts: { since?: number } = {},
 ): Promise<BlackboardPage> {
-  const rows = await blackboardTable(data).find({ plan_key: planKey });
-  const cursor = rows.reduce((max, r) => (r.id > max ? r.id : max), 0);
-  const since = opts.since ?? 0;
-  const entries = rows
-    .filter((r) => r.id > since)
-    .sort((a, b) => a.id - b.id)
-    .map(toEntry);
-  return { entries, cursor };
+  const page = storeFor(data).readPage(planKey, { since: opts.since });
+  return { entries: page.entries.map(toEntry), cursor: page.cursor };
 }
 
 /** A plan's entries in write order (id asc). `since` returns only entries with `id > since`. */
@@ -247,22 +265,19 @@ export async function detectFileClaimConflicts(
   planKey: string,
   opts: { author_task?: string; files: string[]; beforeId?: number },
 ): Promise<ClaimConflict[]> {
-  const want = new Set((opts.files ?? []).map((f) => String(f).trim()).filter((s) => s !== ""));
-  if (want.size === 0) return [];
-  const me = opts.author_task?.trim() || "";
-  const beforeId = opts.beforeId;
-  const rows = await blackboardTable(data).find({ plan_key: planKey, kind: "file-claim" });
-  const out: ClaimConflict[] = [];
-  for (const r of rows.slice().sort((a, b) => a.id - b.id)) {
-    if (beforeId != null && r.id >= beforeId) continue;
-    if ((r.author_task || "") === me) continue;
-    for (const f of new Set(decodeFiles(r.files).map((x) => x.trim()).filter((x) => x !== ""))) {
-      if (want.has(f)) {
-        out.push({ file: f, author_task: r.author_task, id: r.id, body: r.body, created_at: r.created_at });
-      }
-    }
-  }
-  return out;
+  return storeFor(data)
+    .detectFileClaimConflicts(planKey, {
+      authorTask: opts.author_task,
+      files: opts.files,
+      beforeId: opts.beforeId,
+    })
+    .map((c) => ({
+      file: c.file,
+      author_task: c.authorTask,
+      id: c.id,
+      body: c.body,
+      created_at: c.createdAt,
+    }));
 }
 
 /** Append an entry, idempotently. A blank `body` is rejected. When a `dedupe_key` is supplied and
@@ -273,50 +288,12 @@ export async function appendEntry(
   planKey: string,
   input: BlackboardInput,
 ): Promise<{ inserted: boolean; id: number | bigint }> {
-  const body = typeof input.body === "string" ? input.body.trim() : "";
-  if (!body) throw new Error("blackboard entry requires a non-empty body");
-  const table = blackboardTable(data);
-  const dedupe_key = input.dedupe_key?.trim() || undefined;
-  if (dedupe_key) {
-    const existing = await table.findOne({ plan_key: planKey, dedupe_key });
-    if (existing) return { inserted: false, id: existing.id };
-  }
-  const files = (input.files ?? []).map(String).map((s) => s.trim()).filter((s) => s !== "");
-  try {
-    const id = await table.insert({
-      plan_key: planKey,
-      author_task: input.author_task?.trim() || "system",
-      kind: normalizeKind(input.kind),
-      files: files.length ? JSON.stringify(files) : null,
-      body,
-      wave: typeof input.wave === "number" ? input.wave : null,
-      dedupe_key: dedupe_key ?? null,
-      created_at: now(),
-    });
-    return { inserted: true, id };
-  } catch (err) {
-    // Idempotent write-back under concurrency: two POSTs sharing a dedupe_key can both miss the
-    // findOne pre-check above, then one loses the race on the UNIQUE (plan_key, dedupe_key) index.
-    // Convert that collision into a no-op by re-reading the winner's row, so a retry never 500s.
-    if (dedupe_key && isUniqueViolation(err)) {
-      const existing = await table.findOne({ plan_key: planKey, dedupe_key });
-      if (existing) return { inserted: false, id: existing.id };
-    }
-    throw err;
-  }
+  return storeFor(data).append(planKey, {
+    authorTask: input.author_task,
+    kind: input.kind,
+    files: input.files,
+    body: input.body,
+    wave: input.wave,
+    dedupeKey: input.dedupe_key,
+  });
 }
-
-/** 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 data
- * corruption, not a benign duplicate) is always rethrown rather than silently swallowed. */
-export function isUniqueViolation(err: unknown): boolean {
-  if (!err || typeof err !== "object") return false;
-  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const code = (err as { code?: unknown }).code;
-  if (code === "SQLITE_CONSTRAINT_UNIQUE" || code === "SQLITE_CONSTRAINT_PRIMARYKEY") return true;
-  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const message = (err as { message?: unknown }).message;
-  return typeof message === "string" &&
-    /(unique|primary key) constraint failed|duplicate/i.test(message);
-}

package/app/retro.test.ts

@@ -2,6 +2,7 @@
 import { test } from "node:test";
 import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { memBlackboardSource } from "../test/blackboardDb.ts";
 import { appendEntry } from "./blackboard.ts";
 import { recordTaskDelta } from "./taskDelta.ts";
 import {
@@ -46,7 +47,7 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
       },
     };
   }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  const data = { table: (n: string, pk?: string) => tbl(n, pk), source: memBlackboardSource().source } as any as DataLayer;
   return { data, stores };
 }
 
@@ -335,6 +336,7 @@ test("maybeStartRetro: a secondary blocked-retro persistence failure still retur
   // recordRetro rethrows non-unique DB errors; simulate the blocked-retro insert hitting a
   // FOREIGN KEY failure so the persistence in the createInstance-failure handler throws.
   const failingData = {
+    ...data,
     table: (name: string, pk?: string) => {
       const t = (data as any).table(name, pk);
       if (name !== "plan_retros") return t;

package/db/migrations/025_agentic_blackboard.sql

@@ -0,0 +1,39 @@
+-- Generalize the advisory blackboard onto the agentic channel's blackboard family (ADR 0056, H4 /
+-- #147). Reserved prefix `025` was pre-allocated by H0 (#143) so no two sibling slices collide on
+-- "the next" number.
+--
+-- The per-plan advisory blackboard (issues #51 / #49 D4, migration 009's `plan_blackboard`) is
+-- promoted to `@nanobpm/agentic/blackboard`'s first-class, capability-scoped `agentic_blackboard`
+-- store — the SAME store the new agentic-channel `blackboard` family serves, over the SAME app
+-- SQLite DataLayer. The HTTP hook (`/app/api/hooks/blackboard`) and the channel now read/write one
+-- canonical table (no drift surface), scoped by the plan key exactly as before.
+--
+-- Forward-only and additive (expand phase): a new table + indexes, then a one-shot backfill of the
+-- existing `plan_blackboard` rows (`plan_key` → `scope`) so in-flight plans keep their coordination
+-- history unaffected. The old `plan_blackboard` table is intentionally NOT dropped here — dropping a
+-- table a release just stopped reading is a separate, later contract phase.
+--
+-- The CREATE statements below are the canonical `BLACKBOARD_SCHEMA_SQL` verbatim (the same DDL the
+-- store's `ensureSchema()` and the agentic-channel family apply), so the migration path and the
+-- `CREATE TABLE IF NOT EXISTS` path can never drift. `app/blackboard.schema.test.ts` guards this.
+CREATE TABLE IF NOT EXISTS agentic_blackboard (
+  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_agentic_blackboard_dedupe ON agentic_blackboard (scope, dedupe_key) WHERE dedupe_key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_agentic_blackboard_scope ON agentic_blackboard (scope, id);
+
+-- Backfill: carry every existing per-plan entry over under scope = plan_key, in write order (id asc)
+-- so the new autoincrement ids stay monotonic in the original write order. The old table's UNIQUE
+-- (plan_key, dedupe_key) invariant maps 1:1 onto the new (scope, dedupe_key) index, so no collision.
+INSERT INTO agentic_blackboard (scope, author_task, kind, files, body, wave, dedupe_key, created_at)
+SELECT plan_key, author_task, kind, files, body, wave, dedupe_key, created_at
+FROM plan_blackboard
+ORDER BY id;

package/operations/blackboard.test.ts

@@ -3,35 +3,18 @@
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { memBlackboardData } from "../test/blackboardDb.ts";
 import { noopLog } from "../test/log.ts";
 import readBlackboard from "./readBlackboard.ts";
 import appendBlackboard from "./appendBlackboard.ts";
 
-function memApp(): { app: AppApi; stores: Record<string, any[]> } {
-  const stores: Record<string, any[]> = {};
-  const seq: Record<string, number> = {};
-  function tbl(name: string, pk = "id") {
-    const rows = (stores[name] ??= [] as any[]);
-    return {
-      async insert(row: any) {
-        if (pk === "id") {
-          const id = (seq[name] = (seq[name] ?? 0) + 1);
-          rows.push({ id, ...row });
-          return id;
-        }
-        rows.push({ ...row });
-        return row[pk];
-      },
-      async find(where: any = {}) {
-        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
-      },
-      async findOne(where: any = {}) {
-        return rows.find((r) => Object.entries(where).every(([k, v]) => r[k] === v));
-      },
-    };
-  }
-  const app = { data: { table: (n: string, pk?: string) => tbl(n, pk) }, log: noopLog() } as any as AppApi;
-  return { app, stores };
+// The operations bind to `app.data`; back it with a real in-memory SQLite DataLayer (the same
+// harness `app/blackboard.test.ts` uses) so the hook path exercises the shared `BlackboardStore` /
+// `agentic_blackboard` table end-to-end. `db` is exposed for row-count assertions.
+function memApp(): { app: AppApi; db: { all<T>(sql: string, params?: unknown[]): T[] } } {
+  const { data, db } = memBlackboardData();
+  const app = { data, log: noopLog() } as unknown as AppApi;
+  return { app, db };
 }
 
 function req(method: string, query: Record<string, string>) {
@@ -106,14 +89,15 @@ test("POST with a blank body → 400", async () => {
 });
 
 test("POST is idempotent on dedupe_key (retry → 200, not a duplicate)", async () => {
-  const { app, stores } = memApp();
+  const { app, db } = memApp();
   await seedPlan(app, "o/r#1", "tok");
   const body = { author_task: "t", body: "claim", dedupe_key: "t:claim:1" };
   assertEquals((await call(app, "POST", { token: "tok" }, body)).status, 201);
   const retry = await call(app, "POST", { token: "tok" }, body);
   assertEquals(retry.status, 200);
   assertEquals(retry.body.inserted, false);
-  assertEquals(stores["plan_blackboard"].length, 1);
+  const [{ n }] = db.all<{ n: number }>("SELECT COUNT(*) AS n FROM agentic_blackboard WHERE scope = ?", ["o/r#1"]);
+  assertEquals(n, 1);
 });
 
 test("GET ?since returns only newer entries", async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/test/blackboardDb.ts

@@ -0,0 +1,108 @@
+// A test-only DataLayer stub backed by a real in-memory `node:sqlite` database, for exercising the
+// blackboard adapter (`app/blackboard.ts`) and the agentic `blackboard` family against a real SQLite
+// engine rather than a mock. It mirrors the two surfaces the adapter uses:
+//   - `data.source().db`  — the raw synchronous `SqliteDb` the shared `BlackboardStore` writes to,
+//   - `data.table(name)`  — the async record gateway (only the `plans` table is needed here, for
+//     token→plan resolution), backed by the SAME db so the sync (`planKeyForTokenSync`) and async
+//     (`planKeyForToken`) paths see identical rows.
+import { DatabaseSync, type SQLInputValue } from "node:sqlite";
+import { afterEach } from "node:test";
+import type { DataLayer } from "@nanobpm/urban";
+
+/** The tiny synchronous SQLite handle shape the runtime + the agentic store share. */
+interface SqliteDb {
+  exec(sql: string): void;
+  run(sql: string, params?: unknown[]): { changes: number; lastInsertRowid: number | bigint };
+  all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+  close(): void;
+}
+
+function coerce(p: unknown): SQLInputValue {
+  if (p === null) return null;
+  if (typeof p === "boolean") return p ? 1 : 0;
+  return p as SQLInputValue;
+}
+
+function wrap(db: DatabaseSync): SqliteDb {
+  return {
+    exec: (sql) => db.exec(sql),
+    run: (sql, params = []) => {
+      const r = db.prepare(sql).run(...params.map(coerce));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+    all: <T>(sql: string, params: unknown[] = []) => db.prepare(sql).all(...params.map(coerce)) as T[],
+    close: () => db.close(),
+  };
+}
+
+// Every raw handle these helpers open is tracked here and released after each test, so call sites
+// that drop the returned `close()` (most of them) don't leak native SQLite handles across the run.
+const openDbs = new Set<DatabaseSync>();
+
+afterEach(() => {
+  for (const raw of openDbs) closeTracked(raw);
+});
+
+/** Open a tracked in-memory db and return it with an idempotent `close()` safe to call twice. */
+function openTracked(): { raw: DatabaseSync; close(): void } {
+  const raw = new DatabaseSync(":memory:");
+  openDbs.add(raw);
+  return { raw, close: () => closeTracked(raw) };
+}
+
+function closeTracked(raw: DatabaseSync): void {
+  if (openDbs.delete(raw)) raw.close();
+}
+
+/** A minimal async record gateway over the real db — just the insert/find/findOne subset the
+ * blackboard tests exercise on the `plans` table. */
+function gateway(db: SqliteDb, name: string, pk: string) {
+  const quote = (id: string) => `"${id.replace(/"/g, '""')}"`;
+  return {
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async insert(row: any): Promise<number | bigint | unknown> {
+      const keys = Object.keys(row).filter((k) => row[k] !== undefined);
+      const cols = keys.map(quote).join(", ");
+      const placeholders = keys.map(() => "?").join(", ");
+      const r = db.run(
+        `INSERT INTO ${quote(name)} (${cols}) VALUES (${placeholders})`,
+        keys.map((k) => row[k]),
+      );
+      return pk === "id" ? r.lastInsertRowid : row[pk];
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async find(where: any = {}): Promise<any[]> {
+      const keys = Object.keys(where);
+      const clause = keys.length ? `WHERE ${keys.map((k) => `${quote(k)} = ?`).join(" AND ")}` : "";
+      return db.all(`SELECT * FROM ${quote(name)} ${clause}`, keys.map((k) => where[k]));
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async findOne(where: any = {}): Promise<any> {
+      return (await this.find(where))[0];
+    },
+  };
+}
+
+/** A DataLayer stub over a fresh in-memory SQLite db, plus a `plans` table for token resolution. */
+export function memBlackboardData(): { data: DataLayer; db: SqliteDb; close(): void } {
+  const { raw, close } = openTracked();
+  const db = wrap(raw);
+  db.exec("CREATE TABLE IF NOT EXISTS plans (plan_key TEXT PRIMARY KEY, blackboard_token TEXT);");
+  const data = {
+    source: () => ({ db }),
+    table: (name: string, pk = "id") => gateway(db, name, pk),
+  } as unknown as DataLayer;
+  return { data, db, close };
+}
+
+/**
+ * A bare real-sqlite handle (no tables) for tests whose fake DataLayer keeps its OTHER tables as
+ * in-memory arrays but still needs the blackboard's `data.source().db` seam to resolve to a real
+ * SQLite engine (the store applies its own schema via `ensureSchema()`). Spread its `.source` into
+ * the fake `data`: `{ ...fake, source: bb.source }`.
+ */
+export function memBlackboardSource(): { source: () => { db: SqliteDb }; db: SqliteDb; close(): void } {
+  const { raw, close } = openTracked();
+  const db = wrap(raw);
+  return { source: () => ({ db }), db, close };
+}

package/workers/retro-gather/worker.test.ts

@@ -2,6 +2,7 @@ import { test } from "node:test";
 import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import type { DataLayer } from "@nanobpm/urban";
 import { noopLog } from "../../test/log.ts";
+import { memBlackboardSource } from "../../test/blackboardDb.ts";
 import { appendEntry } from "../../app/blackboard.ts";
 import handler from "./worker.ts";
 
@@ -29,7 +30,7 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
       async update() {},
     };
   }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  const data = { table: (n: string, pk?: string) => tbl(n, pk), source: memBlackboardSource().source } as any as DataLayer;
   return { data, stores };
 }