@openclaw/fs-safe 0.9.0 → 0.11.0

package/docs/writing.md

@@ -38,6 +38,12 @@ await fs.mkdir("snapshots/2026/05");
 Private sibling temporary names are independent of the destination basename,
 so staging does not add a suffix to an otherwise valid long filename.
 
+Write paths reject `path-alias` when symlinks and parent components select a
+different target before and after lexical normalization, such as `link/../file`
+where `link` points into a deeper directory. This avoids silently modifying the
+wrong file. Resolve an intended alias explicitly with `Root.resolve()` before
+passing its canonical path to a mutation.
+
 A failure before the final rename leaves the destination at its previous
 contents. A successful rename publishes the complete replacement. This
 old-or-new guarantee does not apply to `append()` or `openWritable()`, which
@@ -48,6 +54,10 @@ Post-publication verification can still reject after a complete replacement has
 been committed. Rejection does not promise that a successful rename was rolled
 back; the published file or a raced replacement may remain at the destination.
 
+Failed-write cleanup compares exact parent and file identities, including large
+Windows file indexes. Replaced paths and paths whose ownership cannot be verified
+are preserved.
+
 ## Denying mutations
 
 All mutation verbs accept `denyMutations?: DenyMutationPolicy`, either as a root default or per-call option:
@@ -99,8 +109,9 @@ writes but skips file and parent-directory fsync calls. Create-only and append
 publication behavior, permissions, identity checks, and error codes are unchanged.
 Use it only for reconstructible data: a crash may lose the write or leave the
 previous file. `move` and streaming `openWritable` do not use this option.
-The existing pure-JavaScript Windows writer performs no fsync calls in either
-setting; native Windows writes honor the option. Directory sync remains best-effort.
+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.
 
 POSIX modes without read permission, including `0o000` and `0o200`, succeed:
 final verification uses a descriptor retained by the writer rather than reopening
@@ -143,6 +154,61 @@ try {
 }
 ```
 
+### Streamed creation
+
+Pass an `AsyncIterable<Uint8Array>` to `create()` when bytes come from a database,
+network response, or another incremental producer. Buffers are accepted chunks.
+The writer consumes each chunk completely before requesting the next one; it
+does not collect the full input in memory or expose a writable descriptor.
+
+```ts
+async function* snapshotChunks(): AsyncGenerator<Uint8Array> {
+  yield Buffer.from("first stored chunk\n");
+  yield Buffer.from("second stored chunk\n");
+}
+
+await fs.create("restored/config.txt", snapshotChunks(), {
+  mode: 0o600,
+  maxBytes: 8 * 1024 * 1024,
+  durable: false,
+  signal: AbortSignal.timeout(30_000),
+});
+```
+
+`RootCreateStreamOptions` keeps `mkdir`, `mode`, `durable`,
+`assertBeforeMutation`, `denyMutations`, and `mutationSymlinks` from buffered
+creation and adds `maxBytes` and `signal`. Byte chunks have no encoding option;
+streamed creation uses strict publication identity and does not support
+`renameIdentity: "verify-content-with-lock"`. Existing Root defaults apply,
+including explicit `maxBytes`; with no byte cap at either level, input size is
+unlimited. Zero permits an empty input only. Invalid limits reject before I/O.
+
+Unlike buffered creation's JavaScript fallback, streamed creation stages all
+chunks before publishing the final name. Native mode uses no-replace rename;
+the JavaScript fallback hardlinks the completed stage and removes its temporary
+name in the same JavaScript turn. That fallback requires a filesystem supporting
+hardlinks; other processes may briefly observe both names. An existing or
+concurrently created destination is preserved. Existing-target preflight does
+not consume the input. The final mode and durability policy use the same guarded
+writer as other Root operations.
+
+Cancellation checks run before and after producer pulls, before content writes,
+and before publication. `assertBeforeMutation` also rechecks current application
+authority after producer waits and before each partial write. The operation
+waits for any pending producer pull or filesystem write, then awaits the
+producer's `return()` and cleans only the owned unpublished stage. Pass the same
+signal into a producer that may stall: an arbitrary async iterator cannot be
+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.
+
+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
+failures preserve the destination; rejection does not prove that no file was
+created. Cancellation arriving after publication does not undo the completed
+file. Application recovery remains caller-owned.
+
 ### `fs.writeJson(rel, value, options?)`
 
 `JSON.stringify(value, replacer, space)` + atomic write. Adds a trailing newline by default.
@@ -202,16 +268,118 @@ await fs.move("incoming/foo.txt", "archive/foo.txt", { overwrite: true });
 
 Both `from` and `to` are bounded; `..` in either is rejected.
 
+The JavaScript fallback checks both parent directories before and after the
+rename. A failed post-operation check rejects even though the rename may
+already have completed; rejection does not imply rollback.
+
 ### `fs.remove(rel)`
 
 Unlink a file or `rmdir` an empty directory. Non-empty directories throw `not-empty`. For atomic directory replacement, use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
 
+The JavaScript fallback reports failed parent-directory checks after removal.
+The entry may already have been removed when this verification rejects.
+
 ```ts
 await fs.remove("logs/yesterday.log");
 await fs.remove("snapshots/empty-dir"); // ok
 await fs.remove("snapshots/full-dir");  // throws not-empty
 ```
 
+For a tree, opt into bounded recursive removal:
+
+```ts
+await fs.remove("scratch/finished-job", {
+  recursive: true,
+  force: true,
+  maxEntries: 20_000,
+  maxDepth: 32,
+  mutationSymlinks: "reject",
+  signal: AbortSignal.timeout(30_000),
+  assertBeforeMutation: () => assertJobLeaseCurrent(),
+});
+```
+
+| Option | Default / behavior |
+| --- | --- |
+| `recursive` | `false`; opt in to removing non-empty directories. |
+| `force` | `false`; `true` tolerates missing targets and vanished child entries. Other errors still reject. |
+| `order` | `"filesystem"`; `"sorted"` collects and sorts child names lexicographically before descending. Requires `recursive: true`. |
+| `maxEntries` | `100_000` in recursive mode; counts the requested target and every encountered child, including directories and symlinks. |
+| `maxDepth` | `64` in recursive mode; the requested target has depth 0 and each child adds one. An empty directory at the limit can be removed. |
+| `signal` | Stops traversal and new mutations when aborted. Already dispatched work settles and directory handles close before rejection. |
+
+Budgets must be non-negative safe integers or explicit `Infinity`, and require
+`recursive: true`. Omitted budgets retain their finite defaults. An entry or
+depth limit throws `too-large` before processing the over-budget entry.
+
+The default filesystem order streams each directory once, using memory and open
+handles proportional to depth rather than directory width. Sorted order also
+enumerates each directory once, but collects its names before descending and
+deletes directories after their children. It uses JavaScript's default string
+sort, not locale collation. Collected names consume the shared entry budget,
+including sibling names still pending while an earlier directory is traversed.
+With a finite budget, collection overflow rejects before processing that
+directory's children; one extra name distinguishes an exact limit from overflow.
+An `Infinity` entry budget uses a bulk name read while retaining the opened
+directory handle and identity checks. Sorted mode retains collected names, so
+unlimited budgets also permit unlimited name storage.
+
+Sorted traversal preserves lexicographic processing, not the incidental syscall
+timing of a caller that repeatedly rescans parent directories. Each child is
+inspected when visited. Newly added entries can make the final `rmdir` fail with
+`not-empty`; the operation does not retry indefinitely.
+
+Recursive removal never follows a discovered symlink or junction. With an
+omitted `mutationSymlinks` policy it unlinks that entry, preserving the existing
+nonrecursive behavior. Both explicit mutation policies reject discovered links.
+`follow-parents-within-root` permits aliases only in the requested target's
+parents, and still rejects a final link. Root and per-call `denyMutations` policies
+remain additive; a denied descendant prevents removal of the enclosing requested
+tree before any entry is removed.
+
+The operation retains exact identities for the traversal directories and each
+observed target. Swapped or missing ancestors reject even with `force: true`;
+an abort reason or authority refusal carrying `ENOENT` is not treated as absence.
+Authority is rechecked immediately before each direct `unlink` or `rmdir`
+dispatch. Directory handles close before their directories are removed, including
+on Windows. If both traversal and close fail, `SuppressedError` retains both
+failures. Directory-stream filesystem errors use the same removal codes as
+`unlink` and `rmdir`, with the original error in `cause`; caller abort and
+authority refusals retain their original values.
+
+When `force: true` encounters a missing directory during an `opendir` or read,
+it closes any open stream and reaches the ordinary final target check. The
+surviving ancestors and original target identity are checked again; a replacement
+is never accepted as a missing directory. An actually vanished child does not
+prevent processing later siblings.
+
+Filesystem failures normalized by the recursive removal owner and its direct
+symlink rejections carry additional `FsSafeError.details` context:
+
+```ts
+type RemoveFailureDetails = {
+  operation: "remove";
+  phase: "enumerate" | "inspect" | "remove";
+  relativePath: string;
+};
+```
+
+`relativePath` is relative to the requested removal target, using host path
+separators: `""` identifies that target and `"nested/link"` identifies a child
+on POSIX. It does not replace caller spelling with the canonical Root path.
+`enumerate` covers directory stream operations, `inspect` covers initial child
+observations, and `remove` covers final identity checks and unlink/rmdir failures.
+The existing error codes, messages, and causes remain unchanged. Errors that
+already have their own identity, including caller authority and cancellation
+reasons, are propagated without adding or changing their details. Context is
+diagnostic; it is not permission to retry or mutate an entry.
+
+Removal is incremental, not atomic. A later budget, cancellation, identity, or
+filesystem failure does not restore already removed entries. As with existing
+`remove`, this is a guarded JavaScript operation in every native mode: pathname
+checks are best-effort against a hostile concurrent process and do not create
+an atomic check-and-delete syscall. Use OS isolation for that threat model.
+
 ### `fs.mkdir(rel)`
 
 `mkdir -p`. Creates missing parents.
@@ -247,9 +415,9 @@ try {
 Options are `{ denyMutations?, mkdir?, mode?, writeMode? }`, where `writeMode`
 is `"replace"` (default), `"append"`, or `"update"`. `replace` truncates existing
 files; `update` keeps existing contents. Streaming writes go directly to the
-destination — there is no atomic-rename step. If you need both streaming and
-atomicity, write to a sibling temp yourself and rename when done; the
-[`atomic`](atomic.md) helpers can do this for you.
+destination — there is no atomic-rename step. For exclusive publication of a
+complete stream, use [`create()`](#streamed-creation). For streamed replacement,
+the [`atomic`](atomic.md) helpers provide a staged writer.
 
 On POSIX, existing-target opens use `O_NONBLOCK` as an admission safeguard so
 a no-reader FIFO cannot stall regular-file validation. This does not change

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -46,6 +46,14 @@
       "types": "./dist/root.d.ts",
       "default": "./dist/root.js"
     },
+    "./copy": {
+      "types": "./dist/copy.d.ts",
+      "default": "./dist/copy.js"
+    },
+    "./guest": {
+      "types": "./dist/guest.d.ts",
+      "default": "./dist/guest.js"
+    },
     "./config": {
       "types": "./dist/config.d.ts",
       "default": "./dist/config.js"
@@ -126,12 +134,15 @@
   },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
+    "benchmark:methods": "node benchmarks/runner.mjs",
     "benchmark:publish": "pnpm build && node scripts/bench-publish.mjs",
     "build": "node scripts/prepack-build.mjs",
     "lint:file-size": "node scripts/check-file-size.mjs",
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
     "prepack": "node scripts/prepack-build.mjs",
     "test": "vitest run",
+    "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:merge": "node scripts/merge-coverage.mjs",
@@ -156,13 +167,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.9.0",
-    "@openclaw/fs-safe-darwin-x64": "0.9.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.9.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.9.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.9.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.9.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.9.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.11.0",
+    "@openclaw/fs-safe-darwin-x64": "0.11.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.11.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.11.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.11.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.11.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.11.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {