@openclaw/fs-safe 0.14.0 → 0.16.0

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

@@ -6,11 +6,11 @@ half-written replacement appears at the destination. Create-only writes
 (`create`, `createJson`, and `write` with `overwrite: false`) use sibling-temp
 staging with an atomic no-replace rename only on backends that provide one —
 the native binding, which `require` mode guarantees and `auto` mode uses when
-the binding loads. The pure-JavaScript fallback has no atomic no-clobber
-rename and does not stage: it claims the final name exclusively with `O_EXCL`
-and writes content in place, so a concurrent observer can see the new file
-before its content is complete. Use `require` mode when that visibility window
-matters.
+the binding loads. Ordinary buffered creation in the pure-JavaScript fallback
+claims the final name exclusively with `O_EXCL` and writes content in place, so
+a concurrent observer can see the new file before its content is complete.
+Buffered `create` and `createJson` accept `atomic: true` to stage complete content
+on this fallback too. Streamed creation already stages before publication.
 `append` and `openWritable` intentionally modify an opened file in place;
 `move`, `remove`, and `mkdir` mutate directory entries rather than file bytes.
 Each verb applies the boundary checks appropriate to its operation.
@@ -113,6 +113,14 @@ Native and pure-JavaScript Windows writers honor the option. Replacement writes
 sync staged content before rename and the final mode through the retained file
 handle. Directory sync remains best-effort.
 
+For `create` and `createJson`, `durable: "file"` requires each file sync to succeed,
+including on `EPERM`; it overrides a disabled Root durability default. Parent
+directory synchronization retains the existing best-effort policy. This also
+applies to streamed creation and is independent of publication strategy. Boolean
+durability options keep their existing behavior, including compatibility paths
+that tolerate `EPERM`. A failed file sync before staged publication prevents
+publication; a failure after publication can leave the complete file present.
+
 POSIX modes without read permission, including `0o000` and `0o200`, succeed:
 final verification uses a descriptor retained by the writer rather than reopening
 the published file. The requested mode is not relaxed for verification.
@@ -154,6 +162,41 @@ try {
 }
 ```
 
+### Atomic buffered creation
+
+```ts
+await fs.create("config/seed.json", initial, { atomic: true });
+await fs.createJson("config/settings.json", { enabled: true }, { atomic: true });
+await fs.create("config/flushed.json", initial, { atomic: true, durable: "file" });
+```
+
+`atomic: true` keeps the destination absent until all bytes have been written.
+The native backend uses its no-replace rename; the JavaScript fallback hardlinks
+the completed stage and unlinks its temporary name in the same JavaScript turn.
+The fallback requires hardlink support and fails without publishing partial bytes
+when that mechanism is unavailable. Other processes can briefly observe both
+names. Existing and raced entries are preserved, including dangling symlinks;
+ordinary confinement, type, hardlink, and symlink-policy rejections still apply.
+`assertBeforeMutation` retains its live checks through content writes and publication.
+
+Omitted or `false` preserves the existing buffered behavior. The option belongs
+to buffered `create` and `createJson`, not replacement writes or Root defaults.
+Streamed creation has no atomic opt-out. `atomic` changes visibility, not the
+existing `durable` file/directory synchronization policy; it does not turn
+best-effort synchronization into a strict crash-durability guarantee or strengthen
+JavaScript pathname containment.
+
+Atomic and streamed creates settle owned cleanup and close operations before
+returning. Failed or unverifiable cleanup is reported rather than silently
+discarded. Errors after publication and incomplete-settlement errors carry the
+existing `StagedFileFailureDetails` publication/cleanup receipts where the writer
+can establish them; native disposal can retain them inside a `SuppressedError`
+cause. Preserve those details when handling errors: a rejection can follow
+complete publication, and an indeterminate link or native rename must preserve names for
+recovery. A cleanup or close failure also retains the original operation failure.
+No later verification, mode, or synchronization failure authorizes deleting an
+already published complete destination. See [receipt meanings](staged-file.md).
+
 ### Streamed creation
 
 Pass an `AsyncIterable<Uint8Array>` to `create()` when bytes come from a database,
@@ -202,6 +245,12 @@ forcibly interrupted, so cancellation waits for its pending work and cleanup to
 settle. Do not mutate a yielded chunk until the next pull. Producer errors retain
 their original value when cleanup succeeds.
 
+Streamed creation retains the `signal` and `assertBeforeMutation` callback
+selected when the call starts. Replacing or deleting those options during a
+producer wait does not change the in-flight operation. Abort the original signal
+or update the live authority state checked by the original callback to revoke
+it; the callback continues to receive the original options object as `this`.
+
 An aborted or failed operation can leave created parent directories. If a
 stage's identity or parent cannot be verified during cleanup, the existing
 guarded cleanup preserves it. After publication, later verification or cleanup
@@ -268,6 +317,10 @@ await fs.move("incoming/foo.txt", "archive/foo.txt", { overwrite: true });
 
 Both `from` and `to` are bounded; `..` in either is rejected.
 
+Mutation policy is captured at call start; changes to caller-owned denial arrays
+apply to later moves. For live cancellation or revocation, throw from
+`assertBeforeMutation` immediately before dispatch.
+
 The default no-clobber mode requires the native helper. It admits both parent
 directory descriptors and performs a descriptor-relative no-replace rename, so
 a competitor that creates the target first is preserved and the source remains
@@ -407,6 +460,19 @@ an atomic check-and-delete syscall. Use OS isolation for that threat model.
 await fs.mkdir("snapshots/2026/05");
 ```
 
+Pass `{ private: true }` to create missing components with private permissions.
+An existing requested directory must already satisfy that policy; fs-safe does
+not repair it or change existing ancestor permissions. Concurrent creators may
+reuse the winner only after it passes the same checks.
+
+Buffered, streamed, and JSON `create` calls also accept `private: true`.
+New POSIX directories default to `0700` and files to `0600`; conflicting
+group/world or privilege bits are rejected before creation. Restrictive
+owner-only file modes remain available through `mode`. On Windows, creation
+uses protected ACLs rather than interpreting POSIX mode bits as access rules.
+This does not change `create`'s no-overwrite behavior or select its durability
+policy. See [creation](creation.md) for supported backends and owned descriptors.
+
 ### `fs.ensureRoot()`
 
 Treats `""` / `"."` as the root itself. Useful when a generic helper computes a relative directory and might end up at the root.
@@ -501,7 +567,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.16.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -25,6 +25,8 @@
   },
   "files": [
     "dist/archive-parser.wasm",
+    "dist/windows-security-bridge.cs",
+    "dist/windows-security-bridge.ps1",
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
@@ -144,10 +146,10 @@
     "test:bun": "bun node_modules/vitest/vitest.mjs run --config scripts/bun-vitest.config.ts",
     "test:bun:native": "bun scripts/bun-native-proof.mjs && bun node_modules/vitest/vitest.mjs run --config scripts/bun-native-vitest.config.ts",
     "test:coverage": "vitest run --coverage",
-    "test:coverage:collect": "pnpm build && vitest run --coverage --coverage.reporter=json --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.statements=0 --coverage.thresholds.branches=0",
+    "test:coverage:collect": "pnpm build && pnpm archive:wasm:allocator-tests && vitest run --coverage --coverage.reporter=json --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.statements=0 --coverage.thresholds.branches=0",
     "test:coverage:merge": "node scripts/merge-coverage.mjs",
     "test:security": "vitest run test/fs-safe.test.ts test/read-boundary-bypass.test.ts test/write-boundary-bypass.test.ts test/additional-boundary-bypass.test.ts test/adversarial-boundary-payloads.test.ts",
-    "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm docs:check && pnpm test && node scripts/check-pack.mjs",
+    "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm archive:wasm:allocator-tests && pnpm docs:check && pnpm test && node scripts/check-pack.mjs",
     "docs:check": "node scripts/check-doc-examples.mjs",
     "docs:site": "node scripts/build-docs-site.mjs",
     "native:build": "pnpm --filter @openclaw/fs-safe-native-build build",
@@ -164,24 +166,25 @@
     "crabbox:stop": "crabbox stop",
     "crabbox:warmup": "crabbox warmup",
     "archive:wasm": "node scripts/build-archive-wasm.mjs",
+    "archive:wasm:allocator-tests": "node scripts/build-archive-wasm.mjs --allocator-tests",
     "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.16.0",
+    "@openclaw/fs-safe-darwin-x64": "0.16.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.16.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.16.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.16.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.16.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.16.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {
     "@emnapi/runtime": "2.0.0-alpha.5",
-    "@napi-rs/cli": "3.9.1",
-    "@types/node": "^26.5.1",
-    "@vitest/coverage-v8": "5.0.0",
-    "fast-check": "^4.9.0",
+    "@napi-rs/cli": "3.10.3",
+    "@types/node": "^26.6.1",
+    "@vitest/coverage-v8": "5.0.1",
+    "fast-check": "^4.10.1",
     "istanbul-lib-coverage": "3.2.2",
     "istanbul-lib-report": "3.0.1",
     "istanbul-reports": "3.2.0",
@@ -189,10 +192,10 @@
     "tar": "7.5.22",
     "typescript": "^7.0.2",
     "vite": "8.3.0",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@11.25.0"
+  "packageManager": "pnpm@12.4.2"
 }

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 };
-}