# @effected/walker Path traversal: upward (`Walker.ascend` / `ascendWithin` / `ascendToMarker` / `firstMatch` / `findUpward` / `findUpwardAll` / `findRoot` / `findUpwardWith`, plus `*Sync` twins including `findUpwardSyncWith`) and downward (`descend`, the public glob-file walker), and path containment (`confineRelative` lexical, `confineReal` physical), plus `PosixPath` (cwd-free POSIX path arithmetic for pure code). Sixth migration; the first package extracted from an already-merged sibling rather than ported from a `*-effect` repo. **Design doc:** `@./okf/modules/walker.md` ## Tier: boundary **Boundary tier**: `effect` and `@effected/glob` are the only peers and there are no runtime dependencies, but walker does IO. `FileSystem` and `Path` arrive through the `R` channel from `effect` core, so the consumer's platform layer is the single place POSIX-vs-win32 semantics are chosen. Requiring core services costs no dependency. The `@effected/glob` peer is mostly type-and-property — `descend` imports `GlobPattern` as a type and calls `matches()`. The one value import is `compileAndExpand` (in `Expand.ts`), which calls `GlobPattern.compileResult` and references `GlobPatternError`; the peer was already declared, so the dependency graph is unchanged. Walker needs **no platform package, even in tests** — core's `Path.layer` plus a real in-memory volume from `@effected/memfs` (a devDependency). Do not add `@effect/platform-node`, and do not hand-roll a `FileSystem.layerNoop` tree: `__test__/fixtures.ts` seeds files and symlinks into the volume, and injects the unreadable and vanished directories as `readDirectory` faults — and an unresolvable link as a `realPath` fault — that decline for every other path. The volume owns the parent-directory arithmetic and the symlink semantics `descend` reads, so neither is re-derived in the fixture. The upward suites in `Walker.test.ts` do the same: `findUpward`'s fixtures seed a volume via `MemoryFileSystem.layerWith`, and the denied probe is an `exists` fault on a candidate that is genuinely present — so disarming the fault moves the answer. `Walker` is a static class with a private constructor, not an `as const` namespace object — an `as const` object's member types are inferred in the built `.d.ts` and lose their TSDoc entirely, while a class's `static readonly` declarations keep it. Call syntax is unaffected (`Walker.ascend(...)`). ## The one absorbing loop `firstMatch` is the whole algorithm. `findRoot` is a genuine one-line specialization of it (`firstMatch(dirs, isRoot)` — the candidate expansion is the identity). `findUpward` first flattens each directory's candidates in **directory-major** order, then reuses the same loop. Three properties are load-bearing. Each has a test, and each test has been watched failing against a deliberately broken implementation: - **Absorption is per candidate.** A failing probe means "this candidate did not match", never "abort the scan". One `EACCES` ancestor must not hide a valid root above it. The corollary: not-found and cannot-look are deliberately **indistinguishable** to the caller. Discovery is best-effort, and a `None` may mean a directory was unreadable rather than empty. - **Defects propagate.** `firstMatch` uses `Effect.catch`, which catches failures and not defects. **Never** change it to `Effect.catchCause`. - **`firstMatch` short-circuits.** The scan stops at the first match; later candidates are never probed. A marker predicate can be expensive — `isWorkspaceRoot` reads and parses a `package.json` — so this is not just an optimization. Every upward error channel is `never` — including `ascend`'s, whose two caller-error guards (`maxDepth`, `stopAt`) are **defects**, not failures. The one typed error in the package is `descend`'s `DescendError` — see below. ## `descend` — the downward glob-file walker `descend(pattern, options)` expands a compiled `@effected/glob` `GlobPattern` under `options.cwd`, returning matching FILE paths relative to `cwd`, POSIX separators, sorted. The walker is **semantics-free**: dotfile behavior and every other matching option are carried by the compiled pattern the caller hands in — never re-derived here. - **A path is answered in the spelling it matched under**: `./src/*.ts` answers `./src/a.ts`, as it always has. Consumers re-filter the answer with a spelling-sensitive `matches` (`@effected/github-actions`' `CacheKey` does), so never canonicalize output. Internally the walk IS canonical. `enumerationRoots` prefixes are canonical, and each root carries its alternatives' `spellings` in pattern order. The machine reads each canonical directory once and answers a file ONCE, in the first spelling it matches under: the earliest alternative's. `{src,./src}/*.ts` reads `src` once and answers `src/index.ts` alone, and `./` never makes `cwd` look like a boundary. Unreadable and depth-exceeded paths are spelled through the root's own earliest spelling (`./**` reports its base as `.`). - A literal pattern (no magic, no braces, not negated) fast-paths to one stat; missing is zero matches. The stat and the answer are the compiled row glob matches (`enumerationPrefix` of a one-row literal is the whole row), never the source: an escape is undone (`src/\x/f.js` stats `src/x/f.js`), and at level 1 and up glob has popped `

/..` (`f.js/x/..` answers `f.js`, as minimatch and node-glob read it), and an answer that does not match as spelled is none. A `.`, `..` or empty segment the row keeps (level 0) is resolved physically by `resolvesPhysically`: it must follow an `lstat` Directory, never a file, a missing name or a link, because `join` normalizes it lexically where the kernel fails ENOTDIR or ENOENT (#1283). Without `followSymlinks` no directory such a path passes through may be a link (`link/e/..` reaches `link` through it, #1290); under it a link may be passed through, and a `.` or empty segment after one names its target (`link/./*.js` answers `link/./d.js`), while a `..` after one is still refused, since the kernel resolves it from the target. A magic root's spellings pass the same check: a spelling that does not resolve (`f.js/../` at level 0) answers nothing. Braces are magic here (glob's `hasMagic` ignores them). A magic pattern walks each of `enumerationRoots` — one per brace alternative, each with its own prefix and depth, so `packages/{a,b}/src/*.ts` reads only those two directories; a **negated** pattern walks from `cwd` itself (its matches can land outside the inner pattern's prefix); a missing base directory is an **empty result**, not an error. A pattern that lexically climbs above `cwd` via `..` segments is zero matches, refused before any filesystem access — the walk never reads outside its documented root lexically, and physically only while `followSymlinks` is off (under it a link targeting outside `cwd` IS descended, as `@actions/glob` follows links out of the tree). - Only files match. A symlink counts when it stat-resolves to a file (`stat` follows links, as node's does); a symlinked **directory is never descended** by default (cycle safety, detected by an `lstat` kind check) — the walk base and each directory on the way to it included: a base reached through a link is an empty result, and so is a literal pattern reached through one — unless `followSymlinks: true` opts in — then links are entered under `@actions/glob`'s per-branch `traversalChain` guard: each `DescendFrame` carries its branch's ancestor real paths, and a directory is a cycle only when its real path is already an ancestor of the branch it sits on. The guard is per-branch, never walk-global — two sibling links to one target BOTH enumerate (a global visited set silently dropped the second, and a test pins that it does not). Only the base and each link pay a `FileSystem.realPath`; a plain directory's real path is its parent's plus its name. A link whose `realPath` fails is never entered, and the failure goes through `onUnreadable` like a failed `readDirectory` (NotFound stays the silent benign race). Dangling = no match either way. - Unreadable directory mid-walk: `onUnreadable: "fail"` (default) fails typed as `DescendError` — the OPPOSITE of the upward per-probe absorption, because a swallowed subtree in a downward enumeration is silently missing membership. `"skip"` absorbs and continues. `"record"` absorbs and resolves to a `DescendResult { matches, unreadable }` instead of a bare array, where each `UnreadableDirectory` is `{ path, cause }` — the absorbed `readDirectory` (or, for a link under `followSymlinks`, `realPath`) `PlatformError` travels with the entry, so a caller that must report WHY never re-reads the directory. The walk base records as `path: ""`. A NotFound mid-walk is a benign vanished-directory race and reads as empty in every mode — it is never recorded. - Depth past `maxDepth` (default 256) is a typed `depthExceeded` failure, never a truncation; an invalid `maxDepth` is a **defect**, exactly `ascend`'s guard. - The descent is a worklist dequeued by head index (never `Array.shift()`), and a pattern that cannot match below one level (`crossesSegments` false and not negated) reads a single level and never descends. - **The pattern bounds its own reads** (`internal/patternBounds.ts`, applied in the machine before the `maxDepth` check). Without a globstar no directory deeper than the source's separator count can reach is queued. Under `dot: false` no hidden directory is queued unless a segment names one. Glob exposes no `dot`, so a differential `matches` probe proves it. Neither bound holds, and nor does the literal fast path, for a pattern glob reports `matchesByBasename`: `matchBase` is on and some brace alternative compiles to ONE path portion, which matches by basename at any depth (`*.js` and `x/../*.js` match `b/d/f/g.js`, #1261; `**` matches `.a/f.js`; `c.js` matches `b/c.js`). glob reads it off the compiled rows, the test matching itself applies, so walker never re-derives it from the source: a multi-portion pattern (`src/[ab]/*.ts`, `src/{a,b}*/*.ts`) keeps its depth bound and a tight `maxDepth` under `matchBase`, and a bare `**` without `matchBase` prunes hidden directories like any other. `__test__/PatternBoundsSweep.test.ts` compiles every pattern of up to three segments over a fixed alphabet and every option that rewrites rows, pins that nothing pruned matches inside a hidden directory, and walks 94,528 compilations (braces, classes, extglobs and escapes included, under `matchBase`, `dot` and every level) with `descendSync` over a memfs tree against a brute-force `matches` filter, plus every bounded one again under the tightest `maxDepth` its separators allow: zero differences. The literal fast-path classes (a literal running past a file through `.`/`..`, an escaped literal) are compared too: the filter resolves every spelling physically against the tree, as the fast path and a magic root's spellings do (#1283, #1290). Extend its alphabet, never patch one spelling at a time. They skip READS only, never a match, so the answer is unchanged. They are why a bounded pattern never trips `maxDepth` or an unreadable directory it has no reason to enter. Never make either bound "tighter" by guessing: an unmodelled syntax answers "no bound". `__test__/DescendBounds.test.ts` counts reads through both drivers. - `prune` suppresses **directories only** — a FILE named `.git` (a submodule or worktree gitlink) stays matchable. ## One walk, two drivers The downward walk is ONE generator, `src/internal/descendMachine.ts`, yielding filesystem requests (`Stat`, `Lstat`, `RealPath`, `ReadDirectory`). `descend` / `descendEntries` (`Descend.ts`) answer them through core's `FileSystem`; `descendSync` / `descendEntriesSync` (`DescendSync.ts`) answer them from a caller-supplied `WalkerSyncFileSystem` (a `node:fs`-shaped port: `readDirectory`, `stat`, `lstat`, `realPath`; `code: "ENOENT"` is the benign race). Every rule lives in the machine — **never put one in a driver**; a driver only maps its platform's answers and failures. Path joining is a caller function, not a request. The sync forms are on the root entry (pure); `@effected/walker/node-sync` binds them to Node (`nodeWalkerSyncOps`), and `__test__/entrypoints.test.ts` pins that `.` never reaches it. Sync record-mode causes are `unknown` (`UnreadableDirectory`): the port has no `PlatformError`. Otherwise the sync forms return the Effect forms' own types (`DescendResult`, `DescendEntry`, `DescendEntriesResult`) — never add parallel sync result types — and an entry's stat lives on `info`. A memfs handle satisfies the sync port directly (its sync interface carries `realPath`). - **`boundaries`** — marker FILE names. A directory strictly below `cwd` holding one contributes nothing (no matches, no descent); `cwd` itself is never a boundary and a directory merely *named* like a marker does not count. The rule is positional: it also applies between `cwd` and the walk base and to a literal pattern, so the answer never depends on whether the pattern has magic. Not `Walker.ascend`'s `stopAt` (an inclusive upward ceiling) — keep the names apart. - **`descendEntries`** keeps the stat the walk already read (no extra syscall). The kit ships no fingerprint: which fields to hash is the consumer's policy. - `__test__/DescendSync.test.ts` is a parity matrix — sync vs `Effect` over ONE memfs volume, with faults mirrored on the sync port. It needs fixtures that reach every driver mapping (a vanished directory, an unresolvable and a denied link); without them a broken `ENOENT` mapping passed. The sync fault handlers (`readDirectory`, `realPath`) mirror the Effect ones. ## One upward machine, two drivers The upward forms and `confineReal` run ONE generator, `src/internal/upwardMachine.ts`, yielding `Exists`, `RealPath` and `Present` requests; `src/internal/upwardDrivers.ts` answers them through core `FileSystem` or the sync port (`stat` succeeding = exists; `realPath` throwing `ENOENT` = not found; `lstat` succeeding = present). Same rule as the downward walk: **never put a rule in a driver**. `ascend` is pure and calls the machine's `ascendChain` with no driver, so its `R` stays `Path`. `__test__/WalkerSync.test.ts` and `ConfineReal.test.ts` are parity matrices over one memfs volume. `WalkerSyncPath` mirrors core `Path` (`sep`, `join`, `dirname`, `resolve`, `isAbsolute`). The port also carries `readFile(path): string` (UTF-8, as memfs's sync port answers it), which no walk calls: it serves the caller's own reads beside a walk. - `findUpwardSyncWith(dirs, accept, { cache })` is the validating search: the nearest dir whose `accept` returns `Option.some`. It runs no machine, because walker reads nothing there. Stop rules come from the `dirs` chain. The cache is a caller-owned per-directory memo of accept's answers, rejections included. A throwing `accept` propagates uncached. - `findUpwardWith(dirs, accept, { cache })` is its Effect form: `accept` answers `Effect, E, R>`, the scan and cache are the same, and `E` is not absorbed — a failure or interruption of `accept` ends the search with nothing cached for that directory (earlier entries stay). Recover inside `accept` to treat a failed read as "not valid". - `ascendToMarker` stops at the nearest directory holding a marker ENTRY (any kind), probing nothing above it; empty markers / an empty name die. - `findUpwardAll` probes the whole nearest hit directory, nothing above it. - `confineReal` resolves SEGMENT BY SEGMENT. Never replace that with one `realPath` of a `..`-bearing path: node's JS `fs.realpath` (the Node `FileSystem` off win32) runs `path.resolve` first, so `base/link/../x` would read as inside while the OS opens the link target's sibling. memfs's `realPath` is physical, so the `out/../passwd` cases catch a walker that collapses `..` itself, but NOT one that hands the whole path to a lexical-first `realPath` — no memfs volume behaves that way. Unresolvable is refused, the base itself is `empty`, a relative base dies. - **`NotFound` from `realPath` is never proof of absence.** A dangling link answers it too, and a write through one creates the target wherever it points. Every not-found segment is re-asked with `Present` (`lstat`); only "nothing lives here" continues lexically, while a present entry (the dangling link) or a failed `lstat` is `unresolvable`. A dangling link is refused even when its target would be inside the base: nothing resolved proves where it leads. Never drop the `Present` request to save a syscall. - Every caller-named root (`cwd`, the confine base, `stopAt`, a ceiling) goes through `internal/absolute.ts`'s `isPinnedAbsolute`: on win32 a driveless `\repo` is absolute to `isAbsolute` yet names whichever drive the process is on, so it dies like `C:repo`; UNC `\\server\share` is fine. A candidate spelled `\x` is refused `absolute`, mirroring `C:x`. - `descend`'s `cwd` must be absolute (relative and `""` die: the empty-base drive escape, `join("", "C:/x")`), and a missing `cwd` is an empty answer. - `match: "directory" | "any"` matches a directory as its parent's entry, by resolved kind; prune/boundaries/unentered links withhold only what lies below it. ## `PosixPath` POSIX path arithmetic as static methods, ported from core's `posixImpl` (`Path.ts`), imported by nothing in the walker. No `resolve`. `relative` never reads a working directory: it answers two absolute paths as core does, and two relative paths when every working directory agrees. Otherwise it throws. `__test__/PosixPath.test.ts` holds it to `node:path/posix`, with `relative` checked against 125 colliding working directories. Never "fix" a throw by assuming a name. ## Invariants - `ascend` is **lexical, not physical**: `Path.dirname` does not resolve symlinks, so ascending out of a symlinked directory follows the given path. Correct for config discovery. A **physical** ceiling (`Git.repoRoot`'s answer) never matches `stopAt` from a symlinked start; that is `Walker.ascendWithin`, a separate static so `ascend`'s `R` stays `Path` alone → `okf/decisions/physical-ceiling-is-a-separate-static.md` — Load when: touching `stopAt`, `ascendWithin`, or bounding a walk by a repository root. - `ascend` is a bounded `for` loop, not recursion. It terminates at `dirname`'s root fixpoint; `maxDepth` (default 256) guards a pathological `Path`. - `stopAt` must be **absolute** and is compared in **normalized** form (`path.resolve` on both sides), not by raw string equality; it stays **inclusive**. Raw equality made the ceiling fail **open**: an unnormalized ceiling matched nothing and the ascent ran to the filesystem root with no error to notice it by. Normalization is idempotent, so a caller that resolves first is unaffected. Both sides go through `resolve` — normalizing only the ceiling would desynchronize it from an unnormalized chain element (`/a/b/.` names `/a/b`). - A **relative** `stopAt` is a **defect** (`Effect.die`), exactly as an invalid `maxDepth` is, and is never resolved against `process.cwd()`. Resolving one would let the same ceiling name different directories in a hook, a CLI and a test runner — the fail-open class again, through a different door. This is why `ascend` reads `process.cwd()` nowhere. Absoluteness is judged by the injected `Path`, so win32 accepts `C:\repo`. Only the **ceiling** is constrained: a relative `start` still ascends to the relative root, and a test pins that the rejection was not over-applied to `start`. - **Never "upgrade" the `stopAt` guard to a typed error.** `@effected/config-file`'s resolver contract absorbs every typed failure into `Option.none()`, so a typed rejection would be swallowed there and re-emerge as a clean-looking "no config found" — the silent wrong answer the guard exists to prevent. `Effect.catch` does not catch defects, so only a defect survives that absorption. A test reconstructs the absorbing caller and pins it. This is the same failure-vs-defect line as `maxDepth`: malformed input fails typed, a statically-wrong caller option dies. - Normalization governs the **comparison only** — the returned chain stays the lexical one derived from `start`, because rewriting it would break the lexical contract for every caller that passes no `stopAt` at all. - `maxDepth` must be a **positive integer**. Anything else — `< 1`, `NaN`, or a non-integer like `2.5` — is a **defect** (`Effect.die`), never a silently-empty chain. The guard is `!Number.isInteger(maxDepth) || maxDepth < 1`, because `NaN < 1` and `2.5 < 1` are both `false`. - `findUpward` is **directory-major**: every candidate in the nearest directory is exhausted before ascending. A candidate-major interleave would let a distant ancestor's `.apprc` beat a nearer `config/.apprc`. - `start` is required. Walker never reads `process.cwd()`. ## Build The bundler's default config carries the one narrow `_base` suppression (`{ messageId: "ae-forgotten-export", pattern: "_base" }`) for the synthesized base of the class factory behind each of the package's three tagged errors: `DescendError`, `PathEscapeError` and `GlobExpansionError`. It is one pattern covering all three. Never widen it.