@openclaw/fs-safe 0.5.1 → 0.5.3

package/docs/local-roots.md

@@ -1,11 +1,9 @@
 # Local roots
 
-`local-roots` is a small set of helpers for code that holds a list of trusted base directories ("roots") and wants to look up an absolute path or a relative-to-some-root reference against any of them.
-
-The shape covers two needs:
-
-- "Resolve this path string to an absolute path that lives inside one of the configured roots, or refuse it."
-- "Read this path, where it could be `/abs/path`, `~/relative`, `file://…`, or simply the basename of a file in one of my roots."
+The local-roots helpers accept a file path plus a list of trusted absolute
+directories and return the first canonical root that contains the file. Use
+them when configuration may name one of several approved media, cache, or
+workspace roots.
 
 ```ts
 import {
@@ -14,92 +12,102 @@ import {
 } from "@openclaw/fs-safe/advanced";
 ```
 
-## Shape of a "roots input"
+## Input shape
 
-Both helpers take roots as either an array of strings or a `LocalRootsInputOptions` record. Each root is an absolute path the caller already trusts:
+Both helpers take one options object. `filePath` may be absolute, home-relative,
+relative to the current working directory, or a local `file://` URL. Relative
+inputs are resolved exactly as Node resolves them; they are not searched as a
+basename under each root.
 
 ```ts
 type LocalRootsInputOptions = {
-  roots: string[];                    // absolute paths
-  allowAbsolute?: boolean;            // accept absolute inputs (default true)
-  allowFileUrls?: boolean;            // accept file:// URLs (default true)
-  expandHome?: boolean;               // expand ~ in inputs (default true)
+  filePath: string;
+  roots: readonly string[]; // trusted absolute paths, checked in order
+  label?: string;           // used in validation errors
 };
 ```
 
-If a root is a symlink, it is canonicalized at lookup time. The helpers work in the order roots are listed: the first root that contains the resolved path wins.
-
-## `resolveLocalPathFromRootsSync(input, options)`
+Roots may use `~` or local `file://` spellings, but each resolved root must be
+absolute. Existing root symlinks are canonicalized before containment is
+checked. Invalid root entries throw `FsSafeError("invalid-path")`; an invalid
+`file://` input throws `Error`. A path that is valid but does not fall inside
+any usable root returns `null`.
 
-Synchronous resolution. Returns:
+## `resolveLocalPathFromRootsSync(options)`
 
 ```ts
-type LocalRootsPathResult =
-  | { ok: true; absolutePath: string; rootDir: string; relativePath: string }
-  | { ok: false; reason: "outside-roots" | "invalid-input" };
+type ResolveLocalPathFromRootsSyncOptions = LocalRootsInputOptions & {
+  allowMissing?: boolean; // default false
+  requireFile?: boolean;  // default false
+};
+
+type LocalRootsPathResult = {
+  path: string; // canonical candidate path
+  root: string; // canonical containing root
+};
 ```
 
+For an existing upload:
+
 ```ts
 import { resolveLocalPathFromRootsSync } from "@openclaw/fs-safe/advanced";
 
-const r = resolveLocalPathFromRootsSync("photo.jpg", {
+const r = resolveLocalPathFromRootsSync({
+  filePath: "/srv/uploads/photo.jpg",
   roots: ["/srv/uploads", "/srv/cache"],
+  requireFile: true,
 });
 
-if (!r.ok) return reply(400, r.reason);
-console.log(r.absolutePath);  // /srv/uploads/photo.jpg (assuming it's there)
-console.log(r.rootDir);       // /srv/uploads
-console.log(r.relativePath);  // photo.jpg
+if (!r) throw new Error("photo is outside the configured roots");
+console.log(r.path); // canonical path to photo.jpg
+console.log(r.root); // canonical /srv/uploads
 ```
 
