@cosyte/script-utils 0.0.1 → 0.1.0

package/phi-scan.js

@@ -0,0 +1,1936 @@
+// @cosyte/script-utils/phi-scan
+//
+// THE SHARED MACHINERY OF THE `@cosyte/*` PHI COMMIT-GATE, PARAMETERISED.
+//
+// WHY THIS FILE EXISTS, IN ONE SENTENCE: `scripts/parser-template/` is a SCAFFOLD, not a
+// dependency, so `scripts/phi-scan.ts` was COPIED into every parser repo, and a newly-found escape
+// therefore cost one pull request and one adversarial review PER REPO. Three escape classes have
+// been closed that way already (the index union, the completeness rule, and the read filters), and
+// each one was paid for thirteen times. The machinery lives here so the next one is paid for once.
+//
+// WHAT IS SHARED AND WHAT IS NOT. This module owns the ENGINE: argument parsing, the allow-list and
+// override log, target enumeration on all three routes, the union of the working-tree walk with the
+// bytes git carries, content deduplication under git's own `blob <len>\0` framing, the completeness
+// rule, the refusals, and the cross-cutting SSN/email FLOOR. It does NOT own the per-standard,
+// field-level detectors (names, DOB, MRN / member id, address, phone), which genuinely differ per
+// healthcare standard and are supplied by the caller through `detect`.
+//
+// THE FIVE PER-REPO AXES ARE PARAMETERS, NOT FORKS. They differ between repos, which is an argument
+// for parameters and not against sharing:
+//
+//   1. EXIT CODES        `exitCodes`, REQUIRED. The siblings deliberately disagree; a default here
+//                        would be the porting mistake this whole campaign exists to catch.
+//   2. ROOTS+EXCLUSIONS  `scanRoots` (REQUIRED), `excludedPaths` and `isWalkReadable` (both
+//                        DEFAULTED, so a change to the shared default reaches every consumer
+//                        through a version bump instead of thirteen edits).
+//   3. `--staged` SCOPE  `isStagedReadable`, REQUIRED. Widening it changes what a COMMIT is blocked
+//                        on, which is a hook decision each repo takes for itself.
+//   4. GITLINKS          `regularBlobModes`, DEFAULTED to git's two regular-blob modes.
+//   5. EOL NORMALIZATION No parameter. The walk/index deduplication is BY CONTENT, so where a `text`
+//                        attribute or `core.autocrlf` makes the index carry LF and the working tree
+//                        CRLF, BOTH forms are scanned rather than one being assumed to stand for the
+//                        other. It is listed because a port must CHECK it, not skip it.
+//
+// ZERO DEPENDENCIES AND NO BUILD STEP, the same constraint the rest of this package carries. `git`
+// is the only subprocess, always through `execFileSync` with array args, never shell-form.
+//
+// PHI DISCIPLINE INSIDE THIS FILE ITSELF: no literal identifier-shaped value appears anywhere in
+// this source, not even as an example in a comment. A repo that widens its scan roots to the whole
+// repository reads its own `node_modules` copy of this file only if it is not gitignored, and a
+// diagnostic ABOUT a PHI leak is itself a PHI surface. Describe the shape; never write one down.
+
+import { readFileSync, statSync, lstatSync, existsSync, readdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { join, resolve, relative, sep, isAbsolute } from "node:path";
+
+/**
+ * Every state in which the scan cannot account for something. Raised throughout, caught in `run`,
+ * and turned into the caller's REFUSE code there.
+ *
+ * IT IS NOT EXPORTED, DELIBERATELY. A consumer that could catch it could also swallow it, and every
+ * one of these states must reach a non-zero exit.
+ */
+class InvocationError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = "InvocationError";
+  }
+}
+
+/**
+ * A target whose bytes could not be read, carrying the errno the filesystem gave.
+ *
+ * IT IS AN `InvocationError`, SO THE DEFAULT IS STILL REFUSAL. The subclass exists for exactly one
+ * decision, the ENUMERATION TOCTOU WINDOW in `run`: between the walk listing a path and the sweep
+ * opening it, an editor, a build or a test can remove it. The errno is what tells "the file is
+ * gone" from "the file is there and something else failed", and nothing else in this engine may
+ * branch on it. Every other read failure keeps taking the refuse path unchanged.
+ */
+class TargetReadError extends InvocationError {
+  /**
+   * @param {string} message
+   * @param {string | undefined} errnoCode The `code` the filesystem error carried, when it had one.
+   */
+  constructor(message, errnoCode) {
+    super(message);
+    this.name = "TargetReadError";
+    this.errnoCode = errnoCode;
+  }
+}
+
+/** git's file modes for a regular blob. Every other mode names something with no bytes to read. */
+const DEFAULT_REGULAR_BLOB_MODES = new Set(["100644", "100755"]);
+
+/**
+ * AXIS 2's shared default read filter for the two SWEEPING routes: Markdown is documentation rather
+ * than fixture data and may legitimately describe a violator value.
+ *
+ * IT IS A DEFAULT RATHER THAN A CONSTANT SO THAT MOVING IT IS ONE CHANGE. Every `@cosyte/*` scanner
+ * carries this exemption today, and a tracked `.md` is therefore read by NEITHER sweeping route
+ * (the union inherits this filter on purpose, so `all` mode's verdict cannot depend on which copy of
+ * a file it reached). Whether that boundary should move is a real question with a real cost on both
+ * sides: `README.md` and `CHANGELOG.md` ship inside the npm tarball, and a `.md` named explicitly on
+ * argv IS scanned today, so the escape is route-dependent rather than file-dependent. Moving it is a
+ * deliberate change to THIS line, with its own measurement, and it then reaches every consumer
+ * through a version bump.
+ *
+ * @param {string} relPath A repo-relative, forward-slashed path.
+ * @returns {boolean} `true` when the sweeping routes may read this path's bytes.
+ */
+export function exemptsMarkdown(relPath) {
+  return !relPath.toLowerCase().endsWith(".md");
+}
+
+/**
+ * Normalise and CHECK the caller's configuration.
+ *
+ * IT THROWS A `TypeError` RATHER THAN RETURNING A CODE, because at the point a required axis is
+ * missing there is no trustworthy code to return: `exitCodes` is itself the thing that was not
+ * supplied. That escapes to node's own exit 1 with a stack, which is loud and lands on the author's
+ * very first run of their own scanner.
+ *
+ * WHAT IT CHECKS AND WHAT IT DOES NOT, SCOPED TO WHAT IS ENFORCED HERE RATHER THAN TO AN INTENT.
+ * An earlier draft of this docblock said a misconfigured scanner "must not be able to report clean",
+ * and a reviewer falsified that sentence twice in four lines. Both reproductions were the same
+ * shape: a configuration this function ACCEPTED, whose roots then matched nothing, so every
+ * index-keyed rule went silently empty and the run printed `OK: no hits`. So the two are named:
+ *
+ *   1. A ROOT IS NORMALISED THE SAME WAY A PATH IS. `"./src"` is a spelling the type describes as
+ *      valid, and it walked correctly while `isUnderScanRoot` compared it against the NORMALIZED
+ *      index path `src/...` and never matched. Measured: `["src"]` refused a tracked mode-120000
+ *      entry at exit 2 while `["./src"]` reported clean at exit 0 over the same repository.
+ *   2. A ROOT THAT RESOLVES OUTSIDE THE REPOSITORY IS REFUSED, because no index path can ever be
+ *      under it, which is the same silently-empty state arrived at by another spelling.
+ *
+ * IT IS STILL NOT AN EXHAUSTIVE GUARANTEE, and the residual is named rather than implied: the
+ * CONTENT of a caller's predicates is not checkable here. `isStagedReadable` admitting a path
+ * outside every scan root is the one containment that matters, and it is enforced where it can be
+ * observed, in `buildTargetsForStaged`, not here.
+ *
+ * @param {import("./phi-scan.js").PhiScanConfig} config
+ * @returns {Required<Omit<import("./phi-scan.js").PhiScanConfig, "detect">> & { detect?: import("./phi-scan.js").DetectFn }}
+ */
+function normalizeConfig(config) {
+  if (typeof config !== "object" || config === null) {
+    throw new TypeError("runPhiScan(config) expects a configuration object.");
+  }
+
+  const repoRoot = config.repoRoot ?? process.cwd();
+  if (typeof repoRoot !== "string" || repoRoot === "") {
+    throw new TypeError("runPhiScan: `repoRoot` must be a non-empty string when given.");
+  }
+
+  const codes = config.exitCodes;
+  if (typeof codes !== "object" || codes === null) {
+    throw new TypeError(
+      "runPhiScan: `exitCodes` is REQUIRED ({ clean, hits, refuse }). There is deliberately no " +
+        "default: the sibling @cosyte/* scanners do not agree on these numbers, and a caller that " +
+        "branches on the code (CI does) must read this repo's own contract, never an inherited one.",
+    );
+  }
+  for (const key of /** @type {const} */ (["clean", "hits", "refuse"])) {
+    const value = codes[key];
+    if (!Number.isInteger(value) || value < 0 || value > 125) {
+      throw new TypeError(
+        `runPhiScan: exitCodes.${key} must be an integer in 0..125, got ${String(value)}.`,
+      );
+    }
+  }
+  if (codes.clean === codes.hits || codes.clean === codes.refuse || codes.hits === codes.refuse) {
+    throw new TypeError(
+      "runPhiScan: exitCodes.clean, .hits and .refuse must be three DIFFERENT numbers. A caller " +
+        "has to be able to tell `this corpus contains something that looks like PHI` from `this " +
+        "scan is not trustworthy`: those need different human responses, and collapsing them makes " +
+        "the second read as the first.",
+    );
+  }
+
+  const rawRoots = config.scanRoots;
+  if (!Array.isArray(rawRoots) || rawRoots.length === 0) {
+    throw new TypeError(
+      'runPhiScan: `scanRoots` is REQUIRED and must name at least one root. Use `["."]` for the ' +
+        "whole repository.",
+    );
+  }
+  /** @type {Set<string>} */
+  const scanRootSet = new Set();
+  for (const root of rawRoots) {
+    if (typeof root !== "string" || root === "") {
+      throw new TypeError("runPhiScan: every entry in `scanRoots` must be a non-empty string.");
+    }
+    // THE SAME NORMALIZATION EVERY OTHER PATH GETS, and it is the fix for reproduction 1 above:
+    // `isUnderScanRoot` compares against repo-relative, forward-slashed paths, so a root must be one
+    // too or it matches nothing while still walking correctly. This maps `./src`, `src/` and
+    // `<repoRoot>/src` onto `src`, and the repository root itself onto `.`.
+    const rel = relative(repoRoot, isAbsolute(root) ? root : resolve(repoRoot, root))
+      .split(sep)
+      .join("/");
+    if (rel === ".." || rel.startsWith("../")) {
+      throw new TypeError(
+        `runPhiScan: scanRoots entry ${JSON.stringify(root)} resolves outside the repository ` +
+          `(${rel}). No path git can name is under it, so every index-keyed rule would go silently ` +
+          `empty and the sweep would report clean over a corpus it never had in scope.`,
+      );
+    }
+    scanRootSet.add(rel === "" ? "." : rel);
+  }
+  // Deduped, so two spellings of one root cannot walk the same tree twice.
+  const scanRoots = [...scanRootSet];
+
+  if (typeof config.isStagedReadable !== "function") {
+    throw new TypeError(
+      "runPhiScan: `isStagedReadable` is REQUIRED. It decides which staged blobs a COMMIT is " +
+        "blocked on, which is a per-repo hook decision and must not be inherited silently.",
+    );
+  }
+
+  // THE OPTIONAL AXES ARE SHAPE-CHECKED TOO, AND THAT IS NOT TIDINESS. A reviewer measured
+  // `excludedPaths: ["a"]`, which is a plausible reading of "repo-relative paths": it survived
+  // normalization, reached `.has(...)` inside enumeration, threw an uncaught `TypeError` from there,
+  // and the run took node's exit 1, which the exit contract reserves for HITS FOUND. Checking the
+  // shape here turns that into a throw that says what to fix, before any scan begins.
+  if (config.excludedPaths !== undefined && typeof config.excludedPaths.has !== "function") {
+    throw new TypeError(
+      "runPhiScan: `excludedPaths` must be a Set (or anything with `.has(path)`), not an array.",
+    );
+  }
+  if (config.regularBlobModes !== undefined && typeof config.regularBlobModes.has !== "function") {
+    throw new TypeError(
+      "runPhiScan: `regularBlobModes` must be a Set (or anything with `.has(mode)`).",
+    );
+  }
+  for (const key of /** @type {const} */ (["isWalkReadable", "detect"])) {
+    if (config[key] !== undefined && typeof config[key] !== "function") {
+      throw new TypeError(`runPhiScan: \`${key}\` must be a function when given.`);
+    }
+  }
+  for (const key of /** @type {const} */ (["allowListPath", "overrideLogPath"])) {
+    const value = config[key];
+    if (value !== undefined && (typeof value !== "string" || value === "")) {
+      throw new TypeError(`runPhiScan: \`${key}\` must be a non-empty string when given.`);
+    }
+  }
+  if (config.argv !== undefined && !Array.isArray(config.argv)) {
+    throw new TypeError("runPhiScan: `argv` must be an array of strings when given.");
+  }
+
+  return {
+    repoRoot,
+    argv: config.argv ?? process.argv.slice(2),
+    exitCodes: { clean: codes.clean, hits: codes.hits, refuse: codes.refuse },
+    scanRoots,
+    excludedPaths: config.excludedPaths ?? new Set(),
+    isWalkReadable: config.isWalkReadable ?? exemptsMarkdown,
+    isStagedReadable: config.isStagedReadable,
+    regularBlobModes: config.regularBlobModes ?? DEFAULT_REGULAR_BLOB_MODES,
+    allowListPath: config.allowListPath ?? join(repoRoot, "scripts", "phi-allow-list.txt"),
+    overrideLogPath: config.overrideLogPath ?? join(repoRoot, "phi-scan-overrides.md"),
+    detect: config.detect,
+  };
+}
+
+/**
+ * Run the PHI scan and RETURN an exit code. Nothing here calls `process.exit`, so a test can drive
+ * the engine in-process; the scanner script is the one that exits.
+ *
+ * ===========================================================================================
+ * MODES
+ *   `--staged`            scan only the blobs `git diff --cached` names.
+ *   `<path> [<path>...]`  scan specific paths.
+ *   (no args)             `all` mode: sweep the scan roots, as a union with the bytes git carries.
+ *
+ * `--allow-fixture <path>` IS A MODIFIER, NOT A MODE. A bypass is subtractive, so it must not also
+ * decide what gets scanned: a lone `--allow-fixture X` used to select `paths` mode over exactly
+ * `X`, then withdraw `X`, then report a clean whole run having opened nothing. The mode is chosen by
+ * positional paths alone, and in `paths` mode the flag is UNCONDITIONALLY UNIONED into the target
+ * list, deduped by repo-relative path, so it means the same thing in every argv.
+ * ===========================================================================================
+ * THE COMPLETENESS RULE: a target this run ENUMERATED and NEVER READ refuses, IN EVERY MODE, NAMING
+ * THE PATHS. The comparison is a SET DIFFERENCE, never a size: a count counts the targets that DID
+ * get read, so a plausible-looking total hides exactly the paths that did not.
+ *
+ * ENUMERATION IS THE RUN'S OWN DECLARATION OF WHAT IT WILL READ, so the read filters upstream of it
+ * are not weakened by the rule: a path the read filter dropped, a gitignored entry, an excluded
+ * path and a staged path outside `isStagedReadable` never become targets at all. What the rule
+ * catches is a path that BECAME a target and then did not get opened.
+ *
+ * A BYPASS NAMING A PATH THIS RUN DOES NOT ENUMERATE ALSO REFUSES: such a flag subtracts nothing, so
+ * honouring it silently would let a developer believe a file was acknowledged when the run never had
+ * it in scope.
+ *
+ * WHAT IT COSTS, STATED RATHER THAN LEFT TO BE DISCOVERED: `--allow-fixture` CANNOT REACH THE CLEAN
+ * CODE IN ANY MODE. The flag, the override log and the rejection gate are all kept, so an attempt is
+ * RECORDED AND REFUSED rather than silently honoured.
+ * ===========================================================================================
+ * `all` MODE READS THE BYTES GIT CARRIES AS A UNION WITH THE WALK.
+ *
+ * The walk answers "what is on disk under the scan roots", which is not the question "what does this
+ * repository carry". Three states were measured in which the walk alone reported clean at exit 0
+ * over a TRACKED file carrying a live, detectable hit: the path OCCUPIED BY A DIRECTORY (a path-SET
+ * reconciliation cannot see this one, because the path IS present: only reading the OBJECT closes
+ * it), the working tree SHORT of a tracked file, and the two copies simply DIFFERING.
+ *
+ * So `git ls-files -s -z` is read for the whole index, and every in-scope tracked path whose bytes
+ * the walk did not already read VERBATIM is scanned through `git cat-file blob <sha>`. It is a union
+ * and never a replacement: the walk still runs first and still reaches UNTRACKED files, which git
+ * cannot name at all.
+ *
+ * DEDUPLICATION IS BY CONTENT, NOT BY PATH, AND THAT IS THE EOL AXIS. A walk target is skipped by
+ * the union only when the bytes it read hash to the index entry's own object id, so on a clean
+ * checkout the union adds ZERO reads and NEVER invokes `git cat-file`. The exact fixed cost is ONE
+ * `git rev-parse --show-object-format` per `all`-mode run, because the deduplication needs the
+ * algorithm before it can compare anything. Where the two copies of a path DIFFER, BOTH are scanned.
+ *
+ * A HIT FROM THE UNION IS LABELLED `(git index)` OR `(git index; the working tree differs)`, ON THE
+ * REPORTED LOCUS ONLY, and a footer counts how many of the reported hits came from those bytes. A
+ * hit naming the bare path would send a developer to open a file that is clean, or not there at all,
+ * and a single label would hide that re-staging is part of the remedy for the second kind. The
+ * target's `path` stays undecorated because every filter, exclusion and completeness tier keys on it.
+ * The `detect` callback is handed the LOCUS as `path`, so a caller cannot get this wrong.
+ *
+ * THE INDEX HALF IS NOT NARROWED BY `scanRoots`: every path the index carries is considered, because
+ * a root list is the WALK's scope and not a statement about what the repository carries. `--staged`
+ * is untouched by that and keeps its own scope, which is what a COMMIT is blocked on.
+ *
+ * `all` MODE REFUSES WHEN GIT CANNOT READ THE INDEX, OR READS IT EMPTY, and the two arrive through
+ * DIFFERENT branches and carry DIFFERENT sentences, because the remedies differ. Measured on git 2.39.5: a directory that is no repository at all FATALS (exit
+ * 128), so the `catch` is what turns it into a refusal, and WITHOUT that catch the throw escapes and
+ * the run takes node's own exit 1, which this contract reserves for HITS FOUND. A repository whose
+ * index is empty, and a directory inside a repository with nothing tracked under it, both print
+ * nothing and exit 0, which is what the size check is for. A scaffolded repo must therefore
+ * `git init` and commit before an `all`-mode run means anything.
+ * ===========================================================================================
+ *
+ * @param {import("./phi-scan.js").PhiScanConfig} config
+ * @returns {number} The exit code, drawn from `config.exitCodes`.
+ * @example
+ *   process.exit(
+ *     runPhiScan({
+ *       exitCodes: { clean: 0, hits: 1, refuse: 2 },
+ *       scanRoots: ["."],
+ *       isStagedReadable: (p) => p.startsWith("test/fixtures/"),
+ *     }),
+ *   );
+ */
+export function runPhiScan(config) {
+  return new PhiScan(normalizeConfig(config)).run();
+}
+
+class PhiScan {
+  /** @param {ReturnType<typeof normalizeConfig>} cfg */
+  constructor(cfg) {
+    this.cfg = cfg;
+    /** Does any scan root name the repository root itself? Then everything is in scope. */
+    this.wholeRepo = cfg.scanRoots.includes(".");
+    /** Reported loci whose bytes came from the index, for the report's per-origin footer. */
+    /** @type {Set<string>} */
+    this.indexLoci = new Set();
+  }
+
+  // -------------------------------------------------------------------------
+  // Paths
+  // -------------------------------------------------------------------------
+
+  /**
+   * A repo-relative, forward-slashed path: the key every filter, exclusion, dedupe and completeness
+   * tier uses, and the only spelling that appears in a diagnostic.
+   *
+   * @param {string} p
+   * @returns {string}
+   */
+  normalizePath(p) {
+    const abs = isAbsolute(p) ? p : resolve(this.cfg.repoRoot, p);
+    return relative(this.cfg.repoRoot, abs).split(sep).join("/");
+  }
+
+  /**
+   * AXIS 2, the ROOT half of scope: is this entry the scan's BUSINESS at all?
+   *
+   * THERE ARE TWO SCOPE PREDICATES AND COLLAPSING THEM REOPENS A MEASURED HOLE. This one decides
+   * whether an entry is in scope; the READ filters (`isWalkReadable`, `isStagedReadable`) decide
+   * whether a REGULAR FILE's bytes get read. Every non-regular and non-blob check keys on THIS one.
+   * Two sibling ports independently shipped a single shared predicate and both had the routes
+   * disagree about the same entry: a `.md`-named link fell out through the read filter on one route
+   * while the other refused it. A link's NAME is no evidence at all about what is on the other side
+   * of it, which is exactly what a read filter is entitled to assume about a file and is not
+   * entitled to assume about a link.
+   *
+   * A bare root name is in scope because git records no index entry for a directory. A scan root
+   * appearing as an index entry therefore means it is not a directory, and AT LEAST these readings
+   * exist: the root has been replaced by a blob or a link; it is a FILE ROOT, which this engine
+   * admits, since `scanRoots` derives a root's kind from the filesystem; or it is a gitlink, a
+   * nested repository, which the index refusal names in those words. No enumeration is attempted.
+   * An earlier draft predated file roots and said the first reading was the only one.
+   *
+   * @param {string} relPath
+   * @returns {boolean}
+   */
+  isUnderScanRoot(relPath) {
+    if (this.wholeRepo) return true;
+    return this.cfg.scanRoots.some((root) => relPath === root || relPath.startsWith(`${root}/`));
+  }
+
+  // -------------------------------------------------------------------------
+  // Argument parsing
+  // -------------------------------------------------------------------------
+
+  /**
+   * @param {string[]} argv
+   * @returns {{ mode: "all" | "staged" | "paths", paths: string[], allowFixtures: string[] }}
+   */
+  parseArgs(argv) {
+    let staged = false;
+    /** @type {string[]} */
+    const paths = [];
+    /** @type {string[]} */
+    const allowFixtures = [];
+    let i = 0;
+    while (i < argv.length) {
+      const a = argv[i];
+      if (a === "--") {
+        for (let j = i + 1; j < argv.length; j += 1) {
+          const v = argv[j];
+          if (v !== undefined) paths.push(v);
+        }
+        break;
+      } else if (a === "--staged") {
+        staged = true;
+        i += 1;
+      } else if (a === "--allow-fixture") {
+        const next = argv[i + 1];
+        if (next === undefined) {
+          throw new InvocationError("--allow-fixture requires a path argument");
+        }
+        allowFixtures.push(next);
+        i += 2;
+      } else if (a !== undefined && a.startsWith("--")) {
+        throw new InvocationError(`Unknown flag: ${a}`);
+      } else if (a !== undefined) {
+        paths.push(a);
+        i += 1;
+      } else {
+        i += 1;
+      }
+    }
+
+    if (staged && paths.length > 0) {
+      throw new InvocationError("--staged cannot be combined with positional paths");
+    }
+
+    // THE MODE IS CHOSEN BY POSITIONAL PATHS ALONE. Letting a bypass select the mode made
+    // `--allow-fixture X` scan exactly `X`, then withdraw it, then report a clean whole run over a
+    // corpus it never touched.
+    /** @type {"all" | "staged" | "paths"} */
+    let mode;
+    if (staged) mode = "staged";
+    else if (paths.length > 0) mode = "paths";
+    else mode = "all";
+
+    // A BYPASS IS NOT A TARGET LIST, AND WHICH TIER REFUSES IT IS THE CONTRACT (AC-17). In `paths`
+    // mode the run's declared scope is argv, so a bypass naming something else subtracts nothing and
+    // is refused by the UNMATCHED tier, which says so and names it. In `all` mode the declared scope
+    // is the whole corpus, so a bypass declares a path this run would have read and is refused by the
+    // COMPLETENESS tier: `run` adds it to the enumerated set for exactly that reason. Both refuse,
+    // and neither can reach the clean code.
+    //
+    // WHAT THIS IS NOT: the flag still does not choose the MODE. Letting it made
+    // `--allow-fixture X` scan exactly `X`, then withdraw it, then report a clean whole run over a
+    // corpus it never touched, and that is the hole the mode rule below closes. Dedupe is by
+    // repo-relative path, so one file named twice on argv is one target, not two.
+    const seed = [...paths];
+    const scanPaths = mode === "paths" ? this.dedupeByRepoPath(seed) : paths;
+
+    return { mode, paths: scanPaths, allowFixtures };
+  }
+
+  /**
+   * Dedupe argument paths by the repo-relative path each resolves to, keeping the caller's original
+   * spelling for the first occurrence: that spelling is what gets resolved and echoed back.
+   *
+   * @param {string[]} paths
+   * @returns {string[]}
+   */
+  dedupeByRepoPath(paths) {
+    const seen = new Set();
+    /** @type {string[]} */
+    const out = [];
+    for (const p of paths) {
+      const key = this.normalizePath(p);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(p);
+    }
+    return out;
+  }
+
+  // -------------------------------------------------------------------------
+  // Allow-list + override log
+  // -------------------------------------------------------------------------
+
+  /**
+   * The positive declaration that specific identifiers are synthetic.
+   *
+   * ONE ESCAPE IS DISCLOSED RATHER THAN CLOSED: an allow-list that EXISTS but cannot be READ (a
+   * directory at that path, or mode 000) makes `readFileSync` throw a plain `Error`, which is not an
+   * `InvocationError` and is therefore rethrown, and the run takes node's own exit 1 with a stack. A
+   * caller reads that as "hits found". `loadOverrideLog` has the identical shape. Both are left
+   * alone deliberately rather than papered over by widening a catch or enumerating `EACCES`/
+   * `EISDIR`: a deny-list of spellings buys exactly one more evasion per round, and this repo
+   * retired that shape once already on the `attw` gate. The exit contract below therefore says
+   * MISSING rather than "missing or unreadable", and says 1 is reserved but NOT exclusive.
+   *
+   * @returns {import("./phi-scan.js").AllowList}
+   */
+  loadAllowList() {
+    if (!existsSync(this.cfg.allowListPath)) {
+      throw new InvocationError(`allow-list not found at ${this.cfg.allowListPath}`);
+    }
+    const raw = readFileSync(this.cfg.allowListPath, "utf8");
+    /** @type {Set<string>} */ const names = new Set();
+    /** @type {Set<string>} */ const dobs = new Set();
+    /** @type {Set<string>} */ const ids = new Set();
+    /** @type {Set<string>} */ const emailDomains = new Set();
+    for (const lineRaw of raw.split(/\r?\n/)) {
+      const line = lineRaw.trim();
+      if (line.length === 0 || line.startsWith("#")) continue;
+      const sp = line.indexOf(" ");
+      if (sp < 0) continue;
+      const tag = line.slice(0, sp);
+      const value = line.slice(sp + 1).trim();
+      if (value.length === 0) continue;
+      switch (tag) {
+        case "NAME":
+          names.add(value.toUpperCase());
+          break;
+        case "DOB":
+          dobs.add(value);
+          break;
+        case "ID":
+          ids.add(value.toUpperCase());
+          break;
+        case "EMAILDOMAIN":
+          emailDomains.add(value.toLowerCase());
+          break;
+        default:
+          break;
+      }
+    }
+    return { names, dobs, ids, emailDomains };
+  }
+
+  /** @returns {Set<string>} Every path the override log records, repo-relative. */
+  loadOverrideLog() {
+    if (!existsSync(this.cfg.overrideLogPath)) return new Set();
+    const raw = readFileSync(this.cfg.overrideLogPath, "utf8");
+    /** @type {Set<string>} */
+    const out = new Set();
+    for (const lineRaw of raw.split(/\r?\n/)) {
+      const m = /^###\s+(.+?)\s*$/.exec(lineRaw);
+      if (m && m[1] !== undefined) out.add(this.normalizePath(m[1]));
+    }
+    return out;
+  }
+
+  /** @param {string[]} allowFixtures */
+  validateAllowFixtures(allowFixtures) {
+    if (allowFixtures.length === 0) return;
+    const overrides = this.loadOverrideLog();
+    const missing = allowFixtures
+      .map((p) => this.normalizePath(p))
+      .filter((p) => !overrides.has(p));
+    if (missing.length > 0) {
+      const lines = missing.map((p) => `  - ${p}`).join("\n");
+      throw new InvocationError(
+        `--allow-fixture rejected: no matching entry in ${this.relOverrideLog()} for:\n${lines}\n` +
+          `Add a "### <path>" subsection to ${this.relOverrideLog()} and commit it.`,
+      );
+    }
+  }
+
+  /** @returns {string} The override log's repo-relative path, for a diagnostic. */
+  relOverrideLog() {
+    return this.normalizePath(this.cfg.overrideLogPath);
+  }
+
+  /** @returns {string} The allow-list's repo-relative path, for a diagnostic. */
+  relAllowList() {
+    return this.normalizePath(this.cfg.allowListPath);
+  }
+
+  // -------------------------------------------------------------------------
+  // git
+  // -------------------------------------------------------------------------
+
+  /**
+   * Which of these paths git considers ignored.
+   *
+   * ONE BOUNDARY, NOT TWO: an ignored entry is already out of scope for the file route, so applying
+   * the same rule to a link keeps a single boundary rather than inventing a second, stricter one for
+   * links alone. `git check-ignore` is INDEX-AWARE, so `git add -f` on an ignored link does not buy
+   * a bypass: once tracked it is no longer reported ignored.
+   *
+   * @param {string[]} paths Repo-relative or absolute paths.
+   * @returns {Set<string>} The repo-relative paths git reports ignored.
+   */
+  gitIgnored(paths) {
+    /** @type {Set<string>} */
+    const ignored = new Set();
+    if (paths.length === 0) return ignored;
+    try {
+      // SECURITY: array-form execFileSync, no shell. Default (Buffer) encoding, because
+      // `encoding: "buffer"` together with `input` is rejected by Node.
+      const out = execFileSync("git", ["check-ignore", "--stdin", "-z"], {
+        cwd: this.cfg.repoRoot,
+        input: paths.map((p) => this.normalizePath(p)).join("\0"),
+        stdio: ["pipe", "pipe", "ignore"],
+        maxBuffer: 64 * 1024 * 1024,
+      });
+      for (const p of out.toString("utf8").split("\0")) {
+        if (p.length > 0) ignored.add(p);
+      }
+    } catch {
+      // `git check-ignore` exits 1 when nothing matches, and fatals outside a repository. Treat both
+      // as "none ignored": in `all` mode the missing index is refused separately and loudly, and
+      // pruning nothing can only ever make the sweep read MORE.
+    }
+    return ignored;
+  }
+
+  /**
+   * The repository's object format as a Node hash name, or `null` when git says something we do not
+   * recognise. `null` disables the union's content deduplication, which scans MORE, never less.
+   *
+   * WHEN GIT WILL NOT SAY AT ALL THE ANSWER IS `sha1`, NOT `null`, and the two cases are stated
+   * apart. A git too old to know `--show-object-format` predates sha256 repositories entirely, so
+   * the fallback is a derivation rather than a guess; an answer we do not recognise is a git NEWER
+   * than this file, and there the honest move is to stop deduplicating.
+   *
+   * @returns {string | null}
+   */
+  gitObjectHash() {
+    let answer;
+    try {
+      // SECURITY: array-form execFileSync, no shell.
+      answer = execFileSync("git", ["rev-parse", "--show-object-format"], {
+        cwd: this.cfg.repoRoot,
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+        .toString("utf8")
+        .trim();
+    } catch {
+      return "sha1";
+    }
+    if (answer === "sha1") return "sha1";
+    if (answer === "sha256") return "sha256";
+    return null;
+  }
+
+  /**
+   * The object id git would record for these bytes, under its own `blob <len>\0` framing.
+   *
+   * Used only to answer "did the walk already read EXACTLY the bytes the index carries here", so a
+   * wrong answer can only ever cost a second scan of the same content. THIS IS THE EOL AXIS: where a
+   * `text` attribute or `core.autocrlf` makes the index carry LF and the working tree CRLF, the two
+   * ids differ and BOTH copies are scanned.
+   *
+   * @param {string} algorithm
+   * @param {Buffer} bytes
+   * @returns {string | null}
+   */
+  blobOid(algorithm, bytes) {
+    try {
+      return createHash(algorithm)
+        .update(`blob ${String(bytes.length)}\0`)
+        .update(bytes)
+        .digest("hex");
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Every stage-0 index entry keyed by repo-relative path, plus the paths that have a record but NO
+   * stage-0 record.
+   *
+   * THREE OUTCOMES, NOT TWO, AND THE SPLIT IS THE POINT (AC-18). `unreadable` means git could not
+   * say what this repository carries; `empty` means it said, and the answer is nothing. Both refuse
+   * the sweep, and an empty answer still counts as no corpus: an empty map would make every tracked
+   * path untracked, which is the one state in which the union silently stops existing. What differs
+   * is the REMEDY, so the two states carry different sentences rather than one that covers both.
+   *
+   * 🛑 THE STAGE DIGIT IS READ, AND KEYING ON IT IS NOT OPTIONAL. THE RULE IS THE ABSENCE OF STAGE 0.
+   * Do NOT re-derive it from a record count or from a mode, and do NOT port it from the `--staged`
+   * route: that route spots an unmerged path from `--raw`'s status `U` and a destination mode of
+   * `000000`, and NOTHING IN `ls-files -s` LOOKS LIKE THAT. An unmerged path is reported here only at
+   * stages 1, 2 and/or 3, with ORDINARY BLOB MODES, so the mode rule cannot see it. A sibling's draft
+   * took the FIRST record per path and never looked at the stage: it scanned STAGE 1, THE MERGE BASE,
+   * labelled it as the bytes git carries, and printed a clean line over a marker living only in
+   * stage 3.
+   *
+   * @returns {{ status: "read", entries: Map<string, import("./phi-scan.js").IndexEntry>, unmerged: string[] } | { status: "unreadable" | "empty" }}
+   */
+  gitIndexEntries() {
+    let out;
+    try {
+      // SECURITY: array-form execFileSync, no shell. `-z` is NUL-separated and unquoted, so it
+      // matches the walk's forward-slash relative paths exactly. `maxBuffer` is raised because a
+      // TRUNCATED list is a SHORT list, and a short list is the unscanned corpus this whole rule is
+      // about; Node throws `ENOBUFS` rather than truncating, so the bound refuses either way.
+      out = execFileSync("git", ["ls-files", "-s", "-z"], {
+        cwd: this.cfg.repoRoot,
+        stdio: ["ignore", "pipe", "ignore"],
+        maxBuffer: 64 * 1024 * 1024,
+      });
+    } catch {
+      // LOAD-BEARING. A directory that is no repository FATALS at 128; without this catch the throw
+      // escapes and the run takes node's exit 1, which this contract reserves for HITS FOUND.
+      return { status: "unreadable" };
+    }
+    /** @type {Map<string, import("./phi-scan.js").IndexEntry>} */
+    const entries = new Map();
+    /** @type {Set<string>} */
+    const higherStages = new Set();
+    for (const rec of out.toString("utf8").split("\0")) {
+      if (rec.length === 0) continue;
+      // `<mode> <oid> <stage>\t<path>`; a path may contain anything but NUL.
+      const m = /^(\d{6}) ([0-9a-f]+) (\d)\t([\s\S]+)$/.exec(rec);
+      const mode = m?.[1];
+      const oid = m?.[2];
+      const stage = m?.[3];
+      const path = m?.[4];
+      if (mode === undefined || oid === undefined || stage === undefined || path === undefined) {
+        // An unparseable record means the list may be SHORT in a way we cannot see, which is the one
+        // thing this sweep must never scan past. It is UNREADABLE rather than empty: git answered,
+        // and the answer is one this engine cannot account for.
+        return { status: "unreadable" };
+      }
+      if (stage === "0") entries.set(path, { mode, oid });
+      else higherStages.add(path);
+    }
+    // A path is unmerged when it has a record and none of them is stage 0. The set difference is
+    // taken rather than assuming the two are disjoint.
+    const unmerged = [...higherStages].filter((p) => !entries.has(p));
+    if (entries.size === 0 && unmerged.length === 0) return { status: "empty" };
+    return { status: "read", entries, unmerged };
+  }
+
+  // -------------------------------------------------------------------------
+  // Enumeration: the walk
+  // -------------------------------------------------------------------------
+
+  /**
+   * Enumerate the scan roots.
+   *
+   * `Dirent`'s predicates are lstat answers and are not exhaustive: an entry that is neither a
+   * directory nor a regular file is collected into `unscannable` rather than dropped, so the caller
+   * can refuse instead of reporting clean over it.
+   *
+   * IGNORED DIRECTORIES ARE PRUNED DURING DESCENT, ONE `git check-ignore` PER LEVEL. That is not an
+   * optimisation bolted onto a filter: `scanRoots: ["."]` is the only honest default for a freshly
+   * scaffolded repo, and without pruning such a sweep descends into `node_modules`.
+   *
+   * WHY IT IS EQUIVALENT TO FILTERING AFTERWARDS, NAMED AS THE RULE THAT ACTUALLY CARRIES IT. An
+   * earlier draft said "git cannot re-include a path under an excluded directory", which is a
+   * gitignore-PATTERN rule and does not settle this on its own, because the filter it replaces
+   * asked `check-ignore` too. The load-bearing property is that `git check-ignore` IS INDEX-AWARE AT
+   * DIRECTORY GRANULARITY. Measured on git 2.39.5, with `node_modules/` in `.gitignore`:
+   *
+   *   - nothing tracked underneath  -> `check-ignore node_modules` exits 0 and the directory is
+   *     pruned, which is right, because no file under it could have survived the file-level filter
+   *     either;
+   *   - one file force-added underneath -> `check-ignore node_modules` exits 1, the directory is NOT
+   *     pruned, and the walk descends and reads the tracked file exactly as before.
+   *
+   * The file-level filter still runs below, so pruning only ever removes work the filter would have
+   * removed anyway. `test/phi-scan-engine.test.ts` pins BOTH directions, because a test that only
+   * plants a violator in an ignored directory measures that pruning happens, not that it is safe.
+   *
+   * A DIRECTORY NAMED `.git` IS SKIPPED BY NAME, at any depth. It is git's own object store rather
+   * than the corpus, git does not report it ignored, and the union already reads what the repository
+   * carries. This is a literal name, never a predicate over content.
+   *
+   * A SCAN ROOT MAY NAME A REGULAR FILE, AND THE KIND IS DERIVED FROM THE FILESYSTEM RATHER THAN
+   * DECLARED. That is a deliberate API decision, and it was made against a measurement rather than a
+   * preference: one sibling declares its roots as `{ rel, shape: "directory" | "file" }` and lists a
+   * single file (`README.md`) among them, and an earlier draft of this walk fed every root straight
+   * to `readdirSync`, so such a root threw `ENOTDIR` from here, uncaught, and the run took node's own
+   * exit 1, which this contract reserves for HITS FOUND. Deriving the kind keeps the parameter a
+   * plain `string[]` and still expresses that shape.
+   *
+   * THAT PARTICULAR ROOT READS NOTHING UNDER THE DEFAULT `isWalkReadable`, and the example is
+   * caveated rather than left to be copied. A file root goes through the same read filter every
+   * other file does, so with the shared Markdown exemption in place `scanRoots: ["README.md"]` was
+   * measured returning `OK: no hits` at exit 0 over a live dashed identifier. A repo porting a `.md`
+   * root has to override that filter as well.
+   *
+   * WHAT DERIVING GIVES UP, STATED RATHER THAN LEFT TO BE FOUND: a declaration can notice that a root
+   * is not the KIND it was meant to be, and derivation cannot. A root that was a file and became a
+   * directory is descended, and one that was a directory and became a file is read as a file, in both
+   * cases silently. What is NOT given up is the non-regular case: a root that is neither is collected
+   * as unscannable and refused, exactly as an entry inside one would be.
+   *
+   * A MISSING ROOT IS SKIPPED BY THE WALK, AND THAT IS UNCHANGED FROM THE COPIED SCANNERS rather
+   * than chosen here. Two root states are refused or normalised away in `normalizeConfig` (a
+   * spelling that matches no index path is normalised away and the run proceeds; a root outside the
+   * repository throws), and this one is neither.
+   *
+   * WHAT IT NO LONGER DOES IS CONTRIBUTE NOTHING IN SILENCE, and that is a change. A draft of this
+   * paragraph claimed the states in which a root contributes nothing were not enumerable, and named
+   * three anyway: a MISSING root; an UNREADABLE one, which `lstatOrNull`'s bare catch reports the
+   * same way (an `EACCES` on a parent directory, or an `ELOOP`); and a root whose every file the
+   * read filter drops, which is what a `.md` file root does under the default `isWalkReadable`. The
+   * set still is not enumerated, because nothing here has measured it to be complete - and it no
+   * longer has to be. `run`'s PER-ROOT OBSERVATION RULE asks the question from the other end, of
+   * the paths actually READ, so a root that yielded nothing refuses whatever put it in that state.
+   *
+   * A DIRECTORY THE WALK CANNOT LIST IS COLLECTED AND REFUSED, NOT THROWN OUT OF. `readdirSync` used
+   * to run bare here, so an `EACCES` on a root (or on any directory under one) escaped uncaught and
+   * the run took node's own exit 1, the code this contract reserves for HITS FOUND. It is the third
+   * of the three root KINDS this engine settles (AC-10): a regular file root is scanned as one
+   * target, a root naming a symbolic link is refused rather than followed, and a directory that
+   * cannot be enumerated is refused at the caller's `refuse` code, naming the path.
+   *
+   * The result is SORTED by repo-relative path, so a report and a refusal read the same way twice.
+   *
+   * @returns {{ files: string[], unscannable: import("./phi-scan.js").Unscannable[], unenumerable: import("./phi-scan.js").Unscannable[] }}
+   */
+  walkRoots() {
+    /** @type {string[]} */
+    const files = [];
+    /** @type {import("./phi-scan.js").Unscannable[]} */
+    const unscannable = [];
+    /** Directories the walk reached and could not list. `kind` is the errno, never a path. */
+    /** @type {import("./phi-scan.js").Unscannable[]} */
+    const unenumerable = [];
+
+    // Split the roots by what is actually THERE, before the descent. A root naming a regular file is
+    // one target; a root naming a directory is a frontier; a root naming anything else is refused
+    // through the same unscannable path an entry inside one would take.
+    /** @type {string[]} */
+    const rootDirs = [];
+    for (const root of this.cfg.scanRoots) {
+      const abs = root === "." ? this.cfg.repoRoot : join(this.cfg.repoRoot, ...root.split("/"));
+      const stats = lstatOrNull(abs);
+      if (stats === null) continue; // A missing root, skipped. See the docblock above.
+      if (stats.isDirectory()) rootDirs.push(abs);
+      else if (stats.isFile()) {
+        if (this.cfg.isWalkReadable(this.normalizePath(abs))) files.push(abs);
+      } else {
+        unscannable.push({ path: this.normalizePath(abs), kind: statsKind(stats) });
+      }
+    }
+
+    let frontier = rootDirs;
+    const visited = new Set(frontier);
+
+    while (frontier.length > 0) {
+      /** @type {string[]} */
+      const nextDirs = [];
+      for (const dir of frontier) {
+        if (!existsSync(dir)) continue;
+        let listing;
+        try {
+          listing = readdirSync(dir, { withFileTypes: true });
+        } catch (err) {
+          // A DIRECTORY THAT CANNOT BE LISTED IS A REFUSAL, NEVER A CRASH. The errno is recorded
+          // and nothing else: a message off the filesystem is text this engine cannot vouch for.
+          unenumerable.push({
+            path: this.normalizePath(dir),
+            kind:
+              err !== null && typeof err === "object" && "code" in err
+                ? String(err.code)
+                : "unreadable",
+          });
+          continue;
+        }
+        for (const e of listing) {
+          const full = join(dir, e.name);
+          if (e.isDirectory()) {
+            if (e.name === ".git") continue;
+            if (visited.has(full)) continue;
+            visited.add(full);
+            nextDirs.push(full);
+          } else if (e.isFile()) {
+            // A READ filter. The branch below is deliberately NOT subject to it: that exemption is a
+            // judgement about a file whose bytes the walk could have read, and a link's name is no
+            // evidence at all about what is on the other side.
+            if (!this.cfg.isWalkReadable(this.normalizePath(full))) continue;
+            files.push(full);
+          } else {
+            unscannable.push({ path: this.normalizePath(full), kind: direntKind(e) });
+          }
+        }
+      }
+      frontier = this.pruneIgnoredDirs(nextDirs);
+    }
+
+    files.sort((a, b) => (this.normalizePath(a) < this.normalizePath(b) ? -1 : 1));
+    unscannable.sort((a, b) => (a.path < b.path ? -1 : 1));
+    unenumerable.sort((a, b) => (a.path < b.path ? -1 : 1));
+    return { files, unscannable, unenumerable };
+  }
+
+  /**
+   * @param {string[]} dirs
+   * @returns {string[]} The subset git does not report ignored.
+   */
+  pruneIgnoredDirs(dirs) {
+    if (dirs.length === 0) return dirs;
+    const ignored = this.gitIgnored(dirs);
+    return dirs.filter((d) => !ignored.has(this.normalizePath(d)));
+  }
+
+  // -------------------------------------------------------------------------
+  // Enumeration: the three routes
+  // -------------------------------------------------------------------------
+
+  /**
+   * `all` mode's enumeration: the walk, PLUS the index the union half reads.
+   *
+   * THE TWO INDEX-ROUTE REFUSALS ARE RETURNED RATHER THAN THROWN, AND THAT IS A CHANGE (AC-15).
+   * They used to fire here, BEFORE the sweep, so an unmerged entry or a tracked link discarded every
+   * hit the walk was about to find and a consumer saw a refusal with no indication that PHI had
+   * already been found. The caller raises them after the walk sweep, printing the hits first. The
+   * refusal still wins the exit code and the clean line is still unreachable from there; what
+   * changes is that a finding already made is not thrown away. The cost is stated rather than
+   * hidden: a developer now waits out the walk before being told the index is unreadable at one
+   * path.
+   *
+   * @returns {{ targets: import("./phi-scan.js").Target[], index: Map<string, import("./phi-scan.js").IndexEntry>, indexRefusals: string[] }}
+   */
+  buildTargetsForAll() {
+    const { files, unscannable, unenumerable } = this.walkRoots();
+
+    // One `git check-ignore` over all three lists, so a link, a file and an unlistable directory get
+    // the same boundary.
+    const ignored = this.gitIgnored([
+      ...files.map((f) => this.normalizePath(f)),
+      ...unscannable.map((u) => u.path),
+      ...unenumerable.map((u) => u.path),
+    ]);
+
+    const blocked = unenumerable.filter(
+      (u) => !ignored.has(u.path) && !this.cfg.excludedPaths.has(u.path),
+    );
+    if (blocked.length > 0) {
+      // AC-10, the third root kind. Named one by one rather than listed under a count, because the
+      // remedy is per path and a developer re-running the gate once per directory learns to
+      // distrust it.
+      const named = blocked.map((u) => `${u.path} (${u.kind})`).join(", ");
+      throw new InvocationError(
+        `refusing the scan: could not enumerate ${named}. A directory the walk cannot list ` +
+          `contributes nothing while looking exactly like one that is empty, so the sweep would ` +
+          `cover less than its own configuration says. Make it readable, or drop it from the scan ` +
+          `roots.`,
+      );
+    }
+
+    this.refuseUnscannable(
+      unscannable.filter((u) => !ignored.has(u.path) && !this.cfg.excludedPaths.has(u.path)),
+      "The walk can neither read such an entry nor vouch for what is on the other side of it.",
+      "Remove it, replace it with a regular file, or (if it is genuinely not part of the corpus) " +
+        "untrack it and add it to .gitignore.",
+    );
+
+    const listed = this.gitIndexEntries();
+    if (listed.status !== "read") {
+      // AC-18: TWO STATES, TWO MESSAGES, because the remedies differ. "Run this inside a git
+      // repository with a readable index" is no help to somebody whose repository is fine and whose
+      // index is empty, and one sentence for both was measured sending a reader to the wrong one.
+      throw new InvocationError(
+        listed.status === "empty"
+          ? "refusing the sweep: the git index holds no entries, so every check the sweep makes " +
+              "against what git carries would pass vacuously and every path would look untracked. " +
+              "Stage and commit this repository's corpus, then re-run."
+          : "refusing the sweep: could not read this repository's git index, so the sweep would be " +
+              "the working-tree walk's word alone and could report clean over tracked bytes it " +
+              "never opened. Run it inside a git repository with a readable index.",
+      );
+    }
+
+    /** @type {string[]} */
+    const indexRefusals = [];
+
+    // THE INDEX ROUTE IS NOT FILTERED TO `scanRoots` (AC-12). `scanRoots` is the WALK's scope: it
+    // answers "what is on disk under the roots this repo declared". The index answers "what does
+    // this repository CARRY", which is not a question a root list is entitled to narrow. Measured on
+    // the first consumer: three real messages under an undeclared top-level directory were read by
+    // neither route, and a tracked link outside every root was reached by neither. So every path the
+    // index carries is considered here, and `--staged` is untouched by that: it keeps its own scope,
+    // which is what a COMMIT is blocked on.
+    //
+    // Unmerged first, and under its OWN sentence: an unmerged path is not a link and not a gitlink,
+    // and reporting it as one sends a developer looking for something that is not there.
+    const unmergedMessage = this.unscannableMessage(
+      listed.unmerged
+        .filter((p) => !this.cfg.excludedPaths.has(p))
+        .map((p) => ({ path: p, kind: "no stage-0 blob" })),
+      "An unmerged path has no single merged blob, so there is no one set of bytes git carries here " +
+        "for the sweep to read, only the conflicting sides and, when there is one, their base.",
+      "Resolve the conflict and stage the result, then re-run.",
+      { one: "path is unmerged", many: "paths are unmerged" },
+    );
+    if (unmergedMessage !== null) indexRefusals.push(unmergedMessage);
+
+    // The index's own non-blob entries. `120000` is a symbolic link, whose blob is its TARGET PATH
+    // and not any content; `160000` is a gitlink, which carries another repository's commit id and
+    // no bytes at this path at all.
+    const nonBlobMessage = this.unscannableMessage(
+      [...listed.entries]
+        .filter(
+          ([p, e]) => !this.cfg.regularBlobModes.has(e.mode) && !this.cfg.excludedPaths.has(p),
+        )
+        .map(([p, e]) => ({ path: p, kind: gitModeKind(e.mode) })),
+      "Git records no readable content at such a path: a symbolic link's blob is its target path, " +
+        "and a gitlink is another repository's commit id, never bytes here.",
+      "Untrack it, or replace it with a regular file.",
+      // Its own noun: the offender is an INDEX RECORD, and a gitlink's working tree may not exist at
+      // all, so "not a regular file" would send a developer to a path where there is nothing to see.
+      { one: "index entry is not a regular blob", many: "index entries are not regular blobs" },
+    );
+    if (nonBlobMessage !== null) indexRefusals.push(nonBlobMessage);
+
+    const targets = files
+      .map((abs) => ({ abs, rel: this.normalizePath(abs) }))
+      .filter(({ rel }) => !ignored.has(rel) && !this.cfg.excludedPaths.has(rel))
+      .map(({ abs, rel }) => ({ path: rel, read: () => readFileSync(abs) }));
+    return { targets, index: listed.entries, indexRefusals };
+  }
+
+  /**
+   * The tracked paths the union half is entitled to read: EVERY regular blob the index carries, not
+   * only the ones under a scan root (AC-12).
+   *
+   * `scanRoots` IS THE WALK'S SCOPE AND NOT THE INDEX'S. The walk answers "what is on disk under the
+   * roots this repo declared"; the index answers "what does this repository CARRY", and narrowing
+   * the second by the first was measured hiding three real messages under an undeclared top-level
+   * directory from BOTH routes. The two READ filters still apply, so the `.md` exemption and
+   * `excludedPaths` mean the same thing on both sweeping routes: one boundary, not two.
+   *
+   * IT IS COMPUTED BEFORE THE FIRST BYTE IS READ, AND THAT IS LOAD-BEARING. This set is part of what
+   * `all` mode ENUMERATES, so both completeness tiers see it: a bypass naming a tracked-but-absent
+   * path subtracts something real rather than being refused as naming nothing, and a target that
+   * ends up unread is named by the unread refusal whichever route would have read it.
+   *
+   * @param {Map<string, import("./phi-scan.js").IndexEntry>} index
+   * @returns {string[]}
+   */
+  unionCandidatePaths(index) {
+    return [...index]
+      .filter(([p, e]) => this.cfg.regularBlobModes.has(e.mode) && this.cfg.isWalkReadable(p))
+      .filter(([p]) => !this.cfg.excludedPaths.has(p))
+      .map(([p]) => p);
+  }
+
+  /**
+   * THE UNION HALF of `all` mode: the bytes git carries at every in-scope tracked path whose bytes
+   * the walk did not already read VERBATIM.
+   *
+   * `readOids` maps a path the walk actually READ to the object id of what it read. A path absent
+   * from it was never opened, whatever the reason, so its blob is scanned; a path present with a
+   * DIFFERENT id had a different copy read, so its blob is scanned too. That second case is the EOL
+   * axis.
+   *
+   * THOSE TWO CASES CARRY DIFFERENT ORIGIN LABELS, AND THE REMEDY IS WHY (AC-14). `(git index)` is a
+   * path whose working-tree copy this run did not read at all: it is absent, occupied by a
+   * directory, or outside the walk's roots, so there is nothing on disk to open. `(git index; the
+   * working tree differs)` is a path whose disk copy WAS read and carries other bytes, so the file a
+   * developer opens is clean and RE-STAGING is part of the fix. One label for both hid that
+   * difference behind the same sentence.
+   *
+   * @param {Map<string, import("./phi-scan.js").IndexEntry>} index
+   * @param {Map<string, string>} readOids
+   * @returns {import("./phi-scan.js").Target[]}
+   */
+  buildTargetsForGitIndex(index, readOids) {
+    /** @type {import("./phi-scan.js").Target[]} */
+    const targets = [];
+    for (const path of this.unionCandidatePaths(index)) {
+      const entry = index.get(path);
+      if (entry === undefined) continue;
+      if (readOids.get(path) === entry.oid) continue;
+      targets.push({
+        path,
+        origin: readOids.has(path) ? "git index; the working tree differs" : "git index",
+        // SECURITY: array-form execFileSync, no shell. The object id is git's own output, and naming
+        // the OBJECT rather than the path is the whole point: it cannot be redirected by whatever
+        // the working tree currently holds. `maxBuffer` defaults to 1 MiB, so a larger tracked blob
+        // fails the read and REFUSES rather than reporting a truncated scan clean.
+        read: () =>
+          execFileSync("git", ["cat-file", "blob", entry.oid], {
+            cwd: this.cfg.repoRoot,
+            encoding: "buffer",
+            stdio: ["ignore", "pipe", "pipe"],
+          }),
+      });
+    }
+    return targets;
+  }
+
+  /**
+   * @param {string[]} paths
+   * @returns {import("./phi-scan.js").Target[]}
+   */
+  buildTargetsForPaths(paths) {
+    return paths.map((p) => {
+      const abs = isAbsolute(p) ? p : resolve(this.cfg.repoRoot, p);
+      if (!existsSync(abs)) throw new InvocationError(`File not found: ${p}`);
+      if (!statSync(abs).isFile()) throw new InvocationError(`Not a regular file: ${p}`);
+      return { path: this.normalizePath(abs), read: () => readFileSync(abs) };
+    });
+  }
+
+  /**
+   * `--staged`: exactly the blobs a commit would carry.
+   *
+   * `--raw` rather than `--name-only` because the DESTINATION MODE is the only thing that
+   * distinguishes a staged regular file from a staged symlink or gitlink. `git show :<path>` does not
+   * stand in for it: for a symbolic link it hands back the target path as if it were content, and it
+   * is the mode, not the answer, that says so.
+   *
+   * `--diff-filter=d` IS AN EXCLUSION ("everything EXCEPT deletions"), NOT AN ALLOW-LIST OF STATUS
+   * LETTERS, AND THE POLARITY IS THE WHOLE POINT. An allow-list drops every letter it does not name,
+   * silently; that polarity is what made sibling scanners miss `R` (rename) and then `T`
+   * (typechange), each found by a separate refuter pass one round apart. An unfamiliar or future
+   * status letter can now only ever cost a wasted scan or a loud refusal, never a missed file.
+   * Against an `AMT` allow-list, what `d` newly enumerates is `U` (unmerged), `X` (unknown) and `B`
+   * (broken pairing). Measured on git 2.39.5, a conflicted path lists as one record with destination
+   * mode `000000`, so the stride is unaffected and the mode is not a regular blob, which puts it
+   * through the refusal below instead of past it.
+   *
+   * `T` (TYPECHANGE) IS ENUMERATED, AND LEAVING IT OUT MAKES THE MODE CHECK UNREACHABLE WHENEVER THE
+   * FILE IS ALREADY TRACKED: replacing a TRACKED regular file with a link is not an add and not a
+   * modify, so an `AM` allow-list deletes the record before any mode can be read.
+   *
+   * `--no-renames` IS SEPARATELY LOAD-BEARING. Rename detection is on by default, so `git mv <link>
+   * <scan root>/<name>` stages as one record carrying TWO paths, which desyncs the two-field stride.
+   * Turning detection off makes the destination arrive as an ordinary single-path `A` and the source
+   * a `D` the filter drops, which makes the stride STRUCTURAL rather than conditional on the
+   * caller's `diff.renames` setting.
+   *
+   * @returns {import("./phi-scan.js").Target[]}
+   */
+  buildTargetsForStaged() {
+    let listBuf;
+    try {
+      // SECURITY: array-form execFileSync, no shell.
+      listBuf = execFileSync(
+        "git",
+        ["diff", "--cached", "--raw", "-z", "--no-renames", "--diff-filter=d"],
+        {
+          cwd: this.cfg.repoRoot,
+          encoding: "buffer",
+          stdio: ["ignore", "pipe", "pipe"],
+          maxBuffer: 64 * 1024 * 1024,
+        },
+      );
+    } catch (err) {
+      throw new InvocationError(
+        `git diff --cached failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    // `--raw -z` emits `<info>\0<path>\0` per record. `R` and `C` are the only statuses carrying a
+    // SECOND path and `--no-renames` means git cannot emit either, so the stride is two fields. A
+    // record that does not parse REFUSES rather than being skipped: a silently shortened list is
+    // exactly the shape this scan must never report clean over.
+    const fields = listBuf.toString("utf8").split("\0");
+    /** @type {{ path: string, mode: string, status: string }[]} */
+    const staged = [];
+    let i = 0;
+    while (i < fields.length) {
+      const info = fields[i];
+      if (info === undefined || info.length === 0) {
+        i += 1;
+        continue;
+      }
+      const m = RAW_RECORD.exec(info);
+      const mode = m?.[1];
+      const status = m?.[2];
+      const path = fields[i + 1];
+      if (mode === undefined || status === undefined || path === undefined || path.length === 0) {
+        throw new InvocationError(
+          "could not read the output of `git diff --cached --raw -z`: unrecognized record. " +
+            "Refusing rather than scanning a list that may be short.",
+        );
+      }
+      staged.push({ path, mode, status });
+      i += 2;
+    }
+
+    // THIS ROUTE'S REFUSALS KEY ON `isStagedReadable`, WHICH IS THE CALLER'S OWN SCOPE FOR IT
+    // (AC-16). They used to key on the ROOT half instead, and for a caller whose staged scope is
+    // narrower than its roots that REFUSED a commit the repo's own gate had always let through:
+    // measured on the first consumer, a staged `src/notes.txt` symbolic link is outside a
+    // `src/**.ts` staged scope and was refused at the refuse code where the repo's own scanner
+    // exited 0. What a commit is blocked on is a hook decision each repo takes for itself, and
+    // widening it from inside a shared engine takes that decision away.
+    //
+    // 🛑 THIS NARROWS WHAT THIS ROUTE REFUSES, AND THE COMPENSATING CONTROL IS NAMED RATHER THAN
+    // ASSUMED. A staged non-regular entry the caller's staged scope declines is no longer refused
+    // HERE. It is still refused by `all` mode twice over: the walk classifies it with
+    // `Dirent.isSymbolicLink()` when it sits under a scan root, and the index route refuses the
+    // tracked mode-120000 record wherever it sits, now that that route is not narrowed to the roots
+    // either. So the sweep a repository runs in CI still refuses it; the pre-commit hook no longer
+    // does. See `documentation/decisions/0003-the-phi-scan-engine-gap-settlements.md`.
+    //
+    // AN UNMERGED PATH IS NOT ONE OF THESE. Its destination mode is `000000`, which the mode rule
+    // would otherwise describe as "a git mode-000000 entry" beside a sentence about content git
+    // holds at the path, and both halves are false for a conflicted regular file.
+    const unmerged = staged.filter((s) => s.status === "U" || s.mode === "000000");
+    const stagedReadable = (/** @type {{ path: string, mode: string, status: string }} */ s) =>
+      this.cfg.isStagedReadable(s.path) && !this.cfg.excludedPaths.has(s.path);
+
+    // THE CONTAINMENT IS ENFORCED, NOT ASSUMED, AND IT USED TO BE THE WORD "by construction".
+    // `isStagedReadable` and `scanRoots` are two independent keys a repo fills in, and nothing
+    // relates them. A reviewer measured what that costs: with roots narrowed to `src` and this
+    // filter left at the shared Markdown exemption, a STAGED mode-120000 entry under
+    // `test/fixtures/` was outside every scan root, so the non-regular refusal above never saw it,
+    // and the route then ENUMERATED it, READ it, handed the link's TARGET PATH to the detector as
+    // if it were content, counted the scan complete, and printed `OK: no hits` at exit 0. That is
+    // exactly the hole the two-predicate rule exists to close, arriving through configuration
+    // instead of through code.
+    //
+    // So a staged path this filter admits and `isUnderScanRoot` does not is REFUSED. Narrowing it
+    // silently to the intersection would be the wrong repair: it would hide a misconfiguration that
+    // the author needs to see, in the one place the gate is a commit blocker.
+    this.refuseUnscannable(
+      staged
+        .filter(
+          (s) =>
+            this.cfg.isStagedReadable(s.path) &&
+            !this.isUnderScanRoot(s.path) &&
+            !this.cfg.excludedPaths.has(s.path),
+        )
+        .map((s) => ({ path: s.path, kind: "outside every scan root" })),
+      "`isStagedReadable` admits a path no scan root covers, so the checks that key on the ROOT " +
+        "half of scope never ran for it: its bytes would be read without anything having " +
+        "established that there are bytes there to read.",
+      "Widen `scanRoots` to cover it, or narrow `isStagedReadable` to stay inside them.",
+      {
+        one: "staged path is readable but outside every scan root",
+        many: "staged paths are readable but outside every scan root",
+      },
+    );
+
+    // THE MISCONFIGURATION REFUSAL ABOVE COMES FIRST ON PURPOSE. Both it and the two below can fire
+    // over the same entry, and a developer whose `isStagedReadable` admits a path no root covers
+    // needs to hear that rather than a sentence about this one entry's kind.
+    this.refuseUnscannable(
+      unmerged.filter(stagedReadable).map((s) => ({ path: s.path, kind: "no stage-0 blob" })),
+      "An unmerged path has no stage-0 blob, so the index holds no single set of bytes a commit " +
+        "would carry here, only the conflicting sides and, when there is one, their base.",
+      "Resolve the conflict and stage the result, then re-run.",
+      { one: "staged path is unmerged", many: "staged paths are unmerged" },
+    );
+
+    this.refuseUnscannable(
+      staged
+        .filter(
+          (s) =>
+            stagedReadable(s) && !unmerged.includes(s) && !this.cfg.regularBlobModes.has(s.mode),
+        )
+        .map((s) => ({ path: s.path, kind: gitModeKind(s.mode) })),
+      "The index holds no file content for such an entry, so scanning it would prove nothing about " +
+        "what it refers to.",
+      "Unstage it, or replace it with a regular file.",
+    );
+
+    // Every remaining readable record is a regular blob: anything non-regular was refused above,
+    // anything unmerged was refused above it, and anything outside the roots before that.
+    return staged
+      .filter((s) => this.cfg.isStagedReadable(s.path) && !this.cfg.excludedPaths.has(s.path))
+      .map((s) => s.path)
+      .map((relPath) => ({
+        path: relPath,
+        // SECURITY: array-form execFileSync, no shell. `:<path>` is a git pathspec.
+        read: () =>
+          execFileSync("git", ["show", `:${relPath}`], {
+            cwd: this.cfg.repoRoot,
+            encoding: "buffer",
+            stdio: ["ignore", "pipe", "pipe"],
+          }),
+      }));
+  }
+
+  /**
+   * The absolute path of a repo-relative one, for a question about the filesystem rather than
+   * about the corpus. Only the TOCTOU re-check asks one.
+   *
+   * @param {string} relPath
+   * @returns {string}
+   */
+  absolutePath(relPath) {
+    return relPath === "." ? this.cfg.repoRoot : join(this.cfg.repoRoot, ...relPath.split("/"));
+  }
+
+  /**
+   * Did this root yield at least one file whose bytes were ACTUALLY READ?
+   *
+   * IT IS ASKED OF `read`, WHICH IS EVIDENCE OF OBSERVATION RATHER THAN A PLAN TO OBSERVE, and it
+   * is asked per root rather than of the union, because the union is exactly what hides a starved
+   * root: one productive root makes the whole sweep look productive.
+   *
+   * @param {string} root A normalised scan root.
+   * @param {Set<string>} read The repo-relative paths this run opened.
+   * @returns {boolean}
+   */
+  anyReadUnder(root, read) {
+    for (const p of read) {
+      if (root === "." || p === root || p.startsWith(`${root}/`)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Is this read failure the ENUMERATION TOCTOU WINDOW rather than a state the run must refuse?
+   *
+   * FOUR CONDITIONS, ALL OF THEM NECESSARY, because each one is a different question the run can
+   * still answer honestly afterwards:
+   *
+   *   1. `all` MODE. The other two routes were asked for a path BY NAME - on argv, or by git's
+   *      own index - so a caller is owed an answer about that path rather than a shrug.
+   *   2. THE WALK'S OWN TARGET, never the union's. The union reads an OBJECT by id, which cannot
+   *      go missing between enumeration and read.
+   *   3. `ENOENT`, exactly. Every other errno says the entry is still there and something else
+   *      went wrong, which is the state a scan must never report past.
+   *   4. UNTRACKED. Git carries bytes at a tracked path, so a tracked file that vanished still
+   *      leaves this run with content it declared it would read and did not.
+   *
+   * @param {unknown} err
+   * @param {import("./phi-scan.js").Target} target
+   * @param {Map<string, import("./phi-scan.js").IndexEntry> | null} index
+   * @returns {boolean}
+   */
+  isVanishedUntracked(err, target, index) {
+    return (
+      err instanceof TargetReadError &&
+      err.errnoCode === "ENOENT" &&
+      index !== null &&
+      target.origin === undefined &&
+      !index.has(target.path)
+    );
+  }
+
+  /**
+   * Refuse over entries the enumeration reached and cannot scan. EVERY offender IN THE GROUP is
+   * named, not just the first: a developer who has to re-run the gate once per link learns to
+   * distrust it.
+   *
+   * A refusal names the entry's own repo-relative path and an engine-owned token for its kind. IT
+   * NEVER REPORTS A LINK TARGET, which is text off the working tree and can itself carry PHI.
+   *
+   * `noun` is overridable because the refusal must say something TRUE about what it refused: an
+   * unmerged path is not a non-regular file, it is a path with no single blob.
+   *
+   * @param {import("./phi-scan.js").Unscannable[]} entries
+   * @param {string} why
+   * @param {string} remedy
+   * @param {{ one: string, many: string }} [noun]
+   */
+  refuseUnscannable(entries, why, remedy, noun) {
+    const message = this.unscannableMessage(entries, why, remedy, noun);
+    if (message !== null) throw new InvocationError(message);
+  }
+
+  /**
+   * The refusal message for a group of unscannable entries, or `null` when the group is empty.
+   *
+   * SPLIT FROM THE THROW so a refusal can be DEFERRED rather than raised where it is computed. The
+   * index route's two refusals are built before the sweep and raised after it, so the hits the walk
+   * found are printed first; every other caller throws immediately, as before.
+   *
+   * @param {import("./phi-scan.js").Unscannable[]} entries
+   * @param {string} why
+   * @param {string} remedy
+   * @param {{ one: string, many: string }} [noun]
+   * @returns {string | null}
+   */
+  unscannableMessage(
+    entries,
+    why,
+    remedy,
+    noun = { one: "entry is not a regular file", many: "entries are not regular files" },
+  ) {
+    if (entries.length === 0) return null;
+    const lines = entries.map((u) => `  - ${u.path} (${u.kind})`).join("\n");
+    const phrase = entries.length === 1 ? noun.one : noun.many;
+    return `refusing the scan: ${String(entries.length)} ${phrase}:\n${lines}\n${why} ${remedy}`;
+  }
+
+  // -------------------------------------------------------------------------
+  // Detection
+  // -------------------------------------------------------------------------
+
+  /**
+   * The format-agnostic FLOOR: a dashed Social Security Number shape, and an email at a domain the
+   * allow-list does not declare.
+   *
+   * BOTH BRANCHES CONSULT THE ALLOW-LIST, AND THE SSN BRANCH DOING SO IS A CORRECTION. A sibling's
+   * refuter measured that its dashed-SSN branch consulted nothing, so the footer's claim that the
+   * token allow-list "is the only remedy that reaches a clean run" was FALSE for exactly that
+   * branch: a developer meeting it had no remedy at all, the bypass having been closed. Declaring an
+   * identifier is a reviewed, committed act, which is the mechanism this gate is built on; a
+   * detector that cannot be answered is a detector people route around.
+   *
+   * The declared form is matched BOTH as written and with its separators removed, so one `ID` entry
+   * covers both renderings rather than requiring a repo to guess which one a fixture uses.
+   *
+   * THE MATCHED TOKEN IS A LOCAL, AND IT STAYS ONE. It decides whether the allow-list already
+   * declares this identifier and is then dropped: the hit that leaves this function carries a
+   * position and a rule, so there is no record for a later reporting path to print. See
+   * `reportHits` for why that is structural rather than a call-site decision.
+   *
+   * @param {string} path The reported LOCUS.
+   * @param {string} content
+   * @param {import("./phi-scan.js").AllowList} allow
+   * @param {import("./phi-scan.js").Hit[]} hits
+   */
+  scanCommonShapes(path, content, allow, hits) {
+    for (const m of content.matchAll(/\b\d{3}-\d{2}-\d{4}\b/g)) {
+      const value = m[0];
+      if (allow.ids.has(value.toUpperCase())) continue;
+      if (allow.ids.has(value.replace(/\D/g, ""))) continue;
+      hits.push({ path, segment: "(ssn)", reason: "dashed SSN pattern" });
+    }
+    for (const m of content.matchAll(/\b[A-Za-z0-9._%+-]+@([A-Za-z0-9.-]+\.[A-Za-z]{2,})\b/g)) {
+      const domain = (m[1] ?? "").toLowerCase();
+      if (!allow.emailDomains.has(domain)) {
+        hits.push({ path, segment: "(email)", reason: "email with non-test domain" });
+      }
+    }
+  }
+
+  /**
+   * Scan one target and RETURN THE BYTES IT OBSERVED. The bytes are returned rather than a boolean
+   * so `all` mode can ask whether the walk already read exactly what the index carries at this path.
+   *
+   * THE CALLER'S DETECTOR IS HANDED THE LOCUS, NOT THE TARGET PATH, so a hit from the union half
+   * cannot be reported against a bare path a developer would open and find clean. That used to be a
+   * sentence in a comment; here it is the only path a caller can reach.
+   *
+   * A DETECTOR THAT THROWS REFUSES THE SCAN rather than escaping to node's own exit code. A
+   * per-standard parser meeting input it cannot handle is an ordinary event, and the code node would
+   * pick is the one this contract reserves for HITS FOUND.
+   *
+   * 🛑 THE REFUSAL PRINTS THE DETECTOR'S OWN MESSAGE VERBATIM, AND THAT IS A DISCLOSED RESIDUAL
+   * RATHER THAN A CLOSED ONE. Everywhere else this engine prints only a repo-relative path and a
+   * token from a closed set, precisely because a diagnostic ABOUT a PHI leak is itself a PHI
+   * surface. A caller's error message is text this engine cannot vouch for, and a parser that
+   * interpolates the record it choked on will put that record on stderr, which is CI logs. It is not
+   * suppressed, because a refusal nobody can diagnose is its own defect, and it is not new: before
+   * this engine existed the same string reached the same place through node's default handler. What
+   * is new is that it is written down, here and on `DetectFn`. Throw a message that names the
+   * position, never the content.
+   *
+   * @param {import("./phi-scan.js").Target} target
+   * @param {import("./phi-scan.js").AllowList} allow
+   * @param {import("./phi-scan.js").Hit[]} hits
+   * @returns {Buffer}
+   */
+  scanTarget(target, allow, hits) {
+    let buf;
+    try {
+      buf = target.read();
+    } catch (err) {
+      throw new TargetReadError(
+        `could not read ${target.path}: ${err instanceof Error ? err.message : String(err)}`,
+        err !== null && typeof err === "object" && "code" in err ? String(err.code) : undefined,
+      );
+    }
+    const text = buf.toString("utf8");
+    // Scope is decided on the target's own path; only the REPORTED locus carries the origin label,
+    // so a labelled target is never a differently-scoped one.
+    const locus = target.origin === undefined ? target.path : `${target.path} (${target.origin})`;
+    // Recorded rather than re-derived from the locus string: the footer counts hits in bytes git
+    // carries, and reading that back off the text of a path is a parse of the engine's own prose.
+    if (target.origin !== undefined) this.indexLoci.add(locus);
+
+    this.scanCommonShapes(locus, text, allow, hits);
+
+    const detect = this.cfg.detect;
+    if (detect !== undefined) {
+      try {
+        detect({
+          path: locus,
+          text,
+          bytes: buf,
+          allow,
+          hit: (h) => {
+            // THE LOCUS AND THE RULE ARE TAKEN; ANY `value` A DETECTOR PASSES IS DROPPED HERE. A
+            // per-standard detector holds the record it parsed, so it is the caller most likely to
+            // hand over a token that is real PHI, and the engine is the side that can refuse to
+            // carry it. Dropping it at the boundary is what makes "no matched value reaches a
+            // report" a property of this engine rather than of every detector's discipline.
+            hits.push({ path: locus, segment: h.segment, reason: h.reason });
+          },
+        });
+      } catch (err) {
+        throw new InvocationError(
+          `the field detector threw on ${locus}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    return buf;
+  }
+
+  // -------------------------------------------------------------------------
+  // Reporting
+  // -------------------------------------------------------------------------
+
+  /**
+   * Print the hits.
+   *
+   * SPLIT FROM THE CLEAN LINE ON PURPOSE. Every refusal that can follow a read prints the hits
+   * FIRST, so a run that is both incomplete and carrying hits prints both. The clean line is printed
+   * only once every tier has passed, so it can never appear beside a refusal.
+   *
+   * IT NAMES A POSITION AND STOPS THERE: the repo-relative locus, the locator inside it, and the
+   * rule that fired. THE MATCHED TOKEN IS NEVER PRINTED. This is the one surface that would have
+   * the token in hand, which is exactly why the rule is stated on it: stderr is a CI log, a CI log
+   * is a transcript nobody retains deliberately, and a diagnostic ABOUT a PHI leak that quotes the
+   * leak is a second copy of it in a worse place (`phi-safety` P4, `observability` B1). Nothing is
+   * redacted here either, because the value never reaches this function: a seam a call site has to
+   * remember is a seam the next call site forgets.
+   *
+   * WHAT A DEVELOPER DOES WITH A HIT THEY CANNOT READ THE VALUE OF, since an error owes an action
+   * (`observability` B2): open the named path, find the shape the named rule describes, and either
+   * remove it or declare it in the allow-list the footer names if it is genuinely synthetic. The
+   * position is what locates the token; the token itself was never the remedy.
+   *
+   * THE FOOTER IS SCOPED TO WHAT THIS ENGINE KNOWS. It does not claim the allow-list reaches a clean
+   * run for every hit, because a per-repo detector supplied through `detect` may raise one without
+   * consulting the allow-list at all, and a sibling shipped exactly that claim and had it refuted.
+   * What is true, and all that is said: the two branches of the cross-cutting floor consult it, a
+   * whole-file bypass is recorded and then refused, and a detector that consults nothing has to be
+   * changed rather than argued with.
+   *
+   * @param {import("./phi-scan.js").Hit[]} hits
+   */
+  reportHits(hits) {
+    if (hits.length === 0) return;
+    /** @type {Map<string, import("./phi-scan.js").Hit[]>} */
+    const byPath = new Map();
+    for (const h of hits) {
+      const arr = byPath.get(h.path);
+      if (arr) arr.push(h);
+      else byPath.set(h.path, [h]);
+    }
+    for (const [path, group] of byPath) {
+      process.stderr.write(`[phi-scan] HIT: ${path}\n`);
+      for (const h of group) {
+        process.stderr.write(`  segment=${h.segment} (${h.reason})\n`);
+      }
+    }
+    // THE PER-ORIGIN FOOTER, AND IT IS A REMEDY RATHER THAN A STATISTIC (AC-14). A hit in bytes git
+    // carries is not answered by editing the file on disk: the identifier is in the index, so
+    // re-staging (or removing the blob) is part of the fix, and a reader counting `HIT:` lines has
+    // no way to tell how many of them are in that state.
+    const fromIndex = hits.filter((h) => this.indexLoci.has(h.path)).length;
+    if (fromIndex > 0) {
+      process.stderr.write(
+        `[phi-scan] ${String(fromIndex)} of those are in bytes git carries at that path, not in ` +
+          `the file on disk: fix the content and RE-STAGE it, or the next sweep reports the same ` +
+          `hit over a working tree that reads clean.\n`,
+      );
+    }
+    process.stderr.write(
+      `[phi-scan] ${String(hits.length)} hit(s) across ${String(byPath.size)} file(s). ` +
+        `The cross-cutting floor (SSN and email shapes) consults ${this.relAllowList()}, so a ` +
+        `genuinely synthetic identifier is declared there: a token-level, reviewed declaration. A ` +
+        `hit raised by this repo's own field detectors is answerable that way only if that detector ` +
+        `consults the allow-list; one that does not has to be changed rather than declared around. ` +
+        `A whole-file --allow-fixture bypass is recorded and then REFUSED, because a scan that ` +
+        `never opened a file has no clean verdict to give about it.\n`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // The run
+  // -------------------------------------------------------------------------
+
+  /**
+   * ===========================================================================================
+   * THE EXIT CONTRACT IS THE CALLER'S, NOT THIS FILE'S. The three codes come from `exitCodes`, and
+   * their meanings are:
+   *
+   *   clean   the scan ran, READ EVERY TARGET IT ENUMERATED, and found nothing. THE ONE
+   *           SUBTRACTION IS THE ENUMERATION TOCTOU WINDOW, and it is bounded rather than
+   *           described: an UNTRACKED file the walk itself listed, in `all` mode, whose read
+   *           failed with `ENOENT`, and which is still absent at the end of the run, is reported
+   *           SKIPPED and does not hold the clean code back. Git carries no bytes at such a path,
+   *           so nothing this repository holds went unread. Every other shape of the same failure
+   *           is in `refuse` below.
+   *   hits    this corpus contains something that looks like PHI. Nothing this engine RAISES ever
+   *           takes it. It is NOT exclusive, and the escapes are named rather than left to be
+   *           discovered: an allow-list or an override log that EXISTS but cannot be READ throws a
+   *           plain `Error`, which is rethrown, and the run takes node's own exit 1.
+   *   refuse  every state this engine RAISES in which the scan cannot account for something: a bad
+   *           argument, a MISSING allow-list, an unlogged bypass, a bypass naming a path this run
+   *           does not enumerate, an in-scope entry that is not a regular file, an unparseable
+   *           `git diff --cached` record, an index git cannot name or names empty, an in-scope index
+   *           entry that is not a regular blob, an in-scope path with no stage-0 blob (unmerged), a
+   *           target whose bytes cannot be read, a field detector that threw, a target enumerated
+   *           but never read, a target that was absent at read time and PRESENT AGAIN at the end
+   *           of the run, and (`all` mode) a SCAN ROOT THAT YIELDED NO FILE THAT WAS READ.
+   * ===========================================================================================
+   * THE PER-ROOT OBSERVATION RULE, `all` MODE ONLY. The completeness rule asks whether every
+   * target was read. It cannot ask whether a root produced a target at all, and a root that
+   * produces none is a sweep that is narrower than its own configuration says: a typo, a directory
+   * that moved or was never created, a root whose every file the read filter drops. ONE
+   * PRODUCTIVE ROOT MAKES THE WHOLE RUN LOOK PRODUCTIVE, which is why the question is asked per
+   * root and answered from the set of paths actually READ, and why the refusal names every starved
+   * root rather than the first.
+   *
+   * IT APPLIES TO A MISSING ROOT TOO, AND THAT DOES NOT CONTRADICT "A MISSING ROOT IS SKIPPED".
+   * The walk still skips it: it is not reported as an unscannable KIND and it does not crash the
+   * enumeration, which is what a missing root used to do. What it no longer does is contribute
+   * nothing in silence.
+   * ===========================================================================================
+   *
+   * @returns {number}
+   */
+  run() {
+    const { clean: EXIT_CLEAN, hits: EXIT_HITS, refuse: EXIT_REFUSE } = this.cfg.exitCodes;
+
+    /** @type {{ mode: "all" | "staged" | "paths", paths: string[], allowFixtures: string[] }} */
+    let args;
+    try {
+      args = this.parseArgs(this.cfg.argv);
+      this.validateAllowFixtures(args.allowFixtures);
+    } catch (err) {
+      if (err instanceof InvocationError) {
+        process.stderr.write(`[phi-scan] ${err.message}\n`);
+        return EXIT_REFUSE;
+      }
+      throw err;
+    }
+
+    const allowed = new Set(args.allowFixtures.map((p) => this.normalizePath(p)));
+
+    /** @type {import("./phi-scan.js").AllowList} */
+    let allow;
+    /** @type {import("./phi-scan.js").Target[]} */
+    let targets;
+    /** `all` mode's index, read once: it is the union half's whole enumeration. */
+    /** @type {Map<string, import("./phi-scan.js").IndexEntry> | null} */
+    let index = null;
+    /** The index route's refusals, raised AFTER the walk sweep so no hit is swallowed. */
+    /** @type {string[]} */
+    let indexRefusals = [];
+    try {
+      // `loadAllowList()` IS INSIDE THIS HANDLER, AND THAT PLACEMENT IS THE POINT. Outside it, a
+      // missing allow-list escaped as an uncaught throw and took node's exit 1, which this contract
+      // reserves for "hits found".
+      allow = this.loadAllowList();
+      if (args.mode === "staged") targets = this.buildTargetsForStaged();
+      else if (args.mode === "paths") targets = this.buildTargetsForPaths(args.paths);
+      else {
+        const built = this.buildTargetsForAll();
+        targets = built.targets;
+        index = built.index;
+        indexRefusals = built.indexRefusals;
+      }
+    } catch (err) {
+      if (err instanceof InvocationError) {
+        process.stderr.write(`[phi-scan] ${err.message}\n`);
+        return EXIT_REFUSE;
+      }
+      throw err;
+    }
+
+    // ENUMERATED: the set of paths this run declared it would read. Everything the read filters
+    // dropped upstream never became a target and is not in here, which is why the completeness rule
+    // does not fire on them. In `all` mode it is the walk's targets UNION the in-scope tracked paths.
+    const enumerated = new Set(targets.map((t) => t.path));
+    if (index !== null) for (const p of this.unionCandidatePaths(index)) enumerated.add(p);
+    // IN `all` MODE A BYPASS IS ITSELF AN ENUMERATION (AC-17). The run's declared scope is the whole
+    // corpus, so naming a path in `--allow-fixture` says "this run would have read that", and the
+    // honest tier for withdrawing it is the completeness rule rather than the unmatched one. It
+    // holds whatever the sweep happens to reach: a path the walk never listed and the index never
+    // carried is still refused HERE, naming it, instead of being reported as subtracting nothing.
+    if (args.mode === "all") for (const p of allowed) enumerated.add(p);
+
+    // TIER: A BYPASS MUST NAME A PATH THIS RUN ENUMERATES. Otherwise it subtracts nothing, and a
+    // flag that subtracts nothing lets a developer believe a file was acknowledged when the run
+    // never had it in scope. Compared by DIFFERENCE, and every offender is named. In `all` mode the
+    // line above makes this tier unreachable, deliberately: there it is the completeness rule's job.
+    //
+    // THIS TIER FIRES BEFORE ANY TARGET IS READ, so no hit exists for it to swallow. That is a
+    // narrower guarantee than the unread tier's and is stated as such rather than generalised.
+    const unmatched = [...allowed].filter((p) => !enumerated.has(p));
+    if (unmatched.length > 0) {
+      process.stderr.write(
+        `[phi-scan] --allow-fixture names ${String(unmatched.length)} path(s) this run does not ` +
+          `enumerate, so the flag subtracts nothing:\n${unmatched.map((p) => `  - ${p}`).join("\n")}\n` +
+          `Scan a corpus that contains the path, or drop the flag.\n`,
+      );
+      return EXIT_REFUSE;
+    }
+
+    /** @type {import("./phi-scan.js").Hit[]} */
+    const hits = [];
+    // READ: filled in only after a target's bytes have actually been through `scanTarget`. This is
+    // evidence of observation, never a plan to observe.
+    /** @type {Set<string>} */
+    const read = new Set();
+    /** Path -> object id of the bytes the walk actually read, so the union can skip a re-scan. */
+    /** @type {Map<string, string>} */
+    const readOids = new Map();
+    const objectHash = index === null ? null : this.gitObjectHash();
+    /**
+     * Paths the walk listed and that were GONE by read time. WHAT THIS MEANS IS DECIDED AFTER THE
+     * SWEEP, not here: see the resolution below for why the window is left open as long as the
+     * run lasts.
+     */
+    /** @type {Set<string>} */
+    const vanished = new Set();
+
+    /**
+     * @param {import("./phi-scan.js").Target[]} batch
+     * @returns {number | null} A refusal code, or `null` when the batch completed.
+     */
+    const sweep = (batch) => {
+      for (const t of batch) {
+        if (allowed.has(t.path)) continue;
+        let bytes;
+        try {
+          bytes = this.scanTarget(t, allow, hits);
+        } catch (err) {
+          // THE ENUMERATION TOCTOU WINDOW: the ONE read failure that is not settled here. It is
+          // recorded and judged after the sweep, because whether the path came back is part of
+          // the answer and this is the earliest the run could possibly know.
+          if (this.isVanishedUntracked(err, t, index)) {
+            vanished.add(t.path);
+            continue;
+          }
+          if (err instanceof InvocationError) {
+            // HITS FOUND SO FAR ARE PRINTED BEFORE THIS REFUSAL, DELIBERATELY, AND THIS IS A CHANGE
+            // FROM THE COPIED SCANNERS. A refuter measured the old ordering: a fatal partway through
+            // the sweep discarded every hit found before it, so a consumer saw a refusal with no
+            // indication that PHI had already been found. The refusal still wins the exit code, and
+            // the clean line is still unreachable from here, so nothing is reported as accounted for
+            // that is not; what changes is that a finding already made is not thrown away.
+            this.reportHits(hits);
+            process.stderr.write(`[phi-scan] ${err.message}\n`);
+            return EXIT_REFUSE;
+          }
+          throw err;
+        }
+        read.add(t.path);
+        if (objectHash !== null && t.origin === undefined) {
+          const oid = this.blobOid(objectHash, bytes);
+          if (oid !== null) readOids.set(t.path, oid);
+        }
+      }
+      return null;
+    };
+
+    const walkFailure = sweep(targets);
+    if (walkFailure !== null) return walkFailure;
+
+    // THE INDEX ROUTE'S OWN REFUSALS, RAISED HERE RATHER THAN WHERE THEY ARE COMPUTED (AC-15). An
+    // unmerged entry or a tracked link anywhere in the index refuses the whole sweep, and the walk
+    // may have found PHI under a root that yielded perfectly well. Refusing at enumeration time
+    // discarded those findings: measured, exit 2 with the refusal alone over a repository whose walk
+    // had five hits in hand. The exit code is still the refusal's, because an incomplete sweep is
+    // not a verdict whatever it found.
+    if (indexRefusals.length > 0) {
+      this.reportHits(hits);
+      for (const message of indexRefusals) process.stderr.write(`[phi-scan] ${message}\n`);
+      return EXIT_REFUSE;
+    }
+
+    // THE UNION. It runs AFTER the walk, not instead of it, and only over the paths the walk did not
+    // already read verbatim.
+    if (index !== null) {
+      const unionFailure = sweep(this.buildTargetsForGitIndex(index, readOids));
+      if (unionFailure !== null) return unionFailure;
+    }
+
+    // THE TOCTOU WINDOW IS RESOLVED AT THE END OF THE RUN, NOT AT THE MOMENT OF THE FAILURE, AND
+    // THE LATE ANSWER IS THE STRONGER ONE. A path that was absent when the sweep reached it and is
+    // present now was not a file being deleted: something wrote there while this run was looking
+    // away, and no verdict this run can give covers the bytes that lived at it in between. Asking
+    // immediately would answer within microseconds of the failure and miss almost all of that.
+    /** @type {string[]} */
+    const reappeared = [];
+    /** @type {Set<string>} */
+    const skipped = new Set();
+    for (const p of vanished) {
+      if (lstatOrNull(this.absolutePath(p)) === null) skipped.add(p);
+      else reappeared.push(p);
+    }
+
+    // THE COMPLETENESS RULE. A SET DIFFERENCE, NEVER A SIZE COMPARISON: a count counts the targets
+    // that DID get read, so `n read of n targets` is exactly the arithmetic that hides which ones did
+    // not. Names every offender.
+    //
+    // THE SKIPPED SET IS THE ONE SUBTRACTION, AND IT IS BOUNDED BY `isVanishedUntracked` RATHER
+    // THAN BY A JUDGEMENT CALL: `all` mode, the walk's own target, `ENOENT`, untracked, and still
+    // absent at the end of the run. Nothing git carries can enter it, so the rule keeps its whole
+    // meaning over the repository and gives up only what the filesystem took away mid-run.
+    const unread = [...enumerated].filter((p) => !read.has(p) && !skipped.has(p));
+
+    // THE PER-ROOT OBSERVATION RULE, `all` MODE ONLY. The completeness rule asks whether every
+    // target was read; it cannot ask whether a root produced a target in the first place, and a
+    // root that produces none is the silently-narrowed sweep: a typo, a directory that moved, a
+    // root whose every file the read filter drops. One productive root makes the whole run look
+    // productive, so the question is asked per root and answered from `read`.
+    const starved =
+      index === null ? [] : this.cfg.scanRoots.filter((root) => !this.anyReadUnder(root, read));
+
+    // Hits FIRST, so nothing below can swallow one.
+    this.reportHits(hits);
+
+    if (skipped.size > 0) {
+      process.stderr.write(
+        `[phi-scan] skipped ${String(skipped.size)} untracked file(s) gone between enumeration ` +
+          `and read:\n${[...skipped].map((p) => `  - ${p}`).join("\n")}\n` +
+          `Nothing this repository carries was left unread: git has no bytes at such a path. ` +
+          `Re-run the scan if the file was meant to stay.\n`,
+      );
+    }
+
+    if (reappeared.length > 0) {
+      process.stderr.write(
+        `[phi-scan] refusing the scan: ${String(reappeared.length)} target(s) were absent when ` +
+          `the sweep reached them and present again at the end of the run:\n` +
+          `${reappeared.map((p) => `  - ${p}`).join("\n")}\n` +
+          `A path that came back carried bytes this run never opened, so the scan has no verdict ` +
+          `about it. Re-run the scan on a tree nothing else is writing to.\n`,
+      );
+      return EXIT_REFUSE;
+    }
+
+    if (unread.length > 0) {
+      process.stderr.write(
+        `[phi-scan] refusing the scan: ${String(unread.length)} target(s) were enumerated and ` +
+          `never read:\n${unread.map((p) => `  - ${p}`).join("\n")}\n` +
+          `A scan that did not open a file has no clean verdict to give about it. If the file is ` +
+          `genuinely synthetic, declare its identifiers in ${this.relAllowList()} rather than ` +
+          `withdrawing the file from the scan.\n`,
+      );
+      return EXIT_REFUSE;
+    }
+
+    if (starved.length > 0) {
+      process.stderr.write(
+        `[phi-scan] refusing the sweep: the all-mode sweep observed no files under ` +
+          `${String(starved.length)} of its ${String(this.cfg.scanRoots.length)} scan roots ` +
+          `(${starved.join(", ")}).\n` +
+          `A root that contributes nothing leaves this sweep covering less than its own ` +
+          `configuration says, and no other tier can see that: the index route reads what git ` +
+          `carries and cannot vouch for a directory on disk. Point the root at a directory or ` +
+          `a file this run can read, widen the read filter that drops its contents, or drop the ` +
+          `root.\n`,
+      );
+      return EXIT_REFUSE;
+    }
+
+    if (hits.length > 0) return EXIT_HITS;
+    // THE CLEAN LINE CARRIES THE SUBTRACTION (AC-13). A reader watching stdout alone must not be
+    // able to take an unqualified OK from a sweep that skipped a file: the skip is on stderr, and
+    // stderr is where a CI log buries it. The unqualified line is byte-for-byte what it was when
+    // nothing was skipped, so a consumer matching it exactly still matches.
+    process.stdout.write(
+      skipped.size > 0
+        ? `[phi-scan] OK: no hits (${String(skipped.size)} untracked file(s) skipped, see stderr)\n`
+        : "[phi-scan] OK: no hits\n",
+    );
+    return EXIT_CLEAN;
+  }
+}
+
+/**
+ * `:<srcmode> <dstmode> <srcsha> <dstsha> <status>`: the info half of a `--raw -z` record.
+ *
+ * THE STATUS LETTER IS CAPTURED, not merely matched, because `U` (unmerged) is the one status whose
+ * refusal has to say something different: its destination mode is `000000`, and calling that "a git
+ * mode-000000 entry" beside a sentence about content git holds at the path is false twice over for a
+ * conflicted regular file.
+ */
+const RAW_RECORD = /^:(?:\d{6}) (\d{6}) [0-9a-f]+ [0-9a-f]+ ([A-Z])\d*$/;
+
+/**
+ * `lstatSync` that reports a missing path as `null` rather than throwing. LSTAT, not stat, so a
+ * symbolic link named as a scan root is seen as a link rather than as whatever it points at: the
+ * walk refuses such an entry everywhere else and a root must not be the one place it follows one.
+ *
+ * @param {string} path
+ * @returns {import("node:fs").Stats | null}
+ */
+function lstatOrNull(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Closed-set, engine-owned description of a `Stats` kind, for a scan root that is neither a
+ * directory nor a regular file. Same closed set as `direntKind`, off the same predicates.
+ *
+ * @param {import("node:fs").Stats} s
+ * @returns {string}
+ */
+function statsKind(s) {
+  if (s.isSymbolicLink()) return "a symbolic link";
+  if (s.isFIFO()) return "a FIFO";
+  if (s.isSocket()) return "a socket";
+  if (s.isBlockDevice()) return "a block device";
+  if (s.isCharacterDevice()) return "a character device";
+  return "not a regular file";
+}
+
+/**
+ * Closed-set, engine-owned description of a directory entry's kind. Nothing off the other side of a
+ * link is ever recorded.
+ *
+ * @param {import("node:fs").Dirent} e
+ * @returns {string}
+ */
+function direntKind(e) {
+  if (e.isSymbolicLink()) return "a symbolic link";
+  if (e.isFIFO()) return "a FIFO";
+  if (e.isSocket()) return "a socket";
+  if (e.isBlockDevice()) return "a block device";
+  if (e.isCharacterDevice()) return "a character device";
+  return "not a regular file";
+}
+
+/**
+ * Closed-set, engine-owned description of a git file mode.
+ *
+ * @param {string} mode
+ * @returns {string}
+ */
+function gitModeKind(mode) {
+  if (mode === "120000") return "a symbolic link";
+  if (mode === "160000") return "a gitlink (a nested repository)";
+  return `a git mode-${mode} entry`;
+}