@openclaw/fs-safe 0.16.0 → 0.17.0

package/docs/root.md

@@ -167,6 +167,8 @@ cleanup, and filesystem requirements.
 `append` accepts `prependNewlineIfNeeded: true` to separate text from existing
 content when neither side supplies a newline. String data uses its `encoding`
 for the newline check, including UTF-16LE; Buffer data uses a single LF byte.
+Empty strings and Buffers add no separator; an empty append still creates a
+missing file.
 
 These five methods and `copyIn` also accept `durable?: boolean`: the per-call value overrides
 `Root.defaults.durable`, which defaults to `true` when omitted. An explicitly
@@ -308,6 +310,13 @@ from that dispatch. A thrown value rejects the operation unchanged; an async
 or thenable-returning callback rejects with `TypeError` before that mutation.
 Synchronous return values are ignored. Callbacks can run multiple times and
 must inspect current authority each time.
+Directory creation rechecks the retained parent after the callback and before
+submitting mkdir, so a replacement is rejected before creating that component.
+Overwrite moves recheck the retained root, parents, source identity and both
+routes after the callback, including destination parents that were missing
+during preparation. Removals recheck cancellation, retained ancestry and exact
+leaf identity before dispatch; `force` tolerates a missing leaf, not replaced
+ancestry. Removing an admitted hardlink still leaves its other names intact.
 
 Already dispatched I/O cannot be revoked. Identity-checked cleanup, final
 permissions, and durability finish under the existing operation owner even

package/docs/sidecar-lock.md

@@ -55,6 +55,7 @@ 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.
+It stops compromise monitoring for forgotten holders, including callbacks from checks already in flight.
 
 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.
 
@@ -64,7 +65,7 @@ Each new sidecar also carries an internal random ownership token encoded as JSON
 
 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.
 
-`release()` propagates an I/O failure that prevents deletion of an unchanged, owned sidecar; it never reports successful cleanup while leaving that lock behind. The handle and manager retain the exact cleanup receipt after a failure, so the same handle can retry `release()` and `manager.drain()` can retry retained cleanup. A changed sidecar remains an ownership mismatch rather than a deletion failure and is left untouched. If both a `withFileLock()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed asynchronous acquisition cleanup uses the same shape, with the cleanup error primary and the acquisition failure suppressed. On Node runtimes without the global `SuppressedError` constructor, fs-safe returns the equivalent `Error` shape with the same name and properties.
+`release()` propagates an I/O failure that prevents deletion of an unchanged, owned sidecar; it never reports successful cleanup while leaving that lock behind. The handle and manager retain the exact cleanup receipt after a failure, so the same handle can retry `release()` and `manager.drain()` can retry retained cleanup. A changed sidecar remains an ownership mismatch rather than a deletion failure and is left untouched. If both a `withFileLock()` or `withFileLockSync()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed asynchronous acquisition cleanup uses the same shape, with the cleanup error primary and the acquisition failure suppressed. On Node runtimes without the global `SuppressedError` constructor, fs-safe returns the equivalent `Error` shape with the same name and properties.
 
 ## API
 
@@ -336,6 +337,12 @@ sidecar no longer matches or after a verification I/O failure. This is
 detection, not revocation of work already in progress. Asynchronous checks are
 serialized, so a slow verification never overlaps the next timer tick.
 
+Ownership-only checks compare serialized bytes, tokens, and file identities
+without decoding an unused default JSON payload. Stale-policy reads still
+decode the payload. Explicit `parsePayload` callbacks keep their existing
+verification and asynchronous-cleanup calls, receivers, and errors;
+synchronous release continues without invoking a custom parser.
+
 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
@@ -438,6 +445,7 @@ error.
 The sync payload, reclaim, and parsing callbacks must also be synchronous. This
 shape is appropriate for a short boot migration; it is a poor fit for a server
 request because retry backoff uses a blocking wait.