-### Resolution order
-
-For each candidate input:
-
-1. If the input is a `file://` URL and `allowFileUrls` is true, decode to an absolute path.
-2. If the input begins with `~/` and `expandHome` is true, expand to the user's home dir.
-3. If the input is absolute (`/...` or Windows drive) and `allowAbsolute` is true, accept it as-is and check it falls under one of the roots.
-4. Otherwise, treat the input as relative and resolve it against each root in order until one contains the resulting path.
-
-If no root contains the result, returns `{ ok: false, reason: "outside-roots" }`.
-
-`"invalid-input"` covers empty strings, embedded NULs, encoded `..` traversal, Windows network paths (`\\server\share`), and other constructs that should not be resolved at all.
+By default the candidate must exist. `allowMissing: true` instead canonicalizes
+the nearest existing ancestor and validates the missing tail, which is useful
+when selecting a future output location. `requireFile: true` rejects existing
+directories and other non-file leaves. Dangling symlinks and candidates whose
+ancestors cannot be canonicalized are rejected rather than treated as safe
+missing paths.
 
-## `readLocalFileFromRoots(input, options)`
+## `readLocalFileFromRoots(options)`
 
-Async. Resolves through the same logic, then reads the file via [`Root`](root.md) so the read benefits from boundary checks, `O_NOFOLLOW`, and fd identity verification.
+The asynchronous helper opens the candidate through the matched [`Root`](root.md),
+so no-follow, identity, hardlink, device-path, and byte-limit checks happen at
+the read itself.
 
 ```ts
+type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
+  hardlinks?: "reject" | "allow";
+  maxBytes?: number;
+  nonBlockingRead?: boolean;
+  symlinks?: "reject" | "follow-within-root";
+};
+
 type LocalRootsReadResult = ReadResult & {
-  rootDir: string;
-  relativePath: string;
+  root: string; // canonical containing root
 };
+```
 
-const r = await readLocalFileFromRoots("photo.jpg", {
+```ts
+const r = await readLocalFileFromRoots({
+  filePath: "/srv/uploads/photo.jpg",
   roots: ["/srv/uploads", "/srv/cache"],
   maxBytes: 8 * 1024 * 1024,
 });
-if (!r) return reply(404);
+if (!r) throw new Error("photo is missing, unreadable, or outside the roots");
 process.stdout.write(r.buffer);
 ```
 
-The result extends `ReadResult` (`{ buffer, realPath, stat }`) with the matched `rootDir` and the path relative to it. Returns `null` if the input doesn't resolve into any root or the file is missing.
-
-### Read options
-
-```ts
-type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
-  hardlinks?: "reject" | "allow";
-  maxBytes?: number;
-  symlinks?: "reject" | "follow-within-root";
-};
-```
-
-The read-side options are forwarded to `Root` for the actual read.
+The helper returns `null` when no configured root can be opened or no safe read
+succeeds. This intentionally collapses missing, outside-root, and per-root read
+failures; use a single `Root` directly when the caller must distinguish those
+outcomes. Omitting `maxBytes` preserves `Root`'s 16 MiB default.
 
-## `local-file-access` companions
+## File URL and Windows-path companions
 
-The `local-file-access` module (re-exported from `@openclaw/fs-safe/advanced`) supplies a few small helpers for input normalization that the roots helpers use under the hood. They are also useful on their own:
+The advanced surface also exports the normalization helpers used around this
+API:
 
 ```ts
 import {
@@ -113,52 +121,20 @@ import {
 } from "@openclaw/fs-safe/advanced";
 ```
 
-- `safeFileURLToPath(fileUrl)` — `url.fileURLToPath` with explicit error throwing. Refuses URLs that decode to network paths.
-- `trySafeFileURLToPath(fileUrl)` — same, returns `undefined` instead of throwing.
-- `isWindowsDriveLetterPath(p, platform?)` — true for `C:\...` style absolute paths when the platform is Windows.
-- `isWindowsNetworkPath(p, platform?)` — true for `\\server\share` and `//server/share` style paths when the platform is Windows.
-- `assertNoWindowsNetworkPath(p, label?)` — throws if it is.
-- `basenameFromMediaSource(source?)` — best-effort filename extraction from URLs / data URIs / paths, for naming downloaded media.
-- `hasEncodedFileUrlSeparator(pathname)` — true for paths containing percent-encoded `/` (`%2F` / `%5C`), which often indicate traversal attempts.
-
-## Common patterns
-
-### Multi-root config: search project, then user, then system
-
-```ts
-const text = await readLocalFileFromRoots(name, {
-  roots: [path.join(projectDir, "templates"), path.join(homedir(), ".app/templates"), "/etc/app/templates"],
-  allowAbsolute: false,  // only resolve names, never absolute paths
-  maxBytes: 256 * 1024,
-});
-```
-
-### Validate a file:// URL at the API boundary
-
-```ts
-import { safeFileURLToPath, isWindowsNetworkPath } from "@openclaw/fs-safe/advanced";
-
-let abs: string;
-try {
-  abs = safeFileURLToPath(req.body.fileUrl);
-} catch {
-  return reply(400, "invalid file URL");
-}
-if (isWindowsNetworkPath(abs)) return reply(400, "network paths not allowed");
-```
-
-### Deny absolute, allow relative-only
-
-```ts
-const r = resolveLocalPathFromRootsSync(input, {
-  roots: ["/srv/workspace"],
-  allowAbsolute: false,
-  allowFileUrls: false,
-});
-```
+- `safeFileURLToPath(fileUrl)` parses a local file URL and refuses remote hosts
+  or paths that decode to Windows network paths.
+- `trySafeFileURLToPath(fileUrl)` returns `undefined` instead of throwing.
+- `isWindowsDriveLetterPath()` and `isWindowsNetworkPath()` classify Windows
+  absolute and network spellings.
+- `assertNoWindowsNetworkPath()` throws for a network path on Windows.
+- `basenameFromMediaSource()` extracts a best-effort filename from a URL, data
+  URI, or path.
+- `hasEncodedFileUrlSeparator()` detects percent-encoded slash or backslash
+  spellings.
 
 ## See also
 
-- [`root()`](root.md) — single-root variant of this multi-root setup.
-- [Path helpers](path.md) — `isPathInside`, `safeRealpathSync` for ad-hoc checks.
-- [`pathScope()`](path-scope.md) — single-root with `Result`-style returns.
+- [`root()`](root.md) — use when one trusted root should preserve individual
+  failure codes.
+- [Path helpers](path.md) — lexical and canonical containment primitives.
+- [`pathScope()`](path-scope.md) — result-shaped single-root validation.

package/docs/native-helper.md

@@ -30,21 +30,27 @@ Configure the mode once during startup. Loading is lazy and cached; changing fro
 ## Native boundary
 
 The bundled native layer exposes policy-free filesystem mechanisms: beneath-root
-open/mkdir/link, no-replace rename, identity reads, archive decode/execution,
+open/mkdir/link, replace and no-replace rename, identity reads, archive decode/execution,
 clone/copy/hash workers, and Windows security descriptor calls. The TypeScript
 layer owns policy, retries, filters, budgets, modes, cleanup, error
 normalization, and the decision to fall back.
 
-- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS` and `renameat2(RENAME_NOREPLACE)`.
-- macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. No-replace publication uses `renameatx_np(RENAME_EXCL)`.
-- Windows uses handle-relative `NtCreateFile`, rejects reparse points, and uses `FileRenameInfoEx` with replacement disabled.
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`.
+- macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace.
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer.
 
-Native primitives back create-only pinned writes, async sidecar creation,
+Native primitives back create-only and replacing pinned writes, async sidecar creation,
 guarded publication, archive acceleration, and direct Windows ACL operations.
 Equivalent JavaScript paths remain available for documented fallback-capable
 features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
 for the exact difference.
 
+The guarded JavaScript mutation path is detection-based, not containment-atomic.
+If a same-privilege peer can replace a writable parent after its identity guard
+but before Node resolves a pathname mutation, the mutation can land outside the
+intended root before the post-operation guard throws. Select `require` rather
+than `auto` or `off` when that concurrent attacker is part of the threat model.
+
 `openBeneath()` returns `{ fd, containment }`. `containment` is
 `"kernel-atomic"` for Linux `openat2` and `"best-effort"` for macOS and
 Windows. Public JavaScript root open/read/writable results also expose the

package/docs/native.md

@@ -41,7 +41,7 @@ The TypeScript layer validates and decides. The native layer never decides
 whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
 
 - Linux uses `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, fd-relative
-  `mkdirat`/`linkat`/`renameat2`, `FICLONE`, and `copy_file_range`.
+  `mkdirat`/`linkat`/`renameat`/`renameat2`, `FICLONE`, and `copy_file_range`.
 - macOS 15.4 and newer first use `openat(O_RESOLVE_BENEATH)`; older kernels walk
   components with `openat(O_NOFOLLOW)` and restart in-root symlinks from the
   pinned root. Both routes apply an `F_GETPATH` post-open containment detector,
@@ -99,7 +99,7 @@ remain TypeScript-owned. What changes is the syscall strength or availability:
 
 | Capability | Native path | Guarded JavaScript path |
 |---|---|---|
-| Root-relative opens/mutations | Descriptor-relative beneath operations. Linux reports `kernel-atomic`; macOS and Windows report `best-effort`. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. A hostile same-UID peer has a wider pathname race window. |
+| Root-relative opens/mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. Linux reports `kernel-atomic`; macOS and Windows report `best-effort`. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves the pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
 | ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | JSZip/node-tar into a private stage, then the same guarded merge policy. |
 | Zstd/bzip2 TAR | Supported. | Unsupported; typed `helper-unavailable`. |
 | Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |

package/docs/output.md

@@ -51,8 +51,11 @@ root"; callers should choose the filename before calling this API.
 Use `maxBytes` when the external producer can create arbitrarily large files,
 and `mode` when the finalized file needs a specific POSIX mode. Both staging
 modes enforce them after the producer returns and before committing the target.
-Requested basenames containing C0/C1 controls or Windows-invalid characters are
-sanitized portably; `fallbackFileName` supplies the name when nothing remains.
+Requested basenames containing C0/C1 controls or Windows-invalid characters go
+through the package's filename sanitizer; `fallbackFileName` supplies the name
+when nothing remains. This removes traversal, device-name, and invalid-character
+hazards but does not trim Windows-normalized trailing dots or spaces; reject or
+rewrite those when cross-platform filename uniqueness matters.
 The same sanitized basename is used for producer staging, guarded internal
 temps, the final rename target, and the returned `path`; raw and staged names
 never diverge.
@@ -73,7 +76,9 @@ and size-limit violations, applies `mode`, fsyncs it, and atomically renames it
 over the target. Existing files and symlink entries are replaced without
 following their contents or referents. The parent identity is guarded across
 the operation and the parent directory is synchronized best-effort after
-rename.
+rename. If an error leaves the sibling temp in place and immediate cleanup
+fails, its verified identity remains registered for a best-effort process-exit
+cleanup retry.
 
 ## Why not pass the final path to the library?
 

package/docs/path-scope.md

@@ -77,7 +77,10 @@ Async. Strict variant: every input must already exist as a regular file inside t
 
 ### `writable(rel, options?)`
 
-Async. Resolves a writable target: ensures the parent directory exists inside the scope, refuses targets whose existing inode is a symlink or hardlinked, and returns the absolute path to use for the write.
+Async. Resolves a writable target: requires the parent directory to already
+exist canonically inside the scope, refuses targets whose existing inode is a
+symlink or hardlinked, and returns the absolute path to use for the write. Use
+`ensureDir()` first when the parent needs to be created.
 
 ```ts
 const t = await uploads.writable("reports/2026/05/report.pdf");

package/docs/path.md

@@ -19,7 +19,9 @@ import {
 } from "@openclaw/fs-safe/path";
 ```
 
-Only `root()`, `FsSafeError`, and the native helper config live on the main entry. Path helpers are deliberately a subpath import so the main entry stays small.
+Path helpers are deliberately a subpath import so the main entry stays focused
+on the root capability, its shared configuration, errors, and external-output
+helper.
 
 ## Boundary checks
 
@@ -62,7 +64,7 @@ Convenience wrapper around `isPathInside`. Same semantics, different name kept f
 Resolve a base directory to an absolute, normalized form ready for prefix comparison. Pre-normalized directories make subsequent `isPathInside` checks unambiguous.
 
 ```ts
-const base = resolveSafeBaseDir("/srv/uploads/.");  // "/srv/uploads"
+const base = resolveSafeBaseDir("/srv/uploads/.");  // "/srv/uploads/"
 ```
 
 ## Realpath and stat
@@ -80,7 +82,9 @@ All `realpath` failures collapse to `null` — there is no distinction between `
 
 ### `safeStatSync(targetPath)`
 
-Synchronous `stat` that returns `null` instead of throwing on missing paths. Returns `Stats` on success.
+Synchronous `stat` that returns `Stats` on success and `null` on any failure,
+including missing paths and permission errors. Use `fs.statSync` directly when
+the distinction matters.
 
 ```ts
 const stat = safeStatSync("/srv/uploads/photo.jpg");

package/docs/permissions.md

@@ -38,6 +38,10 @@ isWorldReadable(bits);
 isGroupReadable(bits);
 ```
 
+POSIX remediation strings shell-quote paths with whitespace or metacharacters
+and protect option-like paths with `--`, so they can be presented as commands
+without letting the inspected pathname add shell syntax.
+
 `inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. Secure reads and callers that protect credential-bearing execution require `ownerTrusted === true`.
 
 ## Advanced Windows ACL helpers
@@ -67,6 +71,10 @@ resolveWindowsUserPrincipal(env);
 The fallback Windows inspector calls `icacls.exe <path>` using its supported
 path-only inspection syntax and classifies principals as trusted, world, or
 group. Trusted defaults include the current user, SYSTEM, and Administrators.
+Built-in PowerShell, `icacls.exe`, and `whoami.exe` invocations have a fixed
+30-second per-process deadline. A command failure or timeout returns an
+unverified result (`source: "unknown"`) so callers fail closed. Advanced callers
+that inject a custom `exec` implementation own that executor's deadline.
 The parser is on the advanced surface so tests and CLIs can process captured
 `icacls` output without spawning a process.
 

package/docs/public-api.md

@@ -0,0 +1,109 @@
+# Public API inventory
+
+This page closes the gap between the narrative guides and the complete package
+surface. The generated declarations define the exact signatures; the lists
+below name the lower-frequency exports that are easy to miss when reading only
+the focused guides. `test/public-api.json` guards the same inventory during
+pack checks.
+
+## Main entry and `root`
+
+The main entry and `@openclaw/fs-safe/root` expose the root capability types,
+including `ContainmentGuarantee`, `RootOpenOptions`, `RootCreateOptions`,
+`RootCreateJsonOptions`, and `WritableOpenMode`. The root-bounded iterator uses
+`RootWalkOptions`, `RootWalkEntry`, `RootWalkDataEntry`, `RootWalkEntryKind`,
+`RootWalkDataEntryKind`, `RootWalkSymlinkPolicy`, `RootWalkLimitBehavior`,
+`RootWalkDirectoryErrorBehavior`, `RootWalkEntryFilter`, and
+`RootWalkEntryFilterResult`.
+
+The root subpath also exports `openLocalFileSafely`, `readLocalFileSafely`, and
+`resolveOpenedFileRealPathForHandle` for trusted absolute-file composition.
+They do not create a root boundary around arbitrary caller input; prefer
+`root()` for untrusted paths.
+
+The error helpers are `categorizeFsSafeError` and `FsSafeErrorDetails`. The
+deprecated native-configuration bridge retains the `FsSafePythonConfig` type.
+
+## `path` and `advanced`
+
+The lexical path surface additionally exports `isNodeError`,
+`isPathRelativeEscape`, `normalizeWindowsPathForComparison`,
+`resolveSafeRelativePath`, `splitSafeRelativePath`, and
+`matchUnsafeDeviceReadPath`. The device matcher is described by
+`UnsafeDeviceReadPathMatch`, `UnsafeDeviceReadPathOptions`, and
+`UnsafeDeviceReadPathReason`.
+
+The advanced root-file primitive exports `OpenRootFileParams`,
+`OpenRootFileSyncParams`, `RootFileOpenResult`, and
+`RootFileOpenFailureReason`. These are composition types for callers building
+their own pinned-open flow, not substitutes for the higher-level `Root` verbs.
+
+## `json` and `store`
+
+Standalone structured reads use `ReadJsonOptions`, `ReadRootJsonSyncOptions`,
+`ReadRootStructuredFileSyncOptions`, and `RootStructuredFileReadResult`.
+
+The store surface additionally exports `FileStoreReadOptions` and
+`JsonFileStoreOptions`. Durable-queue inspection and recovery use
+`jsonDurableQueueEntryExists`, `loadJsonDurableQueueEntry`,
+`readJsonDurableQueueEntry`, and the `JsonDurableQueueLoadOptions` and
+`JsonDurableQueueReadResult` types. `unlinkBestEffort` is the explicitly
+best-effort cleanup helper used by those queue flows.
+
+## Permissions and secure files
+
+Permission inspection exposes `PermissionCheckOptions` and `SafeStatResult`.
+Private-directory creation uses `CreatePrivateDirectoryOptions`. Raw Windows
+descriptor facts use `OwnerAndDaclResult`, `WindowsAccessControlEntry`, and
+`WindowsAceFlags`.
+
+Secure reads split their option and result shapes into
+`SecureFileTrustOptions`, `SecureFilePermissionOptions`,
+`SecureFileInjectOptions`, `SecureFileIoOptions`, and `SecureFileReadResult`.
+
+## Locks, walking, and temp workspaces
+
+The file-lock diagnostics surface includes `FileLockHeldEntry`,
+`FileLockStaleRecovery`, and `SidecarLockCompromisedInfo`.
+`drainFileLockManagerForTest` and `resetFileLockManagerForTest` are test-only
+manager controls; production code should not use them as lock recovery.
+
+Standalone walkers use the `WalkEntryKind` and `WalkSymlinkPolicy` unions.
+Private workspaces expose `TempPathIdentityReceipt` and the
+`TempWorkspaceCleanupResult` union so callers can distinguish removal,
+absence, and identity mismatch.
+
+## Atomic replacement and durability
+
+Atomic helper option and receipt types include
+`MovePathWithCopyFallbackOptions`, `ReplaceDirectoryAtomicOptions`,
+`ReplaceFileAtomicSyncOptions`, `ReplaceFileAtomicResult`,
+`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`, and
+`ReplaceFileDestinationHardlinkPolicy`.
+
+The durability surface also exports the synchronous strict
+`syncDirectorySync`, plus `DirectoryReceipt`, `DurableDirectoryReceipt`,
+`EnsureDurableDirectoryOptions`, `PublishFileExclusiveResult`,
+`PublishFileExclusiveStrategy`, `PublishFileExclusiveCleanup`,
+`PublishFileExclusiveFailurePhase`,
+`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`, and
+`Sha256FileResult`.
+
+## Archives
+
+Archive option and policy types are `ExtractArchiveOptions`,
+`ArchiveEntryFilter`, `ArchiveEntryModePolicy`, and
+`ArchiveFilteredEntryPolicy`. Typed error-code unions are
+`ArchiveFormatErrorCode`, `ArchiveLimitErrorCode`, and
+`ArchiveSecurityErrorCode`. TAR and ZIP preflight composition uses
+`TarEntryInfo` and `ZipArchiveWithFiles`.
+
+`createArchiveSymlinkTraversalError` constructs the typed traversal failure
+used by extractors. `resolvePackedRootDir` finds the single packed root when an
+archive layout permits it; neither helper weakens entry validation.
+
+## Keeping this list honest
+
+Every runtime and type name in `test/public-api.json` must appear somewhere in
+`README.md` or `docs/`. Documentation examples are also checked so a named
+import cannot silently move to another package subpath.

package/docs/quickstart.md

@@ -18,7 +18,11 @@ const fs = await root("/srv/jobs/incoming", {
 
 `root()` resolves the directory through the real filesystem (so symlinked roots become canonical) and verifies it exists. The defaults you pass apply to every call below; per-call options override them.
 
-If the root directory itself does not exist yet, `root()` throws `FsSafeError` with code `not-found`. Either create the directory before calling `root()`, or call `await fs.ensureRoot()` after a successful `root()` to create empty subpaths.
+If the root directory itself does not exist yet, `root()` throws `FsSafeError`
+with code `not-found`; create it before constructing the capability.
+`fs.ensureRoot()` is for generic code that needs to assert or recreate the root
+itself after a handle was successfully constructed. It does not accept a
+subpath and cannot bootstrap a root that prevented `root()` from returning.
 
 ## 2. Read and write text
 
@@ -62,7 +66,7 @@ await fs.remove("notes/archive/today.txt");
 
 ```ts
 const here = await fs.exists("state/config.json"); // boolean
-const stat = await fs.stat("state/config.json");   // { kind, size, mtimeMs, ... }
+const stat = await fs.stat("state/config.json");   // { isFile, isDirectory, size, mtimeMs, ... }
 const names = await fs.list("state");              // string[]
 const entries = await fs.list("state", { withFileTypes: true }); // DirEntry[]
 ```

package/docs/reading.md

@@ -14,12 +14,12 @@ const opened = await fs.open("large.log");               // FileHandle for strea
 
 Regardless of shape, every read goes through the same boundary checks:
 
-1. Resolve the relative path against the canonical real root.
-2. Reject anything that escapes the root (`outside-workspace`).
-3. Reject `..` segments and absolute inputs (unless via `readAbsolute` with an in-root absolute path).
-4. Reject known unsafe device and process-fd paths before opening (`device-path`).
-5. Open with `O_NOFOLLOW` where available. A symlink in the path triggers `symlink` unless the call's `symlinks` policy is `follow-within-root`.
-6. Stat the open fd and compare to the resolved path's identity (`sameFileIdentity`). A swap mid-call triggers `path-mismatch`.
+1. Resolve the input lexically against the canonical real root.
+2. Reject a lexically explicit unsafe device or process-fd namespace (`device-path`). This check precedes component alias policy because paths such as `/dev/fd` are themselves symlinks on common Linux hosts.
+3. Resolve path components and reject anything that escapes the root (`outside-workspace`).
+4. Reject `..` traversal and absolute spellings when they resolve outside the root. In-root absolute spellings remain accepted; `readAbsolute` makes that intent explicit.
+5. Open with `O_NOFOLLOW` where available. Any remaining symlink in the path triggers `symlink` unless the call's `symlinks` policy is `follow-within-root`.
+6. Compare the pre-open path identity, the open fd, and the post-open resolved path (`sameFileIdentity`). A swap mid-call triggers `path-mismatch`.
 7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`).
 8. If `maxBytes` is set, refuse reads larger than the cap (`too-large`).
 
@@ -36,7 +36,8 @@ console.log(`${stat.size} bytes at ${realPath}`);
 
 ### `fs.readText(rel, options?)`
 
-`buffer.toString(encoding)`. Defaults to `defaults.encoding ?? "utf8"`. Pass `encoding` per call to override:
+`buffer.toString(encoding)`. Defaults to `"utf8"`; encoding is a per-call text
+option, not a `RootDefaults` field:
 
 ```ts
 const utf16 = await fs.readText("doc.txt", { encoding: "utf16le" });
@@ -83,14 +84,14 @@ try {
 type RootReadOptions = {
   hardlinks?: "reject" | "allow";   // override defaults.hardlinks
   maxBytes?: number;                // refuse reads larger than this many bytes
-  nonBlockingRead?: boolean;        // schedule the read off the main loop
+  nonBlockingRead?: boolean;        // compatibility hint; safe opens are already nonblocking where supported
   symlinks?: "reject" | "follow-within-root"; // override defaults.symlinks
 };
 ```
 
 `maxBytes` is enforced eagerly: the library reads up to `maxBytes + 1` and throws `too-large` if there is more, so a hostile target cannot silently exhaust memory.
 
-`nonBlockingRead` is a scheduling hint. It does not affect safety — it lets you keep the event loop responsive when reading large files.
+`nonBlockingRead` remains as a compatibility hint. Safe reads always add the platform's nonblocking open flag where available so a raced FIFO cannot pin a worker indefinitely; regular-file descriptor reads retain normal Node behavior.
 
 ## `readAbsolute()` and `reader()`
 
@@ -101,7 +102,9 @@ fs.readAbsolute(absPath, options?)   // ReadResult, abs path must be inside the
 fs.reader(options?)              // (path) => Promise<Buffer>
 ```
 
-`readAbsolute` accepts absolute paths. Anything outside the root throws `outside-workspace`.
+`readAbsolute` accepts absolute paths. Anything outside the root throws
+`outside-workspace`. It also accepts relative paths for compatibility, but use
+`read()`/`readBytes()` when the input contract is explicitly relative.
 
 `reader()` returns a closure that takes either a relative or an absolute path and returns a Buffer. Useful for plugging `fs-safe` into framework loader hooks: