@forwardimpact/libeval 0.1.50 → 0.1.52

package/src/benchmark/task-family.js

@@ -9,7 +9,7 @@
  *       judge.task.md
  *       hooks/                # harness-only; never copied to agent CWD
  *         preflight.sh
- *         score.sh
+ *         invariants.sh
  *       specs/                # copied into agent CWD
  *       workdir/              # copied into agent CWD
  *
@@ -17,45 +17,55 @@
  * a temp dir and `familyRevision` becomes `git:<sha>` of HEAD at clone time.
  * Local paths use the canonical-tree algorithm from design § Family revision
  * algorithm so the result is stable across operating systems.
+ *
+ * Filesystem and subprocess access route through the injected `runtime` bag
+ * (`runtime.fs` async, `runtime.subprocess.run` one-shot, `tmpdir` derived
+ * from `runtime.proc.env`).
  */
 
-import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import {
-  access,
-  constants,
-  lstat,
-  mkdtemp,
-  readdir,
-  readFile,
-  realpath,
-} from "node:fs/promises";
-import { tmpdir } from "node:os";
 import { join, posix, relative, resolve, sep } from "node:path";
 
 const GIT_URL_RE = /^(git@|https?:\/\/|ssh:\/\/|git:\/\/)/;
 const SKIP_DIRS = new Set([".git", "node_modules"]);
+// POSIX `X_OK` (execute permission); node's fs honours the numeric mode, so we
+// avoid importing `node:fs`'s `constants` (which would light the fs smell).
+const X_OK = 1;
+
+/**
+ * Derive the system temp dir from the env (node's `os.tmpdir()` is itself an
+ * env-respecting wrapper). The runtime bag has no `os` slot by design.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {string}
+ */
+function tmpdir(runtime) {
+  return runtime.proc.env.TMPDIR ?? "/tmp";
+}
 
 /**
  * Load a task family from a local path or git URL.
  * @param {string} rootPathOrGitUrl
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {Promise<TaskFamily>}
  */
