@nanobpm/nano-workforce 0.52.0 → 0.54.0

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/024_agentic_transcript.sql

@@ -0,0 +1,43 @@
+-- Agentic visibility plane (ADR 0056, epic #142) — H3 relay transcript store (#146).
+--
+-- The relay family (app/agentic/families/relay.family.ts) mounts @nanobpm/agentic/relay (a bounded
+-- replay ring + three-lane QoS scheduler + incarnation fence) on the app-tier agentic channel and
+-- persists terminal transcripts through @nanobpm/agentic/transcript with retention-by-lifecycle:
+--
+--   • ephemeral streams  → the relay ring is flushed to a durable transcript on job completion
+--                          (and the stream marked `completed`, then retired by a retention sweep);
+--   • long-lived streams → chunks are retained/checkpointed so a reconnecting consumer can resume
+--                          from any offset (reattach), bounded by a rolling offset window.
+--
+-- This DDL is the forward-only, additive boot migration the DataLayer runner applies from
+-- nano.app.json (`data.sources.app.migrations`). It is a byte-for-byte mirror of the package's
+-- canonical `TRANSCRIPT_SCHEMA_SQL` (@nanobpm/agentic/transcript `schema.ts`), which the store also
+-- applies via `ensureSchema()`. The two application paths are kept from drifting by the drift-guard
+-- test `app/agentic/families/relay.family.test.ts` — divergence is a red test, not a silent boot vs.
+-- store mismatch. Additive only (CREATE ... IF NOT EXISTS): it adds no column to an existing table
+-- and drops nothing, so it is safe to apply forward over any earlier schema.
+--
+-- H0 (#143) pre-allocated this exact prefix (024) for H3 so no two sibling slices independently grab
+-- "the next" number (H1=023_agentic_presence, H4=025_agentic_blackboard). `chunk_offset` (not
+-- `offset`) is deliberate: OFFSET is a SQLite keyword, so the column avoids quoting in every query.
+--
+-- Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+-- is untouched — the agentic channel is the only new conversation; advisory semantics preserved (the
+-- transcript never hard-locks or gates a BPMN sequence flow).
+CREATE TABLE IF NOT EXISTS agentic_transcript_stream (
+  stream        TEXT PRIMARY KEY,
+  lifecycle     TEXT NOT NULL,
+  status        TEXT NOT NULL DEFAULT 'open',
+  created_at    TEXT NOT NULL,
+  completed_at  TEXT,
+  first_offset  INTEGER,
+  next_offset   INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS agentic_transcript_chunk (
+  stream        TEXT NOT NULL,
+  chunk_offset  INTEGER NOT NULL,
+  chunk         TEXT NOT NULL,
+  appended_at   TEXT NOT NULL,
+  PRIMARY KEY (stream, chunk_offset)
+);
+CREATE INDEX IF NOT EXISTS idx_agentic_transcript_stream_retention ON agentic_transcript_stream (lifecycle, status, completed_at);

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.52.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 };
 }