@openclaw/fs-safe 0.10.0 → 0.12.0

package/docs/in-place-write.md

@@ -0,0 +1,81 @@
+---
+title: In-place writes
+description: "Replace bytes through a borrowed file handle while preserving its inode and attempting rollback on failure."
+---
+
+# In-place writes
+
+`overwriteFileHandle()` replaces a regular file's contents through a handle the
+caller already owns. Use it when replacing the inode would break hardlinked
+aliases, or when an existing writable file lives in a directory where the caller
+cannot create a sibling temporary file.
+
+```ts
+import { open } from "node:fs/promises";
+import { overwriteFileHandle } from "@openclaw/fs-safe/advanced";
+
+const handle = await open(filePath, "r+");
+try {
+  await overwriteFileHandle(handle, Buffer.from(nextContents, "utf8"), {
+    beforeWrite: () => assertCurrentOwner(),
+  });
+} finally {
+  await handle.close();
+}
+```
+
+## Contract
+
+```ts
+overwriteFileHandle(
+  handle: FileHandle,
+  data: Uint8Array,
+  options?: { beforeWrite?: () => void },
+): Promise<void>;
+```
+
+The handle must be readable and writable, refer to a regular file, and have been
+opened **without append mode**. Node cannot portably inspect a handle's append
+flag, and some operating systems ignore positioned-write offsets for append
+handles. Opening, path admission, symlink and hardlink policy, and closing remain
+the caller's responsibility. The helper never reopens or replaces the inode,
+changes the handle's current position, or closes it. Every hardlinked alias sees
+the in-place changes.
+
+The payload is borrowed, including its byte offset and length. Keep it unchanged,
+attached, and accessible until the returned promise settles. Do not close the
+handle or run concurrent I/O against the file, including through other aliases,
+during preparation, writing, or rollback. This helper does not acquire a lock.
+
+## Preparation, ordering, and failure
+
+The helper checks the file type and original size, then saves only the prefix
+that will be overwritten: `min(data.byteLength, originalSize)` bytes. A short
+prefix read fails with `FsSafeError("read-failed")` before writing. Memory for the
+backup is bounded by that prefix length; a short replacement of a large file does
+not read or buffer the untouched tail.
+
+After preparation, `beforeWrite` runs synchronously once. A thrown value is
+propagated unchanged without any file mutation. A Promise or thenable return is
+rejected with `TypeError`; asynchronous callbacks cannot admit a write. Once
+admitted, the operation finishes the write or its failure recovery without
+calling `beforeWrite` again. This callback is a whole-operation admission point,
+not the per-mutation `assertBeforeMutation` callback used by Root operations.
+It must not change the file, handle, or payload. There is no cancellation option.
+
+For growth, additional tail bytes are written before the existing prefix is
+touched. The prefix is then overwritten, completing partial writes. For shrinkage,
+truncation is last. If a write or truncation fails, the helper attempts to restore
+the saved prefix, if touched, and the original length. It waits for both recovery
+attempts and then rethrows the original error, even when recovery also fails.
+Zero-progress writes fail with `FsSafeError("helper-failed")`.
+
+Recovery is best effort, not atomic publication or a crash-recovery guarantee.
+Other observers can see intermediate contents; failed recovery can leave partial
+bytes. The helper does not chmod or synchronize the file or its directory.
+Normal filesystem effects such as timestamp updates or clearing special mode
+bits can still occur. Callers own any durability or broader transaction policy.
+
+The implementation uses Node positional reads and writes in every native mode;
+it does not load a native binding. Prefer [`Root.write`](writing.md) when atomic
+replacement and root-based path admission are the intended contract.

package/docs/index.md

@@ -52,6 +52,7 @@ await fs.remove("notes/archive/today.txt");
 |---|---|
 | [`root()`](root.md) | One boundary for read/write/move/remove and bounded recursive walking inside a trusted directory. |
 | [`@openclaw/fs-safe/config`](config.md) | Process-global native helper and lock-option defaults. |
+| [`@openclaw/fs-safe/guest`](guest.md) | Python filesystem source for caller-owned guest transports, with admitted roots and descriptor-relative operations. |
 | [Native helper policy](native-helper.md) | Choose `auto`, `off`, or `require` for platform-native primitives. |
 | [Native architecture](native.md) | Understand the thin syscall layer, beneath model, platform mechanisms, and fallback boundary. |
 | [`replaceFileAtomic`](atomic.md) | Sibling-temp + rename, fsync hooks, mode preservation, copy fallback. |
@@ -65,6 +66,7 @@ await fs.remove("notes/archive/today.txt");
 | [`tempWorkspace`](temp.md) | 0700 scratch dir with auto-cleanup. |
 | [`readSecureFile`](secure-file.md) | Absolute file reads with fd pinning, permissions, owner, size, and timeout checks. |
 | [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
+| [`Root.entries`](entries.md) | Guarded nonrecursive entries, bounded name collection, and caller-owned symlink validation. |
 | [`extractArchive`](archive.md) | Policy-driven ZIP/TAR extraction with clamp/filter, metadata/path-depth, link, count, and byte limits. |
 | [Secret files](secret-file.md) | Mode-0600 credentials with size and TOCTOU defense. |
 | [Permissions](permissions.md) | POSIX mode helpers plus Windows ACL inspection, raw owner/ACE facts, remediation, and private-directory creation. |

package/docs/install-path.md

@@ -8,6 +8,7 @@ import {
   resolveSafeInstallDir,
   safeDirName,
   safePathSegmentHashed,
+  safePathSegmentHashedV2,
 } from "@openclaw/fs-safe/advanced";
 ```
 
@@ -35,14 +36,17 @@ if (!r.ok) return reply(400, r.error);
 await fs.mkdir(r.path, { recursive: true });
 ```
 
-For ids whose default-sanitized form might collide (e.g. `"foo/bar"` and `"foo\\bar"` both map to `"foo__bar"`), pass `nameEncoder: safePathSegmentHashed` to append a content hash:
+For untrusted IDs that must occupy separate install directories, pass
+`nameEncoder: safePathSegmentHashedV2`. The default `safeDirName` and legacy
+`safePathSegmentHashed` can map distinct IDs to the same directory; the boundary
+check does not establish which ID owns an existing directory.
 
 ```ts
 const r = resolveSafeInstallDir({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   id: untrustedId,
   invalidNameMessage: "invalid plugin name",
-  nameEncoder: safePathSegmentHashed,
+  nameEncoder: safePathSegmentHashedV2,
 });
 ```
 
@@ -87,11 +91,48 @@ safeDirName("");                       // ""
 
 `safeDirName` does *not* try to be exhaustive about Windows-reserved names or special characters. It is purely a separator-stripping pass — `resolveSafeInstallDir` adds the boundary check on top so an `"../../etc"` input cannot escape `baseDir`.
 
-For stricter sanitization, use `safePathSegmentHashed`.
+Use `safePathSegmentHashedV2` when distinct untrusted IDs need separate names.
+
+### `safePathSegmentHashedV2`
+
+```ts
+function safePathSegmentHashedV2(input: string): string;
+```
+
+Hashes every trimmed ID, including ordinary short names, into `id-v2-` followed
+by 64 lowercase hexadecimal SHA-256 digits. The result is always 70 ASCII bytes,
+contains no separators, and avoids Windows device names and ignored suffixes.
+There is no readable prefix to truncate and no unchanged-name branch. Distinct
+trimmed IDs, including an ID that looks like an encoded output, remain distinct
+unless their full SHA-256 digests collide. The lowercase ASCII output also
+preserves that distinction on case-insensitive and Unicode-normalizing volumes.
+
+The stable V2 digest recipe is SHA-256 of the UTF-8 bytes of
+`"@openclaw/fs-safe:install-path:v2\0"`, followed by the UTF-16LE bytes of
+`input.trim()`, without a byte-order mark. The NUL-terminated prefix separates
+this use of SHA-256 from other hash domains. UTF-16LE preserves exact JavaScript
+code units, including lone surrogates. Inputs are not case-folded or Unicode
+normalized. Surrounding whitespace, as removed by JavaScript `String.trim()`,
+is the only intentional equivalence; internal whitespace remains significant.
+
+```ts
+const segment = safePathSegmentHashedV2("plugin/v1"); // id-v2-<64 hex digits>
+safePathSegmentHashedV2(" plugin/v1 ") === segment;  // true
+safePathSegmentHashedV2("Plugin/v1") === segment;    // false
+```
+
+This encoder computes a name; it does not authorize access or prove ownership
+of a directory. Store the original trimmed ID in application-owned metadata and
+verify it before reusing an existing install directory. Keep each install tree
+on one encoding version. Switching to V2 changes existing paths: use a new base
+directory or explicitly migrate directories after verifying their recorded IDs.
+Do not silently fall back to a legacy path when the V2 path is missing.
 
 ### `safePathSegmentHashed`
 
-Returns a directory-safe segment **plus** a short content hash when sanitization changed the input or when the safe form is too long. Use this when input collisions matter:
+Legacy readable encoding retained for path compatibility. It appends a short
+content hash when sanitization changed the input or when the safe form is too
+long; ordinary short names remain unchanged. Use V2 for new untrusted-ID mappings.
 
 ```ts
 safePathSegmentHashed("plugin-v1");                  // "plugin-v1"  (unchanged short input)
@@ -104,31 +145,35 @@ 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 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.
+The suffix is the first 10 hex characters of `sha256(trimmedInput)`. This is a
+40-bit identifier, and the hash is not applied to every ID: short generated
+outputs overlap with accepted literal inputs. Case variants can also share a
+directory on case-insensitive filesystems. Distinct IDs can therefore alias
+without a hash collision. Do not use this legacy encoder as an identity or
+authorization boundary for untrusted IDs. Inputs that differ only by surrounding
+whitespace intentionally map to the same output. Its output and the default
+encoder selected by `resolveSafeInstallDir` remain unchanged for compatibility.
 
 ## Common patterns
 
 ### Install a plugin
 
 ```ts
-import { resolveSafeInstallDir, assertCanonicalPathWithinBase, safePathSegmentHashed } from "@openclaw/fs-safe/advanced";
+import { resolveSafeInstallDir, assertCanonicalPathWithinBase, safePathSegmentHashedV2 } from "@openclaw/fs-safe/advanced";
 import { extractArchive } from "@openclaw/fs-safe/archive";
 import fs from "node:fs/promises";
 
 const r = resolveSafeInstallDir({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   id: untrustedName,
   invalidNameMessage: "invalid plugin name",
-  nameEncoder: safePathSegmentHashed,
+  nameEncoder: safePathSegmentHashedV2,
 });
 if (!r.ok) return reply(400, r.error);
 
 await fs.mkdir(r.path, { recursive: true, mode: 0o755 });
 await assertCanonicalPathWithinBase({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   candidatePath: r.path,
   boundaryLabel: "plugin install dir",
 });
@@ -148,6 +193,7 @@ const snap = resolveSafeInstallDir({
   baseDir: "/srv/snapshots",
   id: `${runId}-${version}`,
   invalidNameMessage: "invalid snapshot id",
+  nameEncoder: safePathSegmentHashedV2,
 });
 if (!snap.ok) throw new Error(snap.error);
 await fs.mkdir(snap.path, { recursive: true });

package/docs/install.md

@@ -31,6 +31,40 @@ node --version
 # v22.0.0 or newer
 ```
 
+## Bun runtime
+
+Bun 1.4.2 can run the same public APIs and load the matching native package.
+On macOS and Linux, fs-safe uses its Rust N-API addon to call the system
+`realpath` implementation for native resolution. Ordinary resolution follows
+Node's component walk, including lexical normalization of expanded symlink
+targets, in Rust, with a 1,024-link expansion limit that returns `ELOOP` for
+excessive or cyclic expansion. This works around Bun path-resolution defects that
+otherwise reject restrictive permissions and confuse literal POSIX backslashes
+with directory separators. The OS still resolves symlinks and canonical file
+names; fs-safe retains its confinement and file-identity checks.
+
+This works with `bun --jitless` and needs no runtime FFI or JIT. Use native mode
+`auto` or `require` with the matching addon installed. `FS_SAFE_NATIVE_MODE=off`
+still disables all addon loading; `auto` without the addon falls back to Bun's
+resolver. Those configurations retain Bun 1.4.2's limitations with restrictive
+permissions, sockets, literal backslashes, and symlink/parent traversal. Use
+Node if you need full compatibility without the addon. On Bun POSIX, `require`
+also rejects canonicalization when the addon or its canonicalizer is unavailable.
+
+Node and Windows use their existing runtime canonicalizers. On Windows, Bun's
+recursive directory creation receives an absolute spelling that preserves raw
+path components, working around its rejection of existing relative `.` and `..`
+directories. Windows native descriptor-relative operations require Bun to expose
+the paired libuv descriptor bridge from its host executable; a missing or partial
+bridge fails explicitly with `ENOTSUP`. Public paths and caller-supplied filesystem
+adapters remain unchanged.
+
+The upstream fix is tracked in [Bun #42374](https://github.com/oven-sh/bun/pull/42374).
+The adapter can be removed when the supported Bun baseline includes that fix.
+Run native compatibility checks with `pnpm test:bun:native` after building the
+package and addon. See [contributing](contributing.md) for the Node/pnpm toolchain
+and the broader diagnostic suite.
+
 ## TypeScript
 
 Types ship with the package — no `@types/openclaw__fs-safe` needed. The `exports` map in `package.json` provides typed entries for every subpath:

package/docs/native-helper.md

@@ -30,10 +30,17 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 | `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
 
 TAR/gzip in the guarded JavaScript path uses a bundled, import-free WASM build
-of the same Rust parser used by native. `off` still disables native filesystem
-code; it does not disable this portable parser. ZIP fallback still requires
+of the same Rust parser used by native. `off` still disables the optional native
+filesystem helper; it does not disable this portable parser. ZIP fallback still requires
 optional `jszip`, and zstd/bzip2 remain native-only.
 
+On Bun macOS/Linux, the [runtime path adapter](install.md#bun-runtime) uses the
+same Rust addon for system canonicalization in `auto` and `require`. No JIT is
+needed. With `off` or a missing addon in `auto`, Bun's own resolver retains its
+path and permission limitations. Canonicalization in `require` fails with
+`helper-unavailable` if the addon or its canonicalizer is missing, including
+when admitting a temp workspace. Containment and identity checks stay intact.
+
 Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
 
 [`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)
@@ -57,16 +64,18 @@ change the mode policy of existing fallback-capable APIs.
 
 The native layer exposes policy-free filesystem mechanisms: beneath-root
 open/mkdir/link, replace and no-replace rename, identity reads, archive decode/execution,
-clone/copy/hash workers, and Windows security descriptor calls. The TypeScript
+clone/copy/hash workers, POSIX canonicalization, 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`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
 - 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; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
-- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed.
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table.
 
 Native primitives back create-only and replacing pinned writes, async sidecar creation,
-guarded publication, archive acceleration, and direct Windows ACL operations.
+guarded publication, archive acceleration, and direct Windows ACL operations. Windows
+secure-file reads require descriptor-bound owner/DACL facts from the current helper;
+they do not use the standalone pathname inspector's command fallback.
 Equivalent JavaScript paths remain available for documented fallback-capable
 features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
 for the exact difference.

package/docs/native.md

@@ -55,7 +55,12 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
   `FILE_OPEN_REPARSE_POINT`, then explicitly rejects reparse points. Rename and
   hardlink operations stay rooted in already-open handles. Owner/DACL reads
   use `GetSecurityInfo`; private directories receive their protected DACL in
-  the `CreateDirectoryW` call itself.
+  an exclusive, handle-relative `NtCreateFile` call. Their created handles remain
+  open through ACL and pathname-association checks and own any failure cleanup.
+  N-API descriptors cross into and out of
+  this layer only through the host executable's paired libuv descriptor bridge;
+  missing or partial exports fail with `ENOTSUP` instead of trying a raw HANDLE
+  or add-on CRT descriptor namespace.
 
 ## Archives
 
@@ -125,6 +130,13 @@ All routes preserve `wx` semantics and the same source/target identity and
 SHA-256 fencing. Native hashing and Linux whole-file copying run on N-API async
 workers rather than the JavaScript event loop.
 
+Linux range copying confirms every zero-byte result with a positioned source
+read at the current transfer offset, including after earlier calls copied data.
+If readable bytes remain, automatic Root copying resumes its byte loop from
+that offset; exclusive publication removes its partial target before retrying
+the guarded byte-copy fallback. EOF checks preserve descriptor cursors and do
+not bypass the byte limit.
+
 ## Mode semantics
 
 | Mode | Native loading | Fallback |
@@ -133,6 +145,10 @@ workers rather than the JavaScript event loop.
 | `require` | Try once, cache the result | Throw `FsSafeError("helper-unavailable")` |
 | `off` | Never attempt a binding load | Always use guarded JavaScript |
 
+`sha256FileSync()` is a synchronous Node implementation in all three modes and
+does not load the binding. Use asynchronous `sha256File()` for native hashing
+and cancellation that can respond while JavaScript callbacks run.
+
 Features without a safe JavaScript implementation, including zstd/bzip2 TAR,
 Windows private-directory creation, and [retained-directory staging](staged-file.md),
 fail with `helper-unavailable` when native support is absent or off. Staging
@@ -178,7 +194,7 @@ remain TypeScript-owned. What changes is the syscall strength or availability:
 | 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. |
 | `rename-noreplace` | Atomic platform no-replace rename. | Unsupported; no emulation by check-then-rename. |
-| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. | Structured .NET owner/DACL inspection for coarse permission checks; the public raw ACE facts API remains native-only. |
+| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. Secure-file reads query the borrowed open descriptor and compare its 32-bit volume serial and 64-bit file-index projection with Node's bigint receipt. | Structured .NET owner/DACL inspection remains available to standalone pathname reporting. Secure-file reads fail closed without the descriptor capability. |
 | Windows private directory | Creation-time protected DACL. | Unsupported; no weaker pathname-only substitute. |
 
 Use `off` in CI to keep the fallback contract exercised. Use `require` when a

package/docs/output.md

@@ -35,6 +35,7 @@ type ExternalFileWriteOptions<T = void> = {
   maxBytes?: number;
   mode?: number;
   staging?: "workspace" | "sibling"; // default: "workspace"
+  producerIsolation?: "private-directory"; // opt-in for sibling staging
   fallbackFileName?: string;          // safe staged-name fallback
 };
 
@@ -60,7 +61,7 @@ hazards but does not trim Windows-normalized trailing dots or spaces; reject or
 rewrite those when cross-platform filename uniqueness matters.
 `staging: "workspace"` passes the sanitized basename to the producer.
 `staging: "sibling"` embeds that basename in its randomized temporary name.
-When the complete temporary component would exceed 255 bytes under NFC or NFD,
+When the complete temporary component would exceed 255 bytes as written or under NFC or NFD,
 only the embedded tail is shortened, preserving its extension when possible;
 short callback paths remain unchanged. The final target and returned `path` use
 the destination basename, sanitized
@@ -76,8 +77,8 @@ the temp and destination filesystems may differ, or when an externally produced
 partial file must never appear in the destination directory. The final target
 still appears only after guarded finalization.
 
-`staging: "sibling"` gives the producer a randomized temp path in the target
-directory. Choose it only when that directory itself is the approved writable
+By default, `staging: "sibling"` gives the producer a randomized temp path in
+the target directory. Choose it only when that directory itself is the approved writable
 boundary and same-filesystem atomic replacement is required. After the callback
 returns, fs-safe pins and validates the staged regular file, rejects hardlinks
 and size-limit violations, applies `mode`, fsyncs it, and atomically renames it
@@ -91,11 +92,36 @@ cleanup retry.
 Sibling staging shares the [callback sibling owner](temp.md#sibling-temp-writes):
 it checks exact pre-open, descriptor, and current-path identities, retains the
 descriptor through publication, and never chmods or reads a replacement by path.
-Cleanup preserves unverified paths, including partial output when the callback
-throws before admission. Native-off and Windows operation remain supported with
-the platform limits and non-atomic rename/unlink identity checks described there.
+Without producer isolation, cleanup preserves unverified paths, including partial
+output when the callback throws before admission. Native-off and Windows
+operation remain supported with the platform limits and non-atomic
+rename/unlink identity checks described there.
 When `mode` is omitted, output-sibling staging preserves the producer's mode.
 
+Add `producerIsolation: "private-directory"` to sibling staging when the
+producer can leave partial output before throwing. It receives an initially
+absent file path inside a private child workspace under the target parent, on
+the target filesystem. Directory cleanup ownership is captured before the
+callback. A callback exception triggers owned workspace cleanup, including
+partial output, subject to directory identity checks and I/O failures.
+After success, `Root.move` checks source aliases and moves the output to the
+ordinary sibling path; an escaping symlink can fail with `path-alias` here.
+Rejected output still inside the workspace follows its cleanup contract. Once
+output moves to the sibling path, the existing unadmitted-file retention and
+single-link regular-file admission, mode, file sync, and final rename rules apply.
+
+Exact bigint parent and workspace identities are rechecked before moving
+output to the sibling path to reject observed replacements. Cleanup uses the
+existing [`withTempFile` ownership contract](temp.md#withtempfile). A moved or replaced parent or workspace can
+leave original or replacement paths behind; the option does not promise
+cleanup through a retained directory after a rename. The existing Windows,
+native-off, and JavaScript guard limitations remain, with no additional
+permissions or durability guarantee. See the [producer-isolation contract](temp.md#sibling-temp-writes)
+for cleanup and pathname-race details. The option affects only `staging: "sibling"`;
+with `staging: "workspace"`, it is redundant and harmless because the producer
+already uses a private workspace. Omitting it leaves both staging defaults
+unchanged.
+
 ## Why not pass the final path to the library?
 
 If a target parent can be swapped after validation, handing an external library

package/docs/path-case.md

@@ -0,0 +1,64 @@
+# Path case probing
+
+`probePathCaseInsensitiveSync()` observes whether a path's lookup location
+folds ASCII case. It returns `true`, `false`, or `undefined` when the observation
+cannot establish an answer. It does not infer a filesystem property from the
+operating system or cache its result.
+
+```ts
+import { probePathCaseInsensitiveSync } from "@openclaw/fs-safe/advanced";
+
+const insensitive = probePathCaseInsensitiveSync("/srv/data/future.json", {
+  allowTemporaryProbe: false,
+});
+if (insensitive === undefined) {
+  // The application decides how to handle an unavailable observation.
+}
+```
+
+## Lookup location
+
+The input is resolved with Node's `path.resolve()`. Existing targets, including
+directories and final symlinks, are first compared by basename in their parent.
+The probe does not follow a final symlink to decide the target's case behavior.
+Parent aliases are followed. For a missing path, it walks to the nearest existing
+directory whose metadata can be read, without creating the missing directories.
+An unreadable directory listing returns `undefined`.
+
+The probe checks existing directory entries before considering a temporary
+file. Separately listed case variants count as distinct entries even when they
+are hardlinks to the same inode. Identity comparisons retain bigint precision;
+unknown Windows identities do not count as matches. The original entry is
+rechecked after looking up its case variant, so its disappearance or replacement
+invalidates the observation. A detected directory replacement also returns
+`undefined`.
+
+## Temporary probes and cleanup
+
+`allowTemporaryProbe` defaults to `true`. When existing entries give no answer,
+the helper exclusively creates one empty `.fs-safe-case-probe-*` file in the
+selected directory at mode `0o600`. It uses the existing temporary-file owner
+to retain the descriptor and exact cleanup identity. Successful ordinary
+completion removes the probe and closes the descriptor.
+
+Set `allowTemporaryProbe: false` for strictly read-only observation. In that
+mode an empty directory, or one with no useful ASCII-case names, returns
+`undefined` without creating a temporary file. Temporary probing can change
+directory timestamps and trigger filesystem watchers even when cleanup succeeds.
+
+Operational failures, unverified identities, changed entries, and cleanup
+failures return `undefined`. A substituted or hardlinked temporary entry is
+preserved. When cleanup fails operationally, the existing owner retains its
+identity-bound process-exit retry. A creation whose identity cannot be obtained
+may leave an empty file; the helper never guesses cleanup ownership. Therefore
+`undefined` does not promise that no temporary artifact remains.
+
+## Limits
+
+This is a local ASCII-case observation, not a Unicode-normalization test,
+filesystem-wide guarantee, lock, or authorization receipt. Directory enumeration
+and metadata lookups are separate operations. Concurrent changes can invalidate
+or immediately stale a result, and the final identity check and unlink are not
+an atomic conditional deletion. Use temporary probing only where creating a
+temporary file is permitted. The caller retains any admission, serialization,
+fallback, or later mutation policy.

package/docs/path-scope.md

@@ -1,6 +1,6 @@
 # pathScope()
 
-`pathScope()` is an advanced helper with the same boundary semantics as `root()`, but it operates on **absolute paths** the caller already trusts and returns plain `{ ok, path }` results instead of throwing. Use it when you want the boundary check up front before handing an absolute path to another library.
+`pathScope()` prepares absolute paths and returns plain `{ ok, path }` results. `resolve()` and `resolveAll()` check lexical containment without touching the filesystem; `existing()`, `files()`, and `writable()` add the filesystem checks described below. Use it to prepare paths before handing them to another library, whose file-opening and mutation behavior still applies.
 
 ```ts
 import { pathScope } from "@openclaw/fs-safe/advanced";

package/docs/path.md

@@ -36,7 +36,7 @@ isPathInside("/srv/uploads", "/srv/uploads-other/x");        // false
 isPathInside("/srv/uploads", "/srv/uploads");                // true (root itself counts)
 ```
 
-The check is platform-aware: on Windows, paths are normalized for case and separator before comparison.
+The check is platform-aware: on Windows, paths are normalized for case and separator before comparison. This is deliberately a string-only, lexical answer; case folding does not prove that two differently cased prefixes name the same directory on a case-sensitive Windows directory. Root operations perform their own filesystem-identity admission when containment depends on case folding.
 
 ### `isPathInsideWithRealpath(rootDir, target, opts?)`
 

package/docs/permissions.md

@@ -42,7 +42,7 @@ 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`.
+`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. This remains a pathname reporting API with the fallbacks described below. `readSecureFile()` does not use those pathname fallbacks on Windows: it requires descriptor-bound native owner/DACL facts for the exact handle it reads.
 
 ## Advanced Windows ACL helpers
 
@@ -71,8 +71,17 @@ resolveWindowsUserPrincipal(env);
 The fallback Windows inspector reads the owner and DACL together through one
 built-in Windows PowerShell/.NET query. It returns canonical SIDs and numeric
 access masks, so Unicode paths and account names do not pass through lossy
-console display text. `inspectWindowsAcl()` uses the same query and returns
-canonical SIDs in its `principal` fields, with normalized rights tokens.
+console display text. `inspectWindowsAcl()` uses native descriptor facts for
+complete local ACLs with nonzero inherited ACEs (or empty/null DACLs) when the
+optional Windows binding is available. It applies
+the same classifier to native facts and the fallback query, returning canonical
+SIDs in its `principal` fields with normalized rights tokens. Explicit `env` or
+`exec` options retain the query path. Disabled or unavailable native helpers,
+remote or incomplete descriptors, leaf symbolic links, and native query errors
+use the fallback. Explicit ACEs and zero-mask entries also retain the query so
+.NET continues to own its ACE ordering and normalization.
+Structured ACLs containing only canonical SIDs are classified directly from
+the current-user SID without requiring a separate account-name lookup.
 The advanced options retain `currentUserSid` as an explicit classification
 override and `principalTranslationFailed: true` as an immediate unverified
 result. The optional `principalSids` translation cache is still accepted but
@@ -169,6 +178,31 @@ await openSqlite(path.join(sqliteDirectory, "sessions.sqlite"));
 On Windows with native support, this creates the directory and applies a
 protected owner + LocalSystem + Administrators full-control DACL directly with
 an atomic security descriptor; no PowerShell or `icacls` process is launched.
+The native operation retains the parent and exact created-directory handles
+through ACL and final pathname validation. If validation fails, it attempts only
+nonrecursive deletion through the created handle, preserving any pathname
+replacement. If cleanup also fails, the error retains the original failure and
+includes the cleanup failure.
+
+Directory association checks compare the complete 64-bit volume serial and
+128-bit `FILE_ID_INFO` identity, including on ReFS. If that identity class is
+unavailable, the operation fails closed without a narrower file-index fallback.
+Validation confirms that the created directory is local, its DACL is protected
+from inheritance, and its final public pathname opens the same local directory.
+
+This is a point-in-time pathname association check. The function closes its
+handles before returning; callers must keep the pathname's ancestry trusted
+during subsequent use, including opening SQLite databases in the example above.
+The immediate parent and final directory must not be reparse points. Earlier
+ancestor reparse points can be followed; this API does not reject every reparse
+point in the full ancestry.
+
+Path components ending in a space or period are rejected before filesystem
+operations to avoid differing Win32 and native pathname interpretations. This
+also rejects explicit `.` and `..` components, including spellings such as
+`.\private` and `parent\..\private`, as a compatibility restriction. Simple
+relative names without these components remain supported.
+
 This API is Windows-only and native-only; it fails closed with
 `FsSafeError("helper-unavailable")` on other platforms, when native mode is off,
 or when the binding is unavailable. POSIX callers should create private

package/docs/public-api.md

@@ -26,6 +26,11 @@ deprecated native-configuration bridge retains the `FsSafePythonConfig` type.
 
 ## `path` and `advanced`
 
+`safePathSegmentHashedV2` encodes every trimmed install ID with domain-separated
+SHA-256 into a fixed lowercase segment. The legacy `safePathSegmentHashed` keeps
+its existing output but can alias distinct IDs. See [install paths](install-path.md)
+for the exact encoding and migration contract.
+
 The lexical path surface additionally exports `isNodeError`,
 `isPathRelativeEscape`, `normalizeWindowsPathForComparison`,
 `resolveSafeRelativePath`, `splitSafeRelativePath`, and
@@ -38,6 +43,33 @@ The advanced root-file primitive exports `OpenRootFileParams`,
 `RootFileOpenFailureReason`. These are composition types for callers building
 their own pinned-open flow, not substitutes for the higher-level `Root` verbs.
 
+`copyFileHandle` and `CopyFileHandleOptions` transfer bytes between already-open
+regular files without taking over their cursors, lifetime, or publication.
+See [borrowed-handle transfers](copy.md#borrowed-filehandle-transfers).
+
+`readDirectoryIdentity`, `assertDirectoryIdentitySync`, and `DirectoryIdentity`
+provide exact directory observations without owning a descriptor or a mutation.
+The assertion accepts an observed path and optional expected canonical path;
+see [directory identity](directory-identity.md).
+
+`overwriteFileHandle` and `OverwriteFileHandleOptions` provide in-place byte
+replacement through a borrowed regular-file handle. Its once-only `beforeWrite`
+callback admits the complete write and any required best-effort rollback after
+prefix preparation. See [in-place writes](in-place-write.md).
+
+`probePathCaseInsensitiveSync` and `ProbePathCaseOptions` are advanced exports
+for local ASCII-case observations. An unavailable answer remains `undefined`;
+the caller selects any fallback. See [path case probing](path-case.md).
+
+## Guest source
+
+`@openclaw/fs-safe/guest` exports `GUEST_FILESYSTEM_PYTHON`,
+`GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE`,
+`GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE`, and
+`GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON`. These are source and protocol
+constants; the caller launches the Python guest and owns authorization and
+transport lifetime. See the [guest protocol](guest.md).
+
 ## `json` and `store`
 
 Standalone structured reads use `ReadJsonOptions`, `ReadRootJsonSyncOptions`,
@@ -89,8 +121,10 @@ The durability surface also exports the synchronous strict
 `EnsureDurableDirectoryOptions`, `PublishFileExclusiveResult`,
 `PublishFileExclusiveStrategy`, `PublishFileExclusiveCleanup`,
 `PublishFileExclusiveFailurePhase`,
-`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`, and
-`Sha256FileResult`.
+`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`,
+`Sha256FileSyncInput`, `Sha256FileOptions`, and `Sha256FileResult`.
+`sha256FileSync()` provides synchronous pathname or borrowed-descriptor hashing
+with the same byte-budget and digest-result contracts as `sha256File()`.
 
 ## Archives