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

package/dist/fs-utils.d.ts

@@ -22,6 +22,77 @@ export interface PathProbe {
      */
     readonly isDirectory: boolean | null;
 }
+/**
+ * What one `readdir` answered: the entries, or which of the two ways it failed.
+ *
+ * ⛔ **The two failures are NOT one answer, and collapsing them is a wrong
+ * verdict rather than a lost nicety.** This used to be `string[] | null`, where
+ * one `null` meant both *"there is no such directory"* and *"I was refused"*.
+ * Only the first is absence. A POSIX `--x` directory (mode `0111`) is
+ * *traversable* — every file below it opens exactly as written — while
+ * `readdir` returns `EACCES`; a judge that walks a path component by component
+ * then declared a link that opens fine to be a missing file, and said so with
+ * the confident wrong diagnosis *"File not found"*. The condition to report is
+ * that a **directory could not be listed**, which is the caller's to decide, and
+ * it cannot decide what this type will not carry.
+ *
+ * The sibling proof that the distinction is real: `resources/src/okf/discovery.ts`
+ * already reports an unlistable subdirectory as its own `OKF_SUBDIRECTORY_UNREADABLE`
+ * finding rather than as a missing one.
+ */
+export type DirectoryListing = 
+/** The directory was read. `names` is exactly what `readdir` handed back. */
+{
+    readonly outcome: 'listed';
+    readonly names: string[];
+}
+/** There is no such directory (`ENOENT`), or a path component is a file (`ENOTDIR`). */
+ | {
+    readonly outcome: 'absent';
+}
+/**
+ * The directory may well hold the entry asked about; the OS refused the
+ * question. `code` is the errno, for a caller that reports the reason.
+ */
+ | {
+    readonly outcome: 'unreadable';
+    readonly code: string;
+};
+/**
+ * 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 declare function listingFailure(error: unknown): DirectoryListing;
+/**
+ * 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 declare function transientRefusalClause(code: string): string;
 /** How many probes a {@link FsLookupCache} answered, and how many cost syscalls. */
 export interface PathProbeStats {
     /** Probe calls received. */
@@ -51,15 +122,30 @@ export interface PathProbeStats {
  * @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 declare class FsLookupCache {
     #private;
+    /**
+     * 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(): DirectorySpellingIndex;
     /**
      * Probe counters, for tests and `--debug` output.
      *
@@ -167,14 +253,32 @@ export declare class FsLookupCache {
      */
     realpath(targetPath: string): Promise<string>;
     /**
-     * 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: string): Promise<string[] | null>;
+    readdir(dirPath: string): Promise<DirectoryListing>;
 }
 /**
  * Recursively copy a directory
@@ -187,215 +291,320 @@ export declare class FsLookupCache {
  */
 export declare function copyDirectory(src: string, dest: string): Promise<void>;
 /**
- * The one fact on disk that a case-sensitivity question turns on: what the
- * parent directory actually contains, paired with the name being asked about.
- *
- * A row, not an answer — {@link classifyFilenameCase} turns it into a verdict.
- * Splitting the two is what lets the verdict be tested against listings that no
- * filesystem will hand you on demand, entry ORDER in particular.
+ * Which spelling rule matched a name, and therefore how faithfully the
+ * asked-for spelling matches disk.
+ *
+ * The three that are not `absent` are ordered from most to least faithful, and
+ * every consumer that reports to a human needs the distinction: only `exact`
+ * opens on every filesystem.
+ *
+ * **The three rules are tried strictly in the order below, first match wins —
+ * the order IS the contract**, because each accepts a strictly weaker notion of
+ * sameness and a weaker rule reached first would mislabel a file that is
+ * genuinely there. {@link DirectorySpellingIndex} implements them as three
+ * lookups over one pre-built index (`indexEntry`/`lookupIn`); it is the only
+ * judge, so nothing upstream can disagree with it about what "the same
+ * filename" means.
+ *
+ * ⚠️ **`exact` and `normalized` are not the same verdict, and collapsing them
+ * is a silently-wrong answer rather than a lost nicety.** Folding both sides
+ * *before* comparing repairs the false "missing" on macOS/APFS — `é` has two
+ * encodings (NFC `U+00E9` vs NFD `e` + `U+0301`) that are `!==` and that
+ * case-folding does not reconcile, so an accented file that plainly exists was
+ * once reported flatly *missing* — and over-corrects 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 a folded judge
+ * answers "exists, exact match, no issue". Keeping both facts is the point —
+ * the link resolves (so it must not be reported broken), *and* it resolves only
+ * by folding (so a caller can warn). `@vibe-agent-toolkit/resources` turns
+ * `'normalized'` into `LINK_NORMALIZATION_MISMATCH`. 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).
+ *
+ * ⚠️ **Case-folding is applied to the NFC-folded form, not to raw bytes.**
+ * `toLowerCase()` does not reconcile NFC against NFD, so a name that differs in
+ * *both* case and normalization would fall out as `absent` and the author would
+ * lose the suggestion. The prohibition that bounds every fold — 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.
  */
-export interface SiblingNames {
+export type FilenameMatch = 
+/** The asked-for name and a directory entry are the same bytes. Opens anywhere. */
+'exact'
+/**
+ * They are different bytes that are equal after Unicode NFC folding — the same
+ * visible filename in two normalization forms. Opens on macOS/APFS and
+ * Windows; **does not open on a byte-exact filesystem** (Linux/ext4, i.e. CI
+ * and most deploy targets), where the two forms simply name different files.
+ */
+ | 'normalized'
+/** They differ by letter case (after folding). Opens only on a case-insensitive filesystem. */
+ | 'case_mismatch'
+/** Nothing in the listing matches, or the directory could not be read. */
+ | 'absent';
+/**
+ * Why a name is not in a listing — the two are a different fact about the tree
+ * and a different thing to tell a human.
+ *
+ * ⛔ **Kept off {@link FilenameMatch} deliberately.** That union names the
+ * *spelling rules* a name can match under, and "the directory refused to be
+ * listed" is not a spelling rule — it is the reason no rule could be tried. It
+ * carries no rank in {@link SPELLING_RANK} and no corrected spelling, and
+ * folding it in as a fifth verdict would silently un-exhaust every switch over
+ * a spelling (the OKF cross-link lane has one) without moving what those
+ * switches actually decide.
+ */
+export type AbsenceCause = 
+/** The directory was listed and holds nothing matching, under any rule. */
+{
+    readonly kind: 'no_such_entry';
+}
+/**
+ * A directory on the path could not be listed, so the question was never
+ * asked. ⚠️ **This is not evidence of absence** — a `--x` directory is
+ * traversable, so the target may well open. A caller reporting it as a
+ * missing file is asserting something it has not learned.
+ *
+ * 🔑 **It carries WHICH directory and WHICH errno because the alternative was
+ * a remedy nobody can aim.** Collapsing every refusal to the bare word left
+ * each consumer able to say only "a directory on that path refused" — useless
+ * to a reader staring at a five-segment path, and identical whether the cause
+ * was a mode bit they can fix or a descriptor shortage they should just
+ * re-run past.
+ */
+ | {
+    readonly kind: 'directory_unreadable';
+    /** The errno `readdir` refused with: `EACCES`, `EMFILE`, `ENFILE`, `ELOOP`, … */
+    readonly code: string;
     /**
-     * Basename being asked about, i.e. `path.basename(filePath)` — **verbatim, in
-     * whatever Unicode normalization form the path carries**. Nothing folds it on
-     * the way in; {@link classifyFilenameCase} owns every comparison rule there is.
+     * The directory that refused — **absolute**, forward-slashed.
+     *
+     * 🔒 **Sanitize before quoting it to a human.** An absolute path in a
+     * finding is the developer's `$HOME` in every CI log, and both consumers
+     * of this field re-express it against a root they own
+     * (`issueLocation(dir, projectRoot)` in the link lane,
+     * `safePath.relative(bundleRoot, dir)` in the OKF lane) before it reaches
+     * a message. It is absolute *here* because those two roots differ and the
+     * walk root this was found under is neither of them.
      */
-    readonly expectedName: string;
+    readonly directory: string;
     /**
-     * The parent directory's entry names **exactly as `readdir` returned them**,
-     * or `null` when it could not be read. Raw, unfolded bytes — which is what
-     * makes "this link only resolves after normalization" a question the judge can
-     * still answer. See {@link classifyFilenameCase}.
+     * Whether re-running could get a different answer — see
+     * {@link TRANSIENT_LISTING_ERRNOS}.
      *
-     * `null` is not `[]` — an unreadable or absent directory versus a readable
-     * empty one. {@link classifyFilenameCase} deliberately collapses them (both
-     * are "no such entry"), but the distinction is kept in the row because it is
-     * a *fact*, and the judge that wants it — a check that says "the directory
-     * itself is missing" rather than "the file is missing" — cannot recover it
-     * once the fill has thrown it away.
+     * Derived once, here, rather than by each consumer: two lanes write a
+     * "re-run before investigating" remedy off this fact, and a second errno
+     * list is exactly how those two come to disagree about it.
      */
-    readonly names: readonly string[] | null;
-}
+    readonly transient: boolean;
+};
+/** The refusal half of {@link AbsenceCause}: a directory that would not be listed. */
+export type DirectoryRefusal = Extract<AbsenceCause, {
+    kind: 'directory_unreadable';
+}>;
 /**
- * The materialized listing column: parent directory → that directory's entry
- * names, or `null` when it could not be read.
+ * 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.
  *
- * `null` carries exactly the meaning {@link SiblingNames.names} documents — an
- * unreadable or absent directory, which is *not* the same fact as a readable
- * empty one (`[]`), even though {@link classifyFilenameCase} collapses the two
- * into one verdict.
+ * 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.
  *
- * A *missing key* is a third thing again, and never a legal input to judgement:
- * see {@link siblingNamesFrom}.
+ * @param listing - A `readdir` outcome that was refused
+ * @param directory - The directory that was asked about
+ * @returns The refusal, with `directory` forward-slashed
  */
-export type SiblingNamesTable = ReadonlyMap<string, readonly string[] | null>;
+export declare function directoryRefusalFor(listing: Extract<DirectoryListing, {
+    outcome: 'unreadable';
+}>, directory: string): DirectoryRefusal;
+/** What one directory entry name matched, and how the directory spells it. */
+export type ComponentMatch = {
+    match: Exclude<FilenameMatch, 'absent'>;
+    actualName: string;
+} | {
+    match: 'absent';
+    because: AbsenceCause;
+};
 /**
- * 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.
+ * What judging a whole path said, and the two spellings a message quotes.
  *
- * @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
- */
-export declare function fillSiblingNames(filePaths: Iterable<string>, fsCache: FsLookupCache): Promise<SiblingNamesTable>;
-/**
- * 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.
- *
- * Internal on purpose — {@link classifyFilenameCaseFrom} is the public judge.
- *
- * @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 union rather than one interface with an optional field: {@link AbsenceCause}
+ * is required exactly when the verdict is `absent` and unreachable otherwise, so
+ * a caller cannot report a path as missing without having read *which* absence
+ * it is.
  */
-export declare function siblingNamesFrom(table: SiblingNamesTable, filePath: string): SiblingNames;
+export type PathSpelling = {
+    /** The worst spelling defect on the path. */
+    match: Exclude<FilenameMatch, 'absent'>;
+    /** The path relative to the walk root, spelled as the caller asked for it. */
+    askedPath: string;
+    /** The same path as disk spells it. */
+    actualPath: string;
+} | {
+    /** No component matched — see `because` before calling anything missing. */
+    match: 'absent';
+    /** The path relative to the walk root, spelled as the caller asked for it. */
+    askedPath: string;
+    /** Empty: nothing matched, so there is no disk spelling to quote. */
+    actualPath: string;
+    /** Whether the entry is really gone, or the listing was refused. */
+    because: AbsenceCause;
+    /**
+     * What the walk DID establish before it stopped: the components above
+     * the one it could not find or could not ask about.
+     *
+     * 🪤 Carried because dropping it discarded a verdict. `Locked/t.md`
+     * against a disk `locked/` that then refuses to list: component 1 was
+     * judged and found a case mismatch — a defect that 404s on a
+     * case-sensitive filesystem whatever the mode bit below says — and a
+     * bare `absent` threw it away, so the report called the spelling
+     * "unverified" about a component VAT had verified and found wrong.
+     */
+    verified: VerifiedPrefix;
+};
 /**
- * Which pass of {@link classifyFilenameCase} produced the answer.
+ * The components of a path a walk judged before it stopped, and their verdict.
  *
- * The three that are not `absent` are ordered by how faithfully the asked-for
- * spelling matches disk, and every consumer that reports to a human needs the
- * distinction: only `exact` opens on every filesystem.
+ * Both paths are `/`-joined and relative to the walk root, like the
+ * {@link PathSpelling} they ride on; both are empty when the FIRST component
+ * is the one that could not be judged.
  */
-export type FilenameMatch = 
-/** The asked-for name and a directory entry are the same bytes. Opens anywhere. */
-'exact'
+export interface VerifiedPrefix {
+    /** The worst spelling defect among the judged components. */
+    readonly match: Exclude<FilenameMatch, 'absent'>;
+    /** The judged components as the caller spelled them. */
+    readonly askedPath: string;
+    /** The same components as disk spells them. */
+    readonly actualPath: string;
+}
 /**
- * They are different bytes that are equal after Unicode NFC folding — the same
- * visible filename in two normalization forms. Opens on macOS/APFS and
- * Windows; **does not open on a byte-exact filesystem** (Linux/ext4, i.e. CI
- * and most deploy targets), where the two forms simply name different files.
+ * 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.
  */
- | 'normalized'
-/** They differ by letter case (after folding). Opens only on a case-insensitive filesystem. */
- | 'case_mismatch'
-/** Nothing in the listing matches, or the directory could not be read. */
- | 'absent';
-/** What {@link classifyFilenameCase} decided about one asked-for filename. */
-export interface FilenameCaseVerdict {
+export declare class DirectorySpellingIndex {
+    #private;
+    constructor(fsCache: FsLookupCache);
+    /**
+     * 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(): number;
+    /** How many directory entries were examined, across every index built. */
+    get entriesIndexed(): number;
+    /** Every directory that has been listed, for never-reached-above-the-root pins. */
+    get indexedDirectories(): string[];
     /**
-     * Whether the name resolves to an entry at all — `true` for both `exact` and
-     * `normalized`, i.e. exactly where the author's own machine opens the file.
-     * Derivable from {@link FilenameCaseVerdict.match}; kept because "does this
-     * path resolve" is the question most callers are actually asking.
+     * 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`
      */
-    exists: boolean;
+    lookup(directory: string, name: string): Promise<ComponentMatch>;
     /**
-     * The entry actually on disk, **verbatim as `readdir` returned it**, or
-     * `null` when nothing matched. Raw rather than folded on purpose: this is the
-     * string a caller suggests writing, and a folded reconstruction of an NFD
-     * entry is a spelling that does not open the file on Linux.
+     * 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`
      */
-    actualName: string | null;
-    /** Which pass matched. See {@link FilenameMatch}. */
-    match: FilenameMatch;
+    judgePath(root: string, resolvedPath: string): Promise<PathSpelling>;
 }
+/** One path to judge, paired with the file whose text asked for it. */
+export interface PathSpellingRequest {
+    /** The referring file, whose own path was enumerated and is therefore trusted. */
+    referrer: string;
+    /** The absolute path the reference resolved to. */
+    target: string;
+}
+/**
+ * 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 declare function spellingWalkRoot(referrer: string, target: string): string;
+/**
+ * The materialized spelling column: one judged path per distinct
+ * (walk root, target) pair.
+ *
+ * A *missing key* is never a legal input to judgement: see
+ * {@link pathSpellingFrom}.
+ */
+export type PathSpellingTable = ReadonlyMap<string, PathSpelling>;
 /**
- * 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
+ * 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 declare function classifyFilenameCase(row: SiblingNames): FilenameCaseVerdict;
+export declare function fillPathSpellings(requests: Iterable<PathSpellingRequest>, fsCache: FsLookupCache): Promise<PathSpellingTable>;
 /**
- * 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}
+ * 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 declare function classifyFilenameCaseFrom(table: SiblingNamesTable, filePath: string): FilenameCaseVerdict;
+export declare function pathSpellingFrom(table: PathSpellingTable, referrer: string, target: string): PathSpelling;
 /**
  * The materialized realpath column: path → its canonical path.
  *
@@ -414,9 +623,9 @@ export type RealpathTable = ReadonlyMap<string, string>;
  * ⚠️ **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`
@@ -440,13 +649,11 @@ export declare function fillRealpaths(paths: Iterable<string>, fsCache: FsLookup
  * 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