@forwardimpact/libharness 0.1.14 → 0.1.15

package/README.md

@@ -1,10 +1,99 @@
 # libharness
 
-Shared test harness and mock infrastructure.
+Shared test fixtures, mocks, and assertion helpers for the monorepo. Imported by
+`*.test.js` files across libraries, products, and services so test code stays
+consistent and test authors stop reinventing the same helpers.
 
-## Getting Started
+Runner-independent: the mock primitive `spy()` does not depend on either
+`node:test` or `bun:test`, so the suite runs under both. See spec 650.
+
+## Usage
+
+```js
+import {
+  // Mock primitive (replaces node:test's mock.fn)
+  spy,
+  // Config / storage / logger / fs
+  createMockConfig,
+  createMockStorage,
+  createSilentLogger,
+  createMockFs,
+  // gRPC / RPC
+  createMockGrpcFn,
+  MockMetadata,
+  createMockObserverFn,
+  createMockTracer,
+  createMockAuthFn,
+  // Clients
+  createMockMemoryClient,
+  createMockLlmClient,
+  createMockAgentClient,
+  createMockVectorClient,
+  createMockGraphClient,
+  createMockToolClient,
+  // Infra
+  createMockSupabaseClient,
+  createMockS3Client,
+  createTurtleHelpers,
+  createMockProcess,
+  withSilentConsole,
+  createMockQueries,
+  // Framework fixtures (pathway data)
+  createTestFramework,
+  createTestLevel,
+  createTestSkill,
+  createTestDiscipline,
+  createTestTrack,
+  createTestBehaviour,
+  createTestCapability,
+  createTestDriver,
+  createTestPerson,
+  createTestRoster,
+  createTestEvidenceRow,
+  // libeval stream/message helpers
+  createToolUseMsg,
+  createTextBlockMsg,
+  createTestTrace,
+  collectStream,
+  stripAnsi,
+  writeLines,
+  createMockAgentQuery,
+  // Assertions
+  assertThrowsMessage,
+  assertRejectsMessage,
+  createDeferred,
+  // Caching
+  memoizeAsync,
+  memoizeOnSubject,
+} from "@forwardimpact/libharness";
+```
+
+The full export list lives in `src/index.js`. Subpath entries
+`@forwardimpact/libharness/fixture` and `@forwardimpact/libharness/mock` remain
+for narrower imports.
+
+## When to extend libharness
+
+Before adding a helper locally in a test file, check `src/index.js`. If the
+helper doesn't exist and would be reused across two or more files, add it to
+libharness in the same PR instead of inlining. See
+[CONTRIBUTING.md](../../CONTRIBUTING.md) READ-DO and DO-CONFIRM checklists for
+the enforced policy and `scripts/check-libharness.mjs` for the pre-commit guard
+that flags inline reimplementations.
+
+## `spy` vs `node:test`'s `mock.fn`
+
+`spy()` matches `mock.fn`'s shape exactly:
 
 ```js
-import { createFixture } from '@forwardimpact/libharness/fixture';
-import { createMock } from '@forwardimpact/libharness/mock';
+const fn = spy((x) => x * 2);
+fn(5);
+fn.mock.calls[0].arguments; // [5]
+fn.mock.calls[0].result;    // 10
+fn.mock.callCount();        // 1
+fn.mock.resetCalls();
+fn.mock.mockImplementation((x) => x + 1);
 ```
+
+Prefer `spy` over `node:test`'s `mock.fn` — `spy` works under both `bun test`
+(the default runner) and `node --test`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libharness",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Shared test harness and mock infrastructure for the Forward Impact monorepo",
   "type": "module",
   "main": "./src/index.js",
@@ -14,7 +14,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "bun run node --test test/*.test.js"
+    "test": "bun test test/*.test.js"
   },
   "keywords": [
     "test",

package/src/fixture/cache.js

@@ -0,0 +1,50 @@
+/**
+ * Cross-file fixture caching helpers. The test runner currently executes one
+ * test file per process, but fixtures loaded inside a file (e.g. starter
+ * framework YAML via `createDataLoader().loadAllData(dir)`) are re-parsed for
+ * every `test(...)` case unless hoisted. See spec 620.
+ */
+
+const caches = new WeakMap();
+const stringCaches = new Map();
+
+/**
+ * Wraps an async factory so it is invoked at most once per unique key.
+ *
+ * @template T
+ * @param {string} key - Cache key. Using the same key returns the cached value.
+ * @param {() => Promise<T>} factory - Factory invoked on miss.
+ * @returns {Promise<T>}
+ */
+export async function memoizeAsync(key, factory) {
+  if (stringCaches.has(key)) return stringCaches.get(key);
+  const promise = Promise.resolve().then(factory);
+  stringCaches.set(key, promise);
+  try {
+    return await promise;
+  } catch (err) {
+    stringCaches.delete(key);
+    throw err;
+  }
+}
+
+/**
+ * Caches the result of `fn(subject)` keyed by identity of `subject`. Useful
+ * for expensive derivations over a frozen input object.
+ *
+ * @template S, T
+ * @param {S} subject
+ * @param {(subject: S) => T} fn
+ * @returns {T}
+ */
+export function memoizeOnSubject(subject, fn) {
+  if (!caches.has(subject)) caches.set(subject, fn(subject));
+  return caches.get(subject);
+}
+
+/**
+ * Clears all memoization caches. Only useful in self-tests of this helper.
+ */
+export function __resetMemoCaches() {
+  stringCaches.clear();
+}

package/src/fixture/eval.js

@@ -0,0 +1,146 @@
+/**
+ * Test helpers for libeval-style streams, tool-use messages, and traces.
+ *
+ * Before these helpers existed, every test file under libraries/libeval/test
+ * inlined its own copy of concludeMsg / redirectMsg / tellMsg / stripAnsi /
+ * collect / writeLines / buildTrace. See spec 620.
+ */
+
+/**
+ * Builds a tool-use message envelope as emitted by the agent SDK.
+ * Replaces per-file concludeMsg / redirectMsg / tellMsg / shareMsg helpers.
+ *
+ * @param {string} name - Tool name, e.g. "Conclude", "Redirect", "Tell", "Share".
+ * @param {object} input - Tool input payload.
+ * @param {object} [options]
+ * @param {string} [options.id] - Explicit tool_use id. Defaults to `${name.toLowerCase()}-1`.
+ * @returns {object} Assistant message with a single tool_use content block.
+ */
+export function createToolUseMsg(name, input, { id } = {}) {
+  return {
+    type: "assistant",
+    message: {
+      content: [
+        {
+          type: "tool_use",
+          id: id || `${name.toLowerCase()}-1`,
+          name,
+          input,
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * Builds an assistant text message envelope as emitted by the agent SDK.
+ * @param {string} text - Text content.
+ * @returns {object} Assistant message with a single text content block.
+ */
+export function createTextBlockMsg(text) {
+  return {
+    type: "assistant",
+    message: {
+      content: [{ type: "text", text }],
+    },
+  };
+}
+
+/**
+ * Reads a PassThrough / Readable stream to a single string.
+ * @param {import("node:stream").Readable} stream
+ * @returns {string}
+ */
+export function collectStream(stream) {
+  const data = stream.read();
+  return data ? data.toString() : "";
+}
+
+/**
+ * Reads a stream and returns non-empty lines.
+ * @param {import("node:stream").Readable} stream
+ * @returns {string[]}
+ */
+export function collectLines(stream) {
+  return collectStream(stream).split("\n").filter(Boolean);
+}
+
+/**
+ * Strips ANSI SGR escape sequences from a string.
+ * @param {string} s
+ * @returns {string}
+ */
+export function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex -- ANSI SGR detection is intentional.
+  return s.replace(/\[[0-9;]*m/g, "");
+}
+
+/**
+ * Writes each line followed by a newline to the writer, then ends it.
+ * @param {import("node:stream").Writable} writer
+ * @param {string[]} lines
+ * @returns {Promise<void>}
+ */
+export async function writeLines(writer, lines) {
+  for (const line of lines) writer.write(line + "\n");
+  await new Promise((resolve) => writer.end(resolve));
+}
+
+/**
+ * Builds a minimal-but-valid trace object for TraceQuery tests.
+ * Replaces a 155-line inline buildTrace in trace-query.test.js.
+ *
+ * @param {object} [overrides]
+ * @param {object} [overrides.metadata]
+ * @param {object[]} [overrides.turns]
+ * @param {object} [overrides.summary]
+ * @returns {object} Trace object.
+ */
+export function createTestTrace(overrides = {}) {
+  const { metadata = {}, turns = [], summary = {} } = overrides;
+  return {
+    schema_version: "1.1",
+    metadata: {
+      session_id: "sess-test",
+      model: "claude-opus-4-7",
+      started_at: "2026-01-01T00:00:00Z",
+      ended_at: "2026-01-01T00:00:05Z",
+      tools: [],
+      ...metadata,
+    },
+    turns,
+    summary: {
+      total_turns: turns.length,
+      total_tokens: 0,
+      tool_calls: 0,
+      errors: 0,
+      ...summary,
+    },
+  };
+}
+
+/**
+ * Creates an async-generator agent query stub. The shape of `messages`
+ * determines per-call behaviour:
+ *  - Flat array of message objects: yielded on every invocation.
+ *  - Array of arrays (batches): the Nth invocation yields messages from the
+ *    Nth batch. Subsequent calls past the last batch repeat the last one.
+ *
+ * @param {object[] | object[][]} messages
+ * @param {(params: object) => void} [onParams] - Invoked with call params.
+ * @returns {Function} Async generator mimicking `query({...})`.
+ */
+export function createMockAgentQuery(messages, onParams) {
+  const isBatched = Array.isArray(messages[0]);
+  let callIndex = 0;
+  return async function* mockQuery(params) {
+    if (onParams) onParams(params);
+    if (!isBatched) {
+      for (const msg of messages) yield msg;
+      return;
+    }
+    const batch = messages[callIndex] ?? messages[messages.length - 1] ?? [];
+    callIndex += 1;
+    for (const msg of batch) yield msg;
+  };
+}

package/src/fixture/index.js

@@ -5,3 +5,5 @@ export {
 } from "./assertions.js";
 export * from "./services.js";
 export * from "./pathway.js";
+export * from "./eval.js";
+export { memoizeAsync, memoizeOnSubject } from "./cache.js";

package/src/fixture/pathway.js

@@ -291,3 +291,161 @@ export function createTestBehaviourEntry(overrides = {}) {
     ...overrides,
   };
 }
+
+/**
+ * Creates a set of mock drivers
+ * @returns {object[]}
+ */
+export function createTestDrivers() {
+  return [
+    createTestDriver({
+      id: "velocity",
+      name: "Velocity",
+      contributingSkills: ["coding", "testing"],
+      contributingBehaviours: ["collaboration"],
+    }),
+    createTestDriver({
+      id: "quality",
+      name: "Quality",
+      contributingSkills: ["testing", "architecture"],
+      contributingBehaviours: ["communication"],
+    }),
+  ];
+}
+
+/**
+ * Creates a set of mock capabilities spanning delivery / scale / ai.
+ * @returns {object[]}
+ */
+export function createTestCapabilities() {
+  return [
+    createTestCapability({ id: "delivery", name: "Delivery", ordinalRank: 1 }),
+    createTestCapability({ id: "scale", name: "Scale", ordinalRank: 2 }),
+    createTestCapability({ id: "ai", name: "AI", ordinalRank: 3 }),
+  ];
+}
+
+/**
+ * Creates a set of mock tracks.
+ * @returns {object[]}
+ */
+export function createTestTracks() {
+  return [
+    createTestTrack({
+      id: "platform",
+      name: "Platform",
+      skillModifiers: { scale: 1, delivery: -1 },
+    }),
+    createTestTrack({
+      id: "forward_deployed",
+      name: "Forward Deployed",
+      skillModifiers: { delivery: 1, scale: -1 },
+    }),
+  ];
+}
+
+/**
+ * Creates a set of mock disciplines.
+ * @returns {object[]}
+ */
+export function createTestDisciplines() {
+  return [
+    createTestDiscipline({
+      id: "software_engineering",
+      name: "Software Engineering",
+      roleTitle: "Software Engineer",
+    }),
+  ];
+}
+
+/**
+ * Builds a complete mock framework (capabilities, skills, disciplines, tracks,
+ * drivers, behaviours, levels) with sensible defaults. Per-slice overrides
+ * replace the default for that slice entirely.
+ *
+ * @param {object} [overrides]
+ * @param {object[]} [overrides.capabilities]
+ * @param {object[]} [overrides.skills]
+ * @param {object[]} [overrides.disciplines]
+ * @param {object[]} [overrides.tracks]
+ * @param {object[]} [overrides.drivers]
+ * @param {object[]} [overrides.behaviours]
+ * @param {object[]} [overrides.levels]
+ * @returns {object} Framework with all slices populated.
+ */
+export function createTestFramework(overrides = {}) {
+  return {
+    capabilities: overrides.capabilities ?? createTestCapabilities(),
+    skills: overrides.skills ?? createTestSkills(),
+    disciplines: overrides.disciplines ?? createTestDisciplines(),
+    tracks: overrides.tracks ?? createTestTracks(),
+    drivers: overrides.drivers ?? createTestDrivers(),
+    behaviours: overrides.behaviours ?? createTestBehaviours(),
+    levels: overrides.levels ?? createTestLevels(),
+  };
+}
+
+/**
+ * Creates a mock person (activity layer / people roster entry).
+ * @param {object} [overrides]
+ * @returns {object}
+ */
+export function createTestPerson(overrides = {}) {
+  return {
+    id: "p-alice",
+    name: "Alice",
+    email: "alice@example.com",
+    level: "mid",
+    discipline: "software_engineering",
+    track: "platform",
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock roster (team snapshot).
+ * @param {object} [overrides]
+ * @returns {object}
+ */
+export function createTestRoster(overrides = {}) {
+  return {
+    team: "t-alpha",
+    members: [createTestPerson()],
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock evidence row shared across map and landmark tests.
+ * @param {object} [overrides]
+ * @returns {object}
+ */
+export function createTestEvidenceRow(overrides = {}) {
+  return {
+    skill_id: "coding",
+    level_id: "mid",
+    matched: true,
+    artifact_id: "art-1",
+    created_at: "2026-01-01T00:00:00Z",
+    github_artifacts: [],
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock skill augmented with per-level markers (human + agent arrays).
+ * @param {object} [overrides]
+ * @returns {object}
+ */
+export function createTestSkillWithMarkers(overrides = {}) {
+  return {
+    ...createTestSkill(),
+    markers: {
+      foundational: { human: ["writes simple code"], agent: [] },
+      working: { human: ["owns features"], agent: ["reviews PRs"] },
+      practitioner: { human: ["mentors peers"], agent: [] },
+      expert: { human: ["shapes strategy"], agent: [] },
+    },
+    ...overrides,
+  };
+}

package/src/mock/clients.js

@@ -1,4 +1,4 @@
-import { mock } from "node:test";
+import { spy } from "./spy.js";
 import { common } from "@forwardimpact/libtype";
 
 /**
@@ -8,13 +8,13 @@ import { common } from "@forwardimpact/libtype";
  */
 export function createMockMemoryClient(overrides = {}) {
   return {
-    GetWindow: mock.fn(() =>
+    GetWindow: spy(() =>
       Promise.resolve({
         messages: [{ role: "system", content: "You are an assistant" }],
         tools: [],
       }),
     ),
-    AppendMemory: mock.fn(() => Promise.resolve({ accepted: "test-id" })),
+    AppendMemory: spy(() => Promise.resolve({ accepted: "test-id" })),
     ...overrides,
   };
 }
@@ -26,7 +26,7 @@ export function createMockMemoryClient(overrides = {}) {
  */
 export function createMockLlmClient(overrides = {}) {
   return {
-    CreateCompletions: mock.fn(() =>
+    CreateCompletions: spy(() =>
       Promise.resolve({
         id: "test-completion",
         choices: [
@@ -40,7 +40,7 @@ export function createMockLlmClient(overrides = {}) {
         usage: { total_tokens: 100 },
       }),
     ),
-    CreateEmbeddings: mock.fn(() =>
+    CreateEmbeddings: spy(() =>
       Promise.resolve({
         data: [{ index: 0, embedding: [0.1, 0.2, 0.3] }],
       }),
@@ -56,7 +56,7 @@ export function createMockLlmClient(overrides = {}) {
  */
 export function createMockAgentClient(overrides = {}) {
   return {
-    ProcessUnary: mock.fn(() =>
+    ProcessUnary: spy(() =>
       Promise.resolve({
         resource_id: "test-conversation",
         choices: [
@@ -69,7 +69,7 @@ export function createMockAgentClient(overrides = {}) {
         ],
       }),
     ),
-    ProcessStream: mock.fn(),
+    ProcessStream: spy(),
     ...overrides,
   };
 }
@@ -81,7 +81,7 @@ export function createMockAgentClient(overrides = {}) {
  */
 export function createMockTraceClient(overrides = {}) {
   return {
-    RecordSpan: mock.fn(() => Promise.resolve()),
+    RecordSpan: spy(() => Promise.resolve()),
     ...overrides,
   };
 }
@@ -93,7 +93,7 @@ export function createMockTraceClient(overrides = {}) {
  */
 export function createMockVectorClient(overrides = {}) {
   return {
-    SearchContent: mock.fn(() =>
+    SearchContent: spy(() =>
       Promise.resolve({
         identifiers: [],
       }),
@@ -109,7 +109,7 @@ export function createMockVectorClient(overrides = {}) {
  */
 export function createMockGraphClient(overrides = {}) {
   return {
-    QueryByPattern: mock.fn(() =>
+    QueryByPattern: spy(() =>
       Promise.resolve({
         identifiers: [],
       }),
@@ -125,7 +125,7 @@ export function createMockGraphClient(overrides = {}) {
  */
 export function createMockToolClient(overrides = {}) {
   return {
-    CallTool: mock.fn(() =>
+    CallTool: spy(() =>
       Promise.resolve({
         content: "Tool result",
       }),

package/src/mock/fs.js

@@ -1,5 +1,4 @@
-import { mock } from "node:test";
-
+import { spy } from "./spy.js";
 /**
  * Creates a mock filesystem backed by an in-memory Map
  * @param {Object<string, string>} files - Initial file contents keyed by path
@@ -20,7 +19,7 @@ export function createMockFs(files = {}) {
   return {
     data,
     dirs,
-    readFile: mock.fn(async (path, encoding) => {
+    readFile: spy(async (path, encoding) => {
       const content = data.get(path);
       if (content === undefined) {
         const err = new Error(
@@ -31,13 +30,13 @@ export function createMockFs(files = {}) {
       }
       return encoding ? content : Buffer.from(content);
     }),
-    writeFile: mock.fn(async (path, content) => {
+    writeFile: spy(async (path, content) => {
       data.set(
         path,
         typeof content === "string" ? content : content.toString(),
       );
     }),
-    readdir: mock.fn(async (path) => {
+    readdir: spy(async (path) => {
       const entries = [];
       const prefix = path.endsWith("/") ? path : `${path}/`;
       for (const key of data.keys()) {
@@ -51,7 +50,7 @@ export function createMockFs(files = {}) {
       }
       return entries;
     }),
-    stat: mock.fn(async (path) => {
+    stat: spy(async (path) => {
       if (data.has(path)) {
         return { isFile: () => true, isDirectory: () => false };
       }
@@ -64,10 +63,10 @@ export function createMockFs(files = {}) {
       err.code = "ENOENT";
       throw err;
     }),
-    mkdir: mock.fn(async (path) => {
+    mkdir: spy(async (path) => {
       dirs.add(path);
     }),
-    access: mock.fn(async (path) => {
+    access: spy(async (path) => {
       if (!data.has(path) && !dirs.has(path)) {
         const err = new Error(
           `ENOENT: no such file or directory, access '${path}'`,
@@ -76,7 +75,7 @@ export function createMockFs(files = {}) {
         throw err;
       }
     }),
-    copyFile: mock.fn(async (src, dest) => {
+    copyFile: spy(async (src, dest) => {
       const content = data.get(src);
       if (content === undefined) {
         const err = new Error(
@@ -87,8 +86,8 @@ export function createMockFs(files = {}) {
       }
       data.set(dest, content);
     }),
-    existsSync: mock.fn((path) => data.has(path) || dirs.has(path)),
-    readFileSync: mock.fn((path, encoding) => {
+    existsSync: spy((path) => data.has(path) || dirs.has(path)),
+    readFileSync: spy((path, encoding) => {
       const content = data.get(path);
       if (content === undefined) {
         const err = new Error(
@@ -99,13 +98,13 @@ export function createMockFs(files = {}) {
       }
       return encoding ? content : Buffer.from(content);
     }),
-    writeFileSync: mock.fn((path, content) => {
+    writeFileSync: spy((path, content) => {
       data.set(
         path,
         typeof content === "string" ? content : content.toString(),
       );
     }),
-    mkdirSync: mock.fn((path) => {
+    mkdirSync: spy((path) => {
       dirs.add(path);
     }),
   };

package/src/mock/grpc.js

@@ -1,5 +1,4 @@
-import { mock } from "node:test";
-
+import { spy } from "./spy.js";
 /**
  * Creates a mock gRPC factory function
  * @param {object} overrides - Method overrides
@@ -9,21 +8,21 @@ export function createMockGrpcFn(overrides = {}) {
   const mockGrpc = {
     Server: function () {
       return {
-        addService: mock.fn(),
-        bindAsync: mock.fn((uri, creds, callback) => callback(null, 5000)),
-        tryShutdown: mock.fn((callback) => callback()),
+        addService: spy(),
+        bindAsync: spy((uri, creds, callback) => callback(null, 5000)),
+        tryShutdown: spy((callback) => callback()),
         ...overrides.server,
       };
     },
-    loadPackageDefinition: mock.fn(() => ({
+    loadPackageDefinition: spy(() => ({
       test: { Test: { service: {} } },
     })),
-    makeGenericClientConstructor: mock.fn(() => function () {}),
+    makeGenericClientConstructor: spy(() => function () {}),
     ServerCredentials: {
-      createInsecure: mock.fn(),
+      createInsecure: spy(),
     },
     credentials: {
-      createInsecure: mock.fn(),
+      createInsecure: spy(),
     },
     status: {
       OK: 0,
@@ -48,7 +47,7 @@ export function createMockGrpcFn(overrides = {}) {
   };
 
   const mockProtoLoader = {
-    loadSync: mock.fn(() => ({})),
+    loadSync: spy(() => ({})),
     ...overrides.protoLoader,
   };
 

package/src/mock/index.js

@@ -25,3 +25,12 @@ export {
 } from "./clients.js";
 export { createMockServiceCallbacks } from "./service-callbacks.js";
 export { createMockFs } from "./fs.js";
+export { spy } from "./spy.js";
+export {
+  createMockSupabaseClient,
+  createTurtleHelpers,
+  createMockProcess,
+  withSilentConsole,
+  createMockS3Client,
+  createMockQueries,
+} from "./infra.js";

package/src/mock/infra.js

@@ -0,0 +1,219 @@
+/**
+ * Additional infrastructure mocks for services/products tests.
+ *
+ * Historically each consumer inlined its own variant. See spec 620 for the
+ * call-site inventory.
+ */
+
+/**
+ * Creates a mock Supabase-style client with configurable table and storage
+ * behaviour. Covers the patterns found across products/map/test/activity/*.
+ *
+ * @param {object} [options]
+ * @param {Record<string, object>} [options.tables] - Map of table name to
+ *   override. Each override may expose `select`, `insert`, `upsert`, `delete`
+ *   as async functions. Unspecified methods return `{ data: [], error: null }`.
+ * @param {Record<string, string>} [options.files] - Files exposed via
+ *   `storage.from(...).list(prefix)` / `.download(path)`.
+ * @returns {object} Mock client and call-tracking arrays.
+ */
+export function createMockSupabaseClient({ tables = {}, files = {} } = {}) {
+  const calls = {
+    select: [],
+    insert: [],
+    upsert: [],
+    delete: [],
+    download: [],
+    list: [],
+  };
+
+  function record(kind, entry) {
+    calls[kind].push(entry);
+  }
+
+  return {
+    calls,
+    from(table) {
+      const override = tables[table] ?? {};
+      return {
+        async select(...args) {
+          record("select", { table, args });
+          if (override.select) return override.select(...args);
+          return { data: [], error: null };
+        },
+        async insert(rows, opts) {
+          record("insert", { table, rows, options: opts });
+          if (override.insert) return override.insert(rows, opts);
+          return { data: rows, error: null };
+        },
+        async upsert(rows, opts) {
+          record("upsert", {
+            table,
+            rows,
+            onConflict: opts?.onConflict,
+            options: opts,
+          });
+          if (override.upsert) return override.upsert(rows, opts);
+          return { data: rows, error: null };
+        },
+        async delete(...args) {
+          record("delete", { table, args });
+          if (override.delete) return override.delete(...args);
+          return { error: null };
+        },
+      };
+    },
+    storage: {
+      from() {
+        return {
+          async list(prefix) {
+            record("list", { prefix });
+            const names = Object.keys(files)
+              .filter((k) => k.startsWith(prefix))
+              .map((k) => ({
+                name: k.slice(prefix.length),
+                created_at: "z",
+              }));
+            return { data: names, error: null };
+          },
+          async download(path) {
+            record("download", { path });
+            const content = files[path];
+            if (content === undefined) {
+              return { data: null, error: { message: "not found" } };
+            }
+            return {
+              data: { text: async () => content },
+              error: null,
+            };
+          },
+        };
+      },
+    },
+  };
+}
+
+/**
+ * Creates Turtle parsing helpers bound to an injected n3 Parser. Keeps
+ * libharness free of an n3 dependency while allowing services to share the
+ * parseQuads / findAll / findOne idiom.
+ *
+ * @param {import("n3").Parser | Function} ParserOrInstance - n3 Parser class
+ *   or a pre-built parser instance.
+ * @param {object} [options]
+ * @param {string} [options.format="Turtle"] - Parser format.
+ * @returns {object} { parseQuads, findAll, findOne }
+ */
+export function createTurtleHelpers(
+  ParserOrInstance,
+  { format = "Turtle" } = {},
+) {
+  const isClass =
+    typeof ParserOrInstance === "function" &&
+    ParserOrInstance.prototype &&
+    typeof ParserOrInstance.prototype.parse === "function";
+  const parser = isClass ? new ParserOrInstance({ format }) : ParserOrInstance;
+
+  function parseQuads(turtle) {
+    return parser.parse(turtle);
+  }
+
+  function findAll(quads, { subject, predicate, object } = {}) {
+    return quads.filter(
+      (q) =>
+        (!subject || q.subject.value === subject) &&
+        (!predicate || q.predicate.value === predicate) &&
+        (!object || q.object.value === object),
+    );
+  }
+
+  function findOne(quads, pattern) {
+    return findAll(quads, pattern)[0];
+  }
+
+  return { parseQuads, findAll, findOne };
+}
+
+/**
+ * Creates a minimal mock `process`-like object with env, stdout, stderr,
+ * exitCode, and simple write capture.
+ *
+ * @param {object} [options]
+ * @param {Record<string, string>} [options.env]
+ * @returns {object}
+ */
+export function createMockProcess({ env = {} } = {}) {
+  const stdout = { chunks: [], write: (s) => stdout.chunks.push(String(s)) };
+  const stderr = { chunks: [], write: (s) => stderr.chunks.push(String(s)) };
+  return {
+    env: { ...env },
+    stdout,
+    stderr,
+    exitCode: 0,
+    exit(code = 0) {
+      this.exitCode = code;
+    },
+  };
+}
+
+/**
+ * Runs `fn` with `console.log`, `console.info`, and `console.warn` suppressed,
+ * returning whatever `fn` returns. Errors still propagate.
+ *
+ * @template T
+ * @param {() => T | Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withSilentConsole(fn) {
+  const originals = {
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+  };
+  console.log = () => {};
+  console.info = () => {};
+  console.warn = () => {};
+  try {
+    return await fn();
+  } finally {
+    console.log = originals.log;
+    console.info = originals.info;
+    console.warn = originals.warn;
+  }
+}
+
+/**
+ * Creates a bag of async query stubs from a plain values object. A function
+ * value is passed through untouched; anything else becomes an async function
+ * returning that value. Collapses landmark-style `stubQueries` boilerplate.
+ *
+ * @param {Record<string, unknown>} values
+ * @returns {Record<string, Function>}
+ */
+export function createMockQueries(values = {}) {
+  const out = {};
+  for (const [key, val] of Object.entries(values)) {
+    out[key] = typeof val === "function" ? val : async () => val;
+  }
+  return out;
+}
+
+/**
+ * Creates a minimal mock S3 client that records command sends and returns a
+ * configurable response.
+ *
+ * @param {object} [options]
+ * @param {(command: object) => unknown} [options.sendFn] - Custom send handler.
+ * @returns {object} { client, sends }
+ */
+export function createMockS3Client({ sendFn } = {}) {
+  const sends = [];
+  return {
+    sends,
+    async send(command) {
+      sends.push(command);
+      if (sendFn) return sendFn(command);
+      return {};
+    },
+  };
+}

package/src/mock/logger.js

@@ -1,5 +1,4 @@
-import { mock } from "node:test";
-
+import { spy } from "./spy.js";
 /**
  * Creates a mock logger with call tracking
  * @param {object} options - Logger options
@@ -11,7 +10,7 @@ export function createMockLogger(options = {}) {
   const capture = options.captureOutput ?? false;
 
   const createMethod = (level) =>
-    mock.fn((appId, msg, attributes) => {
+    spy((appId, msg, attributes) => {
       if (capture) {
         logs.push({ level, appId, msg, attributes });
       }

package/src/mock/observer.js

@@ -1,5 +1,4 @@
-import { mock } from "node:test";
-
+import { spy } from "./spy.js";
 /**
  * Creates a mock observer factory
  * @param {object} logger - Logger to use (optional)
@@ -7,9 +6,9 @@ import { mock } from "node:test";
  */
 export function createMockObserverFn(logger = null) {
   const mockLogger = logger || {
-    debug: mock.fn(),
-    info: mock.fn(),
-    error: mock.fn(),
+    debug: spy(),
+    info: spy(),
+    error: spy(),
   };
 
   return () => ({
@@ -33,20 +32,20 @@ export function createMockObserverFn(logger = null) {
  */
 export function createMockTracer(overrides = {}) {
   return {
-    startSpan: mock.fn((name, options = {}) => ({
+    startSpan: spy((name, options = {}) => ({
       span_id: `span-${Date.now()}`,
       trace_id: `trace-${Date.now()}`,
       name,
       ...options,
     })),
-    startClientSpan: mock.fn((_service, _method) => ({
+    startClientSpan: spy((_service, _method) => ({
       span: {
         span_id: `client-span-${Date.now()}`,
         trace_id: `trace-${Date.now()}`,
       },
       metadata: { get: () => [], set: () => {} },
     })),
-    startServerSpan: mock.fn((_service, _method, _request, metadata) => ({
+    startServerSpan: spy((_service, _method, _request, metadata) => ({
       span_id: `server-span-${Date.now()}`,
       trace_id: metadata?.get?.("x-trace-id")?.[0] || `trace-${Date.now()}`,
     })),
@@ -54,8 +53,8 @@ export function createMockTracer(overrides = {}) {
       run: (span, fn) => fn(),
       getStore: () => null,
     }),
-    endSpan: mock.fn(),
-    recordError: mock.fn(),
+    endSpan: spy(),
+    recordError: spy(),
     ...overrides,
   };
 }

package/src/mock/spy.js

@@ -0,0 +1,44 @@
+/**
+ * Portable mock function helper. Replaces `mock.fn` from `node:test` so the
+ * test suite can run under either node:test or bun:test.
+ *
+ * Shape matches node:test's `mock.fn` to keep call-inspection sites
+ * (`fn.mock.calls[0].arguments`, `fn.mock.callCount()`, `fn.mock.resetCalls()`)
+ * unchanged across the codebase.
+ *
+ * @template T
+ * @param {(...args: any[]) => T} [impl] - Initial implementation.
+ * @returns {((...args: any[]) => T) & { mock: { calls: Array<{arguments: any[], result?: T, error?: unknown, this: unknown}>, callCount: () => number, resetCalls: () => void, mockImplementation: (newImpl: (...args: any[]) => T) => void } }}
+ */
+export function spy(impl) {
+  let _impl = impl;
+  const calls = [];
+  const fn = function (...args) {
+    const rec = { arguments: args, this: this };
+    if (!_impl) {
+      calls.push(rec);
+      return undefined;
+    }
+    try {
+      const result = _impl.apply(this, args);
+      rec.result = result;
+      calls.push(rec);
+      return result;
+    } catch (err) {
+      rec.error = err;
+      calls.push(rec);
+      throw err;
+    }
+  };
+  fn.mock = {
+    calls,
+    callCount: () => calls.length,
+    resetCalls: () => {
+      calls.length = 0;
+    },
+    mockImplementation: (newImpl) => {
+      _impl = newImpl;
+    },
+  };
+  return fn;
+}

package/src/mock/storage.js

@@ -1,5 +1,4 @@
-import { mock } from "node:test";
-
+import { spy } from "./spy.js";
 /**
  * Creates a mock storage instance with tracking
  * @param {object} overrides - Method overrides
@@ -10,8 +9,8 @@ export function createMockStorage(overrides = {}) {
 
   return {
     data,
-    exists: mock.fn((key) => Promise.resolve(data.has(key))),
-    get: mock.fn((key) => {
+    exists: spy((key) => Promise.resolve(data.has(key))),
+    get: spy((key) => {
       const value = data.get(key);
       if (!value) return Promise.reject(new Error("Not found"));
 
@@ -24,20 +23,20 @@ export function createMockStorage(overrides = {}) {
       }
       return Promise.resolve(value);
     }),
-    put: mock.fn((key, value) => {
+    put: spy((key, value) => {
       data.set(key, value);
       return Promise.resolve();
     }),
-    append: mock.fn((key, value) => {
+    append: spy((key, value) => {
       const existing = data.get(key) || "";
       data.set(key, existing ? `${existing}\n${value}` : value);
       return Promise.resolve();
     }),
-    delete: mock.fn((key) => {
+    delete: spy((key) => {
       data.delete(key);
       return Promise.resolve();
     }),
-    findByPrefix: mock.fn(() => Promise.resolve([])),
+    findByPrefix: spy(() => Promise.resolve([])),
     ...overrides,
   };
 }