@openclaw/fs-safe 0.14.0 → 0.15.0

package/docs/root.md

@@ -72,12 +72,22 @@ The default `order: "sorted"` enumerates and sorts each directory's names;
 wide directories. Budget exhaustion yields a `"truncated"` marker by
 default or throws `FsSafeError("too-large")` with `limitBehavior: "throw"`.
 Use `entryFilter(entry)` to return `"include"`, `"skip"`, or
-`"skip-subtree"`. `"skip"` omits the current entry but still descends into a
-directory; `"skip-subtree"` omits a directory and all of its descendants.
+`"skip-subtree"`, directly or through a Promise. `"skip"` omits the current
+entry but still descends into a directory; `"skip-subtree"` omits a directory
+and all of its descendants.
+Filters run serially outside metadata batches, with the options object as their
+`this` receiver. After an awaited filter resolves, the walk checks cancellation
+and revalidates the current listing directory and Root identities before using
+the decision. Captured entry metadata retains its snapshot semantics.
+
+Cancellation and iterator disposal wait for a pending filter to settle; they do
+not race the callback or close its directory while it is running. Callback
+throws and promise rejections reject the walk through normal cleanup.
 Directory reads remain fail-fast by default. With
 `onDirectoryError: "skip-and-report"`, the iterator instead yields
 `{ relativePath, kind: "directory-error", size: 0, error }` and continues with
-the remaining tree.
+the remaining tree. That policy also covers identity-check failures after an
+awaited filter, while callback failures always reject.
 See [Directory walking](walk.md) for the pure-Node guarantees and the contrast
 with the standalone best-effort walkers.
 
@@ -290,6 +300,15 @@ the caller, which must check authority before its own later writes.
 
 All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
 
+For writes, creates, streams, and copies, parent creation admits the prospective
+file and each missing directory before creating that directory, including on the
+Windows native route. An exact deny on an existing parent does not prevent using
+that parent to write an allowed child. If a deeper missing parent is denied,
+earlier admitted directories may remain; the denied directory and file are not
+created. With `mkdir: false`, missing parents are never created. Native Windows
+policy-aware creation requires the direct-child helper and fails with
+`helper-unavailable` if it is absent.
+
 All mutation methods also accept `mutationSymlinks`. `"reject"` rejects symlink
 components; `"follow-parents-within-root"` resolves contained parent directory
 aliases but rejects the final component if it is a symlink, including a dangling

package/docs/sidecar-lock.md

@@ -9,6 +9,13 @@ normal meaning, and ordinary colon-bearing POSIX paths remain valid.
 
 JavaScript raw-sidecar creation passes mode `0o600` to that exclusive open. On POSIX, the process umask may further restrict the new file but cannot add group or other access. No pathname `chmod` fallback is used.
 
