@openclaw/fs-safe 0.10.0 → 0.11.0

package/docs/sidecar-lock.md

@@ -2,6 +2,8 @@
 
 `acquireFileLock()` and `withFileLock()` provide a cross-process file lock with retry and process-exit cleanup. The lock is implemented as a sidecar file (e.g. `state.json` ↔ `state.json.lock`) — only one acquirer can create the sidecar with `O_CREAT | O_EXCL` at a time.
 
+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.
+
 ```ts
 import { acquireFileLock } from "@openclaw/fs-safe/file-lock";
 
@@ -61,7 +63,7 @@ function withFileLockSync<T, TPayload>(targetPath: string, options: FileLockSync
 type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   managerKey?: string;                   // optional in-process manager namespace
   lockPath?: string;                     // override; defaults to `${targetPath}.lock`
-  staleMs?: number;                      // default 30_000
+  staleMs?: number;                      // non-negative or Infinity; default 30_000
   timeoutMs?: number;                    // overall acquire deadline; default unbounded
   retry?: FileLockRetryOptions;
   staleRecovery?: "fail-closed" | "remove-if-unchanged"; // default "fail-closed"
@@ -86,7 +88,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   lockRoot?: Root;
   retainOnExit?: boolean;               // keep the sidecar across process exit (default false)
   onCompromised?: (info: { lockPath: string; normalizedTargetPath: string }) => void;
-  compromiseCheckIntervalMs?: number;
+  compromiseCheckIntervalMs?: number;    // 0/omitted disables; otherwise 1..2_147_483_647
 };
 
 type FileLockRetryOptions = {
@@ -245,7 +247,14 @@ type FileLockHandle = {
 captured at acquisition. Set `compromiseCheckIntervalMs` together with
 `onCompromised` for a cheap periodic check; the callback fires once after the
 sidecar no longer matches or after a verification I/O failure. This is
-detection, not revocation of work already in progress.
+detection, not revocation of work already in progress. Asynchronous checks are
+serialized, so a slow verification never overlaps the next timer tick.
+
+The compromise-check interval is validated before payload evaluation or
+filesystem acquisition. Omit it or pass `0` to disable monitoring; enabled
+intervals must be finite and between 1 and 2,147,483,647 milliseconds. Values
+outside that range are rejected instead of being clamped by Node.js to an
+unexpectedly tight polling loop.
 
 ## Synchronous locks
 

package/docs/temp.md

@@ -262,8 +262,8 @@ const result = await writeSiblingTempFile<string>({
 // result.filePath, result.result (returned by writeTemp)
 ```
 
-`writeSiblingTempFile` chooses a random, initially absent sibling name in `dir`
-and calls `writeTemp()`. After the callback succeeds, it validates the produced
+By default, `writeSiblingTempFile` chooses a random, initially absent sibling
+name in `dir` and calls `writeTemp()`. After the callback succeeds, it validates the produced
 regular file before taking ownership: symlinks, directories, other non-regular
 files, hardlinks, and changes between the pre-open pathname, opened descriptor,
 and current pathname are rejected. The callback must finish and close its
@@ -292,12 +292,40 @@ Omitting either option or passing `false` skips that sync, never the identity
 checks. Parent synchronization can be unsupported or fail without rejecting
 the write, so success is not a strict crash-durability receipt.
 
-Cleanup only unlinks an admitted file while the parent, pathname identity, and
-single-link regular-file checks still agree. Observed substitutes are preserved,
+Without producer isolation, cleanup only unlinks an admitted file while the
+parent, pathname identity, and single-link regular-file checks still agree.
+Observed substitutes are preserved,
 including during process-exit cleanup. Operational cleanup failures retain an
 identity-bound exit retry. If the callback throws or admission fails, no file
 has been adopted: even a regular partial file is left for caller-directed
-recovery. The helper never recursively removes a sibling temp.
+recovery. The helper never recursively removes a sibling temp file path.
+
+Set `producerIsolation: "private-directory"` in `WriteSiblingTempFileOptions`
+when the producer can leave partial output before throwing. The callback then
+receives an initially absent file path inside a private child workspace under
+`dir`, on the same filesystem as the final target. fs-safe captures directory
+cleanup ownership before invoking the callback. A callback exception triggers
+owned workspace cleanup, including partial output, subject to directory
+identity checks and I/O failures. The callback must still finish and close its
+writer before returning.
+
+After the callback succeeds, `Root.move` checks source aliases and moves the
+output to the ordinary sibling path before file admission. An escaping symlink
+can fail with `path-alias` at this step. Rejected output still inside the owned
+workspace follows its cleanup contract. Once output moves to the sibling path,
+failures before file adoption retain it for caller-directed recovery, as above.
+File admission, requested modes, sync options, and final rename keep their
+existing contracts; `resolveFinalPath(result)` still names a direct child of `dir`.
+
+The isolated path retains exact bigint identities for both the parent and the
+workspace and rechecks them before moving output to the sibling path. An
+observed replacement is rejected. Cleanup uses the existing
+[`withTempFile` ownership contract](#withtempfile), backed by [`tempFile`](#tempfile):
+moving or replacing the parent or workspace can leave the original or
+replacement paths in place. This option does not promise cleanup through a
+retained directory after a rename, stronger permissions, or additional crash
+durability. Omitting it preserves the direct sibling callback path and
+unadmitted partial-file retention.
 
 On POSIX, admission uses no-follow and nonblocking open flags, so a FIFO swap
 does not block the helper. Windows retains Node's guarded pathname-open behavior
@@ -345,7 +373,7 @@ If `replaceFileAtomic` does what you need, prefer that. Use
 the final destination still needs root-boundary checks.
 Its private workspace uses the same identity-aware directory cleanup as
 `tempFile()`: moving and replacing the workspace preserves the replacement.
-The callback staging component is capped at 255 bytes under NFC and NFD by
+The callback staging component is capped at 255 bytes as written and under NFC and NFD by
 shortening only an overlong embedded destination tail, while preserving an
 extension when possible. Short callback paths and the final target stay
 unchanged. This workspace owns its contents, unlike the unadmitted sibling
@@ -440,6 +468,7 @@ import fs from "node:fs/promises";
 
 const r = await writeSiblingTempFile({
   dir: "/srv/cache",
+  producerIsolation: "private-directory",
   writeTemp: async (tempPath) => {
     const handle = await fs.open(tempPath, "w");
     try {

package/docs/types.md

@@ -45,7 +45,7 @@ type DirEntry = PathStat & {
 };
 ```
 
-Returned by `Root.list(rel, { withFileTypes: true })`. Includes every
+Returned by `Root.list(rel, { withFileTypes: true })` and [`Root.entries()`](entries.md). Includes every
 `PathStat` field plus the entry's `name`.
 
 ## `BasePathOptions`

package/docs/writing.md

@@ -154,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.
@@ -230,6 +285,101 @@ 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.
@@ -265,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.10.0",
+  "version": "0.11.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -50,6 +50,10 @@
       "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"
@@ -137,6 +141,8 @@
     "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",
@@ -161,13 +167,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.10.0",
-    "@openclaw/fs-safe-darwin-x64": "0.10.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.10.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.10.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.10.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.10.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.10.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": {