-export async function loadTaskFamily(rootPathOrGitUrl) {
+export async function loadTaskFamily(rootPathOrGitUrl, runtime) {
+  if (!runtime) throw new Error("runtime is required");
   const isGit = GIT_URL_RE.test(rootPathOrGitUrl);
   let rootPath;
   let familyRevision;
   if (isGit) {
-    const dir = await mkdtemp(join(tmpdir(), "fit-benchmark-family-"));
-    await gitClone(rootPathOrGitUrl, dir);
+    const dir = await runtime.fs.mkdtemp(
+      join(tmpdir(runtime), "fit-benchmark-family-"),
+    );
+    await gitClone(runtime, rootPathOrGitUrl, dir);
     rootPath = dir;
-    familyRevision = "git:" + (await gitHead(dir));
+    familyRevision = "git:" + (await gitHead(runtime, dir));
   } else {
     rootPath = resolve(rootPathOrGitUrl);
-    familyRevision = "sha256:" + (await canonicalTreeHash(rootPath));
+    familyRevision = "sha256:" + (await canonicalTreeHash(runtime, rootPath));
   }
 
-  const tasks = await discoverTasks(rootPath);
+  const tasks = await discoverTasks(runtime, rootPath);
 
   return {
     rootPath,
@@ -73,27 +83,30 @@ export async function loadTaskFamily(rootPathOrGitUrl) {
  * @param {TaskFamily} _family
  * @param {string} judgeProfilesDir
  * @param {string} judgeProfile
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {Promise<void>}
  */
 export async function assertJudgeProfileStaged(
   _family,
   judgeProfilesDir,
   judgeProfile,
+  runtime,
 ) {
   const candidate = join(judgeProfilesDir, `${judgeProfile}.md`);
   try {
-    await access(candidate);
+    await runtime.fs.access(candidate);
   } catch {
     throw new Error(`judge profile not staged: ${candidate}`);
   }
 }
 
-async function discoverTasks(rootPath) {
+async function discoverTasks(runtime, rootPath) {
+  const fs = runtime.fs;
   const tasksRoot = join(rootPath, "tasks");
   const tasks = [];
   let entries;
   try {
-    entries = await readdir(tasksRoot, { withFileTypes: true });
+    entries = await fs.readdir(tasksRoot, { withFileTypes: true });
   } catch (e) {
     if (e.code === "ENOENT") return tasks;
     throw e;
@@ -104,17 +117,23 @@ async function discoverTasks(rootPath) {
     const supervisorPath = join(taskDir, "supervisor.task.md");
     const judgePath = join(taskDir, "judge.task.md");
     const preflightPath = join(taskDir, "hooks", "preflight.sh");
-    const scorePath = join(taskDir, "hooks", "score.sh");
+    const invariantsPath = join(taskDir, "hooks", "invariants.sh");
     tasks.push({
       id: entry.name,
       paths: {
         taskDir,
         instructions: join(taskDir, "agent.task.md"),
-        supervisor: (await fileExists(supervisorPath)) ? supervisorPath : null,
-        judge: (await fileExists(judgePath)) ? judgePath : null,
+        supervisor: (await fileExists(fs, supervisorPath))
+          ? supervisorPath
+          : null,
+        judge: (await fileExists(fs, judgePath)) ? judgePath : null,
         hooks: join(taskDir, "hooks"),
-        preflight: (await fileExecutable(preflightPath)) ? preflightPath : null,
-        score: (await fileExecutable(scorePath)) ? scorePath : null,
+        preflight: (await fileExecutable(fs, preflightPath))
+          ? preflightPath
+          : null,
+        invariants: (await fileExecutable(fs, invariantsPath))
+          ? invariantsPath
+          : null,
         specs: join(taskDir, "specs"),
         workdir: join(taskDir, "workdir"),
       },
@@ -124,18 +143,18 @@ async function discoverTasks(rootPath) {
   return tasks;
 }
 
-async function fileExists(path) {
+async function fileExists(fs, path) {
   try {
-    await access(path);
+    await fs.access(path);
     return true;
   } catch {
     return false;
   }
 }
 
-async function fileExecutable(path) {
+async function fileExecutable(fs, path) {
   try {
-    await access(path, constants.X_OK);
+    await fs.access(path, X_OK);
     return true;
   } catch {
     return false;
@@ -149,16 +168,18 @@ async function fileExecutable(path) {
  *   sort by NFC-normalised POSIX-style root-relative path
  *   row = <rel-path>\0<hex-sha256>\n
  *   sha256(concat(rows))
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string} rootPath
  * @returns {Promise<string>} hex digest
  */
-async function canonicalTreeHash(rootPath) {
-  const real = await realpath(rootPath);
+async function canonicalTreeHash(runtime, rootPath) {
+  const fs = runtime.fs;
+  const real = await fs.realpath(rootPath);
   const rows = [];
-  for await (const filePath of walkFiles(real)) {
+  for await (const filePath of walkFiles(fs, real)) {
     const rel = toPosix(relative(real, filePath)).normalize("NFC");
-    const target = await realpath(filePath);
-    const bytes = await readFile(target);
+    const target = await fs.realpath(filePath);
+    const bytes = await fs.readFile(target);
     const hex = createHash("sha256").update(bytes).digest("hex");
     rows.push({ rel, hex });
   }
@@ -168,15 +189,15 @@ async function canonicalTreeHash(rootPath) {
   return acc.digest("hex");
 }
 
-async function* walkFiles(dir) {
-  const entries = await readdir(dir, { withFileTypes: true });
+async function* walkFiles(fs, dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
     const full = join(dir, entry.name);
     if (entry.isDirectory()) {
       if (SKIP_DIRS.has(entry.name)) continue;
-      yield* walkFiles(full);
+      yield* walkFiles(fs, full);
     } else if (entry.isSymbolicLink()) {
-      const resolvedFile = await resolveSymlinkToFile(full);
+      const resolvedFile = await resolveSymlinkToFile(fs, full);
       if (resolvedFile) yield full;
     } else if (entry.isFile()) {
       yield full;
@@ -188,12 +209,12 @@ async function* walkFiles(dir) {
  * Return the resolved path if `linkPath` is a symlink to a regular file.
  * Returns null for dangling symlinks or links to non-file targets.
  */
-async function resolveSymlinkToFile(linkPath) {
-  const st = await lstat(linkPath);
+async function resolveSymlinkToFile(fs, linkPath) {
+  const st = await fs.lstat(linkPath);
   if (!st.isSymbolicLink()) return null;
   try {
-    const resolved = await realpath(linkPath);
-    const tstat = await lstat(resolved);
+    const resolved = await fs.realpath(linkPath);
+    const tstat = await fs.lstat(resolved);
     return tstat.isFile() ? resolved : null;
   } catch {
     return null;
@@ -205,38 +226,30 @@ function toPosix(p) {
   return p.split(sep).join(posix.sep);
 }
 
-async function gitClone(url, dir) {
-  await run("git", ["clone", "--depth", "1", url, dir]);
+async function gitClone(runtime, url, dir) {
+  await git(runtime, ["clone", "--depth", "1", url, dir]);
 }
 
-async function gitHead(dir) {
-  const out = await run("git", ["-C", dir, "rev-parse", "HEAD"]);
+async function gitHead(runtime, dir) {
+  const out = await git(runtime, ["-C", dir, "rev-parse", "HEAD"]);
   return out.trim();
 }
 
-function run(cmd, args) {
-  return new Promise((res, rej) => {
-    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (d) => {
-      stdout += d.toString();
-    });
-    child.stderr.on("data", (d) => {
-      stderr += d.toString();
-    });
-    child.on("error", rej);
-    child.on("close", (code) => {
-      if (code === 0) res(stdout);
-      else rej(new Error(`${cmd} ${args.join(" ")} exited ${code}: ${stderr}`));
-    });
-  });
+async function git(runtime, args) {
+  const { stdout, stderr, exitCode } = await runtime.subprocess.run(
+    "git",
+    args,
+  );
+  if (exitCode !== 0) {
+    throw new Error(`git ${args.join(" ")} exited ${exitCode}: ${stderr}`);
+  }
+  return stdout;
 }
 
 /**
  * @typedef {object} Task
  * @property {string} id - Task name (directory name under tasks/)
- * @property {{taskDir: string, instructions: string, supervisor: string|null, judge: string|null, hooks: string, preflight: string|null, score: string|null, specs: string, workdir: string}} paths
+ * @property {{taskDir: string, instructions: string, supervisor: string|null, judge: string|null, hooks: string, preflight: string|null, invariants: string|null, specs: string, workdir: string}} paths
  */
 
 /**

package/src/benchmark/workdir.js

@@ -4,11 +4,14 @@
  * the pre-flight smoke probe, and tear down the process group at end of run.
  *
  * The Workdir handle threads `cwd`, `port`, `pgid`, and trace paths through
- * runAgent → score → judge → teardown.
+ * runAgent → invariants → judge → teardown.
+ *
+ * Filesystem, subprocess, clock, and process-signal access all route through
+ * the injected `runtime` bag. Only raw TCP plumbing (`node:net`) stays direct —
+ * it is not an ambient-dependency smell and the runtime bag models no socket
+ * surface.
  */
 
-import { spawn } from "node:child_process";
-import { cp, mkdir } from "node:fs/promises";
 import { createServer } from "node:net";
 import { connect } from "node:net";
 import { join } from "node:path";
@@ -37,14 +40,24 @@ export class WorkdirManager {
    * @param {object} deps
    * @param {string} deps.stagingDir - Output of `installApm(...)`.
    * @param {string} deps.runOutputDir - Root run-output directory (parent of `runs/`).
+   * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime -
+   *   Ambient collaborators; uses `fs`, `subprocess`, `clock`, `proc`.
    */
-  constructor({ stagingDir, runOutputDir, termGraceMs, familyRootPath }) {
+  constructor({
+    stagingDir,
+    runOutputDir,
+    termGraceMs,
+    familyRootPath,
+    runtime,
+  }) {
     if (!stagingDir) throw new Error("stagingDir is required");
     if (!runOutputDir) throw new Error("runOutputDir is required");
+    if (!runtime) throw new Error("runtime is required");
     this.stagingDir = stagingDir;
     this.runOutputDir = runOutputDir;
     this.termGraceMs = termGraceMs ?? DEFAULT_TERM_GRACE_MS;
     this.familyRootPath = familyRootPath ?? null;
+    this.runtime = runtime;
   }
 
   /**
@@ -54,33 +67,39 @@ export class WorkdirManager {
    * @returns {Promise<Workdir>}
    */
   async start(task, runIndex) {
+    const fs = this.runtime.fs;
     const slug = task.id.replace("/", "__");
     const runDir = join(this.runOutputDir, "runs", slug, String(runIndex));
     const cwd = join(runDir, "cwd");
-    await mkdir(cwd, { recursive: true });
+    await fs.mkdir(cwd, { recursive: true });
 
-    await cp(task.paths.workdir, cwd, { recursive: true }).catch((e) => {
-      if (e.code !== "ENOENT") throw e;
-    });
-    await cp(task.paths.specs, join(cwd, "specs"), {
-      recursive: true,
-    }).catch((e) => {
+    await fs.cp(task.paths.workdir, cwd, { recursive: true }).catch((e) => {
       if (e.code !== "ENOENT") throw e;
     });
-    await cp(join(this.stagingDir, ".claude"), join(cwd, ".claude"), {
-      recursive: true,
-    });
-    await cp(join(this.stagingDir, "node_modules"), join(cwd, "node_modules"), {
+    await fs
+      .cp(task.paths.specs, join(cwd, "specs"), {
+        recursive: true,
+      })
+      .catch((e) => {
+        if (e.code !== "ENOENT") throw e;
+      });
+    await fs.cp(join(this.stagingDir, ".claude"), join(cwd, ".claude"), {
       recursive: true,
-    }).catch((e) => {
-      if (e.code !== "ENOENT") throw e;
     });
+    await fs
+      .cp(join(this.stagingDir, "node_modules"), join(cwd, "node_modules"), {
+        recursive: true,
+      })
+      .catch((e) => {
+        if (e.code !== "ENOENT") throw e;
+      });
 
     const envDirs = [
       ...(this.familyRootPath ? [this.familyRootPath] : []),
       ...(task.paths.taskDir ? [task.paths.taskDir] : []),
     ];
-    const envNames = envDirs.length > 0 ? await loadEnv(envDirs, cwd) : [];
+    const envNames =
+      envDirs.length > 0 ? await loadEnv(envDirs, cwd, this.runtime) : [];
 
     const port = await allocatePort();
     const agentTracePath = join(runDir, "agent.ndjson");
@@ -88,7 +107,7 @@ export class WorkdirManager {
     const judgeTracePath = join(runDir, "judge.ndjson");
 
     const preflight = task.paths.preflight
-      ? await runPreflight(task.paths.preflight, cwd, port)
+      ? await runPreflight(this.runtime, task.paths.preflight, cwd, port)
       : { pgid: 0 };
 
     return {
@@ -111,81 +130,71 @@ export class WorkdirManager {
    * @returns {Promise<{portFree: boolean, descendants: number}>}
    */
   async teardown(workdir) {
+    const { proc, clock } = this.runtime;
     if (workdir.pgid && workdir.pgid > 0) {
       try {
-        process.kill(-workdir.pgid, "SIGTERM");
+        proc.kill(-workdir.pgid, "SIGTERM");
       } catch {
         // Process group already gone — fine.
       }
-      await sleep(this.termGraceMs);
+      await clock.sleep(this.termGraceMs);
       try {
-        process.kill(-workdir.pgid, "SIGKILL");
+        proc.kill(-workdir.pgid, "SIGKILL");
       } catch {
         // Already exited.
       }
       // Poll briefly until the process group is empty — SIGKILL returns
       // before the kernel finishes reaping descendants.
       await waitFor(
-        async () => (await countDescendants(workdir.pgid)) === 0,
+        this.runtime,
+        async () => (await countDescendants(this.runtime, workdir.pgid)) === 0,
         2_000,
       );
     }
     const portFree = await isPortFree(workdir.port);
-    const descendants = await countDescendants(workdir.pgid);
+    const descendants = await countDescendants(this.runtime, workdir.pgid);
     return { portFree, descendants };
   }
 }
 
 /**
  * Spawn preflight. Stays detached so we can SIGTERM the whole process group.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string} script
  * @param {string} cwd - Agent CWD passed via $WORKDIR.
  * @param {number} port - Free TCP port passed via $PORT.
  * @returns {Promise<{pgid: number, error?: {phase: string, message: string, exitCode: number}}>}
  */
-function runPreflight(script, cwd, port) {
-  return new Promise((res, rej) => {
-    let stderr = "";
-    const child = spawn(script, [], {
-      cwd,
-      env: { ...process.env, WORKDIR: cwd, PORT: String(port) },
-      detached: true,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    if (child.pid === undefined) {
-      rej(new Error(`failed to spawn preflight: ${script}`));
-      return;
-    }
-    const pgid = child.pid;
-    child.stderr.on("data", (d) => {
-      stderr += d.toString();
-    });
-    child.on("error", (e) => {
-      res({
-        pgid,
-        error: {
-          phase: "preflight",
-          message: `preflight failed to spawn: ${e.message}`,
-          exitCode: -1,
-        },
-      });
-    });
-    child.on("exit", (code, signal) => {
-      if (code === 0) {
-        res({ pgid });
-        return;
-      }
-      const message = stderr.trim() || `preflight exited with signal ${signal}`;
-      res({
-        pgid,
-        error: {
-          phase: "preflight",
-          message,
-          exitCode: typeof code === "number" ? code : -1,
-        },
-      });
-    });
+async function runPreflight(runtime, script, cwd, port) {
+  const child = runtime.subprocess.spawn(script, [], {
+    cwd,
+    env: { ...runtime.proc.env, WORKDIR: cwd, PORT: String(port) },
+    detached: true,
+    stdio: ["ignore", "pipe", "pipe"],
   });
+  if (child.pid === undefined) {
+    throw new Error(`failed to spawn preflight: ${script}`);
+  }
+  const pgid = child.pid;
+  let stderr = "";
+  const drainStdout = (async () => {
+    for await (const _chunk of child.stdout) {
+      // discard
+    }
+  })();
+  for await (const chunk of child.stderr) stderr += chunk.toString();
+  await drainStdout;
+  const code = await child.exitCode;
+  if (code === 0) return { pgid };
+  const message = stderr.trim() || `preflight exited with code ${code}`;
+  return {
+    pgid,
+    error: {
+      phase: "preflight",
+      message,
+      exitCode: typeof code === "number" ? code : -1,
+    },
+  };
 }
 
 function allocatePort() {
@@ -221,37 +230,35 @@ function isPortFree(port) {
   });
 }
 
-function countDescendants(pgid) {
-  if (!pgid || pgid <= 0) return Promise.resolve(0);
-  return new Promise((res) => {
-    const child = spawn("ps", ["-o", "pid=", "-g", String(pgid)], {
+async function countDescendants(runtime, pgid) {
+  if (!pgid || pgid <= 0) return 0;
+  const child = runtime.subprocess.spawn(
+    "ps",
+    ["-o", "pid=", "-g", String(pgid)],
+    {
       stdio: ["ignore", "pipe", "ignore"],
-    });
-    let out = "";
-    child.stdout.on("data", (d) => {
-      out += d.toString();
-    });
-    child.on("error", () => res(0));
-    child.on("close", () => {
-      const pids = out
-        .split("\n")
-        .map((s) => s.trim())
-        .filter(Boolean)
-        .filter((s) => Number(s) !== process.pid);
-      res(pids.length);
-    });
-  });
-}
-
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
+    },
+  );
+  let out = "";
+  try {
+    for await (const chunk of child.stdout) out += chunk.toString();
+    await child.exitCode;
+  } catch {
+    return 0;
+  }
+  const pids = out
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .filter((s) => Number(s) !== runtime.proc.pid);
+  return pids.length;
 }
 
-async function waitFor(predicate, timeoutMs) {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
+async function waitFor(runtime, predicate, timeoutMs) {
+  const deadline = runtime.clock.now() + timeoutMs;
+  while (runtime.clock.now() < deadline) {
     if (await predicate()) return true;
-    await sleep(50);
+    await runtime.clock.sleep(50);
   }
   return false;
 }

package/src/commands/assert.js

@@ -1,4 +1,3 @@
-import { existsSync, readFileSync } from "node:fs";
 import { basename } from "node:path";
 import jmespath from "jmespath";
 
@@ -6,10 +5,11 @@ import jmespath from "jmespath";
  * Evaluate an assertion and return the structured result.
  * @param {object} values - { grep?: string, query?: string, exists?: boolean, not?: boolean, message?: string }
  * @param {string[]} args - [testName, file]
+ * @param {object} fsSync - Sync filesystem surface (`runtime.fsSync`): `existsSync`, `readFileSync`.
  * @returns {{ test: string, pass: boolean, message?: string }}
  */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: assertion dispatch by type
-export function evaluateAssertion(values, args) {
+export function evaluateAssertion(values, args, fsSync) {
   const testName = args[0];
   if (!testName) throw new Error("assert: missing test name");
 
@@ -34,16 +34,16 @@ export function evaluateAssertion(values, args) {
   let result;
   if (values.exists) {
     if (!file) throw new Error("assert: missing file argument");
-    result = assertExists(file);
+    result = assertExists(file, fsSync);
   } else if (values.grep) {
     if (!file) throw new Error("assert: missing file argument for --grep");
-    result = assertGrep(values.grep, file);
+    result = assertGrep(values.grep, file, fsSync);
   } else if (values["cites-job"]) {
     if (!file) throw new Error("assert: missing file argument for --cites-job");
-    result = assertCitesJob(values["cites-job"], file);
+    result = assertCitesJob(values["cites-job"], file, fsSync);
   } else {
     if (!file) throw new Error("assert: missing file argument for --query");
-    result = assertQuery(values.query, file);
+    result = assertQuery(values.query, file, fsSync);
   }
 
   if (values.not) {
@@ -66,23 +66,31 @@ export function evaluateAssertion(values, args) {
 }
 
 /**
- * Run an assertion, write JSON to stdout, and set process.exitCode on failure.
- * @param {object} values
- * @param {string[]} args
+ * Run an assertion, write JSON to stdout, and return a failure envelope when
+ * the assertion does not pass.
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: true} | {ok: false, code: number, error: string}>}
  */
-export async function runAssertCommand(values, args) {
-  const result = evaluateAssertion(values, args);
-  process.stdout.write(JSON.stringify(result) + "\n");
-  if (!result.pass) process.exitCode = 1;
+export async function runAssertCommand(ctx) {
+  const runtime = ctx.deps.runtime;
+  const args = [ctx.args["test-name"], ctx.args.file];
+  let result;
+  try {
+    result = evaluateAssertion(ctx.options, args, runtime.fsSync);
+  } catch (err) {
+    return { ok: false, code: 1, error: err.message };
+  }
+  runtime.proc.stdout.write(JSON.stringify(result) + "\n");
+  return result.pass ? { ok: true } : { ok: false, code: 1, error: "" };
 }
 
-function assertExists(file) {
-  if (existsSync(file)) return { pass: true };
+function assertExists(file, fsSync) {
+  if (fsSync.existsSync(file)) return { pass: true };
   return { pass: false, message: `${file} not found` };
 }
 
-function assertGrep(pattern, file) {
-  const content = readFileSync(file, "utf8");
+function assertGrep(pattern, file, fsSync) {
+  const content = fsSync.readFileSync(file, "utf8");
   const re = new RegExp(pattern, "im");
   if (re.test(content)) return { pass: true };
   return {
@@ -91,8 +99,8 @@ function assertGrep(pattern, file) {
   };
 }
 
-function assertQuery(expression, file) {
-  const content = readFileSync(file, "utf8");
+function assertQuery(expression, file, fsSync) {
+  const content = fsSync.readFileSync(file, "utf8");
   const data = parseJsonOrNdjson(content);
   const result = jmespath.search(data, expression);
   const truthy =
@@ -109,8 +117,8 @@ function assertQuery(expression, file) {
 
 const JOB_TAG_RE = /<job\s+user="([^"]*)"\s+goal="([^"]*)">/;
 
-function assertCitesJob(jobFile, file) {
-  const jobContent = readFileSync(jobFile, "utf8");
+function assertCitesJob(jobFile, file, fsSync) {
+  const jobContent = fsSync.readFileSync(jobFile, "utf8");
   const match = JOB_TAG_RE.exec(jobContent);
   if (!match) {
     return {
@@ -119,7 +127,7 @@ function assertCitesJob(jobFile, file) {
     };
   }
   const citation = `${match[1]}: ${match[2]}`;
-  const content = readFileSync(file, "utf8");
+  const content = fsSync.readFileSync(file, "utf8");
   if (content.includes(citation)) return { pass: true };
   return { pass: false, message: `missing "${citation}"` };
 }