@vibe-agent-toolkit/utils 0.2.0-rc.5 → 0.2.0-rc.7

package/dist/fs-utils.js

@@ -6,16 +6,88 @@
 // snapshots a builtin's named ESM exports at import time, so `vi.spyOn(fs,
 // 'existsSync')` cannot see a call made through a named binding — the spy
 // attaches and counts zero, which reads exactly like "this function performs no
-// I/O". `classifyFilenameCaseFrom` is guarded by precisely that assertion (it
-// must reach neither `readdir` nor this pair), so a "tidy-up" back to named
-// imports would silently disarm the guard. The async half below already uses the
-// default object for the same reason.
+// I/O". `pathSpellingFrom` and `realpathFrom` are guarded by precisely that
+// assertion (they must reach neither `readdir` nor this pair), so a "tidy-up"
+// back to named imports would silently disarm the guard. The async half below
+// already uses the default object for the same reason.
 import nodeFs from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { toForwardSlash, toNfc } from './path-core.js';
 import { safePath } from './path-utils.js';
+/**
+ * Turn a `readdir` rejection into the failure it actually is.
+ *
+ * ⚠️ **`isFilesystemAccessError` is deliberately NOT used here, and that is not
+ * an oversight.** It answers a different question — *"is this the environment's
+ * fault or a bug in our code?"* — and to answer it, it deliberately groups
+ * `ENOENT` together with `EACCES`. That grouping IS the conflation this function
+ * exists to undo, so reusing the predicate would reinstate the defect while
+ * looking like sharing.
+ *
+ * Anything that is not a recognised *absence* errno reads as unreadable,
+ * including an error carrying no errno at all: "I could not ask" is the answer
+ * that fabricates no finding, and an unrecognised failure has not established
+ * that the directory is missing.
+ *
+ * @param error - Whatever `fs.readdir` rejected with
+ * @returns The listing outcome that error stands for
+ */
+export function listingFailure(error) {
+    const code = typeof error === 'object' && error !== null && 'code' in error
+        ? error.code
+        : undefined;
+    // `ENOTDIR` is absence too: a path component that is a file is a directory
+    // that does not exist, which is exactly what the caller has to report.
+    if (code === 'ENOENT' || code === 'ENOTDIR')
+        return { outcome: 'absent' };
+    return { outcome: 'unreadable', code: typeof code === 'string' ? code : 'UNKNOWN' };
+}
+/**
+ * Refusal errnos that a *re-ask* can legitimately answer differently.
+ *
+ * ⚠️ **This set decides what may be MEMOIZED, which makes it a correctness
+ * boundary rather than a taxonomy.** `EACCES` (a mode bit) and `ELOOP` (a
+ * committed symlink cycle) are facts about the tree: they hold for the whole
+ * run, re-asking buys the same refusal, and caching them is exactly what
+ * {@link FsLookupCache} is for. Descriptor exhaustion is not a fact about the
+ * tree at all — it is a fact about this process at one instant — and a memo
+ * that keeps one un-verifies every path under that directory for the rest of
+ * the run, producing a burst of findings that a re-run does not reproduce.
+ *
+ * **Deliberately short, and everything unlisted is treated as stable.** The two
+ * mistakes are not symmetric: memoizing a transient refusal costs a burst of
+ * wrong answers *within one run*, while re-asking a stable one costs an
+ * unbounded number of syscalls on a `--x` directory that will refuse every one
+ * of them — and on a dead network mount, each of those blocks. `EAGAIN` is
+ * included because it is literally "try again"; `ETIMEDOUT`/`ESTALE`/`EBUSY`
+ * are not, because a re-ask against failing hardware or a hung mount is the
+ * storm this set exists to avoid.
+ */
+const TRANSIENT_LISTING_ERRNOS = new Set(['EMFILE', 'ENFILE', 'EAGAIN']);
+/**
+ * The clause a finding prints about a refusal {@link TRANSIENT_LISTING_ERRNOS}
+ * calls transient — owned here, beside the list, so it describes every member.
+ *
+ * 🪤 Both consumers of `AbsenceCause.transient` used to write their own: "`X`
+ * is descriptor exhaustion" — true of `EMFILE`/`ENFILE` and false of `EAGAIN`,
+ * which is a retryable shortage of some other resource. Two lanes each carrying
+ * the wording for a fact this module was made the single owner of is exactly
+ * how the lanes come to disagree with it; the errno list and the sentence about
+ * it move together only if they live together.
+ *
+ * @param code - The errno the listing was refused with
+ * @returns A clause naming the errno and what kind of condition it is, with no
+ *   trailing punctuation so a caller can continue the sentence
+ */
+export function transientRefusalClause(code) {
+    return `${code} is a transient shortage (a descriptor or other resource this process ran out of for a moment), not a permission`;
+}
+/** Whether this listing failed in a way a later ask could get past. */
+function isTransientRefusal(listing) {
+    return listing.outcome === 'unreadable' && TRANSIENT_LISTING_ERRNOS.has(listing.code);
+}
 /**
  * Per-run memo for the two filesystem lookups that validation repeats on values
  * which are constant for the whole run: `realpath` of roots, and `readdir` of the
@@ -38,15 +110,15 @@ import { safePath } from './path-utils.js';
  * @example
  * ```typescript
  * const fsCache = new FsLookupCache();          // one per run
- * const targets = links.map((link) => link.target);
- * const siblingNames = await fillSiblingNames(targets, fsCache);  // all the I/O, once
- * for (const target of targets) {
- *   classifyFilenameCaseFrom(siblingNames, target);               // pure — no syscall
+ * const requests = links.map((link) => ({ referrer: link.from, target: link.target }));
+ * const spellings = await fillPathSpellings(requests, fsCache);   // all the I/O, once
+ * for (const { referrer, target } of requests) {
+ *   pathSpellingFrom(spellings, referrer, target);                // pure — no syscall
  * }
  * ```
  */
 export class FsLookupCache {
-    /** Directory path → its entry names, or `null` when the directory is unreadable. */
+    /** Directory path → its entry names, or why the listing has none. */
     #listings = new Map();
     /** Path → its canonical path, falling back to the resolved path. */
     #realpaths = new Map();
@@ -55,6 +127,26 @@ export class FsLookupCache {
     /** Probe calls received, and how many of them reached the filesystem. */
     #probeCount = 0;
     #probeMisses = 0;
+    /** The listings turned into spelling indexes, built on first use. */
+    #spellingIndex;
+    /**
+     * The three-way spelling index over this cache's listings — one per run, for
+     * the same reason the listings themselves are.
+     *
+     * ⚠️ **It hangs off the cache rather than off a fill, and that is what makes
+     * the index pay.** A caller that judges its paths in one `fillPathSpellings`
+     * would be fine either way; a caller that judges them one at a time — which
+     * `validateLink` exists to serve — would otherwise re-index the same listing
+     * per path, and the cost would go straight back to
+     * O(paths × entries-in-that-directory) with the listing memo hiding the
+     * syscalls but not the work.
+     *
+     * Lazily built: a run that never judges a path allocates nothing.
+     */
+    get spellingIndex() {
+        this.#spellingIndex ??= new DirectorySpellingIndex(this);
+        return this.#spellingIndex;
+    }
     /**
      * Probe counters, for tests and `--debug` output.
      *
@@ -225,21 +317,63 @@ export class FsLookupCache {
         return safePath.join(await this.realpath(parent), path.basename(absolutePath));
     }
     /**
-     * Entry names of `dirPath`, or `null` when it cannot be read (missing directory,
-     * no permission). The unreadable answer is cached too — re-asking is the same
-     * failed syscall.
+     * What `dirPath` holds, or which of the two ways the question went unanswered.
+     *
+     * A *stable* failure is cached like a success: re-asking a directory whose
+     * mode bits refuse us, or whose path is a symlink cycle, is the same failed
+     * syscall. A **transient** one is not — see {@link TRANSIENT_LISTING_ERRNOS}.
+     *
+     * ⚠️ **The transient entry is dropped only once the promise has SETTLED, and
+     * that timing is the whole design.** Deleting the row up front, or refusing to
+     * store it, would make every concurrent caller start its own `readdir` —
+     * turning the descriptor shortage `EMFILE` reports into a descriptor storm,
+     * i.e. answering the failure with more of its cause. Storing the in-flight
+     * promise keeps the collapse-N-callers-to-one-syscall property intact through
+     * the failure; evicting after it settles is what stops the *next* wave from
+     * inheriting a verdict about a moment that has passed.
+     *
+     * The alternative considered and rejected was a bounded retry inside this
+     * method. It re-issues the syscall *while the shortage is still in progress*
+     * (which is the storm again, only self-inflicted), it needs a backoff timer to
+     * be worth anything, and it hides latency inside a call every caller reads as
+     * a memo lookup. Letting the next ask pay one syscall is the same cost the
+     * cache already bounds: one per directory, per wave.
      *
      * @param dirPath - Directory to list
-     * @returns Entry names, or `null` if the directory could not be read
+     * @returns The entry names, or why there are none to hand back
      */
     readdir(dirPath) {
         const cached = this.#listings.get(dirPath);
         if (cached !== undefined)
             return cached;
         // eslint-disable-next-line security/detect-non-literal-fs-filename -- caller-validated path
-        const pending = fs.readdir(dirPath).catch(() => null);
+        const listed = fs.readdir(dirPath);
+        const pending = listed
+            .then((names) => ({ outcome: 'listed', names }))
+            .catch(listingFailure);
         this.#listings.set(dirPath, pending);
-        return pending;
+        return this.#forgetIfTransient(dirPath, pending);
+    }
+    /**
+     * Hand back `pending`'s answer, dropping the memo row first when the answer is
+     * a *transient* refusal.
+     *
+     * The row is stored by the caller before this is reached, so the wave that
+     * provoked the shortage shares that one syscall; this only decides whether a
+     * LATER wave inherits its verdict. Identity-guarded because a later ask may
+     * already have installed a fresh row, and deleting that one would discard a
+     * listing somebody is awaiting.
+     *
+     * @param dirPath - Directory the row is filed under
+     * @param pending - The row itself, already stored
+     * @returns The same listing `pending` settles to
+     */
+    async #forgetIfTransient(dirPath, pending) {
+        const listing = await pending;
+        if (isTransientRefusal(listing) && this.#listings.get(dirPath) === pending) {
+            this.#listings.delete(dirPath);
+        }
+        return listing;
     }
 }
 /**
@@ -268,202 +402,346 @@ export async function copyDirectory(src, dest) {
     }
 }
 /**
- * List the parent directory of every path in `filePaths` — the only place I/O is
- * legal for this fact, and the pass that must run *before* any judging.
- *
- * ⚠️ **It takes FILE paths, not directory paths, deliberately.** It derives each
- * parent with `path.dirname` itself, so exactly one function in the system owns
- * the key derivation and a caller cannot construct a key that
- * {@link siblingNamesFrom} then misses. Do not "simplify" this to take
- * directories: that hands the derivation back to every call site and reopens the
- * silent-miss class this shape closes.
- *
- * Distinct parents are listed **concurrently**: the shape this replaced asked one
- * link at a time at judgement time, which serialised every `readdir` behind the
- * previous link's `await`. De-duplication is by parent, so N files in one
- * directory cost one listing; the listing itself goes through
- * {@link FsLookupCache.readdir}, which memoizes and shares in-flight promises
- * across fills.
+ * The refusal a `readdir` that was refused stands for — errno, directory and
+ * whether a re-ask could answer differently, derived ONCE beside the errno list.
  *
- * @param filePaths - File paths whose parent directories should be listed
- * @param fsCache - Per-run lookup cache (one instance per validation run)
- * @returns The filled table; empty input yields an empty table with no syscalls
+ * Shared by the spelling judge (through {@link absenceCauseFor}) and the crawl
+ * that defines the population (`file-crawler.ts`), so the two lanes cannot
+ * disagree about which refusals are transient.
+ *
+ * @param listing - A `readdir` outcome that was refused
+ * @param directory - The directory that was asked about
+ * @returns The refusal, with `directory` forward-slashed
  */
-export async function fillSiblingNames(filePaths, fsCache) {
-    const parentDirs = new Set();
-    for (const filePath of filePaths) {
-        parentDirs.add(path.dirname(filePath));
-    }
-    const table = new Map();
-    await Promise.all([...parentDirs].map(async (parentDir) => {
-        // Stored EXACTLY as `readdir` returned it — no Unicode folding, no copy.
-        //
-        // The fill used to fold every entry to NFC here (and `siblingNamesFrom`
-        // folded `expectedName` to match), which left the judge a pure `===` over
-        // pre-reconciled strings. It also destroyed the only evidence that could
-        // distinguish "these two spellings are the same bytes" from "these two
-        // spellings are equal only after folding" — and those are different facts
-        // on a byte-exact filesystem. Comparison semantics now live entirely in
-        // {@link classifyFilenameCase}, so the fill has no opinion to disagree
-        // with, and a hand-written row is raw `readdir` output rather than a form
-        // only the fill knew how to produce.
-        //
-        // The array is the cache's own and is deliberately not copied: the table
-        // type is `readonly string[]`, several tables may share one listing, and
-        // copying every listing per fill is exactly the per-run cost this pair
-        // exists to avoid. Treat it as immutable.
-        table.set(parentDir, await fsCache.readdir(parentDir));
-    }));
-    return table;
+export function directoryRefusalFor(listing, directory) {
+    return {
+        kind: 'directory_unreadable',
+        code: listing.code,
+        directory: toForwardSlash(directory),
+        transient: TRANSIENT_LISTING_ERRNOS.has(listing.code),
+    };
 }
 /**
- * Read the row for `filePath` out of an already-filled table. Pure.
- *
- * **A miss throws rather than degrading to `names: null`.** The fill set is
- * derived from exactly the paths the judge will be asked about, so a missing
- * parent is a programming error — a path judged that nobody filled. The `null`
- * fallback would answer it as "the directory is unreadable", which reports every
- * file under that directory as *missing*: a wrong answer wearing the shape of a
- * graceful degradation, and one no test of the verdict would catch.
+ * The cause for a listing that produced no index.
  *
- * Internal on purpose — {@link classifyFilenameCaseFrom} is the public judge.
+ * @param listing - A `readdir` outcome that is not `listed`
+ * @param directory - The directory that was asked about
+ * @returns Which absence this is, and — when it is a refusal — its detail
+ */
+function absenceCauseFor(listing, directory) {
+    if (listing.outcome === 'absent')
+        return { kind: 'no_such_entry' };
+    return directoryRefusalFor(listing, directory);
+}
+/**
+ * How much worse each spelling is than the one above it.
  *
- * @param table - Table filled by {@link fillSiblingNames}
- * @param filePath - Path being asked about
- * @returns The row: the expected basename plus the parent's entries
- * @throws If `table` holds no entry for the path's parent directory
+ * A path can be wrong in more than one way at once (`Café/Guide.md` against
+ * `café/guide.md`), and a report has to pick one verdict. The worst component
+ * wins: a case mismatch is broken on more machines than a normalization
+ * mismatch is, so reporting the milder one would understate what the author has
+ * to fix. The corrected path is carried either way, so nothing is lost.
  */
-export function siblingNamesFrom(table, filePath) {
-    const parentDir = path.dirname(filePath);
-    // `undefined` can only mean "absent key": a filled entry is an array or an
-    // explicit `null`, never `undefined`.
-    const names = table.get(parentDir);
-    if (names === undefined) {
-        throw new Error(`No sibling listing for directory "${parentDir}" (asked about "${filePath}"). ` +
-            `Fill it with fillSiblingNames() before judging.`);
-    }
-    // Raw on this side too. This lookup reads a row; it does not judge, and
-    // folding here would be judging — see {@link classifyFilenameCase}, which
-    // needs the spelling the caller actually asked for in order to tell a
-    // byte-exact hit from a fold-only one.
-    return { expectedName: path.basename(filePath), names };
+const SPELLING_RANK = {
+    exact: 0,
+    normalized: 1,
+    case_mismatch: 2,
+};
+/** Whether this build failed in a way a later build could get past. */
+function isTransientlyUnreadable(indexed) {
+    return (indexed.index === null &&
+        indexed.because.kind === 'directory_unreadable' &&
+        indexed.because.transient);
+}
+/** Record an entry under whichever of the three spellings it is first for. */
+function indexEntry(index, entry) {
+    if (!index.exact.has(entry))
+        index.exact.set(entry, entry);
+    const folded = toNfc(entry);
+    if (!index.nfc.has(folded))
+        index.nfc.set(folded, entry);
+    const lowered = folded.toLowerCase();
+    if (!index.folded.has(lowered))
+        index.folded.set(lowered, entry);
+}
+/** Ask one indexed listing for a name, under each rule in turn. */
+function lookupIn(index, name) {
+    const exact = index.exact.get(name);
+    if (exact !== undefined)
+        return { match: 'exact', actualName: exact };
+    const folded = toNfc(name);
+    const normalized = index.nfc.get(folded);
+    if (normalized !== undefined)
+        return { match: 'normalized', actualName: normalized };
+    const insensitive = index.folded.get(folded.toLowerCase());
+    return insensitive === undefined
+        ? { match: 'absent', because: { kind: 'no_such_entry' } }
+        : { match: 'case_mismatch', actualName: insensitive };
 }
 /**
- * Decide whether `row.expectedName` names a real entry, and how faithfully.
- *
- * Pure: no filesystem, no cache, no path parsing — it reads only the columns it
- * is handed, which is what makes hand-written listings a legitimate test input.
- * Both columns arrive **raw**, exactly as `readdir` and `path.basename` produced
- * them; this function owns every comparison rule, so nothing upstream can
- * disagree with it about what "the same filename" means.
- *
- * **Three passes, strictly in this order, first match wins — the order IS the
- * contract**, because each pass accepts a strictly weaker notion of sameness and
- * a weaker pass reached first would mislabel a file that is genuinely there:
- *
- * 1. **byte-exact** `entry === expectedName`. On a case-insensitive filesystem a
- *    listing can hold both `readme.md` and `README.md`, in either order; asking
- *    for `README.md` must report it present regardless of which one `readdir`
- *    happened to return first. Same argument, one form weaker, for pass 2.
- * 2. **NFC-folded** `toNfc(entry) === toNfc(expectedName)`. The two columns are
- *    different kinds of value and routinely disagree about one file: `entry` is
- *    an *enumerated* path (`readdir` hands back whatever is on disk, commonly
- *    decomposed) while `expectedName` is a path *derived from markdown link
- *    text* (composed, as an editor writes it). `é` has two encodings (NFC
- *    `U+00E9` vs NFD `e` + `U+0301`) that are `!==` and that case-folding does
- *    not reconcile, so without this pass an accented file that plainly exists
- *    was reported flatly *missing* — not even a case-mismatch hint, since that
- *    needs pass 3 to match. This is one of three sites on that seam; the class
- *    is collected in `docs/architecture/resource-scanning-and-caching.md` §3.6
- *    (ledger entry D7).
- * 3. **case-insensitive, on the folded forms.** Folding first is required, not
- *    tidy: `toLowerCase()` does not reconcile NFC against NFD, so a name that
- *    differs in *both* case and normalization falls out as `absent` and the
- *    author loses the suggestion.
- *
- * ⚠️ **Passes 1 and 2 are not the same verdict, and collapsing them is a
- * silently-wrong answer rather than a lost nicety.** The fix for D7 originally
- * folded both sides *before* comparing, which repaired the false "missing" on
- * macOS/APFS — and over-corrected into the opposite error on Linux/ext4, where
- * the filesystem is byte-exact: a markdown link spelling a filename NFD while
- * disk holds NFC genuinely 404s there, and the folded judge answered "exists,
- * exact match, no issue". `match` is what keeps both facts: the link resolves
- * (so it must not be reported broken), *and* it resolves only by folding (so a
- * caller can warn). {@link classifyFilenameCaseFrom}'s consumer in
- * `@vibe-agent-toolkit/resources` turns `'normalized'` into
- * `LINK_NORMALIZATION_MISMATCH`. The prohibition that bounds every fold reached
- * from here — it yields a comparison key, never a path to open — is stated once
- * at {@link toNfc}, which is also where the reason it is not folded into
- * `safePath.resolve` lives.
- *
- * **Folding is deferred to the miss path, and that is a real saving.** Pass 1
- * calls `toNfc` zero times, so a corpus whose links all resolve byte-exactly —
- * every pure-ASCII corpus, i.e. nearly all of them — normalizes nothing at all.
- * The older shape folded every entry of every directory in the fill,
- * unconditionally.
- *
- * @param row - The listing row, read out of a filled table by {@link siblingNamesFrom}
- * @returns The verdict: whether it resolves, the entry really on disk, and which pass matched
+ * Every directory a run asks about, listed once and indexed once.
+ *
+ * ⚠️ **It owns the listings and never hands one out.** That is deliberate: the
+ * defect it replaced was a per-path scan over a shared raw array, and an
+ * implementation that cannot reach the array cannot scan it. The only ways to
+ * ask a question are {@link DirectorySpellingIndex.lookup} and
+ * {@link DirectorySpellingIndex.judgePath}, both `Map.get` over an index built
+ * at most once per directory — {@link DirectorySpellingIndex.directoriesIndexed}
+ * and {@link DirectorySpellingIndex.entriesIndexed} are what a test counts to
+ * prove the work did not go back to being per-path.
+ *
+ * **Instance-per-run, like the {@link FsLookupCache} it borrows** — it holds a
+ * snapshot of directory contents and must not outlive the run that took it.
  */
-export function classifyFilenameCase(row) {
-    const { expectedName, names } = row;
-    if (names === null) {
-        // Parent directory doesn't exist (or can't be read).
-        return { exists: false, actualName: null, match: 'absent' };
+export class DirectorySpellingIndex {
+    #fsCache;
+    /** Directory → its index, or why it has none. */
+    #indexes = new Map();
+    #directoriesIndexed = 0;
+    #entriesIndexed = 0;
+    constructor(fsCache) {
+        this.#fsCache = fsCache;
     }
-    // Pass 1 — byte-exact.
-    // Tested against `undefined` rather than for truthiness: `readdir` never
-    // yields an empty entry name, but hand-written rows are this function's
-    // advertised input now that it is pure, and `''` is falsy — it would fall
-    // through to a later pass and come back as `actualName: ''` with the wrong
-    // `match`.
-    const exactMatch = names.find(entry => entry === expectedName);
-    if (exactMatch !== undefined) {
-        return { exists: true, actualName: exactMatch, match: 'exact' };
+    /**
+     * How many times a listing was turned into an index.
+     *
+     * Counted at the BUILD, not as `#indexes.size`: the size is the number of
+     * distinct directories asked about, which stays put even if every lookup
+     * rebuilds — the exact regression this number exists to catch.
+     */
+    get directoriesIndexed() {
+        return this.#directoriesIndexed;
     }
-    // Pass 2 — equal only after NFC folding. Reached only when pass 1 missed, so
-    // an all-ASCII corpus never pays for it.
-    const foldedExpected = toNfc(expectedName);
-    const normalizedMatch = names.find(entry => toNfc(entry) === foldedExpected);
-    if (normalizedMatch !== undefined) {
-        return { exists: true, actualName: normalizedMatch, match: 'normalized' };
+    /** How many directory entries were examined, across every index built. */
+    get entriesIndexed() {
+        return this.#entriesIndexed;
     }
-    // Pass 3 — case-insensitive over the folded forms.
-    const loweredExpected = foldedExpected.toLowerCase();
-    const caseInsensitiveMatch = names.find(entry => toNfc(entry).toLowerCase() === loweredExpected);
-    return caseInsensitiveMatch === undefined
-        ? { exists: false, actualName: null, match: 'absent' }
-        : { exists: false, actualName: caseInsensitiveMatch, match: 'case_mismatch' };
+    /** Every directory that has been listed, for never-reached-above-the-root pins. */
+    get indexedDirectories() {
+        return [...this.#indexes.keys()];
+    }
+    /**
+     * Ask what `directory` really calls `name`.
+     *
+     * @param directory - Absolute path of the directory to ask about
+     * @param name - One path component, spelled as the caller asked for it
+     * @returns Which rule matched and the entry's own spelling, or `absent`
+     */
+    async lookup(directory, name) {
+        const indexed = await this.#indexFor(directory);
+        return indexed.index === null
+            ? { match: 'absent', because: indexed.because }
+            : lookupIn(indexed.index, name);
+    }
+    /**
+     * Judge every component of `resolvedPath`, from `root` down.
+     *
+     * Each component is judged against the directory that actually holds it —
+     * which is the corrected spelling of the previous component, not the
+     * asked-for one, so a wrong directory name does not hide a wrong filename
+     * beneath it.
+     *
+     * ⛔ **It never looks above `root`.** The walk starts there and only
+     * descends, and a path that does not live under `root` is refused outright
+     * rather than walked from somewhere else: a verdict that depends on a
+     * directory above the root is a verdict that changes when the tree is moved.
+     * Pick a root the caller has already enumerated, and every component below it
+     * is one the *reference text* contributed — exactly the ones worth judging.
+     *
+     * @param root - Absolute path of a directory known to exist, and an ancestor
+     *   of `resolvedPath` (or `resolvedPath` itself)
+     * @param resolvedPath - Absolute path to judge
+     * @returns The worst spelling defect on the path, plus both spellings of it
+     * @throws If `resolvedPath` does not live at or under `root`
+     */
+    async judgePath(root, resolvedPath) {
+        // `safePath.relative` already answers in forward slashes; saying so out loud
+        // is what makes both the traversal test and the split below safe on Windows.
+        const askedPath = toForwardSlash(safePath.relative(root, resolvedPath));
+        // The root itself: the caller enumerated it to get here, so it resolves,
+        // and there is no component to judge. Asking would mean listing its PARENT.
+        if (askedPath === '')
+            return { match: 'exact', askedPath, actualPath: askedPath };
+        // Tested as a whole SEGMENT rather than as a prefix: `startsWith('..')`
+        // would refuse a real directory named `..cache`.
+        const segments = toForwardSlash(askedPath).split('/');
+        if (segments[0] === '..') {
+            throw new Error(`Path spelling asked about "${askedPath}", which is above the walk root "${root}". ` +
+                `A verdict that depends on a directory above the root changes when the tree moves.`);
+        }
+        return await this.#walk(root, askedPath, segments);
+    }
+    /** The component-by-component descent behind {@link judgePath}. */
+    async #walk(root, askedPath, segments) {
+        const actual = [];
+        let worst = 'exact';
+        let directory = root;
+        for (const segment of segments) {
+            // Sequential by necessity: which directory holds the next component
+            // depends on how this one is really spelled. Every listing is memoized,
+            // so a run pays per DIRECTORY, not per path and not per component.
+            const found = await this.lookup(directory, segment);
+            if (found.match === 'absent') {
+                // The cause travels with the verdict rather than being re-derived: by
+                // the time a caller reports this, the directory that refused is
+                // several frames gone and nothing else can tell the two absences
+                // apart. So does what was learned ABOVE it — see `verified`.
+                return {
+                    match: 'absent',
+                    askedPath,
+                    actualPath: '',
+                    because: found.because,
+                    verified: {
+                        match: worst,
+                        askedPath: segments.slice(0, actual.length).join('/'),
+                        actualPath: actual.join('/'),
+                    },
+                };
+            }
+            if (SPELLING_RANK[found.match] > SPELLING_RANK[worst])
+                worst = found.match;
+            actual.push(found.actualName);
+            directory = safePath.join(directory, found.actualName);
+        }
+        return { match: worst, askedPath, actualPath: actual.join('/') };
+    }
+    /**
+     * The index for one directory, built at most once.
+     *
+     * The promise — not the resolved value — is memoized, so two components
+     * resolving into the same directory concurrently share one listing and one
+     * build rather than racing to do both twice.
+     *
+     * ⚠️ **A transient refusal is dropped here as well as in the listing memo
+     * underneath, and both evictions are load-bearing.** This map caches the
+     * built INDEX, so evicting only `FsLookupCache`'s listing would leave the
+     * moment-in-time refusal pinned at precisely the layer every consumer reads —
+     * a fix that is real and invisible. Same settle-then-evict timing, and the
+     * same identity guard, for the same reason: see {@link FsLookupCache.readdir}.
+     */
+    async #indexFor(directory) {
+        const existing = this.#indexes.get(directory);
+        if (existing !== undefined)
+            return await existing;
+        const building = this.#build(directory);
+        this.#indexes.set(directory, building);
+        const indexed = await building;
+        if (isTransientlyUnreadable(indexed) && this.#indexes.get(directory) === building) {
+            this.#indexes.delete(directory);
+        }
+        return indexed;
+    }
+    /** List one directory and index every entry it holds. */
+    async #build(directory) {
+        this.#directoriesIndexed += 1;
+        const listing = await this.#fsCache.readdir(directory);
+        if (listing.outcome !== 'listed') {
+            // Two failures, two answers: a directory that is not there is absence,
+            // and a directory that refused to be listed is a question nobody got to
+            // ask. Mapping both to `no_such_entry` here is what used to report a
+            // link that opens as a missing file.
+            return { index: null, because: absenceCauseFor(listing, directory) };
+        }
+        const index = { exact: new Map(), nfc: new Map(), folded: new Map() };
+        for (const name of listing.names) {
+            indexEntry(index, name);
+            this.#entriesIndexed += 1;
+        }
+        return { index };
+    }
+}
+/**
+ * Where to start judging `target`, given that `referrer`'s own path came off
+ * the filesystem rather than out of a document.
+ *
+ * ⚠️ **The root is the deepest directory the two paths share, and that choice
+ * is doing real work in both directions.** Everything *above* it was enumerated
+ * (so judging it would compare disk against disk, and on a macOS crawl that
+ * routinely means reporting an NFD component nobody wrote); everything *below*
+ * it is what the reference text contributed, and is precisely what a
+ * misspelling can hide in.
+ *
+ * Falls back to the target's own parent — i.e. judging the basename alone, the
+ * weakest useful answer — when the two paths share no meaningful ancestor
+ * (different drives on Windows, or a relative path).
+ *
+ * @param referrer - Path of the file holding the reference
+ * @param target - Absolute path the reference resolved to
+ * @returns The directory to walk down from
+ */
+export function spellingWalkRoot(referrer, target) {
+    const referrerDir = toForwardSlash(path.dirname(referrer)).split('/');
+    const targetDir = toForwardSlash(path.dirname(target)).split('/');
+    let shared = 0;
+    while (shared < referrerDir.length &&
+        shared < targetDir.length &&
+        referrerDir[shared] === targetDir[shared]) {
+        shared += 1;
+    }
+    // `< 2` rather than `=== 0`: a single shared segment is the filesystem root
+    // (`''` on POSIX) or the drive (`C:` on Windows), and walking down from there
+    // would list directories no caller owns.
+    return shared < 2 ? path.dirname(target) : targetDir.slice(0, shared).join('/');
 }
 /**
- * Judge `filePath` against an already-filled {@link SiblingNamesTable}.
- *
- * This is the judging half of the two-pass shape: {@link fillSiblingNames} does
- * every listing first, then this runs over as many paths as you like with no
- * interleaved I/O.
- *
- * **The signature is not what keeps this free of I/O — a test is.** `fs-utils.ts`
- * imports `node:fs` and `node:fs/promises` at module scope, so this function's
- * module reaches the filesystem freely; taking no {@link FsLookupCache} and no
- * `fs` parameter constrains a future edit not at all, which could call
- * `nodeFs.statSync` on the next line and still typecheck. What actually holds the
- * property is `packages/utils/test/fs-utils.test.ts` →
- * *"judges from a filled table, reaching neither readdir nor the sync stat pair"*:
- * it spies `fs.readdir`, `nodeFs.existsSync` and `nodeFs.statSync` on the very
- * default objects this module imports, drives a positive control through each so
- * a zero cannot mean "the instrument never attached", and asserts the counts do
- * not move across judgement. If a future check needs another fact about the parent
- * directory, widen the *table* rather than reaching for `fs` here — and expect
- * that test, not this signature, to be what stops you.
- *
- * @param table - Table filled by {@link fillSiblingNames}
- * @param filePath - Absolute path to judge
- * @returns The verdict — see {@link FilenameCaseVerdict}
- * @throws If `table` holds no entry for the path's parent directory — see
- *   {@link siblingNamesFrom}
+ * The table key — derived in exactly one place so a filler and a judge cannot
+ * construct different ones for the same question.
  */
-export function classifyFilenameCaseFrom(table, filePath) {
-    return classifyFilenameCase(siblingNamesFrom(table, filePath));
+function spellingKey(referrer, target) {
+    return `${spellingWalkRoot(referrer, target)}\0${target}`;
+}
+/**
+ * Judge every request's whole path — the only place I/O is legal for this fact,
+ * and the pass that must run *before* any judging.
+ *
+ * Distinct (root, target) pairs are walked **concurrently**, and every listing
+ * they need goes through the cache's own {@link DirectorySpellingIndex}
+ * ({@link FsLookupCache.spellingIndex}), so a directory holding N referenced
+ * targets is listed once, not N times, a directory on the path to M of them is
+ * listed once, not M times, and a caller that fills once per path still indexes
+ * each directory only once for the whole run.
+ *
+ * @param requests - Targets to judge, each paired with its referring file
+ * @param fsCache - Per-run lookup cache (one instance per validation run)
+ * @returns The filled table; empty input yields an empty table with no syscalls
+ */
+export async function fillPathSpellings(requests, fsCache) {
+    const distinct = new Map();
+    for (const request of requests) {
+        const key = spellingKey(request.referrer, request.target);
+        if (!distinct.has(key))
+            distinct.set(key, request);
+    }
+    const index = fsCache.spellingIndex;
+    const table = new Map();
+    await Promise.all([...distinct].map(async ([key, request]) => {
+        const root = spellingWalkRoot(request.referrer, request.target);
+        table.set(key, await index.judgePath(root, request.target));
+    }));
+    return table;
+}
+/**
+ * Read the verdict for one reference out of an already-filled table. Pure.
+ *
+ * **A miss throws rather than degrading to `absent`.** The fill set is derived
+ * from exactly the references the judge will be asked about, so a missing row
+ * is a programming error — a path judged that nobody filled. Degrading would
+ * report every such reference as *missing*: a wrong answer wearing the shape of
+ * a graceful degradation, and one no test of the verdict would catch.
+ *
+ * @param table - Table filled by {@link fillPathSpellings}
+ * @param referrer - The file holding the reference
+ * @param target - The absolute path it resolved to
+ * @returns How faithfully the whole path is spelled
+ * @throws If `table` holds no row for this (referrer, target) pair
+ */
+export function pathSpellingFrom(table, referrer, target) {
+    const spelling = table.get(spellingKey(referrer, target));
+    if (spelling === undefined) {
+        throw new Error(`No path spelling for "${target}" (referenced from "${referrer}"). ` +
+            `Fill it with fillPathSpellings() before judging.`);
+    }
+    return spelling;
 }
 /**
  * Canonicalize every path in `paths` — the only place I/O is legal for this
@@ -472,9 +750,9 @@ export function classifyFilenameCaseFrom(table, filePath) {
  * ⚠️ **Rows are keyed by the input path string exactly as given** — not a
  * dirname, not a re-resolved form. {@link realpathFrom} looks that same string
  * up, so any normalization applied here and not there is a silent miss (a loud
- * one, in fact: the judge throws). Contrast {@link fillSiblingNames}, which keys
- * by `path.dirname` *because* many files share one listing; here the answer is
- * per path, so the path is the key.
+ * one, in fact: the judge throws). Contrast {@link fillPathSpellings}, which
+ * keys by (walk root, target) *because* many references share one walk; here the
+ * answer is per path, so the path is the key.
  *
  * Distinct paths are canonicalized **concurrently**: the shape this replaces
  * asked one path at a time at judgement time, which serialised every `realpath`
@@ -505,13 +783,11 @@ export async function fillRealpaths(paths, fsCache) {
  * column exists to remove: a regression no test of the verdict could catch,
  * because the verdict would be identical, only slower.
  *
- * Public, unlike {@link siblingNamesFrom}: a sibling-names row is not yet an
- * answer (it still needs {@link classifyFilenameCase}), whereas here the row IS
- * the answer — so this lookup is itself the judge for this column, and there is
- * nothing left to keep internal.
+ * The row IS the answer here — nothing further has to judge it — so this lookup
+ * is itself the judge for this column.
  *
  * **The signature is not what keeps this free of I/O — a test is.** As with
- * {@link classifyFilenameCaseFrom}, this module imports `node:fs` and
+ * {@link pathSpellingFrom}, this module imports `node:fs` and
  * `node:fs/promises` at module scope, so withholding a {@link FsLookupCache} from
  * the parameter list prevents nothing. The guard is
  * `packages/utils/test/fs-utils.test.ts` → *"judges from a filled table, reaching