@openclaw/fs-safe 0.11.0 → 0.13.0

package/docs/native.md

@@ -50,12 +50,40 @@ 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
   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.
+
+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
 
@@ -125,22 +153,30 @@ 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 |
 |---|---|---|
-| `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
@@ -177,12 +213,12 @@ 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. |
 | `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

@@ -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.

package/docs/path.md

@@ -36,7 +36,11 @@ 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.
+It is a lexical comparison, not a filesystem-admission boundary: it does not
+reject Windows alternate data streams or index-allocation aliases. Use a
+filesystem operation such as `root()` when a caller-controlled path will be
+opened or mutated.
 
 ### `isPathInsideWithRealpath(rootDir, target, opts?)`
 
@@ -54,6 +58,9 @@ type Options = {
 ```
 
 Does not throw on missing inputs — `realpath` failures are absorbed by the underlying `safeRealpathSync`. By default (`requireRealpath: true`) the function returns `false` when either input cannot be resolved. Pass `{ requireRealpath: false }` to fall back to the lexical answer from `isPathInside` instead.
+On Windows it returns `false` for namespace aliases in either raw input or in
+a canonical value returned by `realpath` or the supplied cache. The
+`requireRealpath: false` fallback does not admit those aliases.
 
 ### `isWithinDir(rootDir, targetPath)`
 
@@ -79,12 +86,16 @@ if (real === null) return notFound();
 ```
 
 All `realpath` failures collapse to `null` — there is no distinction between `ENOENT`, `EACCES`, and other I/O errors. Use `fs.realpathSync` directly if you need to branch on the error code.
+This convenience wrapper preserves ordinary Node `realpath` semantics; it is
+not a caller-path admission boundary on its own.
 
 ### `safeStatSync(targetPath)`
 
 Synchronous `stat` that returns `Stats` on success and `null` on any failure,
 including missing paths and permission errors. Use `fs.statSync` directly when
 the distinction matters.
+Like `safeRealpathSync`, it does not apply the pathname-admission policy used
+by the higher-level filesystem boundaries.
 
 ```ts
 const stat = safeStatSync("/srv/uploads/photo.jpg");

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
 
@@ -178,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/private-file-store.md

@@ -47,6 +47,20 @@ fileStoreSync({ rootDir: "/var/lib/app", private: true }).writeJson("config.json
 The sync store intentionally exposes a smaller surface: path resolution,
 lenient reads, and atomic text/JSON writes.
 
+Sync directory modes remain repair-compatible on POSIX, but repairs are applied
+only through an exact-identity, no-follow directory descriptor after the store
+root and admitted parent name are revalidated. Root or component swaps fail
+without chmodding the substituted directory. Matching modes take the no-open
+fast path. Windows uses its existing `mkdir` mode request plus exact directory
+identity checks and never falls back to pathname chmod.
+
+On Linux, Node offers no portable search-only descriptor that can also be
+`fchmod`ed. A mismatched directory without effective read access—including one
+created under an owner-read-removing umask—fails closed with
+`permission-unverified`. Supported macOS x64/arm64 hosts additionally try
+`O_SEARCH` when the directory remains searchable; an inaccessible directory
+still fails rather than restoring the pathname race.
+
 ## See also
 
 - [`fileStore`](file-store.md) — full store API.

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
@@ -56,6 +61,15 @@ prefix preparation. See [in-place writes](in-place-write.md).
 for local ASCII-case observations. An unavailable answer remains `undefined`;
 the caller selects any fallback. See [path case probing](path-case.md).
 
+`resolvePathPrefixSync` and `ResolvedPathPrefix` separate a canonical existing
+path prefix from its raw unresolved suffix after physical symlink traversal.
+See [resolving path prefixes](path-prefix.md).
+
+`probePathSuffixAliasesSync` and `ProbePathSuffixAliasesOptions` compare selected
+missing relative suffixes beneath an existing directory using bounded temporary
+directory probes. The caller owns Unicode-pair policy, caching, and the fallback
+for `undefined`. See [path suffix alias probing](path-suffix-aliases.md).
+
 ## Guest source
 
 `@openclaw/fs-safe/guest` exports `GUEST_FILESYSTEM_PYTHON`,

package/docs/quickstart.md

@@ -60,7 +60,7 @@ await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true })
 await fs.remove("notes/archive/today.txt");
 ```
 
-`move()` defaults to no clobber. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` works on files and empty directories. For non-empty directories, list and remove children first or use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
+`move()` defaults to no clobber. That mode requires the native helper so a concurrent target cannot be replaced between an absence check and the rename; without it, the call fails with `helper-unavailable`. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` works on files and empty directories. For non-empty directories, list and remove children first or use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
 
 ## 5. Inspect
 

package/docs/reading.md

@@ -27,10 +27,17 @@ Regardless of shape, every read goes through the same boundary checks:
 3. Resolve path components and reject anything that escapes the root (`outside-workspace`).
 4. Reject `..` traversal and absolute spellings when they resolve outside the root. In-root absolute spellings remain accepted; `readAbsolute` makes that intent explicit.
 5. Open with `O_NOFOLLOW` where available. Any remaining symlink in the path triggers `symlink` unless the call's `symlinks` policy is `follow-within-root`.
-6. Compare the pre-open path identity, the open fd, and the post-open resolved path (`sameFileIdentity`). A swap mid-call triggers `path-mismatch`.
+6. Compare the pre-open bigint path identity with the open fd, then perform one best-effort final admission: check the captured root identity, compare the policy-aware pathname with the fd, freshly canonicalize and re-admit that target inside the captured root, compare its exact bigint identity without following a final symlink with the fd, and check the root again. Both final pathname observations run even when their spellings match. An observed swap triggers `path-mismatch` or `outside-workspace`; a missing final path triggers `not-found`.
 7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`).
 8. If `maxBytes` is set, refuse reads larger than the cap (`too-large`).
 
+The final fence closes a rejected descriptor before any Root read consumes bytes or
+`open()` hands the descriptor to its caller. It is a sequence of filesystem
+observations, not an atomic kernel pathname/open primitive, so a hostile peer can
+still race the namespace after the last observation. Standalone absolute-file
+helpers have no captured `Root` identity and do not claim this replacement-root
+fence; use a `Root` for untrusted paths.
+
 ## Read shapes
 
 ### `fs.read(rel, options?)`

package/docs/root.md

@@ -100,7 +100,9 @@ The read methods also accept an absolute spelling that already resolves inside
 the root. `readAbsolute()` and `reader()` make that intent explicit and accept
 both the configured root spelling and its canonical real path when the Root was
 created through a directory symlink or Windows junction. An absolute path
-outside the root is still rejected.
+outside the root is still rejected. On Windows, alternate casing is accepted
+only when the differently cased Root prefix has the Root's exact directory
+identity; the operation then continues under the trusted Root spelling.
 
 ### Writes
 
@@ -112,7 +114,7 @@ fs.createJson(rel, value, options?)      // create() variant of writeJson
 fs.append(rel, data, options?)           // append text/buffer; syncs before close by default
 fs.copyIn(rel, sourceAbsPath, options?)  // copy from outside the root, atomically, with size cap
 fs.openWritable(rel, options?)           // FileHandle for streaming writes; supports await using
-fs.move(from, to, options?)              // rename within the root; defaults to no clobber
+fs.move(from, to, options?)              // rename within the root; native-backed no clobber by default
 fs.remove(rel, options?)                 // unlink file, rmdir, or bounded recursive removal
 fs.mkdir(rel, options?)                  // mkdir -p (creates missing parents)
 fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
@@ -219,7 +221,17 @@ source)` can reject a legal POSIX basename such as `c:photo.png`; callers that
 derive portable destination names from host files must sanitize or map that
 basename first.
 
-`openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Use it for streaming output. Prefer `await using` for cleanup.
+On Windows, every Root pathname admission also rejects NTFS alternate-data-stream
+and directory-index aliases: relative names containing `:`, or absolute names
+with a colon beyond the single rooted drive designator, fail with
+`invalid-path` before filesystem access. This includes spellings such as
+`file:stream`, `dir::$INDEX_ALLOCATION`, and `dir:$I30:$INDEX_ALLOCATION`.
+Rooted drive, UNC, and extended-drive paths keep their existing handling, and
+the separate device/network policies remain in force. Ordinary colon-bearing
+names remain valid on POSIX where the operation's existing drive-relative rule
+does not otherwise reject them.
+
+`openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Before truncation or handle return, descriptor and pathname identities are compared with lossless bigint metadata; persistently unknown Windows identities fail closed. The returned `stat` remains an ordinary numeric Node `Stats` object. Use it for streaming output. Prefer `await using` for cleanup.
 
 `remove` leaves non-empty directories unchanged unless `recursive: true` is
 provided. Recursive removal defaults to streaming entries in filesystem order;
@@ -297,7 +309,12 @@ fs.entries(rel, options?)        // nonrecursive AsyncIterable<DirEntry>, includ
 fs.resolve(rel)                  // absolute path inside the root, after canonicalization
 ```
 
-These do not pin a later operation. They are safe to expose to UIs and decision points; for the actual read or write, use the verb methods so the operation pins identity at the point of use.
+These do not pin a later operation. During `stat()`, the exact selected target and
+parent are checked around metadata collection; `list()` checks one exact selected
+directory around the complete name/metadata batch instead of repeating containment
+work for every child. A detectable redirection rejects with `path-mismatch` rather
+than returning names or metadata from the replacement. Results remain advisory
+after the call returns, so use the verb methods for the actual read or write.
 
 `entries()` streams immediate children in filesystem order by default. It
 supports cancellation, a physical-entry limit that throws on overflow, and

package/docs/secret-file.md

@@ -81,6 +81,9 @@ itself must not be an alias. Hardlinks are rejected by default so another
 in-tree name cannot alias the credential; pass `rejectHardlinks: false` only
 when you explicitly trust that layout.
 
+Read options are captured when the call starts. Mutating a shared options
+object while an asynchronous read is in flight cannot relax its link policy.
+
 These readers do not enforce ownership or mode bits on an existing file. Their
 read contract covers pinned identity, file type, link policy, and byte bounds;
 the `0o600` guarantee belongs to the write helpers below. Use