@openclaw/fs-safe 0.5.1 → 0.5.3

package/docs/advanced.md

@@ -56,7 +56,7 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | Export | Page | Notes |
 |---|---|---|
 | `readFileDescriptorBounded`, `readFileDescriptorBoundedSync`, `readFileHandleBounded` | – | Incremental whole-file reads for already-open descriptors/handles. They consume at most `maxBytes + 1`, do not close the input, and throw `FsSafeError("too-large")` on overflow. |
-| `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level no-follow open routed through the root-file path. |
+| `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `rejectSymlinks: false` for explicit in-root following. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |
@@ -82,6 +82,12 @@ try {
 }
 ```
 
+For the symlink-parent guards, `allowMissing` defaults to `true` and permits the
+walk to stop only at an actually absent suffix. When an existing non-directory
+component is followed by another segment, both helpers throw
+`FsSafeError("not-file")` before the platform can expose that state as POSIX
+`ENOTDIR` or Windows `ENOENT`.
+
 ### Local roots and file URLs
 
 | Export | Page | Notes |

package/docs/archive.md

@@ -42,10 +42,10 @@ await extractArchive({
 ### Parameters
 
 ```ts
-type ExtractArchiveParams = {
+type ExtractArchiveOptions = {
   archivePath: string;          // absolute path to the archive
   destDir: string;              // absolute destination directory; must already exist
-  timeoutMs: number;            // wall-clock cap; throws on overrun
+  timeoutMs: number;            // positive wall-clock cap; <= 0/non-finite disables it
   kind?: ArchiveKind;           // "zip" | "tar" | "tar-zstd" | "tar-bzip2"
   stripComponents?: number;     // strip N leading dirs from entry paths
   tarGzip?: boolean;            // when archive is .tar.gz/.tgz
@@ -107,7 +107,7 @@ of leaving a paused parser to drain indefinitely. The native path finishes its
 bounded manifest read before TypeScript policy evaluation, so a rejected plan
 never starts the extraction worker.
 
-If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names).
+If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline.
 
 ### Limits
 
@@ -122,18 +122,22 @@ type ArchiveExtractLimits = {
 };
 ```
 
-Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`, `DEFAULT_MAX_META_ENTRY_BYTES`, `DEFAULT_MAX_ENTRY_PATH_COMPONENTS`). The path-component default is 256. It is evaluated after `stripComponents` and before TypeScript accepts an entry for either JavaScript or native extraction, so rejected entries cannot cause implicit parent-directory creation. The 1 MiB metadata default matches node-tar's `maxMetaEntrySize`; fs-safe passes the same resolved value to node-tar and the native TAR meter.
+Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`, `DEFAULT_MAX_META_ENTRY_BYTES`, `DEFAULT_MAX_ENTRY_PATH_COMPONENTS`). An explicit zero remains zero rather than selecting the default. `maxEntries` counts every archive entry, including entries removed by `stripComponents` or an explicit filter. The path-component default is 256. It is evaluated after `stripComponents` and before TypeScript accepts an entry for either JavaScript or native extraction, so rejected entries cannot cause implicit parent-directory creation. The 1 MiB metadata default matches node-tar's `maxMetaEntrySize`; fs-safe passes the same resolved value to node-tar and the native TAR meter.
 
-A limit violation throws `ArchiveLimitError`. The error's code is one of:
+A limit violation throws `ArchiveLimitError`. Its constant and string code are:
 
-```ts
-ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_SIZE_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.META_ENTRY_SIZE_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT
-```
+| Constant | Code |
+|---|---|
+| `ARCHIVE_SIZE_EXCEEDS_LIMIT` | `archive-size-exceeds-limit` |
+| `ENTRY_COUNT_EXCEEDS_LIMIT` | `archive-entry-count-exceeds-limit` |
+| `EXTRACTED_SIZE_EXCEEDS_LIMIT` | `archive-extracted-size-exceeds-limit` |
+| `ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT` | `archive-entry-extracted-size-exceeds-limit` |
+| `META_ENTRY_SIZE_EXCEEDS_LIMIT` | `archive-meta-entry-size-exceeds-limit` |
+| `ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT` | `archive-entry-path-components-exceeds-limit` |
+| `MANIFEST_SIZE_EXCEEDS_LIMIT` | `archive-manifest-size-exceeds-limit` |
+
+`MANIFEST_SIZE_EXCEEDS_LIMIT` is retained in the public compatibility union;
+no current public extractor emits it.
 
 Catch and branch on the code to surface a meaningful response to the caller.
 
@@ -144,10 +148,12 @@ codes remain `"destination-not-directory"`, `"destination-symlink"`, and
 
 ## What it defends against
 
-- **Path traversal:** entries with `..`, absolute paths, or Windows drive prefixes are rejected (`ArchiveSecurityError`).
+- **Path traversal:** entries with `..`, absolute paths, NUL bytes, or Windows drive-relative segments such as `C:secret` and `nested/C:secret` are rejected (`ArchiveSecurityError`). On Windows, path segments containing `:` are also rejected as alternate data stream names before either backend writes to the filesystem.
 - **Symlink/hardlink entries:** rejected by default. Some archives ship symlink/hardlink entries that point outside the destination once resolved; `extractArchive` does not follow them.
+- **Ambiguous output names:** duplicate names and distinct names that collide after `stripComponents`, case normalization, or Unicode normalization are rejected instead of relying on backend- or volume-specific overwrite order.
 - **TOCTOU during merge:** extraction first writes to a private temp dir, then merges into `destDir` using the same boundary checks as `root().write()`. Destination symlink swaps are checked with the selected platform mechanism; non-Linux routes retain the best-effort race window documented in the [security model](security-model.md#containment-guarantees-by-platform).
 - **Zip bombs:** `maxExtractedBytes` and `maxEntryBytes` apply to *post-decompression* bytes, so highly-compressed payloads hit the cap before they exhaust disk.
+- **Corrupt ZIP payloads:** streamed output must match both the central-directory CRC and declared uncompressed size before it can leave private staging.
 - **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget. Extraction is aborted on overrun.
 - **Metadata bombs:** a fixed-header pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before either TAR implementation buffers them. It understands octal and base-256 size fields without interpreting metadata content.
 
@@ -168,7 +174,7 @@ import { resolveArchiveKind, type ArchiveKind } from "@openclaw/fs-safe/archive"
 const kind = resolveArchiveKind("upload.zip"); // "zip"
 const tar = resolveArchiveKind("upload.tar.gz"); // "tar"
 const zstd = resolveArchiveKind("upload.tar.zst"); // "tar-zstd" when native is available
-const unknown = resolveArchiveKind("upload.bin"); // undefined
+const unknown = resolveArchiveKind("upload.bin"); // null
 ```
 
 Recognizes:
@@ -178,7 +184,7 @@ Recognizes:
 - `*.tar.zst`, `*.tar.zstd`, `*.tzst` → `"tar-zstd"` (native only)
 - `*.tar.bz2`, `*.tbz2`, `*.tbz` → `"tar-bzip2"` (native only)
 
-Returns `undefined` for unknown extensions; check the result before calling
+Returns `null` for unknown extensions; check the result before calling
 `extractArchive` if the filename is caller-controlled. A recognized zstd or
 bzip2 TAR extension with no native binding throws the typed
 `FsSafeError("helper-unavailable")` with installation guidance. This includes
@@ -204,7 +210,8 @@ await extractArchive({
 
 `readArchiveEntry(archivePath, entryPath, { maxBytes, kind? })` reads one
 regular-file entry into a bounded `Buffer` without extracting a tree. It pins
-and privately stages the archive input, rejects link and directory entries,
+and privately stages the archive input, rejects link, directory, and duplicate
+entries, verifies ZIP CRC and declared size,
 and throws `ArchiveLimitError` if decompressed bytes exceed `maxBytes`. ZIP
 inputs retain the archive subpath's 256 MiB compressed-input ceiling.
 With a native binding it uses the same Rust decoders as extraction, including
@@ -248,11 +255,11 @@ import {
 } from "@openclaw/fs-safe/archive";
 ```
 
-- `validateArchiveEntryPath(raw, opts)` — throws `ArchiveSecurityError` for `..`, absolute, drive-prefixed, or otherwise unsafe entry paths.
-- `normalizeArchiveEntryPath(raw)` — POSIX-normalizes the entry path (forward slashes, no `.` segments).
+- `validateArchiveEntryPath(raw, opts)` — throws `ArchiveSecurityError` for `..`, absolute, NUL-containing, drive-relative, or otherwise unsafe entry paths, including alternate data stream names on Windows.
+- `normalizeArchiveEntryPath(raw)` — converts backslashes in the entry path to forward slashes.
 - `stripArchivePath(entryPath, n)` — strip the leading N path components, returning `null` if not enough remain.
 - `resolveArchiveOutputPath({ destDir, entryPath })` — combines the entry path with the destination, after validation.
-- `isWindowsDrivePath(value)` — detects `C:\…` style entries that should be rejected.
+- `isWindowsDrivePath(value)` — detects drive-relative segments such as `C:secret` or `nested/C:secret` that should be rejected.
 
 ## Common patterns
 

package/docs/atomic.md

@@ -14,7 +14,9 @@ import {
 
 ## `replaceFileAtomic` / `replaceFileAtomicSync`
 
-Write `content` to a sibling temp file in the destination directory, optionally `fsync` the temp file, optionally `fsync` the parent directory after rename, then atomically rename over the destination.
+Write `content` to a sibling temp file in the destination directory, apply the parent-directory and final file modes through verified descriptors, optionally `fsync` the file descriptor, optionally `fsync` the parent directory after rename, then atomically rename over the destination. No permission change follows a caller-supplied pathname.
+
+On POSIX, the parent is opened with no-follow and directory-only flags, checked against its pre-open identity, and mode-adjusted through that descriptor. A replacement symlink is rejected rather than followed. If the directory cannot be opened for descriptor access, the operation fails closed instead of retrying by pathname. Windows does not enforce POSIX directory modes and Node cannot consistently open directory descriptors there, so `dirMode` is passed only to `mkdir`; no pathname `chmod` fallback is attempted.
 
 Async replacements to the same destination are serialized inside the current process, so two overlapping `replaceFileAtomic()` calls do not interleave their temp-write/rename phases. Use a sidecar lock when multiple processes may write the same target.
 
@@ -36,18 +38,19 @@ await replaceFileAtomic({
 type ReplaceFileAtomicOptions = {
   filePath: string;                 // destination
   content: string | Uint8Array;
-  dirMode?: number;                 // mode for parent dirs created by the helper
-  mode?: number;                    // explicit mode for the new file (e.g. 0o600)
-  preserveExistingMode?: boolean;   // copy mode from existing destination, when present
-  tempPrefix?: string;
-  renameMaxRetries?: number;
-  renameRetryBaseDelayMs?: number;
-  copyFallbackOnPermissionError?: boolean;
+  dirMode?: number;                 // parent-directory mode (POSIX; default 0o700)
+  mode?: number;                    // new-file mode (default 0o600)
+  preserveExistingMode?: boolean;   // copy existing mode; default false
+  tempPrefix?: string;              // default ".fs-safe-replace"
+  renameMaxRetries?: number;        // EBUSY retries; default 0
+  renameRetryBaseDelayMs?: number;  // exponential base; default 50
+  copyFallbackOnPermissionError?: boolean; // default false
   copyFallbackRestore?: "restore-original" | "none"; // default: "none"
   maxRestoreBytes?: number;          // required with "restore-original"
-  destinationHardlinks?: "reject";
-  syncTempFile?: boolean;           // fsync(temp) before rename
-  syncParentDir?: boolean;          // fsync(parent) after rename (POSIX only)
+  destinationHardlinks?: "reject"; // default unset (no destination nlink policy)
+  syncTempFile?: boolean;           // fsync(temp) before rename, or the final file after copy fallback; default false
+  syncParentDir?: boolean;          // fsync(parent) after rename, POSIX only; default false
+  throwOnCleanupError?: boolean;    // report temp cleanup failure; default false
   beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
   fileSystem?: ReplaceFileAtomicFileSystem; // injectable fs for tests
 };
@@ -87,9 +90,10 @@ The default `copyFallbackRestore: "none"` preserves the existing fallback
 contract: a failed copy can leave a partial destination. For state files where
 preserving the old bytes is more important, choose `"restore-original"` and set
 an explicit `maxRestoreBytes` memory budget. If the destination exists, fs-safe
-snapshots it through a pinned descriptor, overwrites through that same
-descriptor, and synchronizes the result. Any write or sync failure triggers a
-restore and another sync through the same descriptor.
+snapshots it through a pinned descriptor, overwrites and mode-adjusts through
+that same descriptor, and synchronizes the result. Any write, mode, or sync
+failure triggers a byte-and-mode restore and another sync through the same
+descriptor.
 
 Restore failures are `FsSafeError("helper-failed")` values with typed
 `details.cleanup` set to `"restored"` or `"restore-failed"`. An original larger
@@ -99,7 +103,10 @@ fallback.
 
 ### Sync variant
 
-`replaceFileAtomicSync` accepts the same options shape, with the obvious removal of the async-only hooks. Use it inside synchronous boot paths or test setup code.
+`replaceFileAtomicSync` accepts the same base options, a synchronous
+`beforeRename` callback, and `ReplaceFileAtomicSyncFileSystem`. Use it inside
+synchronous boot paths or test setup code. It returns the same
+`{ method: "rename" | "copy-fallback" }` receipt as the async variant.
 
 ## `replaceDirectoryAtomic`
 
@@ -115,13 +122,17 @@ await replaceDirectoryAtomic({
 ```
 
 The helper renames `targetDir` to a generated backup path, renames `stagedDir → targetDir`, then removes the backup. If the second rename fails, it tries to restore the original target before rethrowing.
+Concurrent replacements of the same resolved target are serialized inside the
+current process so their backup, commit, and cleanup phases cannot interleave.
+`backupPrefix`, when supplied, is sanitized as one path prefix and cannot contain
+path separators or NUL bytes; the generated backup tail is randomized.
 
 Use it when callers must see a whole staged tree at the target path. For single-file replacement, `replaceFileAtomic` is the right tool.
 
 ## `writeTextAtomic`
 
 Atomic UTF-8 text write with the same secure defaults as `writeJson`: sibling
-temp file, temp fsync, rename, parent fsync, and final chmod best-effort.
+temp file, descriptor-bound mode setting and fsync, rename, and parent fsync.
 It delegates to `replaceFileAtomic()` with a smaller call shape. Use it when
 you do not need replacement hooks such as `beforeRename`, `preserveExistingMode`,
 or custom copy-fallback policy.
@@ -141,8 +152,8 @@ Options:
 ```ts
 type WriteTextAtomicOptions = {
   mode?: number;             // file mode (default 0o600)
-  dirMode?: number;          // mode for parent dirs created on demand
-  trailingNewline?: boolean; // append "\n" if missing
+  dirMode?: number;          // parent mode (default 0o777 masked by process umask)
+  trailingNewline?: boolean; // append "\n" if missing; default false
   durable?: boolean;         // default true; false skips temp/parent fsync
 };
 ```
@@ -157,7 +168,14 @@ Rename a path. If the rename fails with `EXDEV` (cross-device), fall back to
 copying into a staged sibling path, renaming that staged path into place, and
 then removing only the source entries that were copied. The fallback avoids
 buffering regular files into memory and does not tighten the destination parent
-directory mode.
+directory mode. Staged file modes are applied through their still-open handles.
+If descriptor-bound mode application fails, the staged path is removed and the
+move fails before publication. A transient staged-path cleanup failure retains
+an identity-bound process-exit cleanup retry.
+On POSIX, staged directory modes are applied through no-follow directory
+descriptors; on Windows, Node cannot portably open those descriptors and no
+pathname `chmod` fallback is attempted, so directory modes remain subject to
+Windows' `mkdir(mode)` behavior.
 
 ```ts
 import { movePathWithCopyFallback } from "@openclaw/fs-safe/atomic";
@@ -212,6 +230,17 @@ await replaceFileAtomic({
 });
 ```
 
+The synchronous injectable interface has one optional descriptor-mode operation:
+
+```ts
+type ReplaceFileAtomicSyncFileSystem = {
+  // other required operations omitted
+  fchmodSync?: typeof import("node:fs").fchmodSync;
+};
+```
+
+The async interface already requires `open()`, whose `FileHandle` supplies `chmod()`, so injecting `node:fs` or another conforming adapter needs no new async member. On POSIX, that `open()` must support no-follow directory descriptors as Node does. A custom synchronous filesystem that passes `mode`, `dirMode`, or `preserveExistingMode` must supply `fchmodSync`; omission fails before any file or directory is created and never falls back to a pathname `chmod`. Existing synchronous adapters that request none of those options may omit it; their parent is still opened and identity-checked through a no-follow directory descriptor. Injecting plain `node:fs` supports explicit file and directory modes. Older adapter literals may continue to include `chmod` or `chmodSync` for source compatibility, but those operations are ignored. Copy fallback applies the file mode through its pinned destination descriptor as well, preserving exact modes despite the process umask.
+
 ## See also
 
 - [`root()`](root.md) — when you want method-style writes with the boundary baked in.

package/docs/errors.md

@@ -2,6 +2,10 @@
 
 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.
 
+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";
 ```
@@ -50,8 +54,17 @@ destination.
 
 `category` separates caller-policy failures from operational failures:
 
-- `"policy"` — unsafe input or target state, such as `outside-workspace`, `symlink`, `hardlink`, or `too-large`.
-- `"operational"` — environment/runtime failures, such as helper startup, platform support, timeout, or unverifiable permissions.
+- `"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
 
@@ -74,7 +87,9 @@ type FsSafeErrorCode =
   | "path-alias"
   | "path-mismatch"
   | "permission-unverified"
+  | "read-failed"
   | "secret-exists"
+  | "store-reentrant-update"
   | "symlink"
   | "timeout"
   | "too-large"
@@ -92,9 +107,9 @@ type FsSafeErrorCode =
 | `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, missing/incompatible bundled binary, 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. | Caller didn't validate input; input was a network path on Windows. |
+| `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable. | Caller didn't validate input; input was 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 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. | Target was a directory, FIFO, socket, device. |
+| `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. |
@@ -102,11 +117,13 @@ type FsSafeErrorCode =
 | `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` | The requested operation is not supported on the current platform. | E.g. POSIX-only helper invoked on Windows. |
+| `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. |
 
 ## Branching
 
@@ -138,11 +155,13 @@ try {
 }
 ```
 
-The compiler will flag missing cases when you exhaust the union — keep your switch up-to-date as the library adds new codes.
+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`, `EISDIR`, `EBUSY`) when they don't map cleanly to a library code. Inspect both:
+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";
@@ -154,7 +173,8 @@ try {
     handleFsSafe(err);
     return;
   }
-  if ((err as NodeJS.ErrnoException).code === "EACCES") {
+  const code = (err as NodeJS.ErrnoException).code;
+  if (code === "EACCES" || code === "EPERM") {
     handleAccess();
     return;
   }
@@ -164,6 +184,12 @@ try {
 
 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`:

package/docs/file-store.md

@@ -43,7 +43,7 @@ type FileStore = {
   readonly rootDir: string;
   path(relativePath: string): string;
   root(): Promise<Root>;
-  write(rel, data: string | Buffer, options?): Promise<string>;
+  write(rel, data: string | Uint8Array, options?): Promise<string>;
   writeStream(rel, stream: Readable, options?): Promise<string>;
   copyIn(rel, sourcePath: string, options?): Promise<string>;
   open(rel, options?): Promise<OpenResult>;
@@ -64,6 +64,15 @@ type FileStore = {
 
 `path()` returns the absolute path the store would use, after asserting it stays inside `rootDir`. Useful for logging or for handing to other libraries.
 
+Every `relativePath` is a portable store key, including keys passed to reads,
+`exists`, and `remove`. A segment with a Windows drive-relative spelling such
+as `C:name` (including an embedded segment such as `a/C:name`) throws
+`invalid-path` on every platform. This prevents a key created on POSIX from
+aliasing a different file when the store is moved to Windows. Colons elsewhere,
+such as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain valid.
+Keys with surrounding whitespace also throw `invalid-path`; the store never
+silently trims one caller-supplied key onto another key.
+
 `root()` returns a [`Root`](root.md) handle for the same directory when you need the full surface (move, list, mkdir). It's a fresh handle per call and is safe to call frequently.
 
 ## Writes
@@ -129,6 +138,10 @@ type FileStoreWriteOptions = {
 ## Reads
 
 `open`, `read`, `readBytes`, `readText`, and `readJson` delegate to a fresh `Root` with `hardlinks: "reject"` and the store's `maxBytes`. Same return shapes as `Root`.
+Async and sync reads both report `not-file` when the key names a directory;
+stable hardlinks and symlinks retain `hardlink` and `symlink`. The `IfExists`
+methods return their nullish result only for `not-found`. Operational filesystem
+read failures use `read-failed` with the Node error retained in `cause`.
 
 ## `remove(rel)` / `exists(rel)`
 

package/docs/filename.md

@@ -1,9 +1,9 @@
 # Filenames
 
-`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one portable path segment. Use it as a thin first pass before storing user-supplied names; pair with [`safeDirName`](install-path.md#safedirname) when you need stricter directory-name handling.
+`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one traversal-free path segment. Use it as a thin first pass before storing user-supplied names; pair with [`safeDirName`](install-path.md#safedirname) when you need stricter directory-name handling.
 
 ```ts
-import { sanitizeUntrustedFileName } from "@openclaw/fs-safe";
+import { sanitizeUntrustedFileName } from "@openclaw/fs-safe/advanced";
 
 const safe = sanitizeUntrustedFileName(req.body.fileName, "upload");
 await fs.write(`uploads/${safe}`, body);
@@ -24,9 +24,12 @@ In order:
 3. **Strip non-portable characters.** C0/C1 controls (`0x00`–`0x1f`, `0x7f`–`0x9f`) and the Windows-invalid set `< > : " / \\ | ? *` are removed on every platform.
 4. **Trim again.**
 5. If the result is empty, `"."`, or `".."`, return `fallbackName`.
-6. **Truncate.** If the cleaned segment is longer than 200 characters, take the first 200.
+6. **Suffix Windows reserved basenames.** Compare the part before the first `.` case-insensitively with the Windows device-name set, including `CON`, `PRN`, `AUX`, `NUL`, `CLOCK$`, `CONIN$`, `CONOUT$`, `COM1..9`, `LPT1..9`, and their superscript `¹`, `²`, and `³` variants. Windows-ignored spaces and dots at the end of that basename do not disguise a device name. A match gains `_` before its extension, preserving the original case and extension on every platform.
+7. **Truncate.** If the cleaned segment is longer than 200 UTF-16 code units, take up to the first 200 without splitting a valid Unicode surrogate pair.
 
-That's it. The function stays intentionally small: it produces one traversal-free segment whose characters work across the common POSIX and Windows filename surfaces.
+That's it. The function stays intentionally small: it removes traversal and
+the most obvious cross-platform device and character hazards, but it is not a
+complete portable-filename or uniqueness policy.
 
 ## Examples
 
@@ -38,35 +41,33 @@ sanitizeUntrustedFileName("a\u0000b\tc", "upload");       // "abc"
 sanitizeUntrustedFileName("   ", "fallback");              // "fallback"
 sanitizeUntrustedFileName(".", "fallback");                // "fallback"
 sanitizeUntrustedFileName("..", "fallback");               // "fallback"
-sanitizeUntrustedFileName("a".repeat(300), "x");           // 200-char "aaa..."
+sanitizeUntrustedFileName("CON", "fallback");              // "CON_"
+sanitizeUntrustedFileName("nul.txt", "fallback");          // "nul_.txt"
+sanitizeUntrustedFileName("aux.c", "fallback");            // "aux_.c"
+sanitizeUntrustedFileName("conin$", "fallback");           // "conin$_"
+sanitizeUntrustedFileName("a".repeat(300), "x");          // 200-char "aaa..."
 ```
 
 ## What it does **not** do
 
 The function is deliberately narrow. It will not:
 
-- Reject Windows reserved names (`CON`, `PRN`, `AUX`, `NUL`, `COM1..9`, `LPT1..9`).
 - Replace leading dots (so a name like `.config` stays hidden on POSIX systems).
-- Trim trailing dots or spaces (Windows tolerates them silently).
+- Trim trailing dots. Surrounding spaces are removed by the documented trim
+  steps, but Windows-normalized dot/space spellings can still alias; reject or
+  rewrite them when Windows portability or cross-platform migration matters.
 - Add an extension or change case.
 - Validate file *content*. To enforce an extension allow-list, check after sanitization.
 - Deduplicate against existing files. Append a random suffix if you need uniqueness.
 
-If your domain needs stricter handling, layer it on top:
-
-```ts
-const trimmed = sanitizeUntrustedFileName(input, "upload");
-const noWindowsReserved = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..+)?$/i.test(trimmed)
-  ? "upload"
-  : trimmed;
-```
+Windows reserved basenames are handled by the default portability pass; callers no longer need to layer a separate reserved-name recipe on top.
 
 ## Common patterns
 
 ### Make a unique filename
 
 ```ts
-import { sanitizeUntrustedFileName } from "@openclaw/fs-safe";
+import { sanitizeUntrustedFileName } from "@openclaw/fs-safe/advanced";
 import { randomUUID } from "node:crypto";
 
 const base = sanitizeUntrustedFileName(req.body.fileName, "upload");

package/docs/index.md

@@ -69,6 +69,7 @@ await fs.remove("notes/archive/today.txt");
 | [Permissions](permissions.md) | POSIX mode helpers plus Windows ACL inspection, raw owner/ACE facts, remediation, and private-directory creation. |
 | [`acquireFileLock`](sidecar-lock.md) | Cross-process file lock with retry and fail-closed stale-lock handling. |
 | [`FsSafeError`](errors.md) | Closed code union (with `policy` / `operational` category) you can branch on. |
+| [Public API inventory](public-api.md) | Complete runtime/type export cross-check against the generated declarations. |
 | [`pathScope()`](path-scope.md) | Lower-level absolute-path boundary helper; lives behind `@openclaw/fs-safe/advanced`. |
 | [`@openclaw/fs-safe/advanced`](advanced.md) | Directory of lower-level composition helpers (path scopes, regular-file I/O, install paths, sibling-temp writes, …). |
 | [`@openclaw/fs-safe/test-hooks`](test-hooks.md) | Test-only injection hooks for reproducing open/lstat races. |

package/docs/install-path.md

@@ -95,16 +95,19 @@ Returns a directory-safe segment **plus** a short content hash when sanitization
 
 ```ts
 safePathSegmentHashed("plugin-v1");                  // "plugin-v1"  (unchanged short input)
-safePathSegmentHashed("plugin/v1");                  // "plugin-v1-3f2a..."
-safePathSegmentHashed("plugin\\v1");                 // "plugin-v1-91c4..."  (different hash; same safe form)
-safePathSegmentHashed("Über@");                       // "ber-9aae..."
-safePathSegmentHashed("");                           // "skill"  (empty fallback)
-safePathSegmentHashed(".");                          // "skill"
+safePathSegmentHashed("plugin/v1");                  // "plugin-v1-d9ef8af2eb"
+safePathSegmentHashed("plugin\\v1");                 // "plugin-v1-bed33f465b"
+safePathSegmentHashed("Über@");                       // "ber-e392bba2b3"
+safePathSegmentHashed("");                           // "skill-e3b0c44298"
+safePathSegmentHashed(".");                          // "skill-cdb4ee2aea"
 ```
 
 The sanitization is more aggressive than `safeDirName`: any character not in `[A-Za-z0-9._-]` becomes `-`, runs of `-` collapse, leading and trailing `-` are stripped, the empty/`.`/`..` fallback is `"skill"`. Long results are truncated to 50 chars before the hash is appended.
 
-The hash is the first 10 hex chars of `sha256(originalInput)`. It guarantees that two distinct inputs which sanitize to the same string yield distinct outputs.
+The suffix is the first 10 hex characters of `sha256(trimmedInput)`. It makes
+collisions between distinct trimmed inputs unlikely, but it is a 40-bit
+identifier rather than a mathematical uniqueness guarantee. Inputs that differ
+only by surrounding whitespace intentionally map to the same output.
 
 ## Common patterns
 

package/docs/json.md

@@ -133,7 +133,12 @@ where lower latency matters more than crash-durability.
 
 ### `writeJsonSync(pathname, data)`
 
-Synchronous variant. Convenience wrapper that uses the sync atomic-write path with sensible defaults.
+Synchronous variant. It pretty-prints with two spaces, appends a newline,
+creates parents at `0o700`, writes at `0o600`, and synchronizes the parent
+directory best-effort. It has no options bag. On `EPERM`/`EEXIST`, its legacy
+compatibility path may replace by copy rather than atomic rename; use the async
+`writeJson()`/`replaceFileAtomic()` surfaces when fallback policy must be
+explicit.
 
 ```ts
 writeJsonSync("./prefs.json", { theme: "dark" });
@@ -187,7 +192,8 @@ const state = await readJsonIfExists<State>("./state.json");
 
 | Throw / return | When |
 |---|---|
-| `null` (lenient reads) | File missing or contents are not valid JSON. |
+| `null` from `tryReadJson` / `tryReadJsonSync` | Any read or parse failure. |
+| `null` from `readJsonIfExists` | File is missing; invalid or unreadable input still throws. |
 | `JsonFileReadError` | `readJson` or `readJsonIfExists` saw unreadable or invalid input. Inspect `cause`. |
 | Native `NodeJS.ErrnoException` | Lower-level fs errors not wrapped. |