@forwardimpact/libmock 0.1.14 → 0.1.16

package/README.md

@@ -75,7 +75,7 @@ for narrower imports.
 
 Canonical fakes for the `runtime` collaborator surfaces. Every test that needs
 a fake imports it from here so production and test wire the same shape.
-`createTestRuntime` assembles them into a frozen bag mirroring libutil's
+`createTestRuntime` assembles them into a frozen bag that mirrors libutil's
 `createDefaultRuntime`.
 
 | Surface | Production shape | Factory | Example |
@@ -92,16 +92,17 @@ a fake imports it from here so production and test wire the same shape.
 | grpc health def | stripped `{ Check: { path, … } }` shape | `createMockGrpcHealthDefinition` | `const def = createMockGrpcHealthDefinition();` |
 | repl env | readline/process/os/formatter/storage bundle | `createReplEnvironment` | `const { readline, process } = createReplEnvironment();` |
 
-`test/runtime-completeness.test.js` asserts every field on libutil's `Runtime`
-typedef has a matching fake here, so the fakes can't drift behind the bag.
+`test/runtime-completeness.test.js` asserts that every field on libutil's
+`Runtime` typedef has a matching fake here. So the fakes cannot drift behind
+the bag.
 
 ## When to extend libmock
 
-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
-libmock in the same PR instead of inlining. See
+Check `src/index.js` before you add a helper locally in a test file. If the
+helper does not exist, and two or more files would use it, add it to libmock
+in the same PR. Do not inline it. See
 [CONTRIBUTING.md](../../CONTRIBUTING.md) READ-DO and DO-CONFIRM checklists for
-the enforced policy and `.coaligned/invariants/libmock.rules.mjs` for the
+the enforced policy. See `.jidoka/invariants/libmock.rules.mjs` for the
 pre-commit guard that flags inline reimplementations.
 
 ## `spy` vs `node:test`'s `mock.fn`
@@ -118,5 +119,5 @@ fn.mock.resetCalls();
 fn.mock.mockImplementation((x) => x + 1);
 ```
 
-Prefer `spy` over `node:test`'s `mock.fn` — `spy` works under both `bun test`
+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/libmock",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Shared mocks and test fixtures so every library and service tests the same way.",
   "keywords": [
     "test",

package/src/expect/index.js

@@ -1,7 +1,8 @@
 /**
  * Dependency-free, runner-independent `expect()` shim. Replaces `expect` from
- * `bun:test` so the test suite can run under `node --test` (which ships no
- * `expect`) as well as `bun test`. Mirrors how `spy()` replaced `mock.fn`.
+ * `bun:test` so the test suite can run under `node --test` and under
+ * `bun test`. `node --test` ships no `expect`. Mirrors how `spy()` replaced
+ * `mock.fn`.
  *
  * Covers exactly the matcher surface the converged test files use: `toBe`,
  * `toEqual`, `toMatchObject`, `toBeNull`, `toBeUndefined`, `toBeDefined`,
@@ -16,9 +17,9 @@ import { AssertionError } from "node:assert";
 import { isDeepStrictEqual } from "node:util";
 
 /**
- * Render a value for assertion messages without throwing on circular refs.
+ * Render a value for assertion messages. It does not throw on circular refs.
  * @param {unknown} value - Value to stringify.
- * @returns {string} Human-readable rendering.
+ * @returns {string} Human-readable text.
  */
 function show(value) {
   if (typeof value === "string") {
@@ -41,12 +42,13 @@ function show(value) {
 }
 
 /**
- * Throw or, when negated, swallow — the single choke point that makes `.not`
- * invert every matcher. `pass` is the un-negated truth of the assertion.
+ * Throw, or swallow when negated. This function is the single choke point
+ * that makes `.not` invert every matcher. `pass` is the un-negated truth of
+ * the assertion.
  * @param {boolean} pass - Whether the positive assertion holds.
  * @param {boolean} negated - Whether `.not` is active.
- * @param {string} message - Message for the failing (positive) direction.
- * @param {string} [negatedMessage] - Message for the failing negated direction.
+ * @param {string} message - Message for a failed positive assertion.
+ * @param {string} [negatedMessage] - Message for a failed negated assertion.
  */
 function settle(pass, negated, message, negatedMessage) {
   if (negated) {
@@ -65,7 +67,8 @@ function settle(pass, negated, message, negatedMessage) {
 const ASYMMETRIC = Symbol.for("libmock.expect.asymmetric");
 
 /**
- * Whether `value` is an asymmetric matcher produced by `expect.any` / friends.
+ * Whether `value` is an asymmetric matcher from `expect.any` or a sibling
+ * helper.
  * @param {unknown} value - Candidate.
  * @returns {boolean} True when `value` carries the asymmetric marker.
  */
@@ -98,7 +101,8 @@ function equals(actual, expected) {
     }
     return expected.every((e, i) => equals(actual[i], e));
   }
-  // No asymmetric matcher anywhere → exact deep equality is correct and cheap.
+  // No asymmetric matcher anywhere, so exact deep equality is correct and
+  // cheap.
   if (!containsAsymmetric(expected)) {
     return isDeepStrictEqual(actual, expected);
   }
@@ -128,8 +132,9 @@ function containsAsymmetric(value) {
 }
 
 /**
- * Deep subset match: every own enumerable key of `subset` matches the same key
- * in `actual` (recursively for plain objects, asymmetric-aware).
+ * Deep subset match. Every own enumerable key of `subset` matches the same
+ * key in `actual`. The match recurses into plain objects. The match also
+ * understands asymmetric matchers.
  * @param {unknown} actual - Candidate object.
  * @param {unknown} subset - Expected subset.
  * @returns {boolean} Whether `actual` contains `subset`.
@@ -164,7 +169,7 @@ function matchesObject(actual, subset) {
 }
 
 /**
- * Run a possibly-throwing function and apply the `toThrow` predicate.
+ * Run a function that may throw. Then apply the `toThrow` predicate.
  * @param {() => unknown} fn - The thunk under test.
  * @param {unknown} matcher - undefined, a string (substring), or a RegExp.
  * @param {boolean} negated - Whether `.not` is active.
@@ -343,8 +348,9 @@ function matchers(actual, negated) {
 }
 
 /**
- * Build the async matcher object for a promise-producing actual. Each matcher
- * awaits the promise and applies the underlying matcher to the settled value.
+ * Build the async matcher object for an actual value that produces a promise.
+ * Each matcher awaits the promise. Then it applies the underlying matcher to
+ * the settled value.
  * @param {unknown} actual - A promise (or thenable) under test.
  * @param {boolean} negated - Whether `.not` is active.
  * @param {"resolves" | "rejects"} mode - Which settlement to assert on.
@@ -381,8 +387,9 @@ function asyncMatchers(actual, negated, mode) {
     (name) =>
     (...args) => {
       if (name === "toThrow") {
-        // `rejects.toThrow(x)` asserts the rejection's message; the settled value
-        // here is the rejection itself, so wrap it back into a throwing thunk.
+        // `rejects.toThrow(x)` asserts the rejection's message. The settled
+        // value here is the rejection itself. So wrap it back into a thunk
+        // that throws.
         return wrap((settled) => {
           const thunk = () => {
             throw settled;
@@ -438,8 +445,9 @@ export function expect(actual) {
 }
 
 /**
- * Asymmetric matcher: matches any value constructed by / typed as `ctor`,
- * for use inside `toEqual` / `toMatchObject`. Mirrors Jest/bun `expect.any`.
+ * An asymmetric matcher. It matches any value that `ctor` constructed, or any
+ * value typed as `ctor`. Use it inside `toEqual` and `toMatchObject`. Mirrors
+ * Jest/bun `expect.any`.
  * @param {Function} ctor - A constructor or primitive wrapper (String, Number…).
  * @returns {object} An asymmetric matcher.
  */
@@ -467,7 +475,7 @@ expect.any = (ctor) => ({
 });
 
 /**
- * Asymmetric matcher: matches any non-null, non-undefined value.
+ * An asymmetric matcher. It matches any non-null, non-undefined value.
  * @returns {object} An asymmetric matcher.
  */
 expect.anything = () => ({

package/src/fixture/assertions.js

@@ -1,7 +1,7 @@
 import assert from "node:assert";
 
 /**
- * Asserts that a function throws with a matching message
+ * Asserts that a function throws with a message that matches the pattern
  * @param {Function} fn - Function to test
  * @param {RegExp|string} pattern - Pattern to match
  * @param {string} message - Assertion message
@@ -15,7 +15,8 @@ export function assertThrowsMessage(fn, pattern, message) {
 }
 
 /**
- * Asserts that an async function rejects with a matching message
+ * Asserts that an async function rejects with a message that matches the
+ * pattern
  * @param {Function} fn - Async function to test
  * @param {RegExp|string} pattern - Pattern to match
  * @param {string} message - Assertion message
@@ -29,7 +30,7 @@ export async function assertRejectsMessage(fn, pattern, message) {
 }
 
 /**
- * Creates a deferred promise for async testing
+ * Creates a deferred promise for async tests
  * @returns {object} Object with promise, resolve, and reject
  */
 export function createDeferred() {

package/src/fixture/cache.js

@@ -1,19 +1,19 @@
 /**
- * Cross-file fixture caching helpers. The test runner currently executes one
- * test file per process, but fixtures loaded inside a file (e.g. starter
- * standard YAML via `createDataLoader(runtime).loadAllData(dir)`) are re-parsed for
- * every `test(...)` case unless hoisted.
+ * Helpers that cache fixtures across files. The test runner currently executes
+ * one test file per process. But each `test(...)` case re-parses the fixtures
+ * that a file loads inline, unless you hoist them. One example is the starter
+ * standard YAML from `createDataLoader(runtime).loadAllData(dir)`.
  */
 
 const caches = new WeakMap();
 const stringCaches = new Map();
 
 /**
- * Wraps an async factory so it is invoked at most once per unique key.
+ * Wraps an async factory. Calls the factory 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.
+ * @param {string} key - Cache key. The same key returns the cached value.
+ * @param {() => Promise<T>} factory - Factory to call on a cache miss.
  * @returns {Promise<T>}
  */
 export async function memoizeAsync(key, factory) {
@@ -29,8 +29,8 @@ export async function memoizeAsync(key, factory) {
 }
 
 /**
- * Caches the result of `fn(subject)` keyed by identity of `subject`. Useful
- * for expensive derivations over a frozen input object.
+ * Caches the result of `fn(subject)`. The identity of `subject` is the key.
+ * Use it for expensive derivations over a frozen input object.
  *
  * @template S, T
  * @param {S} subject
@@ -43,7 +43,7 @@ export function memoizeOnSubject(subject, fn) {
 }
 
 /**
- * Clears all memoization caches. Only useful in self-tests of this helper.
+ * Clears all memoization caches. Use it only in self-tests of this helper.
  */
 export function __resetMemoCaches() {
   stringCaches.clear();

package/src/fixture/eval.js

@@ -7,7 +7,7 @@
  */
 
 /**
- * Builds a tool-use message envelope as emitted by the agent SDK.
+ * Builds a tool-use message envelope in the shape the agent SDK emits.
  * Replaces per-file concludeMsg / redirectMsg / tellMsg / shareMsg helpers.
  *
  * @param {string} name - Tool name, e.g. "Conclude", "Redirect", "Tell", "Share".
@@ -33,7 +33,8 @@ export function createToolUseMsg(name, input, { id } = {}) {
 }
 
 /**
- * Builds an assistant text message envelope as emitted by the agent SDK.
+ * Builds an envelope for an assistant text message, in the shape the agent
+ * SDK emits.
  * @param {string} text - Text content.
  * @returns {object} Assistant message with a single text content block.
  */
@@ -76,7 +77,8 @@ export function stripAnsi(s) {
 }
 
 /**
- * Writes each line followed by a newline to the writer, then ends it.
+ * Writes each line to the writer with a newline after it. Then ends the
+ * writer.
  * @param {import("node:stream").Writable} writer
  * @param {string[]} lines
  * @returns {Promise<void>}
@@ -120,15 +122,15 @@ export function createTestTrace(overrides = {}) {
 }
 
 /**
- * Creates an async-generator agent query stub. The shape of `messages`
+ * Creates an async-generator stub for an agent query. 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.
+ *  - Flat array of message objects: the stub yields them on every call.
+ *  - Array of arrays (batches): the Nth call yields messages from the Nth
+ *    batch. Later calls past the last batch repeat the last batch.
  *
  * @param {object[] | object[][]} messages
- * @param {(params: object) => void} [onParams] - Invoked with call params.
- * @returns {Function} Async generator mimicking `query({...})`.
+ * @param {(params: object) => void} [onParams] - Receives the call params.
+ * @returns {Function} Async generator that mimics `query({...})`.
  */
 export function createMockAgentQuery(messages, onParams) {
   const isBatched = Array.isArray(messages[0]);

package/src/fixture/pathway.js

@@ -1,5 +1,5 @@
 /**
- * Pathway test fixtures for creating realistic test data
+ * Pathway test fixtures that create realistic test data
  * Provides mock disciplines, levels, tracks, skills, and behaviours
  */
 
@@ -27,7 +27,7 @@ export function createTestLevel(overrides = {}) {
 }
 
 /**
- * Creates a set of mock levels spanning junior to senior
+ * Creates a set of mock levels from junior to senior
  * @returns {object[]} Array of mock levels
  */
 export function createTestLevels() {
@@ -260,9 +260,9 @@ export function createTestDriver(overrides = {}) {
 }
 
 /**
- * Creates a mock skill matrix entry
+ * Creates a mock skill-matrix entry
  * @param {object} overrides - Properties to override
- * @returns {object} Mock skill matrix entry
+ * @returns {object} Mock skill-matrix entry
  */
 export function createTestSkillEntry(overrides = {}) {
   return {
@@ -278,9 +278,9 @@ export function createTestSkillEntry(overrides = {}) {
 }
 
 /**
- * Creates a mock behaviour profile entry
+ * Creates a mock behaviour-profile entry
  * @param {object} overrides - Properties to override
- * @returns {object} Mock behaviour profile entry
+ * @returns {object} Mock behaviour-profile entry
  */
 export function createTestBehaviourEntry(overrides = {}) {
   return {
@@ -314,7 +314,7 @@ export function createTestDrivers() {
 }
 
 /**
- * Creates a set of mock capabilities spanning delivery / scale / ai.
+ * Creates a set of mock capabilities across delivery / scale / ai.
  * @returns {object[]}
  */
 export function createTestCapabilities() {
@@ -416,7 +416,7 @@ export function createTestRoster(overrides = {}) {
 }
 
 /**
- * Creates a mock evidence row shared across map and landmark tests.
+ * Creates a mock evidence row that map tests and landmark tests share.
  * @param {object} [overrides]
  * @returns {object}
  */
@@ -433,7 +433,7 @@ export function createTestEvidenceRow(overrides = {}) {
 }
 
 /**
- * Creates a mock skill augmented with per-level markers (human + agent arrays).
+ * Creates a mock skill with per-level markers (human + agent arrays).
  * @param {object} [overrides]
  * @returns {object}
  */

package/src/fixture/services.js

@@ -1,9 +1,9 @@
 /**
- * Test fixture utilities for creating dynamic test data
+ * Test fixture utilities that create dynamic test data
  */
 
 /**
- * Creates sample request data for testing
+ * Creates sample request data for tests
  * @param {object} overrides - Properties to override
  * @returns {object} Test request object
  */
@@ -17,7 +17,7 @@ export function createTestRequest(overrides = {}) {
 }
 
 /**
- * Creates sample vector data for testing
+ * Creates sample vector data for tests
  * @param {number} count - Number of vectors to create
  * @returns {Array} Array of test vectors
  */
@@ -30,7 +30,7 @@ export function createTestVectors(count = 3) {
 }
 
 /**
- * Creates sample message data for testing
+ * Creates sample message data for tests
  * @param {number} count - Number of messages to create
  * @returns {Array} Array of test messages
  */
@@ -43,7 +43,7 @@ export function createTestMessages(count = 3) {
 }
 
 /**
- * Creates sample chunk data for testing
+ * Creates sample chunk data for tests
  * @param {number} count - Number of chunks to create
  * @returns {Array} Array of test chunks
  */

package/src/mock/clients.js

@@ -76,11 +76,11 @@ export function createMockAgentClient(overrides = {}) {
 }
 
 /**
- * Creates a mock trace client
+ * Creates a mock span client
  * @param {object} overrides - Method overrides
- * @returns {object} Mock trace client
+ * @returns {object} Mock span client
  */
-export function createMockTraceClient(overrides = {}) {
+export function createMockSpanClient(overrides = {}) {
   return {
     RecordSpan: spy(() => Promise.resolve()),
     ...overrides,
@@ -168,12 +168,12 @@ export function createMockDiscussionClient(overrides = {}) {
 }
 
 /**
- * Reject a request that omits `tenant_id`, mirroring `services/bridge`'s
- * `requireTenant` guard. Every tenant-scoped RPC carries a `tenant_id` in
- * both deployment modes (single-tenant binds the literal `"default"`); an
- * empty value is a caller error, not an empty result. The stateful mock
- * applies the same guard so production callers that forget to thread a
- * `tenant_id` fail in tests exactly as they would against the real service.
+ * Reject a request that omits `tenant_id`. This mirrors the `requireTenant`
+ * guard in `services/bridge`. Every tenant-scoped RPC carries a `tenant_id`
+ * in both deployment modes (single-tenant binds the literal `"default"`).
+ * An empty value is a caller error. It is not an empty result. The stateful
+ * mock applies the same guard. A production caller that forgets to thread a
+ * `tenant_id` fails in tests exactly as it fails against the real service.
  *
  * @param {{tenant_id?: string}} obj
  * @returns {string} the validated tenant id
@@ -208,7 +208,7 @@ function coerceInt64Fields(obj) {
 
 /**
  * Creates a stateful mock discussion client that retains records across
- * save/load cycles, coercing proto int64 fields back to numbers.
+ * save/load cycles. The client coerces proto int64 fields back to numbers.
  * @returns {object} Stateful mock discussion client
  */
 export function createStatefulDiscussionClient() {
@@ -241,8 +241,8 @@ export function createStatefulDiscussionClient() {
       const obj = req?.toJSON?.() ?? req;
       const tenant_id = requireTenant(obj);
       for (const rec of records.values()) {
-        // Filter to the requesting tenant after the correlation scan so a
-        // correlation owned by tenant A is invisible to tenant B.
+        // Filter to the tenant that made the request, after the correlation
+        // scan. A correlation owned by tenant A stays invisible to tenant B.
         if (rec.tenant_id !== tenant_id) continue;
         if (
           Object.values(rec.pending_callbacks ?? {}).includes(
@@ -274,8 +274,8 @@ export function createStatefulDiscussionClient() {
     RecordOrigin: spy(async (req) => {
       const obj = req?.toJSON?.() ?? req;
       const tenant_id = requireTenant(obj);
-      // Tenant-scope the origin key so a comment id recorded by tenant A is
-      // not seen as self-originated by tenant B.
+      // Tenant-scope the origin key so tenant B does not see a comment id
+      // recorded by tenant A as self-originated.
       origins.set(`${tenant_id}:${obj.id}`, obj);
       return {};
     }),

package/src/mock/clock.js

@@ -4,21 +4,22 @@ import { spy } from "./spy.js";
  * Creates a mock clock with controllable time and a no-wait sleep.
  *
  * `now()` returns the current virtual time in ms. `sleep(ms)` advances
- * virtual time by `ms` and resolves on the next microtask — no real
- * timers are scheduled. `advance(ms)` lets a test move time forward
- * without going through `sleep` (e.g. to expire a token).
+ * virtual time by `ms` and resolves on the next microtask. It schedules no
+ * real timers. `advance(ms)` lets a test move time forward without a call
+ * to `sleep` (e.g. to expire a token).
  *
  * Pass `{ sleep, now }` from a returned clock to any constructor that
  * accepts those collaborators to make its tests deterministic.
  *
  * `setTimeout(fn, ms)` / `clearTimeout(handle)` / `setInterval(fn, ms)` /
- * `clearInterval(handle)` delegate to the host's real timers (matching
- * `createDefaultClock`), so a migrated module that schedules work through the
- * injected clock keeps its real-timer test behaviour. Virtual `now()` and the
- * real timers are intentionally independent — a test that needs a fired timer
- * waits on real time as it did before migration; a periodic sweep timer is
- * typically `.unref()`'d and never fires during a unit test, which exercises
- * its eviction path through an explicit `now` argument instead.
+ * `clearInterval(handle)` delegate to the host's real timers, the same as
+ * `createDefaultClock`. So a migrated module that schedules work through
+ * the injected clock keeps its real-timer test behaviour. Virtual `now()`
+ * and the real timers stay independent by design. A test that needs a fired
+ * timer waits on real time, as it did before migration. A periodic sweep
+ * timer is typically `.unref()`'d and never fires during a unit test. The
+ * unit test exercises its eviction path through an explicit `now` argument
+ * instead.
  *
  * @param {object} [options]
  * @param {number} [options.start=0] - Initial virtual time in ms.

package/src/mock/data.js

@@ -1,5 +1,5 @@
 /**
- * Shared test data for common testing scenarios
+ * Shared test data for common test scenarios
  */
 
 // Sample request data

package/src/mock/environments.js

@@ -2,11 +2,12 @@ import { createMockStorage } from "./storage.js";
 
 /**
  * Graph-index test triple: a mock storage, an n3 Store, and a GraphIndex wired
- * to both. GraphIndex and Store are injected so libmock stays dependency-free.
+ * to both. The caller injects GraphIndex and Store so libmock stays
+ * dependency-free.
  * @param {object} opts
  * @param {Function} opts.GraphIndex - libgraph GraphIndex constructor.
  * @param {Function} opts.Store - n3 Store constructor.
- * @param {object} [opts.storageOverrides] - passed to createMockStorage.
+ * @param {object} [opts.storageOverrides] - overrides for createMockStorage.
  * @param {*} [opts.prefixes] - prefixes arg for GraphIndex (default {}).
  * @param {string} [opts.indexKey] - jsonl key (default "test-graph.jsonl").
  * @returns {{ n3Store: object, graphIndex: object, mockStorage: object }}
@@ -25,9 +26,10 @@ export function createGraphIndexFixture({
 }
 
 /**
- * The stripped gRPC health service definition consumers' tests fake — the
- * `{ Check: { path, requestStream, responseStream } }` shape, not librpc's
- * real `healthDefinition` (which librpc's own tests exercise directly).
+ * The stripped definition of the gRPC health service that consumers' tests
+ * fake. It has the `{ Check: { path, requestStream, responseStream } }`
+ * shape. It is not librpc's real `healthDefinition`, which librpc's own
+ * tests exercise directly.
  * @returns {{ Check: { path: string, requestStream: boolean, responseStream: boolean } }}
  */
 export function createMockGrpcHealthDefinition() {
@@ -42,7 +44,7 @@ export function createMockGrpcHealthDefinition() {
 
 /**
  * The readline/process/os/formatter/storage bundle librepl's tests inject.
- * Mirrors libraries/librepl/test/librepl.test.js's pre-collapse beforeEach.
+ * It mirrors libraries/librepl/test/librepl.test.js's pre-collapse beforeEach.
  * @returns {{ readline: object, process: object, os: object, formatter: Function, storage: object }}
  */
 export function createReplEnvironment() {

package/src/mock/finder.js

@@ -2,11 +2,11 @@ import path from "node:path";
 import { spy } from "./spy.js";
 
 /**
- * Creates a mock `Finder` collaborator over an in-memory `files` map. Mimics
- * the real `Finder` surface (`findUpward`, `findData`, `findProjectRoot`,
- * `findPackagePath`, `findGeneratedPath`, `createSymlink`,
- * `createPackageSymlinks`) without touching the real filesystem. Every call
- * is recorded on `calls`.
+ * Creates a mock `Finder` collaborator over an in-memory `files` map. It
+ * mimics the real `Finder` surface (`findUpward`, `findData`,
+ * `findProjectRoot`, `findPackagePath`, `findGeneratedPath`,
+ * `createSymlink`, `createPackageSymlinks`). It does not touch the real
+ * filesystem. The mock records every call on `calls`.
  *
  * @param {object} [options]
  * @param {Object<string, true|string>} [options.files] - Existing paths.

package/src/mock/fs.js

@@ -1,7 +1,7 @@
 import { Readable, Writable } from "node:stream";
 import { spy } from "./spy.js";
 /**
- * Creates a mock filesystem backed by an in-memory Map
+ * Creates a mock filesystem over an in-memory Map
  * @param {Object<string, string>} files - Initial file contents keyed by path
  * @returns {object} Mock fs with readFile, writeFile, readdir, stat, mkdir, access, copyFile
  */
@@ -55,8 +55,8 @@ export function createMockFs(files = {}) {
       data.delete(src);
     }),
     readdir: spy(async (path, opts = {}) => {
-      // Collect immediate children; an entry is a directory if anything lives
-      // below it (a deeper key) or it was registered via mkdir/cp.
+      // Collect immediate children. An entry is a directory if anything lives
+      // below it (a deeper key), or if mkdir/cp registered it.
       const prefix = path.endsWith("/") ? path : `${path}/`;
       const isDir = new Map();
       for (const key of [...data.keys(), ...dirs]) {
@@ -95,7 +95,7 @@ export function createMockFs(files = {}) {
     }),
     mkdtemp: spy(async (prefix) => {
       // Mirror node:fs/promises.mkdtemp: append 6 random chars to the prefix
-      // and register the directory. Returns the created path.
+      // and register the directory. Then return the created path.
       const path = `${prefix}${Math.random().toString(36).slice(2, 8)}`;
       dirs.add(path);
       return path;
@@ -173,8 +173,8 @@ export function createMockFs(files = {}) {
       }
       for (const dir of [...dirs].filter(under)) dirs.add(reroot(dir));
     }),
-    // Timestamps and permissions are not modeled by the in-memory store; these
-    // record the call (via spy) so consumers stay testable and assertable.
+    // The in-memory store does not model timestamps or permissions. These
+    // record the call (with spy) so consumers stay testable and assertable.
     utimes: spy(async () => {}),
     chmod: spy(async () => {}),
     existsSync: spy((path) => data.has(path) || dirs.has(path)),
@@ -230,12 +230,12 @@ export function createMockFs(files = {}) {
       }
       return [...names];
     }),
-    // Permissions are not modeled by the in-memory store; record the call.
+    // The in-memory store does not model permissions. Record the call.
     chmodSync: spy(() => {}),
     openSync: spy((path, flags = "r") => {
-      // For write/append flags, create/truncate; for read flags, require the
+      // For write/append flags, create/truncate. For read flags, require the
       // file to exist (mirror node:fs.openSync ENOENT). Hand back a synthetic
-      // descriptor that records its backing path.
+      // descriptor that records the path it opens.
       const reading = typeof flags === "string" && flags.startsWith("r");
       if (reading && !data.has(path)) {
         const err = new Error(
@@ -251,7 +251,7 @@ export function createMockFs(files = {}) {
     }),
     readSync: spy((fd, buffer, offset = 0, length, position = 0) => {
       // Mirror fs.readSync(fd, buffer, offset, length, position): copy bytes
-      // from the file's stored content into `buffer`, returning the byte count.
+      // from the file's stored content into `buffer`. Return the byte count.
       const path = openFds.get(fd);
       if (path === undefined) {
         const err = new Error("EBADF: bad file descriptor, read");

package/src/mock/gh-client.js

@@ -9,9 +9,9 @@ const GH_METHODS = [
 ];
 
 /**
- * Creates a mock `GhClient` collaborator. Each method is a spy returning the
- * configured `responses[method]` value (or a no-op default). Invocations are
- * recorded on `calls`.
+ * Creates a mock `GhClient` collaborator. Each method is a spy that returns
+ * the configured `responses[method]` value (or a no-op default). The mock
+ * records every call on `calls`.
  *
  * @param {object} [options]
  * @param {Record<string, unknown>} [options.responses] - Per-method returns.

package/src/mock/git-client.js

@@ -40,10 +40,10 @@ const GIT_METHODS = [
 ];
 
 // A response descriptor models one git failure: an `Error` thrown as-is, or
-// `{ throw: <message>, stderr?: <text> }` thrown as an Error carrying that
-// stderr — mirroring how GitClient's `#runRaw` surfaces a failure (the real
-// GitError exposes `.stderr`), so a caller inspecting stderr (e.g. to tell a
-// push rejection from an auth failure) sees a faithful shape.
+// `{ throw: <message>, stderr?: <text> }` thrown as an Error that carries
+// that stderr. This mirrors how GitClient's `#runRaw` surfaces a failure
+// (the real GitError exposes `.stderr`). So a caller that inspects stderr
+// (e.g. to tell a push rejection from an auth failure) sees a faithful shape.
 function isResponseDescriptor(value) {
   return (
     value instanceof Error ||
@@ -52,10 +52,11 @@ function isResponseDescriptor(value) {
 }
 
 // A configured response that is an array of response descriptors is a per-call
-// sequence: consumed one entry per invocation, reusing the last entry once
-// exhausted, so a test can express "push rejected on call 1, succeeds on call
-// 2". An array that is plain data (e.g. a `logByAuthor` commit list) is returned
-// whole — the descriptor check keeps data returns and failure sequences apart.
+// sequence. The mock takes one entry per invocation. It reuses the last entry
+// after the sequence runs out. So a test can express "push rejected on call 1,
+// succeeds on call 2". The mock returns the whole array when it holds plain
+// data (e.g. a `logByAuthor` commit list). The descriptor check keeps data
+// returns and failure sequences apart.
 function makeResponder(configured) {
   const isSequence =
     Array.isArray(configured) && configured.some(isResponseDescriptor);
@@ -75,7 +76,7 @@ function resolveResponse(responder) {
   return value;
 }
 
-// Per-method default returns when no `responses[method]` is configured.
+// Per-method default returns when the caller configures no `responses[method]`.
 // Methods absent here default to a no-op success `{ stdout, stderr, exitCode }`.
 const GIT_DEFAULTS = {
   revListCount: 0,
@@ -90,9 +91,10 @@ const GIT_DEFAULTS = {
 
 /**
  * Creates a mock `GitClient` collaborator. Every method on the real
- * `GitClient` surface is a spy returning a no-op success by default, or the
- * configured `responses[method]` value. `withAuth(token)` returns a client
- * sharing the same `calls` log. Invocations are recorded on `calls`.
+ * `GitClient` surface is a spy that returns a no-op success by default, or
+ * the configured `responses[method]` value. `withAuth(token)` returns a
+ * client that shares the same `calls` log. The mock records every call on
+ * `calls`.
  *
  * @param {object} [options]
  * @param {Record<string, unknown>} [options.responses] - Per-method returns.

package/src/mock/grpc.js

@@ -77,7 +77,7 @@ export class MockMetadata {
   /**
    * Gets metadata value by key
    * @param {string} key - The metadata key
-   * @returns {string[]} Array containing the value, or empty array if not found
+   * @returns {string[]} Array with the value, or empty array if not found
    */
   get(key) {
     const value = this.data.get(key);

package/src/mock/http.js

@@ -31,7 +31,7 @@ export function createMockRequest(options = {}) {
 }
 
 /**
- * Creates a mock HTTP response with tracking
+ * Creates a mock HTTP response that tracks calls
  * @returns {object} Mock response
  */
 export function createMockResponse() {

package/src/mock/index.js

@@ -18,7 +18,7 @@ export {
   createMockMemoryClient,
   createMockLlmClient,
   createMockAgentClient,
-  createMockTraceClient,
+  createMockSpanClient,
   createMockVectorClient,
   createMockGraphClient,
   createMockToolClient,

package/src/mock/infra.js

@@ -1,13 +1,14 @@
 /**
- * Additional infrastructure mocks for services/products tests. Centralizes
- * variants that consumers previously inlined.
+ * Additional infrastructure mocks for services/products tests. This module
+ * centralizes variants that consumers previously inlined.
  */
 import { Writable } from "node:stream";
 
 /**
- * A capturing `Writable` used as the mock `proc.stdout`/`stderr`. It retains
- * the `chunks` accessor existing assertions read AND is a real `Writable`, so
- * it accepts piped input (e.g. a `pipeline()` from a read stream).
+ * A `Writable` that captures output. The mock uses it as
+ * `proc.stdout`/`stderr`. It retains the `chunks` accessor that current
+ * assertions read. It is also a real `Writable`, so it accepts piped input
+ * (e.g. a `pipeline()` from a read stream).
  */
 class CaptureWritable extends Writable {
   constructor() {
@@ -28,15 +29,15 @@ class CaptureWritable extends Writable {
 
 /**
  * Creates a mock Supabase-style client with configurable table and storage
- * behaviour. Covers the patterns found across products/map/test/activity/*.
+ * behaviour. It covers the patterns 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
+ * @param {Record<string, string>} [options.files] - Files exposed through
  *   `storage.from(...).list(prefix)` / `.download(path)`.
- * @returns {object} Mock client and call-tracking arrays.
+ * @returns {object} Mock client and arrays that track calls.
  */
 export function createMockSupabaseClient({ tables = {}, files = {} } = {}) {
   const calls = {
@@ -115,8 +116,8 @@ export function createMockSupabaseClient({ tables = {}, files = {} } = {}) {
 }
 
 /**
- * Creates Turtle parsing helpers bound to an injected n3 Parser. Keeps
- * libmock free of an n3 dependency while allowing services to share the
+ * Creates helpers that parse Turtle with an injected n3 Parser. This keeps
+ * libmock free of an n3 dependency. Services can still share the
  * parseQuads / findAll / findOne idiom.
  *
  * @param {import("n3").Parser | Function} ParserOrInstance - n3 Parser class
@@ -156,8 +157,8 @@ export function createTurtleHelpers(
 }
 
 /**
- * Build an `AsyncIterable<string>` over a fixed list of input chunks, used as
- * the mock `proc.stdin`.
+ * Build an `AsyncIterable<string>` over a fixed list of input chunks. The
+ * mock uses it as `proc.stdin`.
  * @param {string[]} chunks - Lines/chunks the iterator yields in order.
  * @returns {AsyncIterable<string>}
  */
@@ -170,13 +171,14 @@ export function createMockStdin(chunks = []) {
 }
 
 /**
- * Creates a mock `process`-like object matching the `Runtime.proc` surface:
- * `cwd()`, `env`, `argv`, `stdin`, `stdout`/`stderr` (capturing `Writable`s),
- * `exit(code)`, `kill(pid, signal)`, `pid`, `platform`, `on(event, handler)`,
- * and a settable `exitCode`. Writes are captured on `stdout.chunks` /
- * `stderr.chunks` (and the streams accept piped input); kill calls on `kills`;
- * event handlers on `handlers` (fire them via `emit(event, ...args)` to
- * simulate a signal).
+ * Creates a mock `process`-like object that matches the `Runtime.proc`
+ * surface: `cwd()`, `env`, `argv`, `stdin`, `stdout`/`stderr` (`Writable`s
+ * that capture output), `exit(code)`, `kill(pid, signal)`, `pid`,
+ * `platform`, `on(event, handler)`, and a settable `exitCode`. The mock
+ * captures writes on `stdout.chunks` / `stderr.chunks`, and the streams
+ * accept piped input. It records kill calls on `kills`. It records event
+ * handlers on `handlers`. Fire them with `emit(event, ...args)` to simulate
+ * a signal.
  *
  * @param {object} [options]
  * @param {Record<string, string>} [options.env] - Initial env map.
@@ -184,11 +186,12 @@ export function createMockStdin(chunks = []) {
  * @param {string[]} [options.argv] - The frozen `argv` array.
  * @param {string[]} [options.stdin] - Chunks the `stdin` iterator yields.
  * @param {(pid: number, signal: string|number) => any} [options.kill] - Optional
- *   `kill` implementation (e.g. to model a liveness probe); calls are always
- *   recorded on the returned `kills` array regardless.
+ *   `kill` implementation (e.g. to model a liveness probe). The mock always
+ *   records calls on the returned `kills` array regardless.
  * @param {number} [options.pid] - The fake's `pid` (default 1234).
  * @param {string} [options.platform] - The fake's `platform` string
- *   (default `"linux"`; set `"darwin"`/`"win32"` to exercise per-platform code).
+ *   (default `"linux"`). Set `"darwin"`/`"win32"` to exercise per-platform
+ *   code.
  * @returns {object}
  */
 export function createMockProcess({
@@ -203,8 +206,8 @@ export function createMockProcess({
   const stdout = new CaptureWritable();
   const stderr = new CaptureWritable();
   const kills = [];
-  // Registered event handlers (e.g. "SIGTERM"/"SIGINT"); a test can fire them
-  // via `emit(event, ...args)` to simulate a signal without a real process.
+  // Registered event handlers (e.g. "SIGTERM"/"SIGINT"). A test can fire them
+  // with `emit(event, ...args)` to simulate a signal without a real process.
   const handlers = {};
   return {
     env: { ...env },
@@ -235,8 +238,8 @@ export function createMockProcess({
 }
 
 /**
- * Runs `fn` with `console.log`, `console.info`, and `console.warn` suppressed,
- * returning whatever `fn` returns. Errors still propagate.
+ * Runs `fn` and suppresses `console.log`, `console.info`, and `console.warn`.
+ * It returns whatever `fn` returns. Errors still propagate.
  *
  * @template T
  * @param {() => T | Promise<T>} fn
@@ -262,8 +265,9 @@ export async function withSilentConsole(fn) {
 
 /**
  * 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.
+ * value passes through untouched. Anything else becomes an async function
+ * that returns that value. This collapses landmark-style `stubQueries`
+ * boilerplate.
  *
  * @param {Record<string, unknown>} values
  * @returns {Record<string, Function>}

package/src/mock/logger.js

@@ -1,6 +1,6 @@
 import { spy } from "./spy.js";
 /**
- * Creates a mock logger with call tracking
+ * Creates a mock logger that tracks calls
  * @param {object} options - Logger options
  * @param {boolean} options.captureOutput - Whether to capture log output
  * @returns {object} Mock logger

package/src/mock/resource-index.js

@@ -72,9 +72,9 @@ export function createMockResourceIndex(options = {}) {
     },
 
     /**
-     * Find resources by prefix
+     * Finds resources by prefix
      * @param {string} prefix - Prefix to search for
-     * @returns {Promise<string[]>} List of matching keys
+     * @returns {Promise<string[]>} List of keys that match
      */
     async findByPrefix(prefix) {
       const keys = [];

package/src/mock/service-callbacks.js

@@ -1,5 +1,5 @@
 /**
- * Creates a mock service callbacks object for agent testing
+ * Creates a mock service-callbacks object for agent tests
  * @param {object} overrides - Method overrides per service
  * @returns {object} Service callbacks object
  */

package/src/mock/services.js

@@ -1,5 +1,5 @@
 /**
- * Mock service utilities for testing
+ * Mock service utilities for tests
  */
 
 /**

package/src/mock/spy.js

@@ -2,7 +2,7 @@
  * 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
+ * The 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.
  *

package/src/mock/storage.js

@@ -1,8 +1,8 @@
 import { spy } from "./spy.js";
 /**
- * Creates a mock storage instance with tracking
+ * Creates a mock storage instance that tracks data
  * @param {object} overrides - Method overrides
- * @returns {object} Mock storage with data tracking
+ * @returns {object} Mock storage that tracks data
  */
 export function createMockStorage(overrides = {}) {
   const data = new Map();
@@ -78,7 +78,7 @@ export class MockStorage {
   }
 
   /**
-   * Alias for put - stores a value by key
+   * Alias for put. Stores a value by key
    * @param {string} key - The storage key
    * @param {*} value - The value to store
    * @returns {Promise<void>}
@@ -101,7 +101,7 @@ export class MockStorage {
   /**
    * Checks if a key exists
    * @param {string} key - The storage key
-   * @returns {Promise<boolean>} True if key exists
+   * @returns {Promise<boolean>} True if the key exists
    */
   async exists(key) {
     return this.data.has(key);

package/src/mock/subprocess.js

@@ -11,11 +11,12 @@ function asyncIterableOf(str) {
 }
 
 /**
- * A captured-chunks sink for a spawned child's writable stdin. A real
- * `node:stream` Writable (so it is a valid `pipe()` destination, the way a
- * supervisor pipes a service's output into its logger) that records every
- * written chunk on `chunks` instead of forwarding it anywhere. Mirrors the
- * `stdin` the production `createDefaultSubprocess().spawn` exposes.
+ * A captured-chunks sink for a spawned child's writable stdin. The sink is a
+ * real `node:stream` Writable, so it is a valid `pipe()` destination. A
+ * supervisor pipes a service's output into its logger in the same way. The
+ * sink records every written chunk on `chunks`. It does not forward the chunk
+ * anywhere. It mirrors the `stdin` that the production
+ * `createDefaultSubprocess().spawn` exposes.
  */
 function createMockStdinSink() {
   const chunks = [];
@@ -30,14 +31,14 @@ function createMockStdinSink() {
 }
 
 /**
- * Creates a mock subprocess collaborator matching the `Runtime.subprocess`
- * surface. `run(cmd, args, opts)` resolves to `{ stdout, stderr, exitCode }`
- * consulting `responses[cmd]` (default: empty success); `runSync` is its
- * synchronous sibling returning the same shape. `spawn` returns a streaming
- * quad backed by the same responses (its result carries `stdout`/`stderr`
+ * Creates a mock subprocess collaborator that matches the `Runtime.subprocess`
+ * surface. `run(cmd, args, opts)` consults `responses[cmd]` (default: empty
+ * success) and resolves to `{ stdout, stderr, exitCode }`. `runSync` is its
+ * synchronous sibling and returns the same shape. `spawn` returns a streaming
+ * quad backed by the same responses. Its result carries `stdout`/`stderr`
  * AsyncIterables, a captured-chunks `stdin` sink, `exitCode`/`signal` Promises,
- * a `kill(signal)` spy recording on `kills`, and `pid`). All invocations are
- * recorded on `calls`.
+ * a `kill(signal)` spy that records on `kills`, and `pid`. The mock records
+ * every invocation on `calls`.
  *
  * @param {object} [options]
  * @param {Record<string, {stdout?: string, stderr?: string, exitCode?: number}>} [options.responses]
@@ -70,11 +71,13 @@ export function createMockSubprocess({ responses = {} } = {}) {
     return {
       stdout: asyncIterableOf(r.stdout),
       stderr: asyncIterableOf(r.stderr),
-      // A captured-chunks writable; `null` only when a response explicitly
-      // sets `stdin: null` (matching a child spawned without a stdin pipe).
+      // A captured-chunks writable. It is `null` only when a response
+      // explicitly sets `stdin: null`. That matches a child spawned without a
+      // stdin pipe.
       stdin: r.stdin === null ? null : createMockStdinSink(),
       exitCode: Promise.resolve(r.exitCode),
-      // Terminating signal: `null` (clean exit) unless a response overrides it.
+      // The signal that stopped the child is `null` (clean exit) unless a
+      // response overrides it.
       signal: Promise.resolve(r.signal ?? null),
       kills,
       kill: spy((signal) => {

package/src/runtime.js

@@ -5,9 +5,9 @@ import { createMockSubprocess } from "./mock/subprocess.js";
 import { createMockFinder } from "./mock/finder.js";
 
 /**
- * Build a frozen mock runtime bag for tests, matching the production
- * `Runtime` typedef. Every field defaults to its canonical
- * libmock fake and is independently overridable via `overrides`.
+ * Build a frozen mock runtime bag for tests. The bag matches the production
+ * `Runtime` typedef. Every field defaults to its canonical libmock fake.
+ * Override each field independently through `overrides`.
  *
  * @param {object} [overrides] - Per-field replacements.
  * @param {object} [overrides.fs] - Async fs surface (default `createMockFs()`).