@nanobpm/nano-workforce 0.52.0 → 0.54.0

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

@@ -0,0 +1,331 @@
+// nano-workforce — the relay ring + transcript store agentic family (ADR 0056, H3 / #146).
+//
+// This is a sibling slice of the agentic-visibility epic (#142). It plugs into the H0 (#143)
+// family-registration SEAM (`../registry.ts`) as ONE NEW FILE and NOTHING ELSE — it never edits
+// `main.ts`, `drainAndExit`, or any shared boot line. The auto-discovery loader (`../loader.ts`)
+// finds it by the `*.family.ts` suffix and the seam mounts + tears it down.
+//
+// It composes two published primitives — it re-implements NEITHER:
+//   - `@nanobpm/agentic/relay`      — the bounded replay ring, three-lane QoS scheduler
+//     (control > interactive > bulk), resume-from-offset, and incarnation/generation fencing,
+//     all inside {@link RelayHub}. We mount it on the hub's `registerFamilyHandler` seam.
+//   - `@nanobpm/agentic/transcript` — {@link TranscriptStore}, retention-by-lifecycle over the app's
+//     SQLite DataLayer. Ephemeral streams flush the ring to a durable transcript on job completion;
+//     long-lived streams retain chunks so a reconnecting consumer resumes-from-offset (reattach).
+//
+// Its DB schema ships as the reserved forward-only additive migration
+// `db/migrations/024_agentic_transcript.sql` (H0 pre-allocated prefix 024 for H3), a byte-for-byte
+// mirror of the package's canonical `TRANSCRIPT_SCHEMA_SQL`, drift-guarded by this slice's test.
+//
+// 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
+// relay/transcript never hard-lock or gate a BPMN sequence flow).
+import type { ConnectionRegistry } from "@nanobpm/agentic/channel";
+import type { Frame } from "@nanobpm/agentic/protocol";
+import { RELAY_FAMILY, RelayHub, type RelayHubOptions } from "@nanobpm/agentic/relay";
+import {
+  type SqliteDb,
+  type TranscriptLifecycle,
+  type TranscriptRing,
+  type TranscriptSlice,
+  TranscriptStore,
+  type TranscriptStoreOptions,
+  type TranscriptStream,
+} from "@nanobpm/agentic/transcript";
+import type { Logger } from "@nanobpm/urban";
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+
+/** The stable family name this slice registers under the seam (distinct from the wire family key). */
+export const RELAY_FAMILY_NAME = "relay";
+
+/** Read a property off an unknown value without an unsafe `as` cast (mirrors the loader's helper). */
+function readProp(value: unknown, key: string): unknown {
+  if (!value || typeof value !== "object") return undefined;
+  return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+
+/**
+ * A resume-from-offset source with no retained chunks — used to flush/complete a stream that a
+ * producer opened logically but never wrote to, so its transcript is still stamped `completed`
+ * rather than left dangling `open`.
+ */
+const EMPTY_SOURCE: TranscriptRing = { since: () => ({ entries: [] }), nextOffset: 0 };
+
+/** Per-stream bookkeeping the service keeps to drive lifecycle-aware persistence. */
+interface StreamState {
+  /** Retention lifecycle: `ephemeral` (flush+complete on job end) vs `long-lived` (reattach). */
+  lifecycle: TranscriptLifecycle;
+  /** The connection id of the most recent producer, for disconnect-driven completion. */
+  producer?: string;
+  /** Set once an ephemeral stream has been flushed & completed (so it is not re-completed). */
+  completed: boolean;
+}
+
+export interface RelayTranscriptServiceOptions {
+  /** The app-tier hub; the service claims the `relay` family key via its registration seam. */
+  readonly hub: {
+    registerFamilyHandler(family: string, handler: (frame: Frame, conn: RelayConnectionCtx) => void): void;
+  };
+  /** The shared connection registry — its `has(id)` is the liveness source of truth. */
+  readonly registry: ConnectionRegistry;
+  /** The raw SQLite handle (the app DataLayer's `source().db`); absent → transcripts disabled. */
+  readonly db: SqliteDb | undefined;
+  /** A structured logger for lifecycle lines. */
+  readonly log: Logger;
+  /** Options forwarded to the underlying {@link RelayHub} (ring/bulk capacity, default credit). */
+  readonly relay?: RelayHubOptions;
+  /** Options forwarded to the {@link TranscriptStore} (retention window, injectable clock). */
+  readonly transcript?: TranscriptStoreOptions;
+  /**
+   * Apply the transcript DDL from the store on mount (idempotent `CREATE ... IF NOT EXISTS`).
+   * Default `true`: the boot migration is the canonical path, but this makes the service usable
+   * against a bare source too (and is harmless when the migration already ran).
+   */
+  readonly ensureSchema?: boolean;
+}
+
+/** The minimal per-connection surface the relay handler receives from the hub (a {@link RelayHub} `RelayConnection`). */
+interface RelayConnectionCtx {
+  readonly id: string;
+  readonly registry: { has(id: string): boolean };
+  send(frame: Frame): void;
+}
+
+/**
+ * Composes the S5 relay ({@link RelayHub}) with the S6 transcript store ({@link TranscriptStore})
+ * and wires retention-by-lifecycle. It owns NO ring/scheduler/store logic of its own — it observes
+ * `produce` ownership so an ephemeral stream is flushed & completed when its producer disconnects,
+ * and exposes the completion/checkpoint/reattach/sweep surface H6 (#149) and the app drive.
+ */
+export class RelayTranscriptService {
+  /** The mounted relay hub (ring + QoS scheduler + incarnation fence). Exposed for inspection/tests. */
+  readonly relay: RelayHub;
+  /** The transcript store, or `undefined` when no DataLayer is mounted (relay still works, unpersisted). */
+  readonly store: TranscriptStore | undefined;
+
+  readonly #registry: ConnectionRegistry;
+  readonly #log: Logger;
+  readonly #streams = new Map<string, StreamState>();
+
+  constructor(options: RelayTranscriptServiceOptions) {
+    this.#registry = options.registry;
+    this.#log = options.log;
+    // Persistence is advisory: a store that can't be constructed or whose schema can't be applied
+    // (locked/permission-denied/unavailable SQLite) must NOT fail the family mount — fall back to
+    // running the relay unpersisted rather than tearing down the whole agentic channel.
+    let store: TranscriptStore | undefined;
+    if (options.db) {
+      try {
+        store = new TranscriptStore(options.db, options.transcript);
+        if (options.ensureSchema !== false) store.ensureSchema();
+      } catch (err) {
+        this.#log.warn("agentic transcript store unavailable — relay runs unpersisted", {
+          err: String(err),
+        });
+        store = undefined;
+      }
+    }
+    this.store = store;
+
+    this.relay = new RelayHub({
+      ...options.relay,
+      onFenced: (stream, incarnation, current) => {
+        this.#log.warn("agentic relay fenced a stale producer", { stream, incarnation, current });
+        options.relay?.onFenced?.(stream, incarnation, current);
+      },
+      onError: (err, connectionId) => {
+        this.#log.warn("agentic relay message error", { connectionId, err: String(err) });
+        options.relay?.onError?.(err, connectionId);
+      },
+    });
+
+    // Register the `relay` family ourselves (rather than via `registerRelayFamily`) so we can observe
+    // `produce` ownership before delegating to the hub — the hub's own routing still derives purely
+    // from this single registration, and a second `relay` registration is rejected by the seam.
+    options.hub.registerFamilyHandler(RELAY_FAMILY, (frame, conn) => this.#onFrame(frame, conn));
+  }
+
+  /** The tracked stream names (those a producer opened or that were declared). */
+  streams(): string[] {
+    return [...this.#streams.keys()];
+  }
+
+  /**
+   * Declare a stream's retention lifecycle before (or independently of) its first `produce`. The
+   * durable store records lifecycle write-once (first call wins there); in memory the latest call
+   * wins until the stream completes, which is how {@link checkpointStream} upgrades an as-yet
+   * ephemeral stream to `long-lived`. No-op once the stream has already been completed.
+   */
+  declareLifecycle(stream: string, lifecycle: TranscriptLifecycle): void {
+    const state = this.#stateFor(stream);
+    if (!state.completed) state.lifecycle = lifecycle;
+  }
+
+  /**
+   * Complete a stream on job end: flush the relay ring (its whole retained window) to the durable
+   * transcript under the stream's lifecycle. For an `ephemeral` stream this stamps `completed_at`
+   * (so {@link reattach} then serves the durable transcript and {@link sweep} may later retire it);
+   * for a `long-lived` stream it is a snapshot checkpoint that leaves the stream `open`. Idempotent:
+   * re-completing already-persisted offsets is a no-op. Returns the number of newly-persisted chunks.
+   */
+  completeStream(stream: string): number {
+    if (!this.store) return 0;
+    const state = this.#stateFor(stream);
+    const source = this.relay.ring(stream) ?? EMPTY_SOURCE;
+    let flushed: number;
+    try {
+      flushed = this.store.flush(stream, source, state.lifecycle);
+    } catch (err) {
+      // Persistence is advisory: a flush failure must not bubble into the hub's frame handler and
+      // take down unrelated streams. Log and leave the stream uncompleted so a later pass retries.
+      this.#log.warn("agentic relay stream flush failed — leaving stream uncompleted", {
+        stream,
+        lifecycle: state.lifecycle,
+        err: String(err),
+      });
+      return 0;
+    }
+    if (state.lifecycle === "ephemeral") state.completed = true;
+    // Drop producer ownership so a later reconcile does not re-flush a completed stream.
+    state.producer = undefined;
+    this.#log.info("agentic relay stream flushed", {
+      stream,
+      lifecycle: state.lifecycle,
+      flushed,
+      completed: state.completed,
+    });
+    return flushed;
+  }
+
+  /**
+   * Snapshot a long-lived stream's ring into the durable transcript without completing it — the
+   * checkpoint path a growing stream uses so a reconnecting consumer can {@link reattach} past the
+   * ring's resume window. Returns the number of newly-persisted chunks.
+   */
+  checkpointStream(stream: string): number {
+    if (!this.store) return 0;
+    this.declareLifecycle(stream, "long-lived");
+    const source = this.relay.ring(stream) ?? EMPTY_SOURCE;
+    try {
+      return this.store.flush(stream, source, "long-lived");
+    } catch (err) {
+      // Advisory: a checkpoint failure keeps the relay usable — return 0, the stream stays open.
+      this.#log.warn("agentic relay checkpoint flush failed", { stream, err: String(err) });
+      return 0;
+    }
+  }
+
+  /**
+   * Reattach a consumer from offset `from` (inclusive) against the durable transcript — mirrors the
+   * relay ring's `since` contract exactly, so a late/reconnecting consumer resumes identically
+   * whether from the live ring or the persisted transcript. Returns `undefined` with no store.
+   */
+  reattach(stream: string, from: number): TranscriptSlice | undefined {
+    return this.store?.since(stream, from);
+  }
+
+  /** Retention sweep: retire completed-ephemeral transcripts past the retention window. */
+  sweep(now?: number): string[] {
+    const retired = this.store?.sweep(now) ?? [];
+    // Forget the in-memory state of every retired stream so `#streams` stays bounded (and
+    // `#reconcile`'s scan stays cheap) even after many ephemeral streams complete and age out.
+    for (const stream of retired) this.#streams.delete(stream);
+    return retired;
+  }
+
+  /** A stream's persisted transcript metadata, if any (lifecycle/status/offset window). */
+  transcriptOf(stream: string): TranscriptStream | undefined {
+    return this.store?.get(stream);
+  }
+
+  /**
+   * Complete every still-open ephemeral stream (e.g. on shutdown) so no in-flight terminal is lost,
+   * then forget all tracking. Long-lived streams are left for reattach and are not force-completed.
+   */
+  teardown(): void {
+    for (const [stream, state] of this.#streams) {
+      if (state.lifecycle === "ephemeral" && !state.completed) this.completeStream(stream);
+    }
+    this.#streams.clear();
+  }
+
+  /** Handle one inbound `relay` frame: reconcile dead producers, observe ownership, then delegate. */
+  #onFrame(frame: Frame, conn: RelayConnectionCtx): void {
+    this.#reconcile();
+    this.#observe(frame, conn);
+    this.relay.handle(frame, conn);
+  }
+
+  /** Record `produce` ownership so a producer disconnect can drive ephemeral completion. */
+  #observe(frame: Frame, conn: RelayConnectionCtx): void {
+    if (readProp(frame.payload, "op") !== "produce") return;
+    const stream = readProp(frame.payload, "stream");
+    if (typeof stream !== "string" || stream === "") return;
+    this.#stateFor(stream).producer = conn.id;
+  }
+
+  /**
+   * Flush + complete every ephemeral stream whose producer connection is no longer live (the S1
+   * registry dropped it on close or liveness timeout). Lazy, like the relay hub's own dead-subscriber
+   * prune: it runs on each inbound frame, and shutdown covers the quiescent tail via {@link teardown}.
+   */
+  #reconcile(): void {
+    for (const [stream, state] of this.#streams) {
+      if (state.completed || state.lifecycle !== "ephemeral") continue;
+      if (state.producer !== undefined && !this.#registry.has(state.producer)) {
+        this.completeStream(stream);
+      }
+    }
+  }
+
+  #stateFor(stream: string): StreamState {
+    let state = this.#streams.get(stream);
+    if (state === undefined) {
+      state = { lifecycle: "ephemeral", completed: false };
+      this.#streams.set(stream, state);
+    }
+    return state;
+  }
+}
+
+/**
+ * Build the H3 relay family. Copy-of-the-seam pattern: it constructs the {@link RelayTranscriptService}
+ * in `mount` (threading the seam's hub/registry/DataLayer/log) and tears it down in `teardown`. The
+ * created service is exposed to `onMounted` so a driver (H6 correlation, tests) can reach the
+ * completion/reattach surface without re-mounting anything.
+ */
+export function createRelayFamily(options: {
+  readonly relay?: RelayHubOptions;
+  readonly transcript?: TranscriptStoreOptions;
+  readonly ensureSchema?: boolean;
+  /** Called with the live service once mounted, so a driver can drive completion/reattach. */
+  readonly onMounted?: (service: RelayTranscriptService) => void;
+} = {}): AgenticFamily {
+  let service: RelayTranscriptService | undefined;
+  return {
+    name: RELAY_FAMILY_NAME,
+    mount(ctx: AgenticContext): void {
+      service = new RelayTranscriptService({
+        hub: ctx.hub,
+        registry: ctx.registry,
+        // The app's SQLite handle: the same store the advisory blackboard uses. Absent → relay runs
+        // unpersisted (still advisory-correct), rather than failing the whole channel boot.
+        db: ctx.data ? ctx.data.source().db : undefined,
+        log: ctx.log,
+        relay: options.relay,
+        transcript: options.transcript,
+        ensureSchema: options.ensureSchema,
+      });
+      options.onMounted?.(service);
+    },
+    teardown(): void {
+      service?.teardown();
+      service = undefined;
+    },
+  };
+}
+
+/** The discovered family instance (the loader picks up this `family` export). */
+export const family: AgenticFamily = createRelayFamily();
+
+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",