+Synchronous `shouldReclaim` and `shouldRemoveStaleLock` reject Promise or thenable results with `TypeError` before deleting the observed sidecar; an asynchronous result is never approval.
 
 If termination skips the relevant cleanup handler or cleanup fails, the sidecar remains. In particular, `process.exit()` skips asynchronous Root cleanup; await explicit release or drain during application-managed graceful shutdown. Once `staleMs` elapses (or your `shouldReclaim` returns true), acquisition fails closed by default instead of deleting by path.
 

package/docs/staged-file.md

@@ -49,7 +49,7 @@ remain with the caller.
 
 ```ts
 function stageFileInDirectory(options: {
-  directory: string | DirectoryReceipt;
+  directory: string | DirectoryReceipt<Stats | BigIntStats>;
   content: string | Uint8Array;
   mode?: number;
 }): Promise<StagedFile>;
@@ -81,8 +81,9 @@ Creation uses an exclusive, no-follow, close-on-exec open of a generated direct
 child name. Writes use that descriptor. Inspection uses non-following metadata
 operations, never a potentially blocking reopen of the leaf.
 
-A supplied directory receipt must still match at admission. Its numeric
-identity must be exactly representable; ambiguous identity fails closed.
+A supplied directory receipt must still match at admission. Caller receipts can
+carry numeric `Stats` or exact `BigIntStats`; untracked numeric identities must
+be exactly representable. Ambiguous identity fails closed.
 Returned receipts are frozen descriptive snapshots, not mutable authority.
 Changing a supplied receipt after admission cannot retarget the lifecycle.
 

package/docs/store.md

@@ -89,7 +89,9 @@ claim before publication. If another consumer acknowledged, quarantined, or
 replaced that claim, the migration rejects with `FsSafeError("path-mismatch")`
 and leaves the newer generation or failed evidence intact. A stale migration
 rejects both single and batch loads; ordinary callback failures retain their
-existing single-load rejection and batch-skip behavior.
+existing single-load rejection and batch-skip behavior. A caller or migration
+error with code `ENOENT` is still a failure, not a missing queue entry; only a
+claim that is absent or disappears before reading returns `null` from a single load.
 
 On Windows, migration releases its read pin once at this publication boundary
 because an open target can block replacement. It rechecks the exact pathname

package/docs/temp.md

@@ -155,12 +155,15 @@ uses guarded pathname-recursive removal. This fallback never recursively
 removes the public workspace name, but it is not atomic conditional deletion: a
 same-privilege peer that discovers and replaces the private quarantine after
 verification can still redirect the final pathname removal.
+If admitting a cleanup parent fails and closing its descriptor also fails,
+creation rejects with both failures in an `AggregateError`. This does not select
+compatible fallback or retry the indeterminate descriptor close.
 
 Set `cleanupSafety: "require-bounded"` when that concurrent attacker is in scope.
 Creation then requires native no-replace directory rename, native owned-tree
 removal, and a readable retained parent descriptor **before** child creation.
 On POSIX, the final requested `dirMode` must also include owner read
-and search (`(dirMode & 0o500) === 0o500`). Preflight failure throws
+and search (`(dirMode & 0o500) === 0o500`). An unavailable capability throws
 `FsSafeError("helper-unavailable")` without creating a child or calling a scoped
 callback. The child descriptor is opened
 while the new directory still has its private creation mode, before an explicit

package/docs/types.md

@@ -128,6 +128,8 @@ type RootOptions = {
 ## `RootReadOptions` / `RootWriteOptions` / `RootCopyOptions`
 
 ```ts
+import type { CopyCloneMode, RootCopyPublicationReceipt } from "@openclaw/fs-safe";
+
 type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
 type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity" | "mutationSymlinks"> & {
   encoding?: BufferEncoding;
@@ -135,6 +137,11 @@ type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutatio
 };
 type RootCopyOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "maxBytes" | "mkdir" | "mode" | "mutationSymlinks"> & {
   sourceHardlinks?: "reject" | "allow";
+  overwrite?: boolean;
+  clone?: CopyCloneMode;
+  signal?: AbortSignal;
+  preserveSourceMode?: boolean;
+  onDestinationPublished?: (receipt: RootCopyPublicationReceipt) => void;
 };
 type RootOpenWritableOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mkdir" | "mode" | "mutationSymlinks"> & {
   writeMode?: "replace" | "append" | "update";
@@ -150,8 +157,17 @@ type RootAppendOptions = RootWriteOptions & {
 type RootMoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
   overwrite?: boolean;
 };
-type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">;
-type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">;
+type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+  recursive?: boolean;
+  force?: boolean;
+  order?: "filesystem" | "sorted";
+  maxEntries?: number;
+  maxDepth?: number;
+  signal?: AbortSignal;
+};
+type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+  private?: boolean;
+};
 ```
 
 Per-method option shapes. Each picks the `RootDefaults` keys that apply, plus method-specific extras.

package/docs/walk.md

@@ -47,6 +47,10 @@ type WalkDirectoryFailure = {
 
 `depth` starts at `1` for direct children of `rootDir`. `relativePath` is always relative to the supplied root. `scannedEntryCount` counts directory entries examined, including entries filtered out by `include`.
 
+Each entry's `path` is absolute and retains the normalized spelling of the
+supplied root, including followed directory aliases. Paths do not switch to
+the canonical symlink target during descent.
+
 `walkDirectory()` and `walkDirectorySync()` always return `failedDirs`; the property remains optional on the exported `WalkDirectoryResult` type so existing callers that manually construct the legacy result shape remain source-compatible. It lists every directory whose `realpath`/`readdir` threw, so its contents are absent from `entries`. `error` is the thrown value (a `NodeJS.ErrnoException` at runtime), so callers can distinguish a benign missing-directory race (`ENOENT`) from a real read failure (`EACCES`, `EIO`, `ESTALE`, …). The walk-root failure has an empty `relativePath` and `depth: 0`. Failures resolving a symlink's target kind are not reported here.
 
 ## Options
@@ -227,6 +231,9 @@ its exact identity, and rechecks it and the Root identity around each metadata
 batch or individual filesystem-order observation. Sorted batches contain no
 await or caller code between their before/after checks. It tracks canonical
 directories to stop symlink cycles.
+Directory rechecks retain exact identities while using ordinary numeric metadata
+when it represents those identities without rounding. Large identities and
+Windows unknown-identity retries keep the bigint inspection path.
 Neither mode holds a descriptor for every path component, so it is not a process sandbox against a hostile peer that
 can continuously swap and restore directories. Each individual lookup retains
 the documented Node `Root` boundary checks.

package/docs/writing.md

@@ -154,11 +154,17 @@ claimed exclusively first and content is written afterward, so observers can
 briefly see an empty file; failure cleanup removes a claimed file only when its
 identity is unchanged.
 
+After a successful create-only write, failure to close its owned file handle
+rejects the operation and leaves the complete file present. Ordinary buffered
+creation in the JavaScript fallback preserves an earlier write or verification
+failure if close also fails. Native, atomic, and streamed creation retain their
+existing publication and cleanup diagnostics.
+
 ```ts
 try {
   await fs.create("config/seed.json", initial);
 } catch (err) {
-  if (err instanceof FsSafeError && err.code !== "already-exists") throw err;
+  if (!(err instanceof FsSafeError) || err.code !== "already-exists") throw err;
 }
 ```
 
@@ -201,7 +207,8 @@ already published complete destination. See [receipt meanings](staged-file.md).
 
 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
+The writer borrows `Uint8Array` slices without copying their payloads and counts
+their actual byte bounds. It consumes each chunk completely before requesting the next one; it
 does not collect the full input in memory or expose a writable descriptor.
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -170,13 +170,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@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",
+    "@openclaw/fs-safe-darwin-arm64": "0.17.0",
+    "@openclaw/fs-safe-darwin-x64": "0.17.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.17.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.17.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.17.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.17.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.17.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {