@openclaw/openshell-sandbox 2026.9.2 → 2026.9.4

package/node_modules/@openclaw/fs-safe/docs/durability.md

@@ -0,0 +1,313 @@
+---
+title: Directory durability
+description: "Pin directory identities, fsync publication metadata, and durably create nested directory paths."
+---
+
+# Directory durability
+
+`@openclaw/fs-safe/durability` provides the directory side of crash-safe file
+publication. Flushing a file does not guarantee that its containing directory
+entry reached storage; callers that promise durable create, link, rename, or
+unlink operations must also synchronize the affected directory.
+
+```ts
+import {
+  ensureDurableDirectory,
+  pinDirectory,
+} from "@openclaw/fs-safe/durability";
+
+const repository = await ensureDurableDirectory({
+  directoryPath: "/srv/backups/sqlite",
+  mode: 0o700,
+});
+
+const pinned = await pinDirectory(repository, { label: "backup repository" });
+try {
+  await publishSnapshot();
+  const outcome = await pinned.sync();
+  if (outcome.status === "unsupported") {
+    // Decide at the product boundary whether this platform can weaken the promise.
+  }
+} finally {
+  await pinned.close();
+}
+```
+
+## Outcomes and failure semantics
+
+`syncDirectory()` and `PinnedDirectory.sync()` return:
+
+```ts
+type DirectorySyncOutcome =
+  | { status: "synced" }
+  | { status: "unsupported"; code?: string };
+```
+
+POSIX synchronization failures propagate. Windows directory handles do not
+portably support `FlushFileBuffers`; the known unsupported error family is
+reported as `unsupported` after the pathname and pinned identity are checked
+again. Directory-open access failures and other Windows I/O failures still
+propagate.
+
+`syncDirectoryBestEffort()` and `syncDirectoryBestEffortSync()` intentionally
+discard both unsupported outcomes and failures. Use them only when the primary
+write remains useful without a crash-durability promise.
+
+## Pinned directories
+
+`pinDirectory()` rejects final symlinks and non-directories. On POSIX it opens
+with `O_DIRECTORY`, `O_NOFOLLOW`, and `O_NONBLOCK`, then compares the open
+descriptor, pathname identity, and canonical path. `assertCurrent()` repeats
+those checks. This prevents a pathname replacement from turning a later sync
+into proof for a different directory.
+
+Call `close()` in `finally`. Closing is idempotent; using a closed pin fails.
+
+These checks intentionally reject a moved or replaced pathname. For one file's
+abort cleanup through its original directory after a move, use the separate
+[retained-directory staging lifecycle](staged-file.md). Its cleanup authority
+does not weaken `pinDirectory().assertCurrent()` or `.sync()`, and namespace
+cleanup is not proof of crash durability.
+
+## Durable directory creation
+
+`ensureDurableDirectory()` finds and pins the nearest existing ancestor,
+creates the requested path, opens every new directory segment, and synchronizes
+each new parent-to-child edge from the leaf upward. It returns the final
+directory receipt plus the aggregate parent-sync outcome.
+
+By default it uses fs-safe's guarded one-segment-at-a-time absolute-directory
+creator. Advanced callers can pass `create` when directory creation needs
+platform-specific ACLs or another product-owned policy. The callback owns the
+safety of its mutations and must create exactly `directoryPath`; fs-safe
+validates and pins every resulting segment before any synchronization is
+accepted.
+
+`expectedExistingIdentity` binds an existing target to an identity observed by
+the caller before a separate permission or policy check. A missing or replaced
+target fails with `FsSafeError("path-mismatch")`.
+
+## Exclusive file publication
+
+`publishFileExclusive()` materializes one file without clobbering an existing
+target. It pins the source with nonblocking `O_NOFOLLOW`, optionally verifies
+`expectedSourceIdentity`, tries a hardlink first, then synchronizes the target
+parent directory.
+
+For example, a backup archive is complete before publication. If directory
+sync fails, keeping that complete file is more useful than conditionally
+deleting it by pathname:
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe/errors";
+import { publishFileExclusive } from "@openclaw/fs-safe/durability";
+
+try {
+  const result = await publishFileExclusive({
+    sourcePath: stagedArchive,
+    targetPath: finalArchive,
+    strategy: "link-or-copy",
+    onSyncFailure: "preserve",
+    parentReceipt: backupDirectory,
+  });
+  recordDurableBackup(result.identity, result.directorySync);
+} catch (error) {
+  if (
+    error instanceof FsSafeError &&
+    error.details?.phase === "directory-sync" &&
+    error.details.cleanup === "preserved"
+  ) {
+    recordCompleteButPossiblyNonDurableBackup(finalArchive, error.details);
+  } else {
+    throw error;
+  }
+}
+```
+
+### Strategies
+
+| Strategy | Behavior | Native requirement |
+|---|---|---|
+| `link-required` | Create a same-filesystem hardlink or propagate the failure. | No; guarded JS `link` fallback remains. |
+| `link-or-copy` | Try hardlink, then clone, Linux `copy_file_range`, then the JS byte loop for classified unsupported errors. | No; acceleration is optional. |
+| `rename-noreplace` | Atomically move the source without replacing an existing target. Success consumes `sourcePath`. | Yes. |
+
+`"link-required"` propagates an unsupported hardlink failure.
+`"link-or-copy"` falls back only for `EPERM`, `EXDEV`, `ENOTSUP`,
+`EOPNOTSUPP`, or `ENOSYS`; `isHardlinkFallbackError()` exposes that exact
+classifier. The fallback copies from the pinned source into a `wx` target,
+fsyncs it, and fences source and target identity and content before reporting
+success. `parentReceipt`, when supplied, must name the target's direct parent.
+
+With a native binding, the copy fallback first attempts a copy-on-write clone
+(`fclonefileat` on macOS, `FICLONE` on Linux), then Linux
+`copy_file_range`, and finally the existing JavaScript byte loop. Every route
+creates the target exclusively, applies mode `0o600` through its owned
+descriptor independently of the process umask, and goes through the same
+post-copy identity and SHA-256 fencing. Hashing uses an async
+native task when available, so large verification reads do not occupy the
+JavaScript event loop.
+
+On a clone-capable filesystem, publication of a large file becomes mostly a
+metadata operation: data blocks are shared copy-on-write until either file is
+modified. Clone support is filesystem- and mount-dependent, so callers must
+not infer durability or physical independence from timing; an unsupported
+clone or `copy_file_range` transparently continues down the fallback chain.
+
+## Recoverable atomic-replace fallback
+
+`replaceFileAtomic()` normally publishes a synchronized sibling temp with an
+atomic rename. Some Windows filesystems and file owners reject that rename with
+`EPERM` or `EEXIST`; `copyFallbackOnPermissionError: true` permits a non-atomic
+copy fallback.
+
+Callers that cannot tolerate a torn in-place fallback can add:
+
+```ts
+await replaceFileAtomic({
+  filePath: statePath,
+  content: nextState,
+  syncTempFile: true,
+  syncParentDir: true,
+  copyFallbackOnPermissionError: true,
+  copyFallbackRestore: "restore-original",
+  maxRestoreBytes: 4 * 1024 * 1024,
+  destinationHardlinks: "reject",
+});
+```
+
+The existing regular-file destination is pinned before its link count is
+accepted. Its original bytes are read within `maxRestoreBytes`, then the new
+bytes are written and synchronized through the same descriptor. If a write or
+sync tears, fs-safe rewrites the snapshot and fsyncs it before throwing. Inspect
+`details.cleanup`: `"restored"` means the original bytes were put back and
+synchronized; `"restore-failed"` means the replacement and recovery both
+failed, so the destination must be treated as indeterminate. This is recovery
+from a live-process I/O failure, not a transaction or a substitute for an
+application backup protocol.
+
+## Streaming SHA-256
+
+`sha256File()` hashes either a pathname string or an already-open Node
+`FileHandle`. A backup verifier can pin the file itself, compare its size, and
+keep ownership of the handle:
+
+```ts
+import { open } from "node:fs/promises";
+import { sha256File } from "@openclaw/fs-safe/durability";
+
+const snapshot = await open(stagedArchive, "r");
+try {
+  const before = await snapshot.stat();
+  const hash = await sha256File(snapshot);
+  if (hash.bytes !== before.size || hash.digest !== manifest.sha256) {
+    throw new Error("staged backup does not match its manifest");
+  }
+} finally {
+  await snapshot.close();
+}
+```
+
+The result is `{ bytes, digest }`, where `digest` is lowercase hexadecimal.
+The handle overload never closes the caller's descriptor and uses positioned
+reads, so it does not alter the descriptor's current offset. The path overload
+rejects symbolic links and non-regular files, compares lossless bigint identities
+from the pre-open pathname inspection to the opened descriptor and from that
+descriptor to the current pathname, and closes its own handle. All identity
+checks complete before any JavaScript or native hashing. Each inspection allows
+one bounded retry for unknown Windows identity components, retaining known
+components and rejecting known differences immediately. Persistent unknown
+identity fails closed with `path-mismatch`, even for benign files: this trades
+availability for verifiable identity. Retries inspect the same descriptor or
+pathname without reopening the file and repeat the symlink and file-type checks.
+POSIX opens are nonblocking, so a raced FIFO or device is rejected after
+descriptor inspection rather than waiting for a writer.
+
+When the optional binding is active, hashing runs as an async native task and
+does not occupy the JavaScript event loop with digest updates. With native mode
+`off`, or in `auto` when no binding loads, the fallback performs asynchronous
+positioned reads in 64 KiB chunks but updates Node's `Hash` on the JavaScript
+thread. Both paths stream constant-size buffers rather than loading the file
+into memory. Native mode `require` keeps its usual fail-closed loader semantics.
+
+If publication fails after this call created the target, it throws an
+`FsSafeError` with a `details` receipt:
+
+```ts
+type PublishFileExclusiveFailureDetails = {
+  phase:
+    | "hardlink-create" | "hardlink-verify"
+    | "copy-create" | "copy-verify"
+    | "rename-create" | "rename-verify"
+    | "directory-sync";
+  targetCreated: boolean;
+  targetIdentity?: { dev: number | bigint; ino: number | bigint };
+  cleanup: "removed" | "preserved" | "unknown";
+  directorySync?: { status: "failed"; code?: string };
+};
+```
+
+`"removed"` means the path still matched the identity created by this call and
+was unlinked (or was already absent). `"preserved"` means it was deliberately
+retained—for example after a successful no-replace rename—or the pathname had
+been replaced and therefore was not safe to remove. `"unknown"` means cleanup
+could not verify or remove the created identity. Callers that run a second
+application-level guard, such as SQLite snapshot validation, should branch on
+this receipt instead of inferring ownership from path existence. The original
+failure remains available as `cause`. Failures before target creation retain
+their existing error shape and do not claim a cleanup result.
+
+### Directory-sync failure policy
+
+`onSyncFailure` applies only after target creation and content/identity fencing
+have succeeded but synchronizing the containing directory throws:
+
+```ts
+type PublishFileExclusiveSyncFailurePolicy = "rollback" | "preserve";
+```
+
+A returned `{ status: "unsupported", code? }` is an explicit successful
+publication outcome, not a thrown sync failure, so this option does not rewrite
+or clean up that target.
+
+- `rollback` is the default. fs-safe removes the target only if its current
+  identity still matches the file created by this call. A replacement is never
+  removed. The error reports `cleanup: "removed"`, `"preserved"`, or
+  `"unknown"` and `directorySync: { status: "failed", code? }`.
+- `preserve` never attempts that unlink. The error reports
+  `targetCreated: true`, `cleanup: "preserved"`, the created identity, and the
+  failed directory-sync outcome. The file is complete and fenced, but its
+  directory entry is not proven crash-durable.
+
+Choose `rollback` when the pathname must mean “durably committed” and a failed
+commit should disappear from the live process view. Choose `preserve` when the
+payload itself remains valuable—backup archives are the common case—and the
+caller can record, retry, or independently validate durability. Neither choice
+can make a failed directory sync succeed: rollback deletion is also not proven
+durable, and a preserved name may disappear after a crash. Always use the
+typed receipt rather than inferring ownership from `exists()`.
+
+`rename-noreplace` always preserves its target after a successful rename,
+because removing it would discard the source's only remaining name; its typed
+failure receipt makes that explicit regardless of `onSyncFailure`.
+
+`"rename-noreplace"` requires the native helper and atomically moves the
+source to the target without replacement. A collision is reported as
+`EEXIST`, both files remain unchanged, and a successful call returns
+`method: "rename-noreplace"` after synchronizing the source and target parent
+directories. Unlike the link/copy strategies, success consumes `sourcePath`.
+
+## Scope
+
+These primitives establish path identity and filesystem synchronization. One
+`publishFileExclusive()` call is one no-clobber file materialization, not a
+retention policy, multi-file transaction, or application commit protocol. They
+do not decide application commit protocols, marker formats, permission policy,
+or whether an unsupported platform is acceptable. Keep those decisions at the
+owning product boundary.
+
+## See also
+
+- [Migrating to 0.5](migrating-to-0.5.md) — choosing a publication policy during upgrade.
+- [Native architecture](native.md) — clone/copy/hash mechanisms and fallback guarantees.
+- [Errors](errors.md) — typed operational failure handling.

package/node_modules/@openclaw/fs-safe/docs/errors.md

@@ -0,0 +1,232 @@
+# Errors
+
+Every failure that's the library's job to surface lands as an `FsSafeError` with a closed `code` union you can branch on. Catch by code, not by message text — messages may change, codes will not.
+
+Result-based APIs are an exception to throwing: [`pathScope().ensureDir()`](path-scope.md#ensuredir-rel-options)
+and `ensureDirectoryWithinRoot()` return operational failures as
+`{ ok: false, error: string, diagnostic: FsSafeError }`. The diagnostic uses
+`helper-failed` / `operational`, retains the exact native error in `cause`, and
+has the same message as `error`. Its display text names the native code/syscall
+when available but omits raw paths and native messages. Policy failures keep
+the string-only result without `diagnostic`; other `pathScope` methods do not
+gain this field. Directory preparation can partially complete before failing.
+
+Path and archive-entry details embedded in diagnostics escape control characters
+as `\\uXXXX` sequences. This keeps attacker-controlled names on one log line;
+the escaped message is for diagnosis, not for reconstructing the original path.
+
+```ts
+import { FsSafeError, type FsSafeErrorCode } from "@openclaw/fs-safe";
+```
+
+## Shape
+
+```ts
+class FsSafeError extends Error {
+  readonly name: "FsSafeError";
+  readonly code: FsSafeErrorCode;
+  readonly category: "policy" | "operational";
+  readonly details?: Readonly<Record<string, unknown>>;
+
+  constructor(
+    code: FsSafeErrorCode,
+    message: string,
+    options?: { cause?: unknown; details?: Readonly<Record<string, unknown>> },
+  );
+}
+```
+
+`cause` is available through the standard `Error` `cause` property when the failure was triggered by a `NodeJS.ErrnoException` (e.g. a wrapped `EACCES`). Inspect it for the original `code` / `errno` / `syscall` if you need finer-grained reporting.
+
+`details` is an operation-specific receipt, not an alternate error code. For
+example, `publishFileExclusive()` uses it to report the failing phase, created
+target identity, cleanup decision, and failed directory-sync outcome. Narrow
+by `code` and a documented details field before consuming it; do not assume all
+`FsSafeError` instances carry the same keys.
+
+`replaceFileAtomic({ copyFallbackRestore: "restore-original" })` reports a
+failed copy fallback with the exported `ReplaceFileAtomicRestoreFailureDetails`
+shape:
+
+```ts
+type ReplaceFileAtomicRestoreFailureDetails = {
+  cleanup: "restored" | "restore-failed";
+};
+```
+
+Both outcomes use `code: "helper-failed"`. `"restored"` means the original
+snapshot was written back and fsynced through the pinned destination handle.
+`"restore-failed"` means both the replacement and recovery failed; `cause` is
+an `AggregateError` containing both failures. A snapshot that exceeds
+`maxRestoreBytes` fails earlier with `too-large` and does not overwrite the
+destination.
+
+`category` separates caller-policy failures from operational failures:
+
+- `"policy"` — unsafe input or target state rejected by a safety policy, such as `outside-workspace`, `symlink`, `hardlink`, or `too-large`.
+- `"operational"` — routine filesystem outcomes or environment/runtime failures, such as `not-found`, `not-empty`, `not-removable`, helper startup, platform support, timeout, or unverifiable permissions.
+
+Routine absence or inability to remove a path does not by itself indicate a
+filesystem boundary violation. Branch on the specific code when the distinction
+between those operational outcomes matters.
+
+The operational set is exactly `helper-failed`, `helper-unavailable`,
+`not-empty`, `not-found`, `not-removable`, `permission-unverified`, `read-failed`,
+`timeout`, and `unsupported-platform`. Every other current `FsSafeErrorCode`, including
+`store-reentrant-update`, is categorized as `policy`.
+
+## Code union
+
+```ts
+type FsSafeErrorCode =
+  | "already-exists"
+  | "denied-path"
+  | "device-path"
+  | "hardlink"
+  | "helper-failed"
+  | "helper-unavailable"
+  | "insecure-permissions"
+  | "invalid-path"
+  | "not-empty"
+  | "not-file"
+  | "not-found"
+  | "not-owned"
+  | "not-removable"
+  | "outside-workspace"
+  | "path-alias"
+  | "path-mismatch"
+  | "permission-unverified"
+  | "read-failed"
+  | "secret-exists"
+  | "store-reentrant-update"
+  | "symlink"
+  | "timeout"
+  | "too-large"
+  | "unsupported-platform";
+```
+
+## Code reference
+
+| Code | When it fires | Common causes |
+|---|---|---|
+| `already-exists` | `create()`, `createJson()`, `move({ overwrite: false })`. | Target file or directory already at the destination. |
+| `denied-path` | A root mutation matched `denyMutations.paths` or `denyMutations.prefixes`. | Caller configured application-sensitive paths that must not be written, removed, moved, or created. |
+| `device-path` | A read/open target is a known unsafe device or process-fd path. | `/dev/zero`, `/dev/random`, `/dev/stdin`, `/dev/fd/*`, `/proc/*/fd/*`, or a Windows reserved device name. |
+| `hardlink` | Read or copy with `hardlinks: "reject"` saw `nlink > 1`. | File is hardlinked — possibly an alias of an out-of-tree inode. |
+| `helper-failed` | A native mechanism or multi-step operational helper failed. | Inspect `cause` and any operation-specific `details`; retrying may be unsafe if the operation partially completed. |
+| `helper-unavailable` | Required native binding could not be loaded. | Unsupported platform, omitted/missing/incompatible platform package, or `FS_SAFE_NATIVE_MODE=require`. `auto` falls back where possible; `require` fails closed. |
+| `insecure-permissions` | A secure file or path permission check found a mode/ACL that allows broader access than requested. | File or directory is group/world writable/readable; Windows ACL grants broad read. |
+| `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable; a FileStore key used a noncanonical spelling. | Noncanonical FileStore aliases, backslashes, or complete parent segments; a network path on Windows; a drive-relative segment in a portable relative path or store key; or a leading drive-relative spelling such as `C:name` used as a Root destination. Existing-object Root lookups retain broader confined path compatibility, including legal POSIX drive-like names. |
+| `not-empty` | `remove()` on a non-empty directory. | Use `replaceDirectoryAtomic` or remove children first. |
+| `not-file` | Read or copy targeted a non-regular file, or a path walk found a non-directory ancestor. | Target was a directory, FIFO, socket, device, or an existing file was followed by another segment. |
+| `not-found` | The target does not exist (or its parent does not, with `mkdir: false`). | Typical missing-file case. |
+| `not-owned` | A secure file owner check failed. | File is owned by another UID. |
+| `not-removable` | `remove()` couldn't `unlink`/`rmdir` for a reason other than non-empty. | Permissions, device busy, immutable bit. |
+| `outside-workspace` | Path resolves outside the configured root. | `..` traversal; absolute path outside the root; symlink resolved out. |
+| `path-alias` | A path alias check failed (e.g. canonical-real-path moved out of the root). | Symlink resolution lands outside the root. |
+| `path-mismatch` | Post-open identity check failed: the opened fd does not match the resolved path. | TOCTOU — something else swapped the path between resolve and open. |
+| `permission-unverified` | A secure file check could not verify required permissions. | Windows ACL inspection failed; POSIX ownership/mode was unavailable. |
+| `read-failed` | A validated file could not be read because of an operational filesystem or device failure. | I/O error, media failure, or another runtime read failure; inspect `cause`. |
+| `secret-exists` | `createSecretFileAtomic()` found an existing final path. | First-writer-wins secret creation lost a race or the credential was already initialized. |
+| `store-reentrant-update` | A `JsonStore.update()` callback called `update()` or `updateOr()` for the same canonical store before returning. | Reentrant mutation would deadlock or lose an update; return the complete next value from the outer callback. |
+| `symlink` | Path component is a symlink, policy is `reject`. | Caller followed a symlink they shouldn't have, or `symlinks: "reject"` is set. |
+| `timeout` | An operation with a wall-clock budget overran. | Secure file read or timed operation exceeded `timeoutMs`. |
+| `too-large` | A read or bounded walk exceeded its configured budget. | Caller gave a too-permissive file or traversal limit. |
+| `unsupported-platform` | Reserved compatibility code for a platform-specific operation. | No current public helper emits this `FsSafeError` code. Platform-specific APIs currently return a typed unsupported result or use `helper-unavailable`; keep the union member when exhaustively switching across supported package versions. |
+
+Secret writes reject invalid `mode` / `dirMode` values with `invalid-path` before directory creation. Existing secret directories with a mode different from the requested `dirMode` report `insecure-permissions` without chmod; a created directory whose descriptor ownership no longer matches its initializing effective user reports `not-owned`.
+
+Pathname `sha256File()` also reports `path-mismatch` when pre-open, descriptor,
+or current-path identity remains unknown after one bounded Windows retry, even
+if the file is benign. It never reopens to recover identity. Preview symlinks
+report `symlink`, preview or descriptor non-files report `not-file`, and a
+current-path symlink or non-file reports `path-mismatch`.
+
+## Branching
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe";
+
+try {
+  await fs.write("../escape.txt", "x");
+} catch (err) {
+  if (!(err instanceof FsSafeError)) throw err;
+  switch (err.code) {
+    case "outside-workspace":
+      return reply(400, "path escapes workspace");
+    case "already-exists":
+      return reply(409, "exists");
+    case "too-large":
+      return reply(413, "too large");
+    case "not-found":
+      return reply(404, "missing");
+    case "symlink":
+    case "device-path":
+    case "hardlink":
+    case "path-mismatch":
+    case "path-alias":
+      return reply(400, "unsafe path");
+    default:
+      throw err;
+  }
+}
+```
+
+The `default` above deliberately rethrows unknown codes, so it remains safe as
+the union grows. If you want the compiler to flag every newly added code, end
+an exhaustive switch with a `never` assertion instead of a general `default`.
+
+## Distinguishing from `NodeJS.ErrnoException`
+
+Some failures bubble up as native Node errors (e.g. `EACCES`, `EPERM`, `EISDIR`, `EBUSY`) when they don't map cleanly to a library code. Inspect both:
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe";
+
+try {
+  await op();
+} catch (err) {
+  if (err instanceof FsSafeError) {
+    handleFsSafe(err);
+    return;
+  }
+  const code = (err as NodeJS.ErrnoException).code;
+  if (code === "EACCES" || code === "EPERM") {
+    handleAccess();
+    return;
+  }
+  throw err;
+}
+```
+
+A common pattern is to wrap your domain code in a single try/catch that maps both shapes to your application's typed error format.
+
+On Windows, access-denied failures from native root/open filesystem operations
+use `EPERM` to match Node/libuv and the JavaScript fallback. Security-descriptor
+inspection has its own failure surface. Older fs-safe versions could report
+`EACCES` for the same root/open condition, so consumers spanning versions
+should accept both codes.
+
+## Specialty errors
+
+A handful of helpers throw their own typed errors instead of `FsSafeError`:
+
+- `JsonFileReadError` — thrown by [`readJson`](json.md). Carries `cause` so you can distinguish missing (`ENOENT`) from invalid (`SyntaxError`).
+- `ArchiveLimitError` — thrown by [`extractArchive`](archive.md) when an archive size, entry count, path depth, metadata, or extracted-byte budget is exceeded. The `code` field uses the string values exposed by `ARCHIVE_LIMIT_ERROR_CODE` (for example `archive-entry-path-components-exceeds-limit`).
+- `ArchiveSecurityError` — thrown by extraction when entry policy or destination safety fails. Entry codes are `entry-path`, `entry-link`, and `entry-filtered`; destination codes cover non-directory, symlink, and symlink-traversal failures.
+
+These are exported from their respective subpaths.
+
+## Why `FsSafeError`?
+
+Two reasons it isn't a richer hierarchy of subclasses:
+
+1. **Switch on `code`, don't `instanceof` a tree.** `code` is a closed string union the TypeScript compiler can exhaust-check. Subclasses make `instanceof` ladders that drift over time.
+2. **One catch handler.** Library callers often want a single "is this an `fs-safe` failure?" gate before deciding what to do — `instanceof FsSafeError` plus a switch is the cleanest expression of that.
+
+## See also
+
+- [`root()`](root.md) — every method documents the codes it can throw.
+- [Reading](reading.md) — read-path codes.
+- [Writing](writing.md) — write-path codes.
+- [Archive extraction](archive.md) — `ArchiveLimitError` and `ArchiveSecurityError`.