+Root-backed lock records and reclaim guards also claim their final name
+exclusively, including with the native backend. The native path retains the
+admitted parent descriptor and removes incomplete claims only while their exact
+identity remains owned. Ordinary Root creates still stage privately; lock records
+use this internal exclusive-create path so racing contenders can retry without
+an ambiguous rename outcome.
+
 ```ts
 import { acquireFileLock } from "@openclaw/fs-safe/file-lock";
 
@@ -28,13 +35,32 @@ try {
 
 The lock file sits next to the protected resource. If a process crashes mid-lock, the next acquirer notices the held entry, inspects its payload (PID, host, acquired-at timestamp), and decides — via `shouldReclaim` (defaulting to "is the lock older than `staleMs`?") — whether it should keep waiting or fail.
 
-On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit")` handler attempts asynchronous cleanup of held Root-backed locks through their retained Root capability and ownership receipt. The synchronous `process.on("exit")` handler provides last-chance cleanup for raw locks and reclaim guards. Changed sidecars and failed Root cleanup remain in place; cleanup does not keep retrying during shutdown unless another acquisition re-arms it. Locks acquired with `retainOnExit: true` are exempt from both handlers: their sidecar stays in place after exit and is governed only by the caller's own stale policy. Because exit handlers are globally deduplicated across package copies, `retainOnExit` fails closed with `helper-unavailable` if an older copy that cannot honor it registered the handlers first.
+On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit")` handler attempts asynchronous cleanup of held Root-backed locks through their retained Root capability and ownership receipt. The synchronous `process.on("exit")` handler provides last-chance cleanup for raw locks and raw-path reclaim guards. Changed sidecars and failed Root cleanup remain in place; cleanup does not keep retrying during shutdown unless another acquisition re-arms it. Locks acquired with `retainOnExit: true` are exempt from both handlers: their sidecar stays in place after exit and is governed only by the caller's own stale policy. Because exit handlers are globally deduplicated across package copies, `retainOnExit` fails closed with `helper-unavailable` if an older copy that cannot honor it registered the handlers first.
+
+Asynchronous Root-backed stale recovery uses a regular file at the
+`.reclaim` name, created, verified, and removed through that Root. Its ownership
+token and exact bytes are checked after awaited decisions and before stale
+removal; Root mutation policies also apply to the guard. Raw and synchronous
+Root reclaimers use directories and recognize these files as occupied guards.
+Each asynchronous attempt owns its guard directly, outside process-exit cleanup,
+so `beforeExit` cannot release an exclusion still needed by an unsettled attempt.
+Normal completion removes it through the Root. Interrupted creation, revoked
+cleanup authority, identity changes, or process exit can leave the guard in
+place; recover it only after an application-owned liveness check proves the
+attempt has ended. There is no raw-path cleanup fallback. These token/byte
+checks retain the sidecar protocol's cooperative, non-atomic removal boundary.
+The final guard check follows the last sidecar snapshot and parser call, before
+removal. Parsers can run before guard ownership is established or verified;
+invocation is not mutation authority. A failing final parser keeps its error
+even if guard ownership has also changed.
+`manager.reset()` invalidates admission bookkeeping but preserves a pending
+Root guard; let its original attempt settle before retrying that guarded path.
 
 Always release locks in a `finally` block. Application-managed graceful shutdown can await `release()` or `manager.drain()` before terminating. Explicit `process.exit()`, uncaught failures, crashes, default signal handling, and fatal termination (including `SIGKILL`) do not reliably run asynchronous Root cleanup and may leave sidecars. Recover only after an application-owned liveness policy proves the holder cannot still be writing.
 
-Exit cleanup tolerates shared managers created by older package copies that lack reclaim-guard state, and continues through later manager domains. Handler ownership remains first-registration-wins: loading an updated copy does not replace an older copy's registered handler. Restart with the updated copy registering first to obtain the fix. After building, `node scripts/legacy-lock-exit-proof.mjs` checks clean exit, removal of legacy and modern raw locks, and preservation of a retained lock using synthetic temporary files.
+Exit cleanup tolerates shared managers created by older package copies that lack reclaim-guard state, and continues through later manager domains. Handler ownership remains first-registration-wins: loading an updated copy does not replace an older copy's registered handler. First registration is committed only after Node accepts the listener; synchronous `newListener` reentry fails closed and a thrown registration rolls back so a later acquisition can retry. Restart with the updated copy registering first to obtain the fix. After building, `node scripts/legacy-lock-exit-proof.mjs` checks clean exit, removal of legacy and modern raw locks, and preservation of a retained lock using synthetic temporary files.
 
-Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check.
+Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check. If Windows reports a zero device or inode for either identity observation, that check is inconclusive and removal is skipped.
 
 The raw sidecar bytes are not a canonical JSON representation: tools that trim or rewrite the trailing whitespace invalidate the ownership token, so release leaves the changed sidecar in place and fails closed. The token distinguishes cooperating acquisitions; it is not a secret and does not make pathname compare-and-remove atomic against a hostile process that can replace files outside the lock protocol.
 
