@openclaw/fs-safe 0.9.0 → 0.11.0

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,7 +64,7 @@ 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.
 

package/docs/native.md

@@ -59,6 +59,19 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
 
 ## Archives
 
+Native ZIP and TAR entry reads retain a private, unpooled input Buffer in
+the async reader. ZIP reuses its parsed directory; TAR retains admitted member
+offsets. TypeScript validates and selects the requested member before reading. The internal binding borrows that allocation: it must never be
+mutated or detached while the reader or a read task exists. The public API only
+accepts a pathname and owns this buffer exclusively. An N-API reference keeps
+the bytes alive; a mutex serializes access to the retained ZIP cursor. Plain
+TAR copies only the selected range after complete admission, while gzip, zstd,
+and bzip2 replay bounded decompression and validate the full physical stream.
+Concurrent TAR reads share immutable input and own separate decoder state.
+Each output owns a new vector, which N-API transfers to Node without a second
+payload copy on runtimes supporting external buffers. No entry-read path
+requires temporary-file staging. Extraction retains its private staged input.
+
 Rust streams ZIP and TAR payloads, including gzip, zstd, and bzip2. It first
 returns a bounded manifest. TypeScript applies the shared path, filter, strip,
 mode, and byte policies and returns an index-bound extraction plan. Rust then
@@ -120,6 +133,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
@@ -165,7 +182,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. | Established .NET/`icacls` inspection fallback for coarse permission checks; raw ACE facts are 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. | Structured .NET owner/DACL inspection for coarse permission checks; the public raw ACE facts API remains native-only. |
 | 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/permissions.md

@@ -68,11 +68,27 @@ createIcaclsResetCommand(targetPath, { isDir, env });
 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
+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 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
+is no longer needed because the query returns SIDs directly.
+The existing classifier assigns principals to trusted, world, or group;
+trusted defaults include the current user, SYSTEM, and Administrators.
+The built-in query has a fixed 30-second 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.
 Failed owner and ACL inspections retain `error` text and an optional
@@ -86,15 +102,18 @@ characters, including a trailing `…` when truncated. Diagnostics do not copy
 stdout or read target file contents. The separate `errorCause` retains the
 original exception for restricted local diagnosis; do not serialize or expose
 it as display text.
-The parser is on the advanced surface so tests and CLIs can process captured
-`icacls` output without spawning a process.
+The parser and remediation command builders remain on the advanced surface for
+CLIs processing captured `icacls` output or presenting an explicit repair.
+Runtime inspection does not parse that display text. A null DACL reports
+unrestricted access; an empty DACL grants nothing. Inherit-only ACEs do not
+apply to the inspected object, and deny ACEs never subtract coarse grants or
+claim effective-access evaluation. Unsupported ACE layouts remain unverified.
 
 When the native binding is available, `inspectPathPermissions()`
 reads the owner and DACL directly with Windows security APIs. It classifies the
 current user, LocalSystem, and built-in Administrators as trusted and reports
 the world/group read/write facts consumed by secure reads. Descriptor forms it
-cannot classify equivalently fall back to the established owner/.NET and
-`icacls` path; `mode: "off"` exercises that fallback deterministically.
+cannot classify equivalently fall back to the structured .NET query; `mode: "off"` exercises that fallback deterministically.
 
 ## Policy-free owner and DACL facts
 
@@ -164,7 +183,7 @@ This API is Windows-only and native-only; it fails closed with
 or when the binding is unavailable. POSIX callers should create private
 directories through their existing trusted-root creation policy rather than a
 pathname-only compatibility shim. Existing Windows permission inspection still
-retains its .NET/`icacls` compatibility fallback.
+retains its structured .NET compatibility fallback.
 
 Use `createIcaclsResetCommand()` when you need a structured command and argv pair. Use `formatIcaclsResetCommand()` when you only need a remediation string for a user-facing message.
 

package/docs/positional-read.md

@@ -0,0 +1,63 @@
+# Positional reads
+
+Use `readFileWindowFully()` and `readFileWindowFullySync()` to read a bounded
+window from an already-open file. They fill a caller-owned `Buffer`, completing
+short reads until the buffer is full or the file reaches EOF, and return the
+number of bytes read. They never allocate a payload buffer, close the descriptor,
+or change its current offset.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+import { readFileWindowFully } from "@openclaw/fs-safe/advanced";
+
+const workspace = await root("/srv/workspace");
+await using opened = await workspace.open("large.log");
+const buffer = Buffer.allocUnsafe(4096);
+const bytesRead = await readFileWindowFully(opened.handle, buffer, 8192);
+const window = buffer.subarray(0, bytesRead);
+```
+
+## Signatures
+
+```ts
+type ReadFileWindowOptions = { signal?: AbortSignal };
+
+function readFileWindowFully(
+  handle: import("node:fs/promises").FileHandle,
+  buffer: Buffer,
+  position: number,
+  options?: ReadFileWindowOptions,
+): Promise<number>;
+
+function readFileWindowFullySync(
+  fd: number,
+  buffer: Buffer,
+  position: number,
+): number;
+```
+
+`position` and the exclusive window end (`position + buffer.length`) must be
+non-negative safe integers. Invalid ranges throw `RangeError` before reading.
+A zero-length buffer returns zero without I/O. Reading at or beyond EOF also
+returns zero. If EOF occurs within the window, only the returned prefix is
+written; the remaining buffer bytes stay unchanged. Always slice by the returned
+count before using an unsafe-allocated buffer.
+
+These helpers use the caller's open descriptor directly. They do not establish
+path containment, file identity, file-type admission, or a snapshot of concurrently
+modified contents. Use [`Root.open()`](root.md#reads) to admit untrusted paths,
+and keep the handle open and the buffer available until the operation settles.
+Underlying I/O errors propagate unchanged.
+
+## Cancellation
+
+The async variant accepts `signal`. A pre-aborted signal rejects before I/O.
+In-flight cancellation is checked after the pending read settles and before
+another read starts, preserving the signal's reason. Bytes already read remain
+in the buffer; cancellation does not roll them back. Once the promise settles,
+the caller can reuse the buffer or close its handle without a hidden read still
+running.
+
+For a whole-file read that rejects files exceeding a byte limit, use the
+[bounded descriptor readers](advanced.md#files-and-identity) instead. Positional
+reads stop successfully at the requested window and do not probe for extra data.

package/docs/public-api.md

@@ -38,6 +38,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 +116,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