@vibe-agent-toolkit/utils 0.2.0-rc.11 → 0.2.0-rc.12

package/README.md

@@ -28,11 +28,11 @@ The last two columns are the ones that matter when choosing. **"Resolves with ze
 | `./text` | `decodeTextContent` — the one bytes-to-text seam: BOM-announced UTF-8/UTF-16LE/UTF-16BE/UTF-32LE/UTF-32BE, BOM stripped, UTF-8 assumed otherwise; reports the encoding, whether it was a BOM fact or an assumption, and how many U+FFFD the decode substituted. `TextTooLargeError` (`TEXT_TOO_LARGE`) when the engine refuses a string that long | **none** | — | **yes** |
 | `./zod` | `ZodTypeNames`, `getZodTypeName`, `isZodType`, `unwrapZodType`, `isZodOptional`, `isZodNullable` | **none** | — | **yes** |
 | `./glob` | `isGlob`, static base extraction, magic remainder | `path` only | — | **yes** |
-| `./fs` | `normalizePath`, `normalizedTmpdir`, `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`, `copyDirectory`, `fillPathSpellings`, `pathSpellingFrom`, `DirectorySpellingIndex`, `spellingWalkRoot`, `fillRealpaths`, `realpathFrom`, `FsLookupCache`, `readTextContent`, `readTextContentSync`, `readDecodableBytes` (refuses a file past `MAX_DECODABLE_BYTES` by `fstat`, before reading it), `exceedsDecodableLength`, `MAX_DECODABLE_BYTES`, `TextTooLargeError` | `buffer`, `fs`, `fs/promises`, `os`, `path`, `url`, `util` | — | **yes** |
-| `./testing` | `getTestOutputDir`, `getTestOutputBase`, `setupAsyncTempDirSuite`, `setupSyncTempDirSuite`, `removeScratchDir`, `createTempDir`, `removeTempDir`, `tempDirTracker`, `CANNOT_DENY_READS`, `buildHostileTree`, `HOSTILE_NAMES`, `symlinkCapability`, `createSymlink`, `createSymlinkAsync` | `crypto`, `fs`, `fs/promises`, `os`, `path`, `url` | — | **yes** |
+| `./fs` | `normalizePath`, `normalizedTmpdir`, `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`, `fillPathSpellings`, `pathSpellingFrom`, `DirectorySpellingIndex`, `spellingWalkRoot`, `fillRealpaths`, `realpathRowFrom`, `FsLookupCache`, `readTextContent`, `readTextContentSync`, `readDecodableBytes` (refuses a file past `MAX_DECODABLE_BYTES` by `fstat`, before reading it), `exceedsDecodableLength`, `MAX_DECODABLE_BYTES`, `TextTooLargeError` | `buffer`, `fs`, `fs/promises`, `os`, `path`, `url`, `util` | — | **yes** |
+| `./testing` | `getTestOutputDir`, `getTestOutputBase`, `setupAsyncTempDirSuite`, `setupSyncTempDirSuite`, `removeScratchDir`, `createTempDir`, `removeTempDir`, `tempDirTracker`, `scratchTmpdirEnv`, `registerScratchTmpdir`, `CANNOT_DENY_READS`, `tmpdirFoldsCase`, `buildHostileTree`, `HOSTILE_NAMES`, `installFaultFs`, `injectedErrnoError`, `faultRuleOf`, `faultFsSpecOf`, `snapshotTree`, `diffSnapshots`, `subtree`, `symlinkCapability`, `createSymlink`, `createSymlinkAsync`, `atLeastTierTimeout` | `crypto`, `fs`, `fs/promises`, `module`, `os`, `path`, `url` | — | **yes** |
 | `./asset` | `resolveAssetReference` — paths and npm bare specifiers | `fs`, `module`, `os`, `path`, `url` | — | **yes** |
 | `./yaml` | `updateYamlIn`, `verifyConfinedYamlEdit` — byte-surgical YAML edits | **none** | `yaml` | no — needs `yaml` |
-| `./process` | `safeExecSync`, `safeExecResult`, `safeExecFromString`, `isToolAvailable`, `getToolVersion`, `hasShellSyntax`, `CommandExecutionError`, `spawnHardened`, `shouldUseShell`, `windowsShellQuote`, `buildWindowsShellLine`, `resolveShellCommandToken`, `isPathLike`, `makeStdioBlocking`, `describeStdioBlocking` | `child_process`, `path` | `@vibe-validate/git`, `which` | no — needs both |
+| `./process` | `safeExecSync`, `safeExecResult`, `safeExecFromString`, `isToolAvailable`, `getToolVersion`, `hasShellSyntax`, `CommandExecutionError`, `spawnHardened`, `shouldUseShell`, `windowsShellQuote`, `buildWindowsShellLine`, `resolveShellCommandToken`, `isPathLike`, `makeStdioBlocking`, `describeStdioBlocking`, `TERMINATING_SIGNALS`, `isTerminatingSignal`, `reRaiseSignal`, `handleTerminatingSignals`, `REPEAT_SIGNAL_WINDOW_MS`, `killProcessTree` | `child_process`, `path` | `@vibe-validate/git`, `which` | no — needs both |
 | `./git` | `runGit`, `runGitOrThrow`, `gitFindRoot`, `gitLsFiles`, `gitLsOthers`, `isGitIgnored`, `loadGitignoreRules`, `GitTracker`, `gitTreeSnapshot`, `peekGitTreeSnapshot`, `withGitSnapshotCache`, `parseGitUrl`, `isGitUrl`, `nonInteractiveGitOverrides` | `async_hooks`, `fs`, `fs/promises`, `os`, `path`, `url` | `@vibe-validate/git`, `ignore` | no — needs both |
 | `./crawl` | `crawlDirectory`, `crawlDirectorySync`, `crawlPathFilter`, `NEVER_CRAWL_GLOBS`, `BUILD_OUTPUT_GLOBS` | `fs`, `os`, `path`, `url` | `@vibe-validate/git`, `picomatch` | no — needs both |
 | `./skill-test` | `spawnHeadlessClaude`, `assembleClaudeArgs`, `killAllActiveClaudeChildren`, `resolveAuth`, `probeAuthStatus`, `AuthPreflightError`, `applyDeclaredEnv`, `buildForwardedEnv`, `formatForwardedEnvLine`, `isProtectedName`, `protectedEnvNames`, `parseStreamJsonTranscript`, `detectInvocationFromTranscript` | `child_process`, `path`, `stream` | `@vibe-validate/git`, `which` | no — needs both |
@@ -161,11 +161,9 @@ These return **OS-native** separators, because they resolve real filesystem iden
 - `mkdirSyncReal()` - create a directory and return its real path
 - `resolveFromImportMeta()` - resolve paths relative to an `import.meta.url`
 - `dynamicImportPath()` - `import()` an absolute path (works on Windows, which rejects bare absolute paths)
-- `copyDirectory()` - recursive copy that follows a symlinked directory into the tree it points at — contained: a link whose target is outside the source throws `CopyLinkEscapesSourceError`, and a link back into the tree throws `DirectoryWalkRevisitedError`
 - `isUnderRoot(root, candidate)` - the containment verdict a delete/copy/uninstall sink asks, answered by the filesystem: `'inside'` (a strict descendant, realpath-judged), `'outside'` (including the root itself and any symlink that leaves it), or `'absent'` (nothing there yet, and creating it would land inside). Both sides are canonicalized from their deepest existing ancestor, so a root reached through a symlink still contains its members; a refused path throws rather than reading as absent
 - `direntKind(entry)` - what a `Dirent` itself is: `'file' | 'directory' | 'symlink' | 'other'` — the link question asked first, for walks that must not follow (a delete, a size count)
 - `direntKindFollowing(dir, entry)` / `direntKindFollowingSync()` - what a `Dirent` resolves to, one `stat` for a link: `'file' | 'directory' | 'dangling' | 'other'` — for walks over a trusted tree where a link is how the entry got there. Both exist because `isFile()` and `isDirectory()` are BOTH false for a symlink, so a walk that tests only those drops every link silently (`local/dirent-type-needs-symlink-check` refuses that shape)
-- `FollowedWalk` - the cycle guard every following walk holds: `enter(dir)` on the root and each directory recursed into; a directory reached again under a second spelling (a link back into the tree) throws `DirectoryWalkRevisitedError` instead of recursing until the path length runs out
 - `fillPathSpellings(requests, fsCache)` - pass 1 of the case-exact existence check: walk each
   `{ referrer, target }` from the deepest directory the two share, listing every directory on the way
   down exactly once. The only I/O in the pair
@@ -181,7 +179,15 @@ These return **OS-native** separators, because they resolve real filesystem iden
   the root it walks from, for a caller that cannot enumerate its targets up front
 - `FsLookupCache` - per-run memo for `realpath`/`readdir`, sharing in-flight promises. Construct one per
   validation run and let it die with the run — never a module-level singleton, or a long-lived process
-  answers from a stale directory listing.
+  answers from a stale directory listing. `realpath(p)` answers a `RealpathRow` — `{ path, fault }` — and
+  never rejects on a filesystem errno: a path that resolves to nothing, or one the OS declined to resolve,
+  is answered from its nearest resolvable ancestor, the second carrying the `RealpathFault`
+  (`{ errno, faultClass, error }`) for the judge to report against that one target. `fillRealpaths` /
+  `realpathRowFrom(table, p)` read the same rows from a table filled up front (a missing row throws)
+- `realpathNativeSync(p)` / `realpathNative(p)` (main barrel) - the native realpath, forward-slashed, asked
+  again of the JS realpath when the volume cannot answer a final-path query
+  (`isFinalPathUnanswerableError`: Windows' `ERROR_INVALID_FUNCTION` is `EISDIR`; `ENOTSUP`, `EOPNOTSUPP`).
+  Every other error is thrown as it was, for the caller to classify
 
 ### Processes — `@vibe-agent-toolkit/utils/process`
 
@@ -190,6 +196,8 @@ These return **OS-native** separators, because they resolve real filesystem iden
 - `shouldUseShell()` / `windowsShellQuote()` / `buildWindowsShellLine()` - Windows shell-invocation helpers
 - `isToolAvailable()` / `getToolVersion()` / `hasShellSyntax()`
 - `makeStdioBlocking()` - stop `process.exit()` truncating output in a published bin
+- `TERMINATING_SIGNALS` / `isTerminatingSignal()` / `reRaiseSignal()` / `handleTerminatingSignals()` / `REPEAT_SIGNAL_WINDOW_MS` - the signals a process must clean up before dying of, the ONE way to handle them (runs every live guard's cleanup on the first signal, swallows a repeat within `REPEAT_SIGNAL_WINDOW_MS`, ends at once on a later one, otherwise dies of it once the cleanups settle; `local/no-raw-signal-listener` bans raw listeners), and dying of one (status 128+n on POSIX; a fallback exit code on Windows or under PID 1)
+- `killProcessTree()` - SIGKILL a child and everything it started: its process group on POSIX when it leads one, `taskkill /T /F` on Windows, an already-gone target absorbed
 
 ### Git — `@vibe-agent-toolkit/utils/git`
 
@@ -203,14 +211,38 @@ These return **OS-native** separators, because they resolve real filesystem iden
 
 **One root finder, on purpose.** `gitFindRoot()` is the only one in the package. There used to be a second name, `findGitRoot()`, whose entire body was `return gitFindRoot(startDir)`; two names for one function guarantees half of all callers pick each. Keeping it off this entry was not enough — it stayed on the `.` barrel, so both names were still one import away — so it has been removed outright. Replace any `findGitRoot(` with `gitFindRoot(`; the behavior is identical.
 
+### Archives — `@vibe-agent-toolkit/utils/archive`
+
+The ONE module that reads or writes a ZIP or a tarball. `adm-zip` and `tar` are loaded here and nowhere else — by bare name or any subpath, with `import`, `import()`, `require` or `createRequire` (`no-restricted-imports` and `no-restricted-syntax`, with no test-helper exemption), so every lane that opens an archive gets the same answer.
+
+- `extractArchive(source, into, { format, limits, omit? })` - (`omit` leaves an entry unwritten — a host's litter beside a skill — while it is still judged) extract a `{ file, side }` or `{ bytes, label }` archive into the directory `into`. The whole entry list is judged BEFORE anything is written, so a refused archive leaves nothing behind; files are written exclusively, never through a link, with mode `0644` or `0755` by the executable bit only. `limits` is required: an omitted bound is the failure
+- `openArchive(source, options)` / `listArchive(source, options)` - the entries without extracting, for a lane that inspects (`read(entry)` inflates one, bounded by its declared size)
+- `archiveEntryRefusal(entries)` - the entry policy alone, pure: a symbolic link, a hard link, a device, a FIFO or an entry of a type the tar reader does not model (sparse, continuation, an unknown type byte — listed as `other`, never dropped); an absolute, drive-rooted, UNC, `..` or NUL-bearing name; a segment Windows cannot write as named (a `:`, one of `<` `>` `"` `|` `?` `*` or a control character, a trailing dot or space, a device name such as `CON` or `com1.txt`), on every host; one name listed twice; a file with an entry beneath it; two names that are one where a volume folds them (`foldedSegment`)
+- `ArchiveRefusedError` / `ARCHIVE_REFUSED_CODE` - the refusal, with its `reason` (`unreadable` — bytes that are no archive of the format, the one reason a lane may pass bytes on; `unsupported` — an archive that parsed and VAT will not take: a ZIP64 ZIP, a directory two readers would read differently, or a tar entry (named) cut short — never passed on by any lane; `link`, `hardlink`, `special`, `unsafe-name`, `name-clash`, `too-many-entries`, `too-large`) and the first offending `entry`; the CLI maps the code to `INPUT_UNREADABLE`. A filesystem fault is an `FsFaultError` instead — the read on the source's side, every write `environment`
+- `ArchiveEntryReadError` / `ARCHIVE_ENTRY_UNREADABLE_CODE` / `isArchiveEntryReadRefusal(error)` (the class on this subpath; the code and the predicate on the main barrel too) - one ZIP member, of an archive whose entry list passed, that does not inflate or holds other than its directory declares: met when the member is READ — `read(entry)`, an extraction writing it, `zipOfArchive` copying it — never at open. `reason` is `unsupported` and `entry` always names the member. Its own code, `ARCHIVE_ENTRY_UNREADABLE`, so the predicate reads the `VatError` brand and that code — never the reason, the entry or the prototype — and a lane that may go on (the org verb's check of a skill's files) skips that one member and reports it, telling it from every refusal of the whole archive. The CLI maps the code to `INPUT_UNREADABLE`
+- `ARCHIVE_LIMITS` (50,000 entries, 256 MiB expanded) / `ARCHIVE_DOWNLOAD_MAX_BYTES` (100 MiB) - the bounds every VAT lane passes. A tarball is inflated through ONE gzip layer, capped; a stream still compressed after it (gzip again, zstd) is refused, never handed to the tar library's own unbounded sniffing. A ZIP's entry count and a name it lists twice (`name-clash`, as in a tarball) are read off its central directory before the ZIP library builds a record; there are two locks on which directory is the archive's. VAT's own: the end record must be the END of the archive (it and exactly the comment it declares), no end-record or ZIP64 signature may stand beside or after it, its two counts must agree, the directory must run exactly from its start to the end record, no byte may stand before the first local header it lists (a self-extracting stub, adjusted or not), each record's offset must hold that entry's own local header (so a directory record cannot stand over an unlisted entry), and no record may hold `0xFFFFFFFF` for a size or its offset (ZIP64) — else `unsupported`. (A member that does not inflate is refused when it is read: `ArchiveEntryReadError`.) And the library's: the entries it builds must be, name for name, the ones VAT read (`sameDirectory`)
+- `archiveEntryPlace(name)` (main barrel) - an entry name as the segments it lands at: a backslash read as a separator on every host, empty and `.` segments dropped. Pure, and loads no archive library: for a rule over entry NAMES (the skill-ZIP layout)
+- `zipOfDirectory(dir)` - the bytes of a ZIP of a directory, for the lanes that package one; every entry made on Unix whatever host writes it, a directory `0755` and a file `0644` or `0755` by the host's execute bit (Windows has none, so every file it writes is `0644`) — never the mode `stat` reports (on Windows a directory `0666`, which a Unix reader could not enter)
+- `zipOfArchive(source, { format, limits, omit? })` - the ZIP VAT writes of an archive it accepts: judged whole as `extractArchive` judges it, then only the entries it lists (minus `omit`), each named by the place it lands at, mode `0644`/`0755`, every entry made on Unix whatever host writes it (so a host-aware reader reads the mode) — what a lane that passes an archive ON sends, so the bytes that leave are exactly what was judged
+- `readArchiveFile(file, side, limits)` - an archive file's bytes, read once (non-blocking open, sized before reading, a fault classified on `side`), for a lane that both judges and sends them as `{ bytes, label }`
+
 ### Test helpers — `@vibe-agent-toolkit/utils/testing`
 
+- `tarFixture(entries, { gzip? })` / `zipFixture(entries, { compress? })` / `archiveEntriesOfDirectory(dir, prefix?)` - an archive written byte by byte with no library, so a test can make the entries no library will write: a link, a hard link, a FIFO, `../x`, a name listed twice, a declared size that lies. `hostileArchiveRows(limits)` is the shared table of archives every extracting lane must refuse, each with the `reason` expected
+
 - `setupAsyncTempDirSuite()` / `setupSyncTempDirSuite()` - per-suite temp directories with cleanup
 - `createTempDir()` / `createTempDirAsync()` / `removeTempDir()` / `tempDirTracker()` - the per-call temp-directory primitives; `removeTempDir` refuses, by name, anything not inside the host tmpdir as the filesystem sees it
+- `scratchTmpdirEnv(prefix)` - `{ enter, leave, current }`: make a fresh scratch THE temp directory (`TMPDIR` / `TEMP` / `TMP`) for one test and restore it after — the DESTRUCTIVE-CODE guard for any test that reaches a disposal path, spawned children included. Framework-free: register `enter` / `leave` with the runner's hooks; `registerScratchTmpdir(prefix, { beforeEach, afterEach })` does the registering
 - `CANNOT_DENY_READS` / `PERMISSIONS_ENFORCED` - whether a `chmod 000` denies anything on this host (Windows and uid 0 read everything); route through `skip()` so the skip is visible
-- `NODE_EXECUTABLE` / `gitExecutable()` / `resolveExecutable(name)` / `executableCandidates(name, platform, pathext)` - absolute paths for the binaries a fixture spawns: the running node, and `git` found by walking `PATH` once for the first regular executable file (`PATHEXT` names on Windows) and cached. A fixture spawns these instead of a bare `'git'` or `'node'`, so no writable directory on `PATH` decides what runs.
+- `tmpdirFoldsCase()` - whether the OS temp dir's filesystem folds letter case (probed once, not inferred from the platform); gate a case-alias fixture on it
+- `NODE_EXECUTABLE` / `gitExecutable()` / `resolveExecutable(name)` / `findExecutable(name)` (`undefined` instead of a throw, for a test that skips without the tool) / `executableCandidates(name, platform, pathext)` - absolute paths for the binaries a fixture spawns: the running node, and `git` found by walking `PATH` once for the first regular executable file (`PATHEXT` names on Windows) and cached. A fixture spawns these instead of a bare `'git'` or `'node'`, so no writable directory on `PATH` decides what runs.
 - `buildHostileTree(base)` / `hostileTreePerTest(prefix)` / `HOSTILE_NAMES` - the one hostile fixture every sink is tested against: a root with a member, a `..`-named member, a symlink pointing out, one pointing in, a dangling one, an alias link to the root, an unreadable directory, a 200-character name, plus a sibling `victim/secret.txt` outside the root; and the table of names (`../victim`, `..`, `.`, `''`, `/victim`, `C:\victim`, a NUL byte, …) a sink must refuse. Fields the host cannot build are `null`
+- `installFaultFs({ within, faults, rewrites })` / `injectedErrnoError()` - an in-process fs fault injector: patches `node:fs`, `fs.promises` and `FileHandle.prototype` (then `syncBuiltinESMExports`) so a named import, node-tar, adm-zip and write streams are all reached; fails the nth matching call under `within` with a chosen errno (`ENOSPC`, `EACCES`, ...) and can rewrite `stat` results (`ino: 0`, case aliasing). Install BEFORE opening a handle; `cpSync` and native recursive `rmSync` can be failed as a call but not per file inside. `await session.settled()` before `restore()`: a caller's promise can settle while fs work it started goes on (Node's `rm` rejects on its first failed child and leaves the siblings running), and that work would otherwise run under the next session
+- `INJECTED_ERRNOS` - every errno the injector can raise; each has a class in the fs-fault table (a unit test pins it).
+- `faultRuleOf(spec)` / `faultFsSpecOf(json)` and `dist/testing/fault-fs-preload.js` - the injector for a SPAWNED process: `node --import <utils>/dist/testing/fault-fs-preload.js <bin> ...` reads `VAT_FAULT_FS` (`{"within", "faults": [{"family", "op", "pathIncludes", "nth", "errno"}]}`) and installs those faults before the program loads; a spec matches a path by substring, since a predicate cannot cross a process boundary. The preload is never re-exported from `./testing` (importing it IS the installation)
+- `snapshotTree(root, { rewrites, keyPrefix })` / `diffSnapshots(a, b)` / `subtree(s, prefix)` - a comparable picture of a directory tree (kind, mode, sha256, link target) and a diff that names every difference; never follows a link, never opens a special file, fails loudly on an unreadable directory. `rewrites` normalise text (a per-case root, a timestamp) or, with `rewriteBytes`, a binary file (an archive's entry times) before hashing so two runs in different roots compare equal
 - `getTestOutputDir()` / `getTestOutputBase()` - isolated test output paths
+- `atLeastTierTimeout(tierTimeout, budgetMs)` - the timeout a test that needs `budgetMs` passes: `max(tier default, budget)`, so the platform-scaled default is the floor and the measured budget the ceiling — never a literal that shrinks the default on a slow platform, never a multiple that scales an hour-sized budget by the Windows factor. Throws on a non-finite or non-positive input (a config that provided no tier value)
 - `symlinkCapability()` - probes once (memoized per process) whether this host can create symlinks (Windows needs Developer Mode or `SeCreateSymbolicLinkPrivilege`), returning a `SymlinkCapability` token or `null`
 - `createSymlink()` / `createSymlinkAsync()` - the sanctioned way to create a symlink in test code; both require a `SymlinkCapability` from `symlinkCapability()`, so a test cannot reach the raw syscall without first proving the host supports it (or explicitly skipping via vitest's `skip()`)
 
@@ -226,26 +258,96 @@ These are CLI-boundary functions: inner libraries should take a root as a parame
 
 They are nonetheless on their own [`./project`](#import-narrowly) entry rather than the barrel alone. The entry was briefly withdrawn on the grounds that the functions fit few repos — which is true, and is what the paragraph above says — but that answered the wrong question. What decides whether an *entry* exists is how heavy the only remaining door is, and barrel-only these four once cost five third-party packages to reach while their own code imports nothing but `node:fs` and `node:path`. Publishing the entry is not a claim that the ladder fits you — only that finding out shouldn't cost a dependency graph. The barrel is dependency-free now, which is that same rule applied everywhere rather than a reason to fold `./project` back in.
 
+### Ordered and bounded async iteration — `@vibe-agent-toolkit/utils` (barrel only)
+
+- `forEachInOrder(items, fn)` / `mapInOrder(items, fn)` - run `fn` one item at a time, each call starting after the previous settles; the first rejection stops the run and later items never start. For when order is the contract: ordered writes, first-refusal-wins errors, a shared memo or sink, a report whose order is its meaning.
+- `everyInOrder(items, fn)` - `Array#every`, in order and awaited: stops at the first `false`. The idiom for a loop that used to `break`.
+- `mapWithConcurrency(items, fn, limit = FS_CONCURRENCY)` - `Promise.all`-shaped with at most `limit` calls in flight, results in input order. For independent work over a population-sized list, where a bare `Promise.all` would open a descriptor per item.
+- `mapConcurrentFailingInOrder(items, fn)` - `mapWithConcurrency`, but every call settles and the rejection of the EARLIEST item by position is rethrown — the error a sequential loop would have raised, for independent read-only work.
+- `promised(work)` - `work()` as a promise: its value resolves, a synchronous throw rejects. `Promise.try` for a Promise-shaped API over a synchronous body, until the Node floor has it.
+
+These replace `await` inside a loop, which the repo's ESLint config refuses (`no-await-in-loop`, mirroring Sonar S9382). None is written with `async` or a loop.
+
 ### Errors — `@vibe-agent-toolkit/utils` (barrel only)
 
 - `VatError` - the base of every error VAT throws on purpose: `new VatError(code, message, { cause })`. `code` is a stable `SCREAMING_SNAKE` identity a catch block dispatches on; `name` is taken from the subclass.
 - `isVatError(error, code?)` - the dispatch predicate. Reads a `Symbol.for('vat.error')` brand plus `code`, never the prototype chain, so a `dist` copy of a class still matches a `src` instance. A foreign error carrying a `code` (every `node:fs` errno) answers `false`.
+- `fsFaultOf(error)` / `classifyFsFault(error, { side, action, origin?, shapeFromSource? })` / `withFsFault` / `withFsFaultSync` / `fsBoundary(roots)` - the one errno classifier. `fsFaultOf` walks `cause` (bounded) and answers `{ errno, faultClass, path, dest, syscall }` for a filesystem errno — one the table does not list, on an error a system call raised, is `device`, never `undefined` — `path` and `dest` without the `\\?\` namespace prefix Node may report them with, read once there for every consumer — `undefined` for anything else. `classifyFsFault` returns an `FsFaultError` (code `FS_FAULT`, with `side`, `faultClass`, `errno`, `path`, `origin`, `action`) and passes a non-fs error or an existing `VatError` through untouched. Classes: `absent`, `refused`, `exhausted`, `wrong-type`, `occupied`, `busy`, `unsupported` (EROFS included), `device`. `fsBoundary({ source, destination, environment })` decides the side from the path the OS named, not from the wrapper; `shapeFromSource` attributes a layout fault (`isLayoutFault`: the `wrong-type` and `occupied` classes, and `ENOTDIR` — a file in the way) of a write whose layout an input decided to `source`; every other fault keeps its side. The side x class -> refusal table lives in `schema`, not here. `isFsFaultError(error)` dispatches by brand. A site that resolves a link (or a path through links) and has an answer for one that resolves to nothing asks the one predicate `isUnresolvableLinkError` through one of two catch bodies, chosen by its lane. A WRITE lane (a copy, an install) calls `assertUnresolvableLink(error, ctx)`: it returns when the link resolves to nothing, and otherwise throws the error classified on `ctx` (a non-fs error as it was). A READ/REPORT lane calls `linkResolutionFault(error)`: `undefined` when the link resolves to nothing, the `FsFaultFacts` of any other filesystem errno — a fault for that one target, reported against it while the run goes on — and a non-fs error or a `VatError` rethrown. `FsLookupCache.realpath`, `canonicalizeSync`, link validation and the resources projection's extent, realizations and identity are read lanes. The link validator's existence walk (`DirectorySpellingIndex`) reads a directory listing that failed with an errno the predicate calls unresolvable (`ELOOP`) as absence, so one link gets one answer from the walk and the realpath beside it; `listingFailure` itself keeps `absent` to `ENOENT`/`ENOTDIR`, the crawler's enumeration question.
+- `requireConfirmedAbsent(entry, absentError, ctx, { follows, sideOf })` - believe a probe's "nothing there" (`ENOENT` / `ENOTDIR`) only when the parent's listing agrees: an entry it lists (a link excepted only for a probe that `follows` links, which sees through to a missing target; never for an `lstat`) means the probe's answer was a fault, thrown classified on `sideOf(entry)`; a parent that cannot be listed throws too, on `sideOf(parent)` (`ctx` carries the action and no side). A registry read or a destination probe must never read a refused entry as empty or free.
+- `SideOfPath` / `everywhere(side)` / `sideWithin(root, side, outside)` / `refusedPathOf(error, fallback)` - a fault is charged to the side of the path the OS REFUSED, never to the side of the question the read answered: one probe touches more than its own path (a link walk `lstat`s each component, a confirmed absence lists the parent), so presence probes take a `SideOfPath`. `everywhere` is one side for every path (VAT's staging, one input tree); `sideWithin` puts `root` and what lies beneath it on `side` and every other path on `outside` (the project config, an input, inside the project a build writes into); `refusedPathOf` names the path a refusal acted on, for a caller that classifies a walk's refusal itself.
+- `FsFaultError.path` / `.movedFrom` - a fault is named, and `fsBoundary` sides it, by the path the failing SYSCALL acted on, not by Node's `error.path`: for a refused `symlink` or `link` that is the entry being created (`error.dest` — `error.path` is the target text), and for a refused `rename` it is where the entry could not land, with the entry being moved in `movedFrom` and both in the message
+- `foldedSegment(segment)` - one path segment as the strictest volume VAT writes onto compares it (stream suffix and trailing dots and spaces cut, NFKD, upper- then lower-cased): two names with one fold are one entry somewhere. The archive entry policy and the plugin build's `files:` destinations are judged by it
+- `pathPresent(path, mode, sideOf, absence)` - the one presence predicate: `false` only for an absence (the classifier's `absent` class); every other errno is thrown as an `FsFaultError` on `sideOf(<the path the OS refused>)` — the probe, a walked component, or the parent a confirmation lists (origin `content`). Both choices are the caller's and neither has a default. `mode`: `'entry'` (`lstat`: a dangling link is there — ask before writing) or `'follow'` (`stat`: a dangling link is absent — ask before reading). `absence`: `'confirmed'` (believed only once the parent's listing agrees, via `requireConfirmedAbsent`; a contradicted one is thrown — for a place about to be written, the run's own output, or a part of a package whose absence means "go on without it") or `'probe'` (the probe's word — for a caller that refuses or skips an absent path in its own words). Replaces `existsSync`, which answers `false` for an `EACCES` parent too (`local/no-existssync`).
+- `isCapacityFault({ faultClass })` - whether a fault is the machine or the filesystem giving out (`exhausted`, `busy`, `unsupported`, `device`): never the input's content or layout, and the one to report first among several failures of one operation (an archive extraction whose entries fail after the disk filled). `fsBoundary(...).classify(error, action, fallback)` classifies an error already caught, for a catch that must first decide whether it is a filesystem fault at all.
+- `isLayoutFault({ faultClass, errno })` / `isFileInTheWayError(error)` - whether a write's fault is one an input's layout decided (the only kind `shapeFromSource` moves to `source`), for a consumer judging a promoted fault, such as the CLI fault matrix's I8; `ENOTDIR` alone, a file in the way.
+- `FS_SIDES` / `SOURCE_ORIGINS` - every `FsSide` (`source`, `destination`, `environment`) and every `SourceOrigin` (`argument`, `config`, `content`), as `const` tuples the two types derive from: for a consumer that keys a table by them, such as the schema refusal table's drift test.
+- `FS_FAULT_ERRNOS_BY_CLASS` - the classifier's own table, class to errnos: what a check of anything that lists them (the docs' errno table) reads, so it is the same on every host — `os.constants.errno` is the HOST's list (Windows has no `EDQUOT` or `ESTALE`).
+- Single-errno questions, the only home of an errno literal: `isPathAbsentError`, `isNoSuchEntryError` (`ENOENT` alone, for a site where a path component that is a file must stay loud), `isAlreadyExistsError`, `isUnresolvableLinkError` (the link resolves to nothing: absent, `ELOOP`; every other errno is a fault, the device class included — `UNKNOWN` with it, which libuv `src/win/error.c:172` answers both for a network share that is not there and for credentials the share refused — and so are Windows' ambiguous `EINVAL` and `ENAMETOOLONG`, which libuv answers for several Win32 errors each), `isFinalPathUnanswerableError` (`EISDIR`, `ENOTSUP`, `EOPNOTSUPP`: a volume that cannot answer a native realpath at all), `isInvalidArgumentError`, `isNotARegularFileError`, `isWouldBlockError`, `isTimedOutError` (`ETIMEDOUT`: a spawn given a `timeout` ran out of time), `isProcessGoneError`, `isSymlinkUnsupportedError`, `isRenameContentionError` (`EPERM`/`EBUSY`/`EACCES`: a rename racing a scanner). Whether an error is a filesystem fault at all is `fsFaultOf(e) !== undefined`.
 - `prefixMessageOnce(error, prefix)` - prefix a message in place, once per error object — for a seam a retried item passes through more than once, without re-reading the message to find out.
 - `PathEscapesRootError` (on `./path` too) - what `safePath.joinUnderRoot` throws; recognise it with `isVatError(error, PathEscapesRootError.code)`.
 
 Never dispatch on `error.message` — the repo's ESLint config refuses `.message.includes(…)` and friends under `packages/*/src`. Prose is for humans and changes when it is improved; a code changes only when the meaning does.
 
+### Entry identity — `@vibe-agent-toolkit/utils` (barrel only)
+
+- `sameEntry(a, b)` - `'same' | 'different' | 'unknown'`: are two paths ONE entry on disk (case aliasing on APFS/NTFS, a link and its target, two links to one target)? Judged by a `bigint` `lstat` `dev:ino` (plus a link's target `stat`), or by an NFC-lowercased real path where the filesystem reports `ino` 0. An entry the OS refuses to examine is `unknown`, never `different`; an absent entry is `different`.
+- `isInsideByIdentity(child, ancestor)` - `'inside' | 'outside' | 'unknown'`: does some directory above `child` (which need not exist) answer `sameEntry` to `ancestor`? Strict: an entry is not inside itself.
+- `entryIdentities(entry, side)` - the `Identity[]` an entry answers to (`{ id }` or `{ foldedRealPath }`; `[]` when absent). Throws an `FsFaultError` on the `side` the caller names (`FsSide`) when the OS refuses to examine the entry.
+
+### Readable-tree proof and copy — `@vibe-agent-toolkit/utils` (barrel only)
+
+One walk serves both, so the proof and the copy can never disagree. Its options (`TreeWalkOptions`): `links` (`LinkPolicy`) — `'follow-contained'` takes a link as what it points at, inside the root only (a link out throws `CopyLinkEscapesSourceError`, `COPY_LINK_ESCAPES_SOURCE`; a link back into the walk throws `DirectoryWalkRevisitedError`, `DIRECTORY_WALK_REVISITED`), `'preserve'` keeps a link as a link and never examines its target — and an optional `filter(relative)` whose excluded entries are never stat'ed, opened or listed. The one special-file policy: a named pipe, socket or device (or a link to one, or one swapped in after the listing — each file is judged by `fstat` on the handle that is then read) is refused unopened as an `FsFaultError` of class `wrong-type` (`EFTYPE`).
+
+- `proveTreeReadable(root, { links, filter?, side })` - before a verb writes anything, list every directory and open every file of the directory it is about to read (a root that is not a directory is refused by its listing, `ENOTDIR`, as `copyTree` refuses it); the first refusal, in listing order, is an `FsFaultError` on the `side` the caller names (`ProveTreeReadableOptions`), origin `content`, naming the entry.
+- `refuseEscapingLinks({ root, subtree?, skip?, placement, side, flavor, tree, within, consequence })` / `treeContainment(root, candidate)` / `treeChain(root, path, flavor)` - refuse (`COPY_LINK_ESCAPES_SOURCE`) a tree holding a symbolic link that may not be kept, naming the link. Every directory is walked at its REAL path, so a link is judged where it lives, never through an in-tree alias of its directory. `placement`, `side` and `flavor` are required: `side` is whose filesystem a fault on the walk belongs to, and `flavor` is the path rules the tree's links are read under (`HOST_PATH_FLAVOR` for a real tree). Every link is first walked hop by hop by `lstat` and `readlink` alone (`treeChain`, the one resolver, exported for a caller that must judge a path below a root the same way) — a network, absolute, drive-relative or `\\?\` text anywhere on the chain (held to BOTH flavors' rules, since the tree is untrusted), a climb above the root, or a chain longer than the kernel's hop limit is refused before the kernel resolves anything (a Windows kernel asked to resolve `\\host\share` offers the operator's NTLM credentials to that host); a chain that returns to a link it has already met with the same text pending is a cycle and resolves to nothing, like a dangling link. `in-place` (a tree read where it stands) then refuses a link whose chain resolves outside `root` and accepts one that resolves to nothing; `relocated` (a tree an install copies, link text verbatim) holds each link to two more locks, because where a link leads at the source proves nothing about where its text leads once copied: its text is WALKED (`linkTextRefusal`) and must be relative, never rise above the root, pass through no other link, and end at something that exists; AND the kernel's own resolution must exist and be inside the root — a link that resolves to nothing is the same refusal, not a filesystem fault. It is the one check behind a cloned skill source and a local-directory install, both of which keep a link as a link. The link policies are `follow-contained`, `preserve` and `refuse` (a tree that must hold no link at all — one the archive module extracted); the walk `lstat`s its ROOT, so a root that is itself a link is judged by the same policy as every entry under it
+- `assertLocalChain(path, within, flavor)` / `followedStat(Sync)(path, within)` / `requireFollowedStat(Sync)` / `followedKind(Sync)` / `followedRealpath(Sync)` / `realpathNative(Sync)(path, within)` / `isLinkChainRefusedError` / `untrustedTextRefusal(text)` / `untrustedLinkRefusal(linkPath, text)` / `isWithinUnder(path, root, flavor)` / `win32FoldedName(name)` / `HOST_PATH_FLAVOR` / `LINK_CHAIN_REFUSED_CODE` - `link-following.ts`, the ONE module that asks the kernel to follow a link (enforced by: `local/no-link-following-fs`, which also flags a `symlink` made with no type — Node on Windows follows the target to pick one; its allowlist of operator's-own-path files pins each file's exact count of such calls, asserted both ways). Every follower takes `within`, the tree the path is crawled in: the walk starts at that root's real path (resolved once per process) and reads only what lies beneath it, by `lstat`/`readlink`, on every host; a path that IS the operator's input passes itself and the kernel answers it. Under win32 rules a link text is local only when relative or drive-absolute: every other spelling is a network or device path, and a chain through one (or drive-relative, or past the hop limit) throws `LinkChainRefusedError` (`LINK_CHAIN_REFUSED`, class `refused`, its side from its context in `classifyFsFault`; `fsFaultOf` and `linkResolutionFault` read it as a fault). A probe the OS refuses on the way is thrown raw, never a pass. A chain to nothing is `undefined`/`absent` (or the kernel's `ENOENT`, `ELOOP` for a cycle, from the `require` and realpath forms). `untrustedTextRefusal` / `untrustedLinkRefusal` are the one text rule an untrusted tree's link is held to under both flavors (`network`, `absolute`, `drive-relative`, `unportable` — a NUL, or a component ending in a dot or a space — and `climbs-out`); `isWithinUnder` matches a subpath, ordinal-case-folded under win32 (`win32FoldedName`)
+- `copyTree(source, root, relative, { links, filter?, side, onto })` - copy the directory `source` to `relative` under `root` (`''`: onto `root` itself) by that walk, each file from the handle the walk judged, with its mode; each directory gets its source's mode `| 0o700`, so a read-only source never becomes a copy nothing can fill or remove. Takes the proof's options (`ProveTreeReadableOptions`): a read the OS refuses is a classified fault on the `side` the caller names, as the proof's are; a write failure is the raw errno, for the caller's boundary to classify. `root` is a directory the caller made or its user named: made with its parents when absent, adopted when a real directory, and `EEXIST` when a link (to a directory included) or a file stands AT it; what is ABOVE it is the caller's and is followed, unexamined. Every directory between `root` and the copy must be a real one (made when absent): a link or a file there is a `source` fault (`occupied`) naming it. So a copy INTO a tree that holds copied content — links kept — names that tree's root, and is then never made through one of them.
+- `copyRegularFile(source, root, relative, { side, reading, existing, writing })` - copy ONE regular file to `relative` under `root`, as `copyTree` copies one: opened without blocking and judged by `fstat` on that handle (a special file refused unread), its bytes from that handle, its mode kept. The copy is made as `writeFileUnder` makes a file, through the same code: real directories only (made when absent), an exclusive create, bytes and mode set on that handle — never through a link; `existing` decides a regular file already there. A refused read is a classified fault on `side` (origin `content`) whose action reads `read <reading>`; an entry in the copy's way is a `source` fault (`occupied`) naming it; any other write failure is the raw errno. The one single-file copy (`copyFile` is banned by `local/no-destructive-fs`).
+- `readRegularFile(path)` - a file's bytes through a handle opened without blocking: `EFTYPE` for a special file, `EISDIR` for a directory, raw for the caller to classify.
+- `FollowedWalk` - the cycle guard every other following walk holds, built with the side its tree is on (`new FollowedWalk(side)`; a refused realpath in `enter` is an `FsFaultError` there): `enter(dir)` on the root and each directory recursed into; a directory reached again under a second spelling (a link back into the tree) throws `DirectoryWalkRevisitedError` instead of recursing until the path length runs out.
+
+### Tree changes: plan, then apply — `@vibe-agent-toolkit/utils` (barrel only)
+
+Every recursive remove, rename or copy of a destination goes through these two calls. A verb describes what it wants as `TreeChange`s — `replace` (a `TreeFill`: `copy` from a source with a link policy and filter, `write` into the empty staged directory with its declared `reads`, or `link` to a target), `replace-file` (its `FileContents`: bytes, or a function called when the file is staged — after every earlier change of the plan has staged, so an archive of a tree the plan stages is a change of that plan) or `remove` (with an optional `keepIfSameAs`) — each with an `Ownership` of what is there (`must-be-free`, `force`, `vat-made` with a `recognise` returning an `OwnershipVerdict`, `vat-state`) and a `label`.
+
+- `planTreeChanges(changes)` - takes every destination in its canonical spelling (`safePath.resolve`) and decides every change with no side effect, into a `TreePlan` of `PlannedChange`s (`existing`: `EntryKind`; `action`: `PlannedAction` — `create`, `replace`, `remove`, `keep` or `subsumed`, with a `reason`). A remove aliased (by `sameEntry`, never by name) to a replace or an earlier remove, or inside another change's destination, is `subsumed`; a remove whose `keepIfSameAs` names an entry `same` or `unknown` to it is kept, and so is every remove that holds (or cannot be proven not to hold) a kept entry. A destination whose `lstat` answers absent is believed only when its parent's listing agrees (`requireConfirmedAbsent`). Any other two active changes over one tree are refused `TREE_DESTS_OVERLAP` — the calling verb's defect (by identity; by spelling where the outer destination is absent). `unknown` identity is never a refusal (an `ino`-0 filesystem answers it for every pair). Refusals, coded: `TREE_DEST_OCCUPIED` (`must-be-free` over anything but an empty directory), `TREE_DEST_NOT_OWNED` (`vat-made` disowned, with the recogniser's reason), `TREE_DEST_HOLDS_SOURCE` / `TREE_SOURCE_HOLDS_DEST` (a copy source, or a `write` fill's `reads`, that is or lies inside the destination, or holds it). Every `copy` source is proven readable on the fill's declared `side` (required: an input, VAT's staging, or a copy already in user state). `plan.describe()` is the dry run: one `<action> <label> <dest> [(reason)]` line per change.
+- `applyTreePlan(plan, { afterSwap? })` - stage every new entry beside its destination, park every previous one (`.<base>.vat-staged-<random>.previous`), swap, run `afterSwap`, then remove what was parked. A failure before finalize rolls back so every destination is byte-equal to before (a case-aliased directory back under its on-disk spelling); a parked entry is never deleted on a failure path, and one that cannot be put back makes the error `TREE_ROLLBACK_INCOMPLETE` — `TreeRollbackIncompleteError` (`cause`: the failure; `parked`: where each is; `stranded`: each `TreeRollbackStranded` destination), the one shape of that code, which a caller undoing its own `afterSwap` writes throws too. The primitive's own faults are `FsFaultError`s on side `destination` (a copy source's read stays `source`); a `write` fill's raw errno is `destination` only when it names a path under the destination's parent — an input the callback read is rethrown raw, for the verb's boundary. A thrown failure is never mutated: what a failure path could not clean up (a staged entry, a parent it made, a replaced tree beside a failed remove) is recorded beside it — `suppressedFaultsOf`. A parked replaced tree that cannot be removed is a `TreeChangeWarning` coded `TREE_CLEANUP_INCOMPLETE` in `ApplyResult.warnings`; for a `remove` it is a thrown `destination` fault naming the parked path. Removal makes a read-only tree owner-writable first.
+- `applyTreePlanOrLeftover(plan, { afterSwap? })` - `applyTreePlan` for a verb that reports a change it finished even when what it parked could not then be deleted (an uninstall, a clear): a failure before the commit (every swap made, `afterSwap` run) rolled back and is thrown; one after it is returned as `ApplyOutcome.leftover` (a `destination` fault naming the parked entry), never thrown.
+- `renameFileAtomic(from, to)` - one rename (a file or a tree); under win32 `EPERM` / `EBUSY` / `EACCES` is retried up to 6 tries, backoff 50·2ⁿ ms. Raw errno out.
+- `writeFileUnder(root, relative, contents, { existing, writing })` - write a file VAT composes into a tree it is building (one whose source may have shipped links) without ever writing over or through what is there: each directory component must be a real directory, the file is created exclusively; `existing: 'replace'` removes a regular file of that name first (remove, then create — not one step: a create that then fails leaves no file, and its raw errno), a link or directory always refuses (`FsFaultError`, side `source`, origin `content`, class `occupied`, naming the entry). `copyRegularFile` is built on it.
+- `makeDirectoryUnder(root, relative, writing)` - the directory half of `writeFileUnder`: make `relative` under a tree VAT is building, component by component, adopting real directories and refusing a link or file standing where one goes (a recursive `mkdir` would follow the link out of the tree).
+- `requireTestScratch(root, what)` / `TEST_USER_STATE_UNDER` - the fail-closed guard every resolver of user state under the home directory passes its root through: throws when a test process named the tree user state may be in (the shared vitest setup does, in every tier) and `root` is outside it. Unset, it does nothing.
+- `replaceFile(dest, contents)` - write a temp beside `dest`, then `renameFileAtomic` over it: a failed write leaves `dest` byte-equal. Keeps the file's mode, and refuses a file a write in place would be refused on (a read-only one) before writing anything — the rename alone would replace it; writes through a link, which stays a link. Raw errno out.
+- `withTempDir(prefix, work)` / `disposeTempDir(dir)` - a fresh directory under `normalizedTmpdir()`, always disposed of; the work's error is rethrown unchanged, a disposal failure recorded beside it (`suppressedFaultsOf`). When the work SUCCEEDED nothing is thrown: it returns `TempDirOutcome { value, leftover }` — `leftover` required, `undefined` when the directory went, else the `environment` fault naming the directory, for the verb to report as the one `TREE_CLEANUP_INCOMPLETE` warning beside its finished work. `disposeTempDir` answers `undefined` when gone, else that same leftover fault — and refuses (`TEMP_DIR_OUTSIDE_TMPDIR`, a defect, nothing touched) any directory not strictly under the temp directory, since it makes a read-only tree writable before deleting it.
+- `disposeTempDirSync(dir)` - `disposeTempDir` for a process on its way out (a signal handler, an `exit` listener), where no promise settles: synchronous, the same refusal and the same `undefined`-or-leftover answer, no mode repair, and a short bounded retry of a transient refusal (`EBUSY`/`EPERM` while a just-terminated child lets go on Windows).
+- `disposeTempDirAfterFailure(dir, failure)` - for a temp directory handed back on success and removed only when the work failed: disposes of it and records a disposal fault beside `failure` (`suppressedFaultsOf`), never thrown in its place; the same `TEMP_DIR_OUTSIDE_TMPDIR` refusal as `disposeTempDir`.
+- `recordSuppressedFault(error, fault)` - record `fault` (a leftover found while `error` was being handled) beside `error`, off its cause chain, for `suppressedFaultsOf` to read back; a thrown non-object gets a `process.emitWarning` instead.
+- `suppressedFaultsOf(error)` - the faults recorded against a thrown error, and against every error on its cause chain (bounded, cycle-safe), while each was being handled — a leftover the failure path could not remove — so a wrapper thrown in the failure's place (a rollback-incomplete error, a verb's re-wrap) still carries them. Recorded beside the error, never on its cause chain, so never its classification; a thrown non-object gets a `process.emitWarning` instead. The CLI publishes each as a `TREE_CLEANUP_INCOMPLETE` warning naming the leftover.
+- `isTreeChangeResidue(name)` - whether a directory entry is the primitive's own staged, parked or discarded entry, which a listing beside a destination must skip.
+- `isParkedTreeEntry(name)` - whether a directory entry is a parked previous entry (`….vat-staged-<random>.previous`): the residue a sweep may remove, since a staged entry may be another process's change in flight.
+
 ### Directory crawling — `@vibe-agent-toolkit/utils/crawl`
 
 - `crawlDirectory()` / `crawlDirectorySync()` - gitignore-aware directory walks
 - `NEVER_CRAWL_GLOBS` / `BUILD_OUTPUT_GLOBS` - the standard exclusion sets
 - `UnreadablePolicy` - the REQUIRED `unreadable` option on every crawl (and on `gitLsFiles` /
-  `gitLsOthers` under `./git`): `{ refuse: { root, remedy } }` throws `DirectoryListingRefusedError`
-  with an adopter-facing, root-relative sentence when a directory cannot be listed;
+  `gitLsOthers` under `./git`): `{ refuse: { root, remedy, side } }` throws `DirectoryListingRefusedError`
+  with an adopter-facing, root-relative sentence when a directory cannot be listed — coded `FS_FAULT`
+  and carrying the classified fault (on `side`) as its `cause`. A crawl's required `outputs` — the trees
+  the calling verb writes, `[]` for none — is the one declaration of which side a fault is on: a
+  directory that is an output, lies inside one or holds one (the base of a project a build writes
+  into included) is the destination's, any other is on `side` (`settleCrawlRefusal`, for a caller
+  that settles a crawl's refusals itself; `onCrawlOutput(path, outputs)`, for a verb that reads a tree
+  it may itself have written earlier in the run — `vat build`'s plugin phase reading `dist/skills` —
+  and must ask the same declaration which side that tree is on);
   `{ degrade: (refusal) => … }` keeps walking and hands the gap to you to report. There is no
   default — a shorter list nothing can tell from a complete one is the failure this option exists
   to prevent, so the caller states which answer is honest for its lane, and an omitted policy is
   refused up front by name.
+- `rootListingRefusal(error, dir)` - for a caller that asks whether a scan ROOT exists before
+  walking it: the `DirectoryRefusal` a failed `stat`/`readdir` of `dir` stands for, or `undefined`
+  when it is simply absent (`ENOENT`/`ENOTDIR`) — never `existsSync`, which calls an untraversable
+  parent absent.
 
 Glob *pattern inspection* is a separate entry, `./glob`, and stays that way: `./glob` is dependency-free and reaches only `node:path`, whereas crawling reaches the filesystem, `git`, and `picomatch`.
 

package/dist/archive/archive.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The ONE way VAT reads or extracts an archive — an npm tarball, a skill ZIP, a ZIP fetched from
+ * a URL. Every lane goes through here, so every lane has the same answer to the same archive:
+ *
+ * - The archive is read whole, in memory, bounded by the caller's {@link ArchiveLimits}.
+ * - Which archives are extracted is decided from the entry list, before anything is written
+ *   ({@link archiveEntryRefusal}): only regular files and directories, each named inside the
+ *   archive, no two of them one name.
+ * - What is written is written by VAT, never by an archive library: each directory a plain
+ *   `mkdir`, each file an exclusive create that no link satisfies (`openFileUnder`), with mode
+ *   `0644` or `0755` by the archive's executable bit and nothing else of its mode — narrowed by
+ *   the process's umask, as any file it creates is.
+ *
+ * So an extracted tree holds no link, no special file and no setuid bit, whatever the archive said.
+ */
+import { type FsSide } from '../errors/fs-fault.js';
+import { type ArchiveEntry, type ArchiveFormat, type ArchiveLimits } from './entries.js';
+/**
+ * Where an archive is: a file — on the `side` of the verb that named it, an operator's argument
+ * (`source`) or VAT's own download (`environment`) — or bytes already in hand, with the `label`
+ * a refusal names them by.
+ */
+export type ArchiveSource = {
+    readonly file: string;
+    readonly side: FsSide;
+} | {
+    readonly bytes: Uint8Array;
+    readonly label: string;
+};
+/** What every read of an archive is told. Both are required: an omitted bound is the failure. */
+export interface ArchiveReadOptions {
+    readonly format: ArchiveFormat;
+    readonly limits: ArchiveLimits;
+}
+/** What an extraction is told: how to read the archive, and which of its entries not to write. */
+export interface ArchiveExtractOptions extends ArchiveReadOptions {
+    /**
+     * Entries to leave out of what is written (a host's own litter beside a skill). They are still
+     * read and still JUDGED: an archive is refused for a link among them like any other.
+     */
+    readonly omit?: (entry: ArchiveEntry) => boolean;
+}
+/** An archive read into memory: what it lists, and each file's bytes on request. */
+export interface OpenedArchive {
+    /** What a refusal names the archive by: its path, or the label its bytes came with. */
+    readonly label: string;
+    /** Every entry, in archive order, as the archive spells it. Nothing here has been judged. */
+    readonly entries: readonly ArchiveEntry[];
+    /**
+     * The bytes of one of {@link entries} (a file).
+     *
+     * @throws ArchiveEntryReadError (`unsupported`, naming the entry) when it does not inflate to the size it declares
+     */
+    read(entry: ArchiveEntry): Buffer;
+}
+/**
+ * The mode of an extracted file: what the process's own umask gave the file when it was created,
+ * never wider — `0644` at most, or `0755` for an executable entry, with execute granted exactly
+ * where the umask left read. Under `umask 077` an extracted file is `0600` / `0700`, as a file
+ * the user made any other way is.
+ *
+ * @param created - The mode the exclusive create gave the file
+ * @param executable - Whether the archive marked the entry executable
+ */
+export declare function extractedFileMode(created: number, executable: boolean): number;
+/**
+ * An archive file's bytes, through a handle opened without blocking (a named pipe is refused,
+ * never waited on) and sized by `fstat` on that handle before a byte is read. For a lane that
+ * reads an archive ONCE and both judges and passes on those bytes (`{ bytes, label }`).
+ *
+ * @param file - The archive's path
+ * @param side - Whose the file is: an operator's argument (`source`) or VAT's own download (`environment`)
+ * @param limits - The bounds the archive will be held to: a file no archive within them can be is refused unread
+ * @throws FsFaultError on `side` for a read the OS refuses; ArchiveRefusedError `too-large` for a
+ *   file no archive within `limits` can be
+ */
+export declare function readArchiveFile(file: string, side: FsSide, limits: ArchiveLimits): Promise<Buffer>;
+/**
+ * Read an archive into memory and list it. Nothing is judged: a caller that only inspects an
+ * archive (an upload's preflight) sees its links and unsafe names as entries.
+ *
+ * @param source - The archive
+ * @param options - Its `format`, and the `limits` it is held to as it is read
+ * @throws FsFaultError on the source's side when the OS refuses the read; ArchiveRefusedError
+ *   `unreadable` for bytes that are no archive of the format, `too-many-entries` / `too-large`
+ *   for one past `limits`
+ */
+export declare function openArchive(source: ArchiveSource, options: ArchiveReadOptions): Promise<OpenedArchive>;
+/**
+ * Every entry of an archive, in archive order ({@link openArchive}).
+ *
+ * @throws as {@link openArchive}
+ */
+export declare function listArchive(source: ArchiveSource, options: ArchiveReadOptions): Promise<readonly ArchiveEntry[]>;
+/**
+ * Extract an archive into `into`, a directory the caller just made — every entry, or a refusal.
+ *
+ * The whole entry list is judged first ({@link archiveEntryRefusal}); an archive that passes is
+ * written one entry at a time, in archive order, so when this throws nothing is still being
+ * written and the caller may dispose of `into`.
+ *
+ * @param source - The archive
+ * @param into - A fresh directory VAT owns (staging, a cache entry): every write is VAT's own scratch
+ * @param options - The archive's `format`, the `limits` it is held to, and any entries to `omit`
+ * @returns Every entry of the archive, in archive order — an omitted one included
+ * @throws ArchiveRefusedError — the input's refusal — for an archive that is unreadable, past
+ *   `limits`, or holds an entry the policy refuses, with nothing written; ArchiveEntryReadError
+ *   (`ARCHIVE_ENTRY_UNREADABLE`, the input's too) for a member that does not inflate or holds other
+ *   than it declares, met as it is written; FsFaultError on the source's side for a read the OS
+ *   refuses, and side `environment` for a write it refuses
+ */
+export declare function extractArchive(source: ArchiveSource, into: string, options: ArchiveExtractOptions): Promise<readonly ArchiveEntry[]>;
+/**
+ * The ZIP VAT writes of an archive it accepts, in memory: the archive judged whole as an extraction
+ * judges it, then each entry it lists — but those the caller omits — named by the place it lands
+ * at, each file's bytes held to the size it declares, with mode `0644` or `0755` by its executable
+ * bit. Nothing else of the archive's bytes: no local entry its directory does not list, no stub
+ * before it, no comment, no other mode. What a lane that passes an archive ON sends, so the bytes
+ * that leave are exactly the entries that were judged.
+ *
+ * @param source - The archive
+ * @param options - The archive's `format`, the `limits` it is held to, and any entries to `omit`
+ * @returns The new archive's bytes
+ * @throws as {@link openArchive}; ArchiveRefusedError for an entry the policy refuses;
+ *   ArchiveEntryReadError (`ARCHIVE_ENTRY_UNREADABLE`) for a member that does not inflate, or does
+ *   not hold the size it declares
+ */
+export declare function zipOfArchive(source: ArchiveSource, options: ArchiveExtractOptions): Promise<Buffer>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/archive/archive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAmB,KAAK,MAAM,EAAe,MAAM,uBAAuB,CAAC;AAMlF,OAAO,EAAE,KAAK,YAAY,EAAyB,KAAK,aAAa,EAAE,KAAK,aAAa,EAAqD,MAAM,cAAc,CAAC;AAMnK;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,iGAAiG;AACjG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED,kGAAkG;AAClG,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;CAClD;AAED,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC;CACnC;AAaD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,MAAM,CAG9E;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAUxG;AA8CD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAE5G;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAEtH;AAuCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAS1I;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAQzG"}

package/dist/archive/archive.js

@@ -0,0 +1,223 @@
+/**
+ * The ONE way VAT reads or extracts an archive — an npm tarball, a skill ZIP, a ZIP fetched from
+ * a URL. Every lane goes through here, so every lane has the same answer to the same archive:
+ *
+ * - The archive is read whole, in memory, bounded by the caller's {@link ArchiveLimits}.
+ * - Which archives are extracted is decided from the entry list, before anything is written
+ *   ({@link archiveEntryRefusal}): only regular files and directories, each named inside the
+ *   archive, no two of them one name.
+ * - What is written is written by VAT, never by an archive library: each directory a plain
+ *   `mkdir`, each file an exclusive create that no link satisfies (`openFileUnder`), with mode
+ *   `0644` or `0755` by the archive's executable bit and nothing else of its mode — narrowed by
+ *   the process's umask, as any file it creates is.
+ *
+ * So an extracted tree holds no link, no special file and no setuid bit, whatever the archive said.
+ */
+import { classifyFsFault, withFsFault } from '../errors/fs-fault.js';
+import { forEachInOrder } from '../in-order.js';
+import { toForwardSlash } from '../path-core.js';
+import { openForReading } from '../text-file.js';
+import { makeDirectoryUnder, openFileUnder } from '../tree-change/files.js';
+import { ArchiveEntryReadError, ArchiveRefusedError, archiveEntryRefusal, placeOf } from './entries.js';
+import { archiveBytesCap, tooLarge } from './limits.js';
+import { readTar } from './tar-reader.js';
+import { readZip, zipOfEntries } from './zip-reader.js';
+const READERS = {
+    tar: readTar,
+    zip: readZip,
+};
+/** The widest mode an extracted file gets: the executable bit is all an archive's mode decides. */
+const FILE_MODE = 0o644;
+const EXECUTABLE_MODE = 0o755;
+const PERMISSION_BITS = 0o777;
+const READ_BITS = 0o444;
+/**
+ * The mode of an extracted file: what the process's own umask gave the file when it was created,
+ * never wider — `0644` at most, or `0755` for an executable entry, with execute granted exactly
+ * where the umask left read. Under `umask 077` an extracted file is `0600` / `0700`, as a file
+ * the user made any other way is.
+ *
+ * @param created - The mode the exclusive create gave the file
+ * @param executable - Whether the archive marked the entry executable
+ */
+export function extractedFileMode(created, executable) {
+    const granted = created & PERMISSION_BITS;
+    return executable ? (granted | ((granted & READ_BITS) >> 2)) & EXECUTABLE_MODE : granted & FILE_MODE;
+}
+const labelOf = (source) => ('file' in source ? toForwardSlash(source.file) : source.label);
+/**
+ * An archive file's bytes, through a handle opened without blocking (a named pipe is refused,
+ * never waited on) and sized by `fstat` on that handle before a byte is read. For a lane that
+ * reads an archive ONCE and both judges and passes on those bytes (`{ bytes, label }`).
+ *
+ * @param file - The archive's path
+ * @param side - Whose the file is: an operator's argument (`source`) or VAT's own download (`environment`)
+ * @param limits - The bounds the archive will be held to: a file no archive within them can be is refused unread
+ * @throws FsFaultError on `side` for a read the OS refuses; ArchiveRefusedError `too-large` for a
+ *   file no archive within `limits` can be
+ */
+export async function readArchiveFile(file, side, limits) {
+    return await withFsFault({ side, origin: 'argument', action: `read the archive ${toForwardSlash(file)}`, path: file }, async () => {
+        const handle = await openForReading(file);
+        try {
+            if ((await handle.stat()).size > archiveBytesCap(limits))
+                throw tooLarge(toForwardSlash(file), limits);
+            return await handle.readFile();
+        }
+        finally {
+            await handle.close();
+        }
+    });
+}
+async function bytesOf(source, limits) {
+    if ('file' in source)
+        return await readArchiveFile(source.file, source.side, limits);
+    if (source.bytes.byteLength > archiveBytesCap(limits))
+        throw tooLarge(source.label, limits);
+    return Buffer.from(source.bytes.buffer, source.bytes.byteOffset, source.bytes.byteLength);
+}
+/**
+ * One record's bytes, held to the size its entry declared. An entry that does not inflate, or does
+ * not hold what it declares, is in an archive that parsed: `unsupported` — never `unreadable`, which
+ * means bytes that are no archive at all, the one refusal a lane may pass on.
+ */
+function bytesOfRecord(archive, record) {
+    let data;
+    try {
+        data = record.read();
+    }
+    catch (error) {
+        throw new ArchiveEntryReadError(archive, record.name, `does not inflate (${String(error)})`, { cause: error });
+    }
+    if (data.length !== record.size) {
+        throw new ArchiveEntryReadError(archive, record.name, `declares ${record.size} bytes and holds ${data.length}`);
+    }
+    return data;
+}
+async function openRecords(source, options) {
+    const label = labelOf(source);
+    const records = READERS[options.format](await bytesOf(source, options.limits), label, options.limits);
+    const byEntry = new Map(records.map((record) => [record, record]));
+    return {
+        label,
+        entries: records,
+        records,
+        read(entry) {
+            const record = byEntry.get(entry);
+            if (record === undefined)
+                throw new TypeError(`"${entry.name}" is not an entry of ${label}`);
+            return bytesOfRecord(label, record);
+        },
+    };
+}
+/**
+ * Read an archive into memory and list it. Nothing is judged: a caller that only inspects an
+ * archive (an upload's preflight) sees its links and unsafe names as entries.
+ *
+ * @param source - The archive
+ * @param options - Its `format`, and the `limits` it is held to as it is read
+ * @throws FsFaultError on the source's side when the OS refuses the read; ArchiveRefusedError
+ *   `unreadable` for bytes that are no archive of the format, `too-many-entries` / `too-large`
+ *   for one past `limits`
+ */
+export async function openArchive(source, options) {
+    return await openRecords(source, options);
+}
+/**
+ * Every entry of an archive, in archive order ({@link openArchive}).
+ *
+ * @throws as {@link openArchive}
+ */
+export async function listArchive(source, options) {
+    return (await openRecords(source, options)).entries;
+}
+/**
+ * An archive read and judged whole ({@link archiveEntryRefusal}): what an extraction writes, and
+ * what a re-zip writes, are decided by the one entry policy before a byte of either is written.
+ *
+ * @throws as {@link openArchive}; ArchiveRefusedError for an entry the policy refuses
+ */
+async function openJudged(source, options) {
+    const opened = await openRecords(source, options);
+    const refusal = archiveEntryRefusal(opened.entries);
+    if (refusal !== undefined)
+        throw new ArchiveRefusedError(opened.label, refusal);
+    return opened;
+}
+/** The records of a judged archive to write: every one but those the caller omits. */
+const keptRecords = (opened, options) => options.omit === undefined ? opened.records : opened.records.filter((record) => options.omit?.(record) !== true);
+/** Write one accepted entry under `into`: a directory made plainly, a file created exclusively with only its executable bit kept. */
+async function writeRecord(archive, into, record) {
+    const relative = placeOf(record.name).join('/');
+    const writing = `the entry ${record.name} of ${archive}`;
+    if (record.kind === 'directory') {
+        // The archive's own root (`./`) is the directory the caller made.
+        if (relative !== '')
+            await makeDirectoryUnder(into, relative, writing);
+        return;
+    }
+    const data = bytesOfRecord(archive, record);
+    const handle = await openFileUnder(into, relative, { existing: 'refuse', writing });
+    try {
+        await handle.writeFile(data);
+        // On the handle, never by path: nothing swapped in after the create is examined or chmod-ed through.
+        await handle.chmod(extractedFileMode((await handle.stat()).mode, record.executable));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Extract an archive into `into`, a directory the caller just made — every entry, or a refusal.
+ *
+ * The whole entry list is judged first ({@link archiveEntryRefusal}); an archive that passes is
+ * written one entry at a time, in archive order, so when this throws nothing is still being
+ * written and the caller may dispose of `into`.
+ *
+ * @param source - The archive
+ * @param into - A fresh directory VAT owns (staging, a cache entry): every write is VAT's own scratch
+ * @param options - The archive's `format`, the `limits` it is held to, and any entries to `omit`
+ * @returns Every entry of the archive, in archive order — an omitted one included
+ * @throws ArchiveRefusedError — the input's refusal — for an archive that is unreadable, past
+ *   `limits`, or holds an entry the policy refuses, with nothing written; ArchiveEntryReadError
+ *   (`ARCHIVE_ENTRY_UNREADABLE`, the input's too) for a member that does not inflate or holds other
+ *   than it declares, met as it is written; FsFaultError on the source's side for a read the OS
+ *   refuses, and side `environment` for a write it refuses
+ */
+export async function extractArchive(source, into, options) {
+    const opened = await openJudged(source, options);
+    try {
+        // In order: a directory before what goes in it, and the first failure the only one.
+        await forEachInOrder(keptRecords(opened, options), (record) => writeRecord(opened.label, into, record));
+    }
+    catch (error) {
+        throw classifyFsFault(error, { side: 'environment', action: `extract ${opened.label}`, path: into });
+    }
+    return opened.entries;
+}
+/**
+ * The ZIP VAT writes of an archive it accepts, in memory: the archive judged whole as an extraction
+ * judges it, then each entry it lists — but those the caller omits — named by the place it lands
+ * at, each file's bytes held to the size it declares, with mode `0644` or `0755` by its executable
+ * bit. Nothing else of the archive's bytes: no local entry its directory does not list, no stub
+ * before it, no comment, no other mode. What a lane that passes an archive ON sends, so the bytes
+ * that leave are exactly the entries that were judged.
+ *
+ * @param source - The archive
+ * @param options - The archive's `format`, the `limits` it is held to, and any entries to `omit`
+ * @returns The new archive's bytes
+ * @throws as {@link openArchive}; ArchiveRefusedError for an entry the policy refuses;
+ *   ArchiveEntryReadError (`ARCHIVE_ENTRY_UNREADABLE`) for a member that does not inflate, or does
+ *   not hold the size it declares
+ */
+export async function zipOfArchive(source, options) {
+    const opened = await openJudged(source, options);
+    return zipOfEntries(keptRecords(opened, options).flatMap((record) => {
+        const place = placeOf(record.name).join('/');
+        // The archive's own root (`./`) is no entry of the new one.
+        if (place === '')
+            return [];
+        return [{ place, data: record.kind === 'directory' ? undefined : bytesOfRecord(opened.label, record), executable: record.executable }];
+    }));
+}
+//# sourceMappingURL=archive.js.map