@@ -62,6 +88,41 @@ function withFileLockSync<T, TPayload>(targetPath: string, options: FileLockSync
 
 `managerKey` is an optional identifier used to keep state isolated across multiple lock domains in the same process. Use distinct keys for distinct domains (`"snapshot"`, `"compact"`, `"build"`). If omitted, fs-safe derives one from the target path.
 
+Within one manager domain, the canonical target path is the in-process
+arbitration key even when callers supply different explicit `lockPath` values.
+Admission remains pending while payload serialization and stale-policy callbacks
+run, and becomes reentrant only after a matching owner is fully published.
+Foreign owners wait or reach the configured timeout without opening their
+alternate sidecar. Each unguarded attempt still invokes and serializes `payload`
+before a completed foreign holder consumes retry budget, preserving callback and
+retry compatibility; the holder is rechecked before delayed option accessors or
+sidecar I/O. When the candidate resolves to the holder's actual sidecar (the
+default path or an explicitly identical path), asynchronous retries also preserve
+the existing parser observation: bytes are observed first, then its accessor is
+read and the current holder bytes are parsed once per unguarded attempt.
+Distinct alternate sidecars do not trigger that observation. Async acquisition releases
+pending admission before retry backoff;
+synchronous callback reentry cannot let the active stack progress, so it fails
+closed with the normal `file_lock_timeout` fields. Async payload, serialization,
+delayed-option, and stale-policy callbacks carry a process-shared ancestry scope:
+a nested acquisition of the same canonical target in the same manager domain
+fails before waiting on its ancestor, while independent tasks, different targets,
+and different manager domains retain their normal retry behavior. The synchronous
+API uses one process-wide domain. An ancestry snapshot keeps each ancestor that
+is active when the child acquisition starts, even if the current callback's own
+scope already became inactive; later deactivation cannot reclassify that child.
+Detached work started only after every matching ancestor has finished is not
+retained as a descendant. Promise-like callback results are assimilated inside
+that ancestry scope, and the resolved payload crosses the internal return
+boundary in a non-thenable envelope. The helper therefore does not observe a
+stateful payload `then` accessor again outside the reservation.
+
+The pending-admission registry coordinates package copies that implement this
+protocol without placing incomplete state in the legacy held-lock map. An older
+already-loaded executable copy does not consult that registry, so a mixed-version
+process cannot rely on the new in-process arbitration until every copy is updated
+and the process is restarted.
+
 ## Acquire options
 
 ```ts
@@ -105,7 +166,11 @@ type FileLockRetryOptions = {
 };
 ```
 
-`payload` is a function so you can re-evaluate it on each retry (e.g. timestamp, PID).
+`payload` is a function so you can re-evaluate it on each retry (e.g. timestamp,
+PID). Callback-valued option accessors are otherwise captured once for an
+acquisition; the asynchronous same-sidecar parser observation above reads
+`parsePayload` once per unguarded attempt. Callback invocation keeps its
+established receiver behavior.
 
 Asynchronous acquisition snapshots `targetPath`, an explicit `lockPath`, and
 `lockRoot` before its first asynchronous operation. Cwd-dependent path spellings
@@ -295,6 +360,46 @@ deadline budget. Errors from descriptor reads/stats or parsing are not treated
 as missing snapshots, even when their code is `ENOENT`. Held verification,
 release, and reclaim do not retry open denials.
 
+Synchronous `lockRoot` is an authority boundary, not only a containment hint.
+It requires a genuine `Root` returned by the same loaded package copy; a
+structural/custom Root lookalike or a handle constructed by another installed
+copy fails with `helper-unavailable` before any remaining acquisition option or
+nested retry getter, payload evaluation, or filesystem effects. After reading
+`lockRoot` once, the genuine Root and its policies are snapshotted before those
+getters run. Construct `lockRoot` through the same import instance that provides
+the synchronous lock function. The acquirer retains the original Root context,
+exact root, parent, and file identities, and the Root's entry-time read, hardlink,
+mutation-symlink, `denyMutations`, and `assertBeforeMutation` policies. Those
+receipts remain authoritative through same-owner reuse, compromise checks,
+reclaim, explicit release, and process-exit cleanup. If the Root, an admitted
+parent, or the owned entry changes, cleanup leaves the ambiguous path in place.
+Root-backed synchronous records and their exit handler use a separate versioned
+global domain; legacy raw-lock handlers and legacy package copies cannot adopt or
+pathname-delete those records. Root and raw acquisitions never share a
+reentrant reference, even when their owner strings match.
+
+As with asynchronous Root-backed acquisition, synchronous target normalization
+does not create the target's parent. An explicit in-root `lockPath` can therefore
+guard an external or not-yet-created target key without creating anything next
+to that target. Missing directories for the sidecar itself are created one
+component at a time through the retained Root policy; the returned `lockPath`
+uses the admitted canonical spelling. This strengthens earlier synchronous
+behavior that treated `lockRoot` as a one-time lexical/canonical bound and used
+raw pathname operations afterward.
+
+Windows Root-backed target keys use native existing-ancestor canonicalization,
+so long and short spellings of the same target parent share an arbitration key.
+Sidecar admission applies both the retained mutation policy and read/final-link
+policy before payload evaluation; a dangling final sidecar link is rejected
+without creating its target.
+
+Exact Root, parent, and file receipts narrow replacement races but do not make a
+pathname check and the following `open`, `mkdir`, `unlink`, or `rmdir` one atomic
+filesystem operation. A hostile peer with direct write access can still race the
+final syscall. An observed mismatch fails closed and ambiguous entries remain;
+use OS-enforced directory permissions or a native descriptor-relative primitive
+when that attacker model must be excluded.
+
 Both synchronous helpers consume the [process-wide lock defaults](config.md#configurefssafelocks-config).
 A synchronous retry sleep is clamped to the remaining finite deadline, so a long or jittered backoff cannot extend the configured timeout or block forever.
 Per-call options take precedence, including zero values; a per-call `retry`

package/docs/staged-file.md

@@ -105,9 +105,13 @@ touching descriptors.
 basename. Empty, dot, dotdot, separators, absolute paths, NUL, control characters,
 drive-relative spellings, and the stage's own name are rejected.
 
-With `overwrite: false`, publication is genuine kernel no-replace rename; a
-collision leaves both names unchanged and raises `FsSafeError("already-exists")`.
-The stage may then be cleaned or published under another name. With
+With `overwrite: false`, publication is genuine kernel no-replace rename.
+A native collision raises `FsSafeError("already-exists")`, but ordinary errno
+does not prove that a remote rename never committed. Native rename failures
+without explicit pre-dispatch provenance therefore report `indeterminate`:
+cleanup preserves names and closes descriptors, and further publication rejects.
+Only rejection before rename dispatch leaves the stage eligible for cleanup or
+publication under another name. With
 `overwrite: true`, publication is plain atomic replacement. Neither route
 copies. Both source and destination resolve through the retained original
 parent, with checks immediately before rename and after publication.

package/docs/temp.md

@@ -221,9 +221,15 @@ A missing workspace returns `"missing"`. A replacement observed at the public
 name before quarantine returns `"identity-mismatch"` when the parent is stable;
 an ambiguous parent returns `"indeterminate"`. After successful removal,
 repeated cleanup returns `"missing"` without touching a recreated public name.
-Other statuses remain stable. Operational removal errors propagate and later
-cleanup returns `"indeterminate"` without retrying. Disposal and scoped helpers
-ignore returned statuses, while manual cleanup exposes the result.
+Other statuses remain stable. Compatible recursive-removal failures propagate
+the exact thrown value, including `undefined`, `null`, `false`, positive or
+negative numeric zero, bigint zero, an empty string, and `NaN`; they are never
+inferred from value identity or truthiness. Uncertain quarantine and
+retained-parent checks instead return
+`"indeterminate"`. After a propagated removal failure, later cleanup returns
+`"indeterminate"` without retrying. Disposal and scoped helpers ignore returned
+statuses, while manual cleanup exposes the result. A terminal descriptor-close
+failure retains its existing precedence if it also fails during settlement.
 
 When cleanup is part of a retention or audit decision, inspect the receipt
 instead of treating cleanup as fire-and-forget:
@@ -410,6 +416,12 @@ files, hardlinks, and changes between the pre-open pathname, opened descriptor,
 and current pathname are rejected. The callback must finish and close its
 writer before returning. Its return value is preserved as `result`.
 
+Each option is read once before directory creation starts, including both
+callbacks, the temp prefix, isolation, directory and file modes, and sync flags.
+Later changes to the options object do not change the in-flight operation.
+`writeTemp` and `resolveFinalPath` retain their shared internal staging object
+as the callback receiver.
+
 Generated temp filenames suffix Windows reserved-device basenames on every
 platform. Before either an ordinary or isolated producer runs, the completed staging
 name must be a nonempty, non-dot path component with no POSIX or Windows
@@ -536,6 +548,11 @@ await writeViaSiblingTempPath({
 If `replaceFileAtomic` does what you need, prefer that. Use
 `writeViaSiblingTempPath` when the producer needs a concrete temp pathname but
 the final destination still needs root-boundary checks.
+
+The root, target, callback, fallback filename, and temp prefix are read once
+before setup. Later changes to the parameters do not affect the in-flight
+operation; `writeTemp` retains the original parameters object as its receiver.
+
 Its private workspace uses `tempFile()`'s compatible identity-aware cleanup.
 It preserves replacements observed before removal, but retains the final
 pathname-recursive-removal gap described above; this helper does not expose

package/docs/walk.md

@@ -59,12 +59,43 @@ type WalkDirectoryOptions = {
   include?: (entry: WalkDirectoryEntry) => boolean;
   descend?: (entry: WalkDirectoryEntry) => boolean;
 };
+
+type AsyncWalkDirectoryOptions = Omit<WalkDirectoryOptions, "include" | "descend"> & {
+  include?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
+  descend?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
+};
 ```
 
 `symlinks` defaults to `"skip"`. `"include"` returns symlink entries without following them. `"follow"` resolves symlinks with `stat()` and may descend into linked directories, so use it only when that is intentional. Already-visited real directories are skipped so symlink cycles do not recurse forever.
 
+Before descending into a child directory, `skip` and `include` recheck whether
+that entry has become a symlink, including changes made while a filter waits.
+The explicitly supplied walk root may still be a symlink. This best-effort
+child check does not turn the standalone walker into a confinement boundary;
+use `Root.walk()` when root confinement is required.
+
 `include` controls which entries are returned. `descend` controls which directory entries are traversed. A skipped directory can still be returned if `include` accepts it.
 
+The asynchronous `walkDirectory()` accepts `AsyncWalkDirectoryOptions`. It resolves each `include` decision before calling `descend`, and resolves descent before reading the directory's children. Decisions run serially in the existing filesystem-order depth-first traversal. Both callbacks retain the supplied options object as their `this` receiver.
+
+Absent callbacks and primitive results keep the synchronous selection path. Object and function results are awaited directly, including promises and thenables. For JavaScript callers, nullish results retain the default `true`; other resolved values use their existing truthiness. Return booleans or promises of booleans for the typed API.
+
+```ts
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const scan = await walkDirectory("/safe/workspace", {
+  include: (entry) => entry.kind === "file",
+  descend: async (entry) => {
+    const marked = await fs.access(path.join(entry.path, "SKILL.md"))
+      .then(() => true, () => false);
+    return !marked;
+  },
+});
+```
+
+This prunes a directory after finding its marker without listing that directory's children. Callback throws and promise rejections reject the walk; they are not directory failures in `failedDirs`. Filtering still consumes the examined-entry budget. `WalkDirectoryOptions` and `walkDirectorySync()` remain synchronous; the async options do not add confinement or cancellation to the standalone walker.
+
 Unreadable directories are skipped rather than throwing, but every skipped directory is recorded in `failedDirs`. This keeps the helper suitable for best-effort inventories while letting pruning jobs tell an incomplete scan from an empty one: a destructive reconcile that deletes state for paths missing from `entries` must first confirm `failedDirs` holds no real read failures, or a transient `EIO`/`EACCES` blip would be mistaken for mass deletion. Use a stricter root-bounded operation when every entry must be accounted for.
 
 ## Root-bounded async iteration
@@ -123,7 +154,9 @@ If a thrown walk failure and directory close both fail, disposal throws a
 `SuppressedError` with the close failure in `error` and the original failure in
 `suppressed`, preserving both causes.
 
-`entryFilter` is evaluated for each resolved file, directory, or other entry:
+`entryFilter` is evaluated for each resolved file, directory, or other entry.
+The `RootWalkEntryFilter` callback returns a `RootWalkEntryFilterResult`
+or a `Promise<RootWalkEntryFilterResult>`:
 
 ```ts
 for await (const entry of capability.walk("", {
@@ -147,10 +180,43 @@ The result values are `"include"`, `"skip"`, and `"skip-subtree"`. Plain
 `"skip-subtree"` omits that directory and prunes its descendants. Returning
 `"skip-subtree"` for a non-directory is equivalent to `"skip"`.
 
+An asynchronous filter can inspect a marker before deciding whether to prune:
+
+```ts
+for await (const entry of capability.walk("", {
+  symlinkPolicy: "skip",
+  entryFilter: async (entry) => {
+    if (
+      entry.kind === "directory" &&
+      await capability.exists(`${entry.relativePath}/SKILL.md`)
+    ) {
+      return "skip-subtree";
+    }
+    return "include";
+  },
+})) {
+  consume(entry);
+}
+```
+
+Filters run serially outside metadata batches and retain the supplied options
+object as their `this` receiver. When an awaited filter resolves, the walk
+checks cancellation and revalidates the current listing directory and Root
+identities before using the decision. These checks do not refresh the entry's
+captured metadata or pin a later operation.
+
+Cancellation and iterator disposal wait for a pending filter to settle. The
+walk does not race the callback against the abort signal or close its directory
+while the callback is running; callbacks must settle their own work for
+cancellation to finish. Callback throws and promise rejections reject the walk
+through its normal cleanup path, even with `onDirectoryError: "skip-and-report"`.
+
 `onDirectoryError` defaults to `"throw"`, preserving the original fail-fast
 contract. `"skip-and-report"` yields a discriminated
 `{ kind: "directory-error", relativePath, size: 0, error }` marker for a
 directory that cannot be resolved or listed, then continues with its siblings.
+This policy also applies when the directory or Root identity recheck after an
+awaited filter fails; callback failures themselves are not directory errors.
 Every examined directory entry consumes `maxEntries` before filtering, so
 `"skip"` cannot turn the iterator into an unbounded traversal. Reporting and
 `"truncated"` markers describe already-reached state and do not authorize

package/docs/writing.md

@@ -501,7 +501,11 @@ for (const file of files) await fs.write(`${stagingDir}/${file.name}`, file.body
 await fs.move(stagingDir, "snapshots/2026-05-05", { overwrite: true });
 ```
 
-For a true commit-or-rollback over a *directory*, use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
+For guarded whole-directory publication, use
+[`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic). Replacing an
+existing target is a two-rename protocol with a temporary target-absence
+interval and conditional no-replace rollback, not a transactional
+commit-or-rollback.
 
 ### Rotate logs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -167,20 +167,20 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.14.0",
-    "@openclaw/fs-safe-darwin-x64": "0.14.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.14.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.14.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.14.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.14.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.14.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.15.0",
+    "@openclaw/fs-safe-darwin-x64": "0.15.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.15.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.15.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.15.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.15.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.15.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {
     "@emnapi/runtime": "2.0.0-alpha.5",
-    "@napi-rs/cli": "3.9.1",
+    "@napi-rs/cli": "3.10.0",
     "@types/node": "^26.5.1",
-    "@vitest/coverage-v8": "5.0.0",
+    "@vitest/coverage-v8": "5.0.1",
     "fast-check": "^4.9.0",
     "istanbul-lib-coverage": "3.2.2",
     "istanbul-lib-report": "3.0.1",

package/dist/darwin-acl.d.ts

@@ -1,4 +0,0 @@
-import type { NativeDarwinAclFacts } from "./native-binding.js";
-/** Internal descriptor facts only; callers own identity, lifetime, and ACL policy. */
-export declare function inspectDarwinAcl(fd: number): NativeDarwinAclFacts;
-//# sourceMappingURL=darwin-acl.d.ts.map

package/dist/darwin-acl.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"darwin-acl.d.ts","sourceRoot":"","sources":["../src/darwin-acl.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,CAmBjE"}

package/dist/darwin-acl.js

@@ -1,24 +0,0 @@
-import { FsSafeError } from "./errors.js";
-import { getNativeBinding } from "./native.js";
-/** Internal descriptor facts only; callers own identity, lifetime, and ACL policy. */
-export function inspectDarwinAcl(fd) {
-    if (!Number.isInteger(fd) || fd < 0 || fd > 0x7fff_ffff) {
-        throw new FsSafeError("permission-unverified", "Darwin ACL inspection requires a valid descriptor");
-    }
-    const native = getNativeBinding();
-    if (typeof native?.inspectDarwinAcl !== "function") {
-        throw new FsSafeError("helper-unavailable", "Darwin ACL inspection requires the matching native capability");
-    }
-    let facts;
-    try {
-        facts = native.inspectDarwinAcl(fd);
-    }
-    catch (cause) {
-        throw new FsSafeError("permission-unverified", "Darwin descriptor ACL could not be inspected", { cause });
-    }
-    const state = facts && typeof facts === "object" && "state" in facts ? facts.state : undefined;
-    if (state !== "absent" && state !== "empty" && state !== "present") {
-        throw new FsSafeError("permission-unverified", "Darwin ACL inspection returned invalid facts");
-    }
-    return { state };
-}