@openclaw/fs-safe 0.12.0 → 0.13.1

package/docs/install-path.md

@@ -23,7 +23,7 @@ function resolveSafeInstallDir(params: {
 }): { ok: true; path: string } | { ok: false; error: string };
 ```
 
-Computes the absolute install directory for `id` under `baseDir`, after running `id` through `nameEncoder` (`safeDirName` by default). Verifies the result stays inside `baseDir` — anything that would escape returns `{ ok: false, error: invalidNameMessage }`.
+Computes the absolute install directory for `id` under `baseDir`, after running `id` through `nameEncoder` (`safeDirName` by default). Verifies the result stays inside `baseDir` — anything that would escape returns `{ ok: false, error: invalidNameMessage }`. On Windows, contained alternate-stream and filesystem-namespace aliases are rejected with the same result.
 
 ```ts
 const r = resolveSafeInstallDir({
@@ -64,7 +64,7 @@ function assertCanonicalPathWithinBase(params: {
 }): Promise<void>;
 ```
 
-Throws if the candidate resolves outside `baseDir` after `realpath`. The `boundaryLabel` is included in the error message ("Invalid path: must stay within {boundaryLabel}").
+Throws if the candidate resolves outside `baseDir` after `realpath`. On Windows it also throws for alternate-stream or filesystem-namespace aliases in the base, candidate, or canonical path. The `boundaryLabel` is included in the containment-shaped error message ("Invalid path: must stay within {boundaryLabel}").
 
 ```ts
 await assertCanonicalPathWithinBase({

package/docs/install.md

@@ -127,9 +127,10 @@ the matching binary. Consumers do not run a native build, download code at
 runtime, or execute a postinstall step. Omitting optional dependencies keeps
 non-archive fallback-capable operations working in `auto` or `off`. Native-only
 features, including strict owned-tree temp cleanup, retained-directory staging,
-atomic `rename-noreplace`, zstd/bzip2 TAR handling, and Windows private-directory
-creation, remain unavailable. Operations needing the binding in `require` mode fail with
-`helper-unavailable` when the matching package is absent or incompatible.
+atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
+zstd/bzip2 TAR handling, and Windows private-directory creation, remain
+unavailable. Operations without a safe fallback fail with `helper-unavailable`
+when the matching package is absent, incompatible, or disabled.
 
 Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
 before deploying with native mode `require` or native-only features.
@@ -138,15 +139,15 @@ before deploying with native mode `require` or native-only features.
 
 The platform native binaries provide fd-relative open/link/mkdir primitives,
 atomic no-replace rename, and file identity checks. The default is `auto`: use
-the matching binary when it loads, otherwise silently keep the guarded
-JavaScript path. Platforms without one of the seven published targets therefore
-continue through the documented fallback in `auto` mode.
+the matching binary when it loads, otherwise use the guarded JavaScript path
+where a safe fallback exists. Native-only operations fail with
+`helper-unavailable`.
 
 ```ts
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
 configureFsSafeNative({ mode: "auto" });    // default
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript; reject native-only operations
 configureFsSafeNative({ mode: "require" }); // fail closed if unavailable
 ```
 

package/docs/json-store.md

@@ -1,6 +1,6 @@
 # JSON store
 
-`jsonStore` is exported from `@openclaw/fs-safe/store`. It is the absolute-path
+`jsonStore` is exported from `@openclaw/fs-safe/store`. It is the single-path
 convenience wrapper for `fileStore(...).json(...)`: a small read-modify-write
 handle around a single JSON file. It bakes in atomic writes, explicit fallback
 reads, and optional cross-process locking via
@@ -71,6 +71,10 @@ type JsonStore<T> = {
 
 `jsonStore({ filePath })` resolves `rootDir = dirname(filePath)` and calls
 `fileStore({ rootDir, private: true }).json(basename(filePath), options)`.
+On Windows, the factory rejects NTFS alternate-stream and directory-index
+namespace spellings before preparing its private parent. An ordinary
+drive-relative path is anchored at entry and `store.filePath` exposes the
+resulting absolute path; ordinary colon-bearing POSIX paths remain valid.
 
 `durable: false` keeps sibling-temp replace/rename behavior but skips the
 temp-file and parent-directory `fsync` calls. Use it only for reconstructible

package/docs/json.md

@@ -38,6 +38,17 @@ Use `readJson` when missing-or-malformed is a programmer error you want to surfa
 
 `JsonFileReadError` carries `cause` so you can inspect whether the underlying failure was an `ENOENT`, a `SyntaxError`, or something else.
 
+On Windows, filesystem path inputs reject NTFS alternate-stream and
+directory-index namespace spellings such as `file:stream` and
+`dir::$INDEX_ALLOCATION`; ordinary colon-bearing POSIX names remain valid.
+Standalone JSON writers preserve their released support for an ordinary
+drive-relative destination by anchoring its leading drive designator at entry
+without normalizing the remaining suffix. Any additional colon is still
+rejected before filesystem access.
+Strict standalone readers retain `JsonFileReadError` and expose the
+`invalid-path` rejection as its cause, lenient `tryReadJson*` calls return
+`null`, and root-bounded readers report an `open`/`validation` failure.
+
 ## Reading
 
 ### `readJson<T>(filePath, options?)`

package/docs/mutation-policy-proof.md

@@ -0,0 +1,65 @@
+# Hosted mutation-policy proof
+
+The `mutation policy public behavior proof` workflow builds the exact event-head
+package and host addon on Node 24 Linux, macOS, and Windows. Each case executes in
+a fresh process, uses a private temporary fixture, and emits only a bounded,
+canonical receipt. POSIX workers require both real and effective non-root UIDs.
+
+Receipt schema `fs-safe-mutation-policy-proof-v2` deliberately does not describe
+final directory emptiness as a mutation-dispatch count. Root replacement records
+the unchanged contents of the original and replacement parent; denied redirect
+records rejection and unchanged denied/displaced parents. The existing JS mkdir
+counters name their exact child or next component. None counts native syscalls
+or excludes transient mutations that leave no final trace.
+
+## Additional hosted cases
+
+Each POSIX write/create/copy worker, under both native-off and native-require,
+performs an eligible success control, an exact deeper-parent denial after an
+earlier parent is created, a denied redirect after preflight, and a stale-parent
+replacement at the public pre-mkdir authority boundary. Exact directory listings
+and sentinels verify that denied/current/displaced parents contain no prohibited
+child, target, or stage. Copy sources must retain their original bytes.
+
+Redirect injection uses the existing public `@openclaw/fs-safe/test-hooks` subpath
+from `dist`, not a mocked native binding. Only these isolated workers enable
+`NODE_ENV=test`. The exact target and single hook visit are required. The hook is
+after policy preflight but before parent admission; it must not be described as
+a post-parent-admission hook. Stale replacement instead uses the public authority
+callback after child-create policy admission, with an existing sentinel parent
+and a still-missing child. Both implementation files that enforce the following
+freshness check are hash-bound. No unchecked callback ordinal chooses a fault.
+
+Representative POSIX `Root.write` workers refuse authority before the first mkdir,
+after one parent has been created and before the next mkdir, before staging, and
+immediately before publication. Epoch selection uses actual fixture state. The
+publication refusal requires a real single-link, caller-owned mode-0600 stage
+containing the complete payload while the destination still contains its original
+sentinel. The same rejection object must escape, no callback may follow refusal,
+and the owned stage must be gone before fixture teardown.
+
+Windows workers exercise buffer `Root.write` through a stable final-file symlink,
+then refuse before staging a newly created placeholder, before publishing over a
+new placeholder, and before publishing to an existing symlink-selected destination.
+They verify alias binding, destination preservation, observed placeholder/stage
+states, and cleanup before fixture teardown. The default native-off and explicit
+`verify-content-with-lock` native-require configurations both select the existing
+Windows JS buffer writer. The compatibility route is expected not to load the
+addon; the receipt does not mislabel this as native publication or evidence that
+content-verification fallback or lock contention was exercised.
+
+## Bounds and interpretation
+
+The receipt remains below 32 KiB, each worker has a 15-second process timeout and
+4-KiB stdout limit, and the proof step has a six-minute outer timeout. Worker I/O
+and cleanup retain their existing deadlines. The canonical pending/failed receipt
+is preserved if setup, a worker, provenance validation, or emission fails.
+Source, built modules, the public test seam, harness helper, contract tests, and
+host addon are hashed and checked again after workers.
+
+These are deterministic representative observations, not an exhaustive race proof
+or syscall audit. Existing hash-bound internal tests remain complementary for
+other awaited-admission, receipt-refresh, and observation-failure interleavings.
+Windows root replacement and POSIX-specific pinned routes are not claimed on
+Windows. Hosted CI and exact artifact inspection are required before relying on
+new receipts; the proof supplies no performance release clearance.

package/docs/native-helper.md

@@ -15,7 +15,7 @@ consumer Rust build.
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
 configureFsSafeNative({ mode: "auto" });    // default
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript; reject native-only operations
 configureFsSafeNative({ mode: "require" }); // fail closed when the binding is unavailable
 ```
 
@@ -25,8 +25,8 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 
 | Mode | Behavior |
 |---|---|
-| `auto` | Prefer native primitives when the current platform package loads; otherwise silently use the guarded JavaScript path. |
-| `off` | Do not load a native package. Use the guarded JavaScript path deterministically. |
+| `auto` | Prefer native primitives when the current platform package loads; otherwise use guarded JavaScript where a safe fallback exists and reject native-only operations. |
+| `off` | Do not load a native package. Use guarded JavaScript where safe and reject native-only operations deterministically. |
 | `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
@@ -43,6 +43,19 @@ 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.
 
+Native-created descriptors retain their originating native close operation through
+normal and error cleanup, including later mode changes. Node-created roots and
+directory handles keep Node's close operation, and borrowed handles keep their
+caller-owned lifetime. This preserves Node worker-thread descriptor tracking
+without unmanaged-descriptor warnings. A helper missing native close support is
+unavailable before descriptor allocation.
+
+Close retained native resources and let in-flight operations finish before
+forcibly terminating a worker. Native-created descriptors are not registered
+with Node's automatic worker-exit cleanup; `Worker.terminate()` can leave them
+open until process exit. The native close operation handles explicit cleanup,
+not forced worker termination.
+
 [`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)
 remain available in every mode. Their default compatible cleanup uses guarded
 JavaScript quarantine when owned native tree removal is unavailable.
@@ -62,6 +75,20 @@ change the mode policy of existing fallback-capable APIs.
 
 ## Native boundary
 
+The internal Darwin descriptor ACL inspector requires its matching native
+capability in both `auto` and `require`; `off`, a missing package, or an older
+binding without `inspectDarwinAcl` rejects with `helper-unavailable`. Inspection
+failure or malformed facts reject with `permission-unverified`; there is no
+mode-bit or pathname fallback for this capability. Clone admission uses a fused
+descriptor-bound metadata and ACL observation, then compares immutable receipts
+with fresh no-follow pathname identity fences; pathnames never authorize ACL
+state. The payload ACL-clear readback is part of that fused observation. Once
+a clone payload exists, normalization and verification failures become terminal
+`EIO` errors (with the underlying status and detail retained), not capability
+signals that permit an ordinary-copy retry. Checked cleanup cannot undo that
+terminal classification.
+This addition does not change other APIs' native-mode or permission contracts.
+
 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, POSIX canonicalization, and Windows security descriptor calls. The TypeScript
@@ -70,14 +97,17 @@ 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. 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. 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)
+- 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. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
+
+Native primitives back create-only and replacing pinned writes, no-clobber
+`Root.move()`, async sidecar creation, 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. No-clobber moves fail with
+`helper-unavailable` when descriptor-relative parent admission or the atomic
+no-replace rename is unavailable; they never use a check followed by a replacing
+rename. Equivalent JavaScript paths remain available for documented
+fallback-capable features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
 for the exact difference.
 
 The guarded JavaScript mutation path is detection-based, not containment-atomic.

package/docs/native.md

@@ -50,7 +50,20 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
   race-atomic. macOS uses `renameatx_np(RENAME_EXCL)` and permits
   `fclonefileat` in an owned, non-shared parent. The clone is normalized inside
   a private staging directory: flags, ACLs, extended attributes, and broad mode
-  bits are cleared before no-replace publication.
+  bits are cleared before no-replace publication. Clone admission obtains mode,
+  owner, exact identity, flags, and ACL state together from the retained descriptor;
+  immutable receipts are compared across the private staging operation and against
+  fresh no-follow pathname identity reads. Any extended entry on the target parent
+  or private staging directory is rejected before cloning bytes. The payload's
+  cleared ACL and normalized descriptor facts are verified before publication and
+  again, with a fresh published-name identity fence, before its descriptor is
+  returned. Unsupported admission before payload
+  creation or an unsupported clone syscall may still select the documented
+  ordinary-copy path. After the clone creates bytes, normalization and security
+  verification failures report terminal `EIO`, retaining the original error
+  detail; successful cleanup does not make them eligible for ordinary-copy retry.
+  Cleanup failures remain secondary diagnostics, and already-terminal publication
+  errors such as `EEXIST` retain their status.
 - Windows uses handle-relative `NtCreateFile` with `OBJ_DONT_REPARSE` and
   `FILE_OPEN_REPARSE_POINT`, then explicitly rejects reparse points. Rename and
   hardlink operations stay rooted in already-open handles. Owner/DACL reads
@@ -62,6 +75,16 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
   missing or partial exports fail with `ENOTSUP` instead of trying a raw HANDLE
   or add-on CRT descriptor namespace.
 
+The internal macOS `inspectDarwinAcl(fd)` capability reports `absent`, `empty`,
+or `present` for the opened object's extended ACL. It synchronously owns a
+close-on-exec duplicate for inspection, leaves the caller's descriptor and file
+position alone, and never reopens a pathname. Darwin's `acl_get_entry` returns
+zero for an entry; end-of-list is accepted only for the first entry of a valid,
+privately owned empty ACL. Unsupported, malformed, and failed inspection is not
+reported as absence. These facts do not classify individual ACE permissions,
+prove volume ownership enforcement, or add ACL enforcement to private writers
+and secure readers outside the clone path.
+
 ## Archives
 
 Native ZIP and TAR entry reads retain a private, unpooled input Buffer in
@@ -141,18 +164,19 @@ not bypass the byte limit.
 
 | Mode | Native loading | Fallback |
 |---|---|---|
-| `auto` | Try once, cache the result | Use guarded JavaScript when unavailable |
+| `auto` | Try once, cache the result | Use guarded JavaScript when safe; reject native-only operations |
 | `require` | Try once, cache the result | Throw `FsSafeError("helper-unavailable")` |
-| `off` | Never attempt a binding load | Always use guarded JavaScript |
+| `off` | Never attempt a binding load | Use guarded JavaScript when safe; reject native-only operations |
 
 `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
-is currently Linux/macOS only and rejects Windows with `unsupported-platform`.
+Features without a safe JavaScript implementation, including no-clobber
+`Root.move()`, 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 is currently Linux/macOS only and
+rejects Windows with `unsupported-platform`.
 
 The staged-file owner also serves POSIX native pinned writes, including streaming.
 Unpublished files remain at `0600`; requested modes are applied through the
@@ -189,7 +213,7 @@ remain TypeScript-owned. What changes is the syscall strength or availability:
 
 | Capability | Native path | Guarded JavaScript path |
 |---|---|---|
-| Root-relative opens/mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. Linux reports `kernel-atomic`; macOS and Windows report `best-effort`. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves the pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
+| Root-relative opens/mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Linux reports `kernel-atomic`; macOS and Windows report `best-effort`. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
 | ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | Optional JSZip or bundled WASM TAR into guarded private staging, then the same guarded merge policy. |
 | Zstd/bzip2 TAR | Supported. | Unsupported; typed `helper-unavailable`. |
 | Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |

package/docs/output.md

@@ -69,13 +69,23 @@ when needed as described above. Guarded temporary files used only inside
 fs-safe have independent names so their length does not grow with the
 destination basename.
 
+On Windows, `rootDir` and every target parent reject NTFS alternate-stream and
+directory-index namespace spellings such as `file:stream` and
+`dir::$INDEX_ALLOCATION`. A colon in only the requested basename still follows
+the documented portable filename sanitization above instead of being treated
+as a raw stream path. Ordinary colon-bearing POSIX roots and parents remain
+valid.
+
 ## Choosing a staging mode
 
 `staging: "workspace"` is the default. The producer writes in private temp
 storage, then fs-safe copies through the guarded root boundary. Choose it when
 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.
+still appears only after guarded finalization. Its internal `tempFile()` does
+not expose `cleanupSafety` through this API and uses compatible cleanup, with
+the final check-to-pathname-recursive-removal gap documented in
+[`tempFile`](temp.md#tempfile).
 
 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
@@ -104,19 +114,31 @@ 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.
+After success, an available native helper uses guarded no-replace `Root.move`.
+With native mode off, the helper opens and identity-fences the completed regular
+file, creates the randomized sibling through an atomic no-clobber hard link,
+verifies its temporary two-link state, then removes the private name. Windows
+first transfers the pin to an independently verified sibling descriptor so the
+source name can disappear before workspace cleanup, including on runtimes with
+legacy deletion behavior. If that unlink clears the producer's read-only
+attribute, the retained descriptor restores it and the helper verifies mode and
+identity before continuing. This keeps the handoff zero-copy while preserving the
+ordinary retained-descriptor, mode,
+file-sync, and final-rename lifecycle. Escaping symlinks still fail with
+`path-alias`; filesystems without hard-link support fail with
+`helper-unavailable`.
 
 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)
+compatible [`withTempFile` ownership contract](temp.md#withtempfile); this
+output option does not expose `cleanupSafety: "require-bounded"`. A moved or
+replaced parent or workspace can leave artifacts, and a workspace substituted
+in the final check-to-pathname-recursive-removal gap can redirect traversal.
+The option does not promise cleanup through a retained directory after a
+rename. The existing Windows and JavaScript pathname-guard limitations remain,
+with no additional permissions or durability guarantee. Native-off publication
+is supported only where hard links are available. 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

package/docs/path-prefix.md

@@ -0,0 +1,64 @@
+# Resolving an existing path prefix
+
+`resolvePathPrefixSync()` follows filesystem path components until the first
+missing entry. It returns a canonical existing prefix and the unprocessed
+suffix separately, including dangling symlink targets.
+
+```ts
+import { resolvePathPrefixSync, type ResolvedPathPrefix } from "@openclaw/fs-safe/advanced";
+
+const observed: ResolvedPathPrefix = resolvePathPrefixSync("/srv/data/future/file.json");
+// When /srv/data exists but future does not:
+// observed.existingPath is the canonical spelling of /srv/data.
+// observed.unresolvedSegments is ["future", "file.json"].
+```
+
+The result has three readonly fields:
+
+| Field | Meaning |
+| --- | --- |
+| `absolutePath` | Input anchored to the current directory or Windows drive, with raw path components retained and Windows separators converted to backslashes. |
+| `existingPath` | Existing prefix canonicalized by fs-safe's native-realpath owner. This may be a file when the entire path exists. |
+| `unresolvedSegments` | Components from the first missing entry onward, after expanding any earlier symlinks. Empty when the entire path exists. |
+
+## Physical traversal and missing paths
+
+The helper resolves `link/..` from the link's physical target. It does not use
+`path.resolve()` on the full input or a symlink target, because lexical
+normalization would erase that traversal. Relative inputs use the current
+directory; Windows drive-relative inputs use Node's current directory for that
+drive. A root-relative Windows symlink target retains its containing link's
+drive or share root. Windows junctions and full UNC share roots are supported.
+
+At the first `ENOENT`, traversal stops. A suffix such as
+`missing/../live.sqlite` remains `["missing", "..", "live.sqlite"]`, even if
+`live.sqlite` exists beside the missing component. Dot components, repeated
+separators, and a trailing separator in the unresolved suffix are retained.
+Normalizing that suffix would invent an alias to a file the filesystem cannot
+reach through the missing directory. The caller owns any application-specific
+comparison or prospective-path policy.
+
+## Failures and limits
+
+Only `ENOENT` from component inspection produces a missing suffix. Permission,
+I/O, non-directory traversal, symlink-reading, and final canonicalization
+failures propagate. A vanished symlink that was already observed is an error,
+not an unprocessed missing component. NUL bytes reject with `invalid-path`.
+
+Resolution rejects with `ELOOP` after 64 symlink expansions or a repeated
+resolution state. The state retains exact bigint device/inode identity and
+the remaining suffix, so revisiting a link with a shorter suffix is permitted.
+Traversing through a non-directory, including `file/..`, `file/.`, or `file/`,
+rejects with `ENOTDIR`.
+
+Dot and parent components require the directory's search permission before
+they are collapsed. Native realpath alone does not establish this permission
+on every platform. Empty components from repeated or trailing separators do
+not introduce a `.` lookup.
+
+This is a read-only path observation. It neither pins files nor creates a root
+boundary, authorizes access, or guarantees a consistent snapshot during
+concurrent changes. Results can become stale immediately. Use a guarded Root
+operation for subsequent access to untrusted paths; keep any database ownership,
+cache invalidation, and mutation policy with the caller. Native configuration
+and Bun realpath limitations follow the existing [runtime contract](install.md#bun-runtime).

package/docs/path-suffix-aliases.md

@@ -0,0 +1,159 @@
+---
+title: Path suffix alias probing
+description: "Bounded local observations for selected missing relative path suffixes."
+---
+
+# Path suffix alias probing
+
+`probePathSuffixAliasesSync()` observes whether selected missing relative suffixes
+would alias beneath an existing directory. It returns `boolean | undefined`; it
+does not infer filesystem behavior from the operating system or normalize a path
+into an authorization decision.
+
+```ts
+import { probePathSuffixAliasesSync } from "@openclaw/fs-safe/advanced";
+
+const aliases = probePathSuffixAliasesSync({
+  directory: "/trusted/existing-directory",
+  left: "Reports/Caf\u00e9",
+  right: "reports/Cafe\u0301",
+});
+if (aliases === undefined) {
+  // The caller must choose an explicit ambiguity policy.
+}
+```
+
+Use this for suffixes that do not yet exist. For local ASCII-case observations,
+including an explicit read-only mode, use
+[`probePathCaseInsensitiveSync()`](path-case.md). Suffix probing has no read-only
+mode: a nontrivial observation can create and remove directories and requires an
+approved writable parent.
+
+## API and validation
+
+```ts
+type ProbePathSuffixAliasesOptions = {
+  directory: string;
+  left: string;
+  right: string;
+  shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
+};
+
+function probePathSuffixAliasesSync(
+  options: ProbePathSuffixAliasesOptions,
+): boolean | undefined;
+```
+
+The helper reads and validates `directory`, then resolves it to an absolute path
+before reading the suffixes or predicate. Later option getters or the predicate
+cannot retarget a relative directory by changing the working directory. When
+filesystem observations are needed, the directory is canonicalized and its
+identity is checked; an initial directory alias can be followed.
+
+Suffixes must have the same number of ordinary relative path components. Empty
+components, `.` and `..`, absolute suffixes, NUL characters, and non-string path
+inputs are rejected with `TypeError`. Windows additionally rejects drive-relative
+components, colons, and reserved device names, including device aliases with
+extensions or trailing ignored characters. On POSIX, backslashes and colons are
+ordinary filename characters. The optional predicate must be a function.
+
+Both suffixes and the predicate are validated before the identical-suffix fast
+path. Identical, valid, within-budget suffixes return `true` without filesystem
+access or a predicate call. This does not prove that the directory exists or that
+the suffix can be created.
+
+## Fixed resource limits
+
+These limits apply to one call and cannot be raised through options:
+
+| Resource | Limit | On exceeding the limit |
+|---|---|---|
+| Each supplied suffix | 8,192 UTF-16 code units | `RangeError` before mutation |
+| Supplied and resolved directory paths | 32,768 UTF-16 code units each | `RangeError` before mutation |
+| Each suffix's component count | 32 | `RangeError` before mutation |
+| Directory-creation attempts | 128 | `undefined` after cleanup |
+| Successfully created probe directories | 64 | `undefined` after cleanup |
+| Forward filesystem observations | 4,096 | `undefined` after cleanup |
+| Each generated actual path | 32,768 UTF-16 code units | `undefined` after cleanup |
+
+Input limits are checked even for identical suffixes. Dynamic budgets count work
+across the whole call, including collision retries; removing a probe does not
+restore its creation budget. Cleanup is still attempted when a forward budget is
+exhausted and is not disabled by that exhausted budget.
+
+Candidates are generated lazily, only as needed. The helper does not eagerly
+allocate every possible probe name or consume randomness for unused retries.
+These are count and string-size limits, not a wall-clock guarantee. Synchronous
+filesystem calls, randomness, and caller code can block; the helper cannot
+interrupt them or promise a maximum elapsed time.
+
+## Results and caller policy
+
+- `true`: the suffixes are identical, or the requested observations found aliases.
+- `false`: an observation found distinct entries, or the caller's predicate
+  excluded a pair.
+- `undefined`: no reliable answer was obtained, including filesystem failures,
+  identity changes, exhausted collision candidates or dynamic budgets, generated
+  path limits, or incomplete cleanup.
+
+`undefined` is not evidence of either case sensitivity or aliasing. The helper
+does not cache observations, choose a fallback, reserve the future destination,
+or establish a root-confinement boundary. A result applies only to the local
+observations made during that call, not to every Unicode pair, mount, or later
+filesystem state.
+
+The optional trusted, synchronous `shouldProbeCaseVariants` predicate receives
+NFC-normalized component pairs when they differ and are not equivalent under
+ASCII case folding. Without a predicate, those pairs are eligible for probing.
+It is called in component order. Returning `false` excludes
+that pair and produces `false`; it is caller policy, not a filesystem finding.
+A first-component exclusion needs no probes or randomness. A later exclusion
+can follow earlier mutations, so it does not make the call read-only.
+
+A non-boolean predicate result throws `TypeError`; a predicate exception is
+re-thrown unchanged after cleanup attempts. Cleanup problems do not replace the
+original predicate failure. Do not use an asynchronous predicate or rely on the
+resource limits to bound arbitrary callback work.
+
+## Probe design
+
+The helper works through corresponding components, creating nested directories
+to observe inherited lookup behavior. ASCII-case probes use generated names.
+Normalization probes retain the original non-ASCII spellings while substituting
+suitable ASCII letters. When a generated pair is unavailable, the exact raw pair
+can be tried inside an owned neutral directory. Requested names are never
+materialized directly in the caller's unowned parent.
+
+Generated names are conservatively excluded when their NFC lowercase or uppercase
+forms could collide with either requested component. These folds are only a name
+exclusion rule; they never classify two requested paths as aliases. Short neutral
+and ASCII probe names use at most six characters and are no longer than the
+shorter requested component. Generated normalization pairs are also limited by
+the longer original joined path length. A raw-pair fallback adds a directory
+level; filesystem-specific name or path limits can still make it unavailable.
+
+Probes use normal directory creation and the process umask, preserving inherited
+directory behavior. They do not force mode `0700`, change parent permissions, or
+promise private probe names. Creation and removal can affect directory timestamps
+and filesystem watchers.
+
+## Identity and cleanup limitations
+
+The requested directory, canonical parent, and owned probe chain are rechecked
+with exact bigint filesystem identities. An alternate spelling must identify the
+same ordinary directory, not a symlink or unrelated collision. Existing files,
+directories, and symlinks at a candidate name are not removed to make room.
+
+Cleanup attempts owned directories in reverse order with identity checks and
+non-recursive removal. Nonempty directories and observed replacements are
+preserved. A cleanup failure changes an otherwise boolean result to `undefined`.
+If the first identity observation after a successful creation fails, a directory
+can remain: the helper does not guess ownership to delete it.
+
+This is a pathname-based observation helper, not an atomic filesystem
+transaction. There are unavoidable gaps between creation and the first identity
+observation, and between an identity check and a subsequent syscall. No pinned
+directory handle or atomic conditional deletion closes those gaps. Use a trusted,
+approved writable directory and application-level concurrency control where
+needed; do not use this helper as authorization to access attacker-controlled
+paths.