@nanobpm/agentic 0.1.0

package/src/blackboard/store.test.ts

@@ -0,0 +1,189 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { BlackboardStore, isUniqueViolation, normalizeKind } from "./store.ts";
+import type { Clock } from "./store.ts";
+import { openTestDb } from "./test-db.ts";
+
+function fixedClock(start = 1_000): Clock & { set(t: number): void } {
+  let t = start;
+  return { now: () => t, set: (v: number) => (t = v) };
+}
+
+function freshStore(clock?: Clock): BlackboardStore {
+  const store = new BlackboardStore(openTestDb(), clock ? { clock } : {});
+  store.ensureSchema();
+  return store;
+}
+
+test("normalizeKind keeps the known kinds and defaults the rest to note", () => {
+  for (const k of ["file-claim", "constraint-change", "scope-change", "learning", "note"]) {
+    assert.equal(normalizeKind(k), k);
+  }
+  assert.equal(normalizeKind("bogus"), "note");
+  assert.equal(normalizeKind(undefined), "note");
+  assert.equal(normalizeKind(42), "note");
+});
+
+test("append stores an entry and read returns it in write order", () => {
+  const store = freshStore();
+  const a = store.append("board-1", { authorTask: "t1", kind: "note", body: "first" });
+  const b = store.append("board-1", { authorTask: "t2", kind: "learning", body: "second" });
+  assert.deepEqual([a.inserted, b.inserted], [true, true]);
+  assert.ok(b.id > a.id);
+
+  const entries = store.read("board-1");
+  assert.deepEqual(
+    entries.map((e) => [e.authorTask, e.kind, e.body]),
+    [
+      ["t1", "note", "first"],
+      ["t2", "learning", "second"],
+    ],
+  );
+});
+
+test("append defaults author to 'system', normalises unknown kinds, and trims the body", () => {
+  const store = freshStore();
+  store.append("b", { body: "  padded  ", kind: "weird" });
+  const [e] = store.read("b");
+  assert.equal(e?.authorTask, "system");
+  assert.equal(e?.kind, "note");
+  assert.equal(e?.body, "padded");
+});
+
+test("append rejects a blank body", () => {
+  const store = freshStore();
+  assert.throws(() => store.append("b", { body: "   " }), /non-empty body/);
+  assert.throws(() => store.append("b", { body: "" }), /non-empty body/);
+  assert.equal(store.count("b"), 0);
+});
+
+test("dedupeKey makes a repeat append under the same scope a no-op", () => {
+  const store = freshStore();
+  const first = store.append("b", { body: "claim", dedupeKey: "k1" });
+  const again = store.append("b", { body: "claim (retry)", dedupeKey: "k1" });
+  assert.equal(first.inserted, true);
+  assert.equal(again.inserted, false);
+  assert.equal(again.id, first.id);
+  assert.equal(store.count("b"), 1);
+  // The original body wins — the retry did not overwrite it.
+  assert.equal(store.read("b")[0]?.body, "claim");
+});
+
+test("the same dedupeKey under a DIFFERENT scope is a distinct entry", () => {
+  const store = freshStore();
+  const a = store.append("board-a", { body: "x", dedupeKey: "k1" });
+  const b = store.append("board-b", { body: "y", dedupeKey: "k1" });
+  assert.equal(a.inserted, true);
+  assert.equal(b.inserted, true);
+  assert.notEqual(a.id, b.id);
+  assert.equal(store.count("board-a"), 1);
+  assert.equal(store.count("board-b"), 1);
+});
+
+test("a dedupe-less note always appends (partial unique index excludes NULL)", () => {
+  const store = freshStore();
+  store.append("b", { body: "n1" });
+  store.append("b", { body: "n2" });
+  store.append("b", { body: "n3" });
+  assert.equal(store.count("b"), 3);
+});
+
+test("readPage returns a cursor at the head even when since filters everything out", () => {
+  const store = freshStore();
+  store.append("b", { body: "1" });
+  const second = store.append("b", { body: "2" });
+
+  const caughtUp = store.readPage("b", { since: second.id });
+  assert.deepEqual(caughtUp.entries, []);
+  assert.equal(caughtUp.cursor, second.id, "cursor is the true head even with nothing new");
+
+  const empty = store.readPage("missing-board");
+  assert.deepEqual(empty.entries, []);
+  assert.equal(empty.cursor, 0, "an empty board has cursor 0");
+});
+
+test("readPage since returns only entries after the cursor (incremental read)", () => {
+  const store = freshStore();
+  const a = store.append("b", { body: "1" });
+  store.append("b", { body: "2" });
+  const page = store.readPage("b", { since: a.id });
+  assert.deepEqual(page.entries.map((e) => e.body), ["2"]);
+});
+
+test("reads never cross scopes", () => {
+  const store = freshStore();
+  store.append("board-a", { body: "a-only" });
+  store.append("board-b", { body: "b-only" });
+  assert.deepEqual(store.read("board-a").map((e) => e.body), ["a-only"]);
+  assert.deepEqual(store.read("board-b").map((e) => e.body), ["b-only"]);
+});
+
+test("files round-trip as a decoded array, blank/whitespace entries dropped", () => {
+  const store = freshStore();
+  store.append("b", { kind: "file-claim", files: ["src/a.ts", "  ", "src/b.ts", ""], body: "claim" });
+  const [e] = store.read("b");
+  assert.deepEqual(e?.files, ["src/a.ts", "src/b.ts"]);
+});
+
+test("detectFileClaimConflicts surfaces a prior claim by another author on the same file", () => {
+  const store = freshStore();
+  const prior = store.append("b", { authorTask: "t1", kind: "file-claim", files: ["state.rs"], body: "t1 claims" });
+  // t2 is about to claim the same file — compute conflicts as the endpoint does,
+  // AFTER inserting t2's own claim, with beforeId = t2's new id.
+  const mine = store.append("b", { authorTask: "t2", kind: "file-claim", files: ["state.rs"], body: "t2 claims" });
+  const conflicts = store.detectFileClaimConflicts("b", { authorTask: "t2", files: ["state.rs"], beforeId: mine.id });
+  assert.equal(conflicts.length, 1);
+  assert.equal(conflicts[0]?.file, "state.rs");
+  assert.equal(conflicts[0]?.authorTask, "t1");
+  assert.equal(conflicts[0]?.id, prior.id);
+});
+
+test("detectFileClaimConflicts never reports a writer's own earlier claim", () => {
+  const store = freshStore();
+  store.append("b", { authorTask: "t1", kind: "file-claim", files: ["state.rs"], body: "t1 earlier" });
+  const mine = store.append("b", { authorTask: "t1", kind: "file-claim", files: ["state.rs"], body: "t1 again" });
+  const conflicts = store.detectFileClaimConflicts("b", { authorTask: "t1", files: ["state.rs"], beforeId: mine.id });
+  assert.deepEqual(conflicts, []);
+});
+
+test("detectFileClaimConflicts never reports a host/'system' writer's own earlier claim", () => {
+  // A host write leaves authorTask undefined/blank; `append` stores it as "system".
+  // Conflict detection must default the querying author to the SAME "system", or a
+  // host writer falsely conflicts with its own prior host claims.
+  const store = freshStore();
+  store.append("b", { kind: "file-claim", files: ["state.rs"], body: "host earlier" });
+  const mine = store.append("b", { authorTask: "  ", kind: "file-claim", files: ["state.rs"], body: "host again" });
+  const conflicts = store.detectFileClaimConflicts("b", { files: ["state.rs"], beforeId: mine.id });
+  assert.deepEqual(conflicts, []);
+});
+
+test("detectFileClaimConflicts ignores non-file-claim kinds and other scopes", () => {
+  const store = freshStore();
+  store.append("b", { authorTask: "t1", kind: "note", files: ["state.rs"], body: "just a note" });
+  store.append("other", { authorTask: "t1", kind: "file-claim", files: ["state.rs"], body: "other board" });
+  const conflicts = store.detectFileClaimConflicts("b", { authorTask: "t2", files: ["state.rs"] });
+  assert.deepEqual(conflicts, []);
+});
+
+test("detectFileClaimConflicts with no files returns nothing", () => {
+  const store = freshStore();
+  store.append("b", { authorTask: "t1", kind: "file-claim", files: ["a"], body: "claim" });
+  assert.deepEqual(store.detectFileClaimConflicts("b", { authorTask: "t2", files: [] }), []);
+});
+
+test("created_at comes from the injected clock", () => {
+  const clock = fixedClock(0);
+  const store = freshStore(clock);
+  clock.set(Date.parse("2026-01-01T00:00:00.000Z"));
+  store.append("b", { body: "x" });
+  assert.equal(store.read("b")[0]?.createdAt, "2026-01-01T00:00:00.000Z");
+});
+
+test("isUniqueViolation matches unique/primary-key collisions but not other constraints", () => {
+  assert.equal(isUniqueViolation({ code: "SQLITE_CONSTRAINT_UNIQUE" }), true);
+  assert.equal(isUniqueViolation({ code: "SQLITE_CONSTRAINT_PRIMARYKEY" }), true);
+  assert.equal(isUniqueViolation({ message: "UNIQUE constraint failed: agentic_blackboard.scope" }), true);
+  assert.equal(isUniqueViolation({ message: "FOREIGN KEY constraint failed" }), false);
+  assert.equal(isUniqueViolation(new Error("some other error")), false);
+  assert.equal(isUniqueViolation(null), false);
+});

package/src/blackboard/store.ts

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

package/src/blackboard/test-db.ts

@@ -0,0 +1,47 @@
+/**
+ * Test-only helper: a {@link SqliteDb} backed by an in-memory `node:sqlite`
+ * database, mirroring the Node host adapter's `wrapNodeSqlite`. Kept out of the
+ * published build (see `tsconfig.build.json` exclude) — it exists solely so the
+ * store/family tests exercise the store against a real SQLite engine, not a mock.
+ */
+import { DatabaseSync } from "node:sqlite";
+import type { SqliteDb } from "./store.ts";
+
+export interface TestDb extends SqliteDb {
+  close(): void;
+}
+
+function toParams(params: unknown[]): (string | number | bigint | null | Uint8Array)[] {
+  return params.map((p) => {
+    if (p === null) return null;
+    if (typeof p === "string" || typeof p === "number" || typeof p === "bigint" || p instanceof Uint8Array) {
+      return p;
+    }
+    if (typeof p === "boolean") return p ? 1 : 0;
+    // Mirror wrapNodeSqlite's `sqliteParams`: unsupported types (including
+    // `undefined`) throw rather than coerce, so a test can never pass on a
+    // parameter production would reject.
+    throw new TypeError(`unsupported SQLite parameter type: ${typeof p}`);
+  });
+}
+
+export function openTestDb(): TestDb {
+  const db = new DatabaseSync(":memory:");
+  return {
+    exec: (sql) => db.exec(sql),
+    run: (sql, params = []) => {
+      const stmt = db.prepare(sql);
+      const r = stmt.run(...toParams(params));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+    all: <T>(sql: string, params: unknown[] = []): T[] => {
+      const stmt = db.prepare(sql);
+      // Mirror wrapNodeSqlite exactly: return the driver's row objects directly.
+      // A JSON round-trip would throw on `bigint` values and mangle `Uint8Array`
+      // blobs, diverging from production and breaking test-only reads.
+      // biome-ignore lint/plugin: Node sqlite returns untyped row objects; SqliteDb.all<T> is the host adapter boundary.
+      return stmt.all(...toParams(params)) as T[];
+    },
+    close: () => db.close(),
+  };
+}

package/src/channel/auth.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  AUTH_FORBIDDEN,
+  AUTH_UNAUTHORIZED,
+  sharedSecretAuthenticator,
+} from "./auth.ts";
+import type { HandshakeRequest } from "./connection.ts";
+
+test("grants a valid identity token plus capability credential", async () => {
+  const auth = sharedSecretAuthenticator({ secret: "s3cret" });
+  const req: HandshakeRequest = { token: "s3cret", credential: "cap-1", remote: "1.2.3.4" };
+
+  const result = await auth(req);
+  assert.ok(result.ok);
+  assert.equal(result.grant.identity, "1.2.3.4");
+  assert.equal(result.grant.capability, "cap-1");
+});
+
+test("reads the token and credential from query params (blackboard-hook pattern)", async () => {
+  const auth = sharedSecretAuthenticator({ secret: "s3cret" });
+  const req: HandshakeRequest = { query: { token: "s3cret", capability: "cap-1" } };
+
+  const result = await auth(req);
+  assert.ok(result.ok);
+});
+
+test("rejects a wrong identity token with the unauthorized code", async () => {
+  const auth = sharedSecretAuthenticator({ secret: "s3cret" });
+  const result = await auth({ token: "nope", credential: "cap-1" });
+
+  assert.ok(!result.ok);
+  assert.equal(result.code, AUTH_UNAUTHORIZED);
+});
+
+test("rejects a missing capability credential with the forbidden code", async () => {
+  const auth = sharedSecretAuthenticator({ secret: "s3cret" });
+  const result = await auth({ token: "s3cret" });
+
+  assert.ok(!result.ok);
+  assert.equal(result.code, AUTH_FORBIDDEN);
+});
+
+test("honours a custom credential verifier and identity resolver", async () => {
+  const auth = sharedSecretAuthenticator({
+    secret: "s3cret",
+    identityFor: (req) => `worker:${req.query?.instance ?? "?"}`,
+    verifyCredential: (credential) => credential === "good",
+  });
+
+  const accepted = await auth({ token: "s3cret", credential: "good", query: { instance: "w7" } });
+  assert.ok(accepted.ok);
+  assert.equal(accepted.grant.identity, "worker:w7");
+
+  const rejected = await auth({ token: "s3cret", credential: "bad" });
+  assert.ok(!rejected.ok);
+  assert.equal(rejected.code, AUTH_FORBIDDEN);
+});
+
+test("can be configured to not require a credential", async () => {
+  const auth = sharedSecretAuthenticator({ secret: "s3cret", requireCredential: false });
+  const result = await auth({ token: "s3cret" });
+  assert.ok(result.ok);
+});