@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/docs/copy.md

@@ -0,0 +1,197 @@
+# Directory copying and cloning
+
+`@openclaw/fs-safe/copy` materializes independent, caller-owned directory trees. `copyTree` prefers native copy-on-write operations by default, can require cloning, or can copy regular file bytes without cloning or copy offload.
+
+```ts
+import { copyTree, createCloneSource, probeTreeClone } from "@openclaw/fs-safe/copy";
+
+const parent = "/srv/worktrees";
+const backend = probeTreeClone(parent);
+if (backend) {
+  const template = `${parent}/template`;
+  await createCloneSource(template);
+  // Populate this caller-owned template, then keep its contents unchanged.
+  await copyTree(template, `${parent}/checkout`, {
+    clone: "always",
+    signal: AbortSignal.timeout(60_000),
+  });
+}
+```
+
+## Filesystems
+
+| Backend | Operation                                                  | Source preparation                                                                                                          |
+| ------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `apfs`  | Native bulk clone, then directory timestamp repair         | `createCloneSource` creates an empty directory.                                                                             |
+| `btrfs` | One native writable subvolume snapshot                     | `createCloneSource` creates a subvolume; an ordinary directory is not a snapshot source. No `btrfs` executable is required. |
+| `refs`  | Native directory traversal with parallel file block clones | `createCloneSource` creates an empty directory on ReFS, including Dev Drive volumes.                                        |
+| `xfs`   | Native directory traversal with parallel file reflinks     | `createCloneSource` creates an empty directory. The XFS volume must support reflinks.                                       |
+| `zfs`   | Native directory traversal with parallel file reflinks     | `createCloneSource` creates an empty directory. Requires Linux OpenZFS file reflinks and the pool block-cloning feature. |
+
+Native cloning requires source and destination filesystems that support cloning between them. Automatic and ordinary copying can cross filesystems. The source repository used to populate a template can live elsewhere. ReFS, XFS, and ZFS share file data rather than the whole directory metadata tree, so creating many small files still has a cost.
+
+ZFS uses strict file reflinks within one dataset, not dataset snapshots. The installed Linux OpenZFS version must implement `FICLONE`, and the pool must enable `feature@block_cloning`. The probe identifies ZFS even when that feature is unavailable; `clone: "always"` then fails and `"auto"` can copy bytes. Native cloning was verified on OpenZFS 2.4.1 with POSIX ACLs. See the [OpenZFS block-cloning contract](https://openzfs.github.io/openzfs-docs/Basic%20Concepts/Data%20Storage/Block%20Cloning.html) for filesystem limits and pool sharing counters.
+
+Btrfs preserves native subvolume snapshot semantics: nested subvolume contents are not included. Prepare source-only templates without nested subvolumes. This API does not recursively snapshot a hierarchy of subvolumes.
+
+### APFS permissions
+
+APFS directory cloning does not guarantee descendant ACL preservation. With the `CLONE_ACL` flag used here, live macOS testing preserved the source root's ACL but dropped an explicit ACL on a source descendant. Destination ACL inheritance was also omitted below the cloned root. `probeTreeClone` checks filesystem support only; neither it nor `copyTree` checks whether these ACL semantics meet the caller's permission policy. A successful clone is not proof of source ACL preservation or normal file-creation inheritance throughout the tree.
+
+Callers that require source ACL preservation or destination ACL inheritance must use a creation path that preserves their permission policy. For example, a private Git template cache can prohibit custom descendant ACLs and decline cloning when the destination parent has inheritable ACL entries, the template root carries ACLs, or ACL inspection fails; it must also account for policy changes during cloning. Checking only the source root cannot establish that an arbitrary tree has no descendant ACLs. This library does not inspect or repair ACLs after a clone.
+
+Apple [strongly discourages general directory cloning](https://github.com/apple-oss-distributions/xnu/blob/f6217f891ac0bb64f3d375211650a4c1ff8ca1ea/bsd/man/man2/clonefile.2). The [XNU directory-clone authorizer notes unfinished descendant ACL inheritance](https://github.com/apple-oss-distributions/xnu/blob/f6217f891ac0bb64f3d375211650a4c1ff8ca1ea/bsd/vfs/vfs_subr.c#L8879); this is one verified limitation, not Apple's stated complete rationale. The bulk operation remains useful for controlled, immutable templates whose callers accept its metadata semantics.
+
+## API
+
+`TreeCloneBackend` is the `"apfs" | "btrfs" | "refs" | "xfs" | "zfs"` union returned by the probe. `CopyTreeOptions` contains the optional `clone`, `signal`, and `concurrency` arguments. `CopyCloneMode` is the `"auto" | "always" | "never"` strategy shared with [`Root.copyIn`](root.md#writes); tree copies default to `"auto"`, while guarded file copies default to `"never"`.
+
+`probeTreeClone(parentPath)` synchronously inspects an existing directory and returns its supported backend name or `undefined`. It creates no probe artifacts. A filesystem name identifies a candidate backend; for example, an older XFS volume may have reflinks disabled. The actual operation determines availability. An unavailable native binding produces `undefined` in automatic mode; the package's explicit native `require` mode still reports a missing binding as an error.
+
+`createCloneSource(destination, { signal? })` creates an empty cloneable source. Its parent must already exist and the destination must be absent.
+
+`copyTree(source, destination, { clone?, signal?, concurrency? })` copies a directory into an absent destination. Existing destinations are never merged or overwritten. The destination must be outside the source tree.
+
+| `clone` policy     | Behavior                                                                                                                                     |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"auto"` (default) | Prefer native cloning; copy bytes when the binding or filesystem capability is unavailable, or cloning cannot cross the filesystem boundary. |
+| `"always"`         | Require native cloning. Unsupported operations fail without a byte-copy fallback.                                                            |
+| `"never"`          | Copy regular file bytes using reads and writes. No native cloning or copy-offload calls. Works without a native binding.                     |
+
+Automatic copying does not recover from permission errors, I/O errors, cancellation, or rejected source contents such as ReFS named streams. A failed clone must leave the destination absent before fallback can create it; otherwise copying fails rather than merging into a partial tree.
+
+`concurrency` accepts integers from 1 through 32 and bounds active file copies. ReFS, XFS, and ZFS cloning default to 16 workers. Byte copying defaults to four concurrent files on Windows and one elsewhere. Btrfs uses its bulk operation. APFS uses a bulk clone followed by native directory-entry enumeration to restore directory timestamps; known regular files and symbolic links need no additional stat or open.
+
+On Windows, automatic byte copying uses the native binding when available to transfer data between the already-checked file handles in chunks of at most 1 MiB, with smaller buffers for small files. This accelerates NTFS and cross-volume copies without reopening source or destination pathnames. The native worker finishes before its descriptors are closed or cancellation is reported. `clone: "never"` and native-disabled copies use JavaScript read/write loops with reusable buffers: at most 1 MiB per active file on Windows, or 128 KiB elsewhere. Both paths share the file-worker budget across sibling directories, wait for all admitted writes after cancellation or failure, and restore directory timestamps after their descendants finish. Completed directory traversals awaiting writes or metadata are bounded by concurrency; ancestors remain pinned while traversing their children.
+
+On Linux, automatic byte copying also uses the native binding when available. It reads in chunks up to 1 MiB, using smaller buffers for smaller source-size hints, and leaves leading and trailing zero-filled portions of each chunk unwritten in the new file, avoiding their allocation on filesystems that support sparse files. A final size update preserves trailing holes and all-zero files. This path uses reads and writes, without cloning or copy offload; it still reads the full logical contents and does not promise identical sparse extent layout. `clone: "never"` retains the JavaScript byte-copy path.
+
+Tree-copy cleanup attempts every acquired close once, even when another close fails. Portable file handles close output before input; completed directories close their pinned source before target; the public wrapper then closes its source before the destination parent. A copy, identity, metadata, native-clone, or cancellation failure already observed at one of those scopes remains the reported value instead of being replaced by cleanup. If that scope otherwise succeeded, its first close failure is reported unchanged. Concurrent siblings have no global structural close order: the first observed sibling failure stops new work while admitted work settles. Portable copying records caller cancellation when it occurs, so a later abort during cleanup cannot replace an earlier copy failure.
+
+Clones preserve file contents, empty directories, timestamps, executable modes where supported, and literal symbolic links. Editing a clone does not modify its source. Unsupported filesystem operations fail; callers may choose their own copy or checkout fallback after the failed operation has settled.
+
+Native Windows byte copies can store large zero-filled chunks as sparse ranges when the destination is initially empty and its filesystem supports sparse files. This still reads every source byte and creates an independent copy.
+
+The ReFS backend rejects files with alternate data streams and unsupported reparse-point types instead of silently losing their contents. Symbolic links and junctions are preserved.
+
+XFS and ZFS preserve regular-file and directory modes, timestamps, extended attributes, and ACLs. They reject special files, symlink extended attributes, non-UTF-8 names, and directory nesting deeper than 128 levels. Hardlinked source files become independent reflinked files. Portable byte copying preserves file contents, empty directories, modes where supported, file and directory timestamps, and literal symbolic links; it does not promise ownership, ACL, extended-attribute, alternate-stream, or sparse-layout preservation. On Windows, byte copying rejects unresolved symbolic links because Node does not expose their file/directory link type; resolved links keep their literal target and source type. POSIX dangling links are preserved. Choose a copying policy that meets the caller's metadata requirements; automatic copying can select either path.
+
+`readCloneFileMetadata(files)` asynchronously reads APFS data-stream identities and file metadata in one native batch. Results correspond to input order; missing or unsupported entries return `undefined`. The returned `CloneFileMetadata` includes clone ID, device/inode, size, mode, ownership, and timestamps. These are point-in-time observations, not authorization or proof that later reads remain unchanged. Consumers such as Git index adapters must validate their own content and timestamp invariants. The reader does not follow leaf symbolic links.
+
+All input paths must be absolute and valid before native availability is checked. On platforms other than macOS, `auto` and `off` can return one `undefined` per path without the addon, matching native's unsupported result. On macOS, `off` or an unavailable addon still rejects with `helper-unavailable`; JavaScript cannot supply APFS clone IDs. Explicit `require` mode rejects an unavailable addon on every platform, including for an empty batch. Errors from a loaded native helper remain terminal.
+
+## Borrowed FileHandle transfers
+
+`copyFileHandle` from `@openclaw/fs-safe/advanced` copies bytes between two
+already-open regular files. Use it when a snapshot or materialization owner
+has admitted the source and opened its own destination:
+
+```ts
+import { createHash } from "node:crypto";
+import { copyFileHandle } from "@openclaw/fs-safe/advanced";
+
+const digest = createHash("sha256");
+const bytes = await copyFileHandle(sourceHandle, targetHandle, {
+  maxBytes: expectedSize,
+  signal: AbortSignal.timeout(30_000),
+  onChunk: (chunk) => { digest.update(chunk); },
+  assertBeforeMutation: assertSnapshotOwnerCurrent,
+});
+```
+
+`CopyFileHandleOptions` contains optional `maxBytes`, `signal`, `onChunk`, and
+`assertBeforeMutation`. The result is the actual byte count copied through EOF.
+The four options are selected once before descriptor inspection; later mutation
+of the options object cannot replace the active budget, signal, observer, or
+mutation-authority callback.
+The byte limit is not a prefix length: excess data rejects with `too-large`,
+including data added after admission. Omitted limits are unlimited; Root's
+default read cap does not apply. Zero accepts only an empty source. Invalid
+limits reject before descriptor inspection.
+
+The source and target must be distinct regular files; exact device/inode
+aliases, including two handles to hardlinked names, reject before writing.
+Both reads and writes start at position zero and preserve the handles' current
+cursors. Existing destination bytes beyond the copied prefix remain intact.
+The target must have been opened **without append mode**: some platforms ignore
+positional writes on append handles, and Node exposes no portable open-flags
+query. Keep both handles open and free of concurrent I/O through settlement.
+
+The synchronous `onChunk` observer sees each source chunk before any target
+write for that chunk. It receives a borrowed view reused by later reads; consume
+it immediately without retaining or mutating it. This supports source hashing;
+it does not verify bytes persisted by the destination. Callers that require a
+destination digest must still hash the destination handle afterward. Observer
+and authority callbacks may throw; thenable returns reject with `TypeError`
+before the affected write. `assertBeforeMutation` runs immediately before every
+partial-write submission and must inspect current authority each time.
+
+The helper reuses Root copying's bounded read buffer and completes positive
+short reads and writes. JavaScript file transfers use at most 512 KiB of scratch
+space, reduced for smaller source-size hints and capped by a finite byte budget
+plus its one-byte overflow probe. A zero-progress write rejects with `helper-failed`.
+Cancellation is checked before I/O, after source reads, and before each write;
+admitted reads and writes settle before rejection. A rejected operation can
+leave a copied prefix. There is no rollback or pathname cleanup.
+
+This helper never opens or closes a file, truncates, chmods, syncs, renames, or
+publishes it. Source admission, immutability checks, destination preparation,
+durability, publication, and failure recovery stay with the caller. Initial
+descriptor inspection does not prove that the source remained unchanged while
+copying. Keep existing source-fingerprint and publication checks around the
+transfer when building snapshot operations.
+
+### Synchronous descriptor transfers
+
+`copyFileDescriptorSync(sourceFd, targetFd, options?)` provides the same
+zero-origin byte transfer for borrowed numeric descriptors. It shares
+`CopyFileHandleOptions` and returns the copied byte count synchronously:
+
+```ts
+import { copyFileDescriptorSync } from "@openclaw/fs-safe/advanced";
+
+const bytes = copyFileDescriptorSync(sourceFd, targetFd, {
+  maxBytes: expectedSize,
+  assertBeforeMutation: assertSnapshotOwnerCurrent,
+});
+```
+
+The same regular-file and exact-identity admission, byte limits, short-I/O
+handling, cursor preservation, and caller-owned cleanup apply. The target must
+be opened without append mode, and both descriptors must remain open and free
+of concurrent I/O, including inside callbacks. Neither helper makes a mutable
+source into a consistent snapshot or truncates an existing destination suffix.
+
+The synchronous helper snapshots the four options once and invokes both
+callbacks with no receiver (`this` is `undefined` in strict callbacks).
+`onChunk` receives a borrowed view that must be consumed immediately without
+retaining or mutating it. Both callbacks must finish synchronously; thenables
+throw `TypeError` before the current write. Cancellation is cooperative: a
+pre-aborted signal or an abort triggered by a callback stops the transfer before
+the next write. Timers cannot interrupt synchronous filesystem calls while the
+event loop is blocked. Authority runs before every partial write; an abort
+triggered by that assertion prevents the same write.
+
+## Ownership and cancellation
+
+These are low-level operations on caller-owned absolute paths, not Root-relative methods. The source and destination parent must be real directories. The library pins their descriptors and verifies their identities; it does not establish the caller's authorization to use them. Keep the source immutable for the operation, including writes through other aliases, and keep the destination namespace under the caller's control. Literal symlinks in the cloned contents are preserved rather than followed or sanitized.
+
+An already aborted signal prevents dispatch. In-flight cancellation stops cancellable traversal and waits for admitted native writes to finish before rejecting. APFS and Btrfs bulk operations cannot be interrupted once dispatched. An aborted or failed call can therefore leave a destination, including a complete bulk clone. It remains caller-owned; after settlement, the caller decides whether to retain or remove it. Do not start cleanup by racing the cloning promise against an abort promise.
+
+Tree copying preserves caller abort handlers and receives cancellation even when a caller handler stops event propagation, including native cloning and byte-copy fallbacks.
+
+Completion is not a crash-durability guarantee. The API is suitable for reconstructible templates and checkouts; it does not sync every file or replace application-level publication and recovery rules.
+
+A close-only rejection reports descriptor settlement, not whether bytes reached stable storage. The destination can already be complete when a close fails, just as other failed or cancelled calls can leave caller-owned output. Inspect or remove that output only after the copying promise settles and under the same source and destination authority assumptions.
+
+Byte copying retains fractional file and directory access/modification timestamps to the precision supported by Node's timestamp APIs and the destination filesystem. This includes dates before 1970 on Unix. On Windows, [Node's unsigned stat seconds](https://github.com/nodejs/node/blob/v26.8.2/src/node_file-inl.h#L93-L104) can report pre-1970 timestamps as dates about 136 years later; byte copying inherits that upstream limitation.
+
+## Platform tests and benchmarks
+
+After building the host native binding, run `pnpm test test/clone.test.ts test/copy-tree.test.ts`. APFS tests can use the normal macOS temporary directory. For Btrfs, ReFS, XFS, or ZFS, set `FS_SAFE_CLONE_TEST_ROOT` to an existing writable directory on that filesystem. The test creates and cleans only its own temporary children. An explicitly configured unsupported directory fails the test rather than silently skipping platform proof. XFS and ZFS metadata tests require the `attr` and `acl` utilities.
+
+Run `node scripts/clone-xfs-proof.mjs MOUNT` on a real XFS volume to verify the public API, hashes, independent writes, and shared physical extents. It requires `filefrag` from `e2fsprogs`. Add `no-reflink` for an XFS fixture formatted with reflinks disabled; strict copying must fail and automatic copying must succeed through byte copying.
+
+Run `node scripts/clone-zfs-proof.mjs MOUNT POOL` on a dedicated, otherwise idle Linux ZFS pool with compression and deduplication disabled. It verifies both `copyTree` and `Root.copyIn` through hashes and changes in the documented `bclonesaved` pool counter. It requires `zfs`, `zpool`, and `findmnt`, including permission to run `zpool sync`. Add `no-reflink` for a pool without block cloning to verify strict refusal and automatic byte fallback. The script creates and removes only its temporary directory; it does not create pools or change their properties.
+
+Run `node benchmarks/clone.mjs SOURCE DESTINATION_PARENT` after `pnpm build` to compare one, four, and 16 workers on the same immutable source. Add `3 auto` or `3 never` to measure three samples of ordinary copying, including NTFS destinations. It records copying time separately from fixture preparation and full file-hash verification, and retains its uniquely named output directory for inspection. Prepare Btrfs sources with `createCloneSource` first.

package/node_modules/@openclaw/fs-safe/docs/creation.md

@@ -0,0 +1,132 @@
+# Exclusive leaf creation
+
+The creation-policy work is tracked in [#482](https://github.com/openclaw/fs-safe/issues/482).
+
+Use `createDirectory()`, `createDirectorySync()`, and `createFileSync()` from
+`@openclaw/fs-safe/advanced` when an existing, trusted parent should receive
+one new entry. These operations are exclusive and nonrecursive: an existing
+entry throws `FsSafeError("already-exists")`, and missing parents are not
+created. They do not repair or adopt an existing destination. `Root.mkdir()`
+continues to own recursive, idempotent directory creation within a Root.
+
+```ts
+import {
+  createDirectorySync,
+  createFileSync,
+} from "@openclaw/fs-safe/advanced";
+import fs from "node:fs";
+
+createDirectorySync("/trusted/application/new-state", { private: true });
+using file = createFileSync("/trusted/application/new-state/initial.db", {
+  private: true,
+});
+fs.fsyncSync(file.fd);
+```
+
+Both directory variants return `void`; `createFileSync()` returns an empty,
+read/write descriptor owned by `OwnedFileDescriptorSync`, with
+`{ fd, close(), [Symbol.dispose]() }`. Use the
+owner to close it, rather than calling `fs.closeSync()` yourself. Closing and
+disposal are idempotent; a failed close is not retried through a descriptor
+number that might already have been reused. File creation does not write
+payload data or request file or parent-directory synchronization.
+
+## Permission options
+
+`CreateDirectoryOptions` and `CreateFileOptions` both support `private?: boolean`
+for private creation. `mode?: number` selects permission
+bits; invalid values and private requests with group/world or special bits
+reject before mutation. Restrictive owner-only modes remain restrictive.
+Without `private`, ordinary Node defaults and the process umask apply. Private
+POSIX creation requests `0700` for directories and `0600` for files by default;
+the umask may restrict those permissions further. Existing directory privacy
+checks never broaden permissions.
+
+Private POSIX `Root.create()` and `createJson()` writes check the retained descriptor's actual owner and
+permissions before writing payload bytes, after producer and authority callbacks,
+and at publication, including JavaScript fallback writes. Payload writes require
+the temporary `0600` mode even when the requested final mode differs.
+Private ownership, permissions and ACLs are checked before preparing that mode,
+including after authority callbacks; valid restrictive initial modes remain supported.
+A successful `chmod` is insufficient: filesystems that do not
+enforce owner-only permissions reject before payload writes. The requested final
+mode is verified too; a failure after publication preserves the completed file
+and staged creation reports its published outcome.
+
+On macOS (Darwin), private creation also requires an ACL-free result. The native
+helper must provide `inspectDarwinAcl`; native `off`, a missing helper, or an
+older helper without that capability rejects with `helper-unavailable` before
+creating parents or staging entries. There is no system-command fallback for
+Darwin private creation. Operations without `private: true` keep their existing
+native-mode behavior.
+
+Private Darwin directories must retain owner-read or owner-search permission
+after applying the umask so their ACL can be inspected. Modes `0000` and `0200`
+reject with `helper-unavailable` before directory creation. Existing private
+directories with neither permission also reject with `helper-unavailable`;
+permissions are never broadened to inspect them. Modes `0100`, `0300`, and `0400`
+remain supported, as does the default `0700`. Private files with mode `0000`
+remain supported because inspection uses the owned creation descriptor.
+
+Before creation, the parent ACL is inspected for entries that could be inherited
+by the new directory or file, as applicable. Relevant inheritable entries reject
+creation. Noninheriting parent ACLs, such as the usual macOS home-directory
+deny-delete entry, do not reject child creation. Created directories and files
+are checked for owner-only permissions and no ACL before admitting the directory
+or allowing payload writes. An existing directory requested with `private: true`
+must also be owned by the current user, have owner-only permissions, and have no
+ACL. These checks never clear an ACL after creation or repair an existing entry.
+
+On Windows, mode bits alone do not establish privacy. Private creation uses a
+protected current-user, LocalSystem and Administrators DACL. A private staging
+directory supplies trusted-only inheritable permissions before Node creates
+the file. The original Node descriptor stays pinned while its full Windows
+identity is compared with a security handle before the file DACL is protected.
+An already broadly accessible file is rejected, not repaired. Keep the trusted
+parent ancestry and staging directory ACL protected from untrusted changes;
+post-operation checks do not make pathname-based fallback operations atomic
+against an adversary who can change that namespace.
+
+The internal async writer awaits system commands, file opens and closes, and
+security verification. It does not wrap the synchronous creator in a promise.
+Short identity checks and the existing guarded link/unlink critical sections
+remain synchronous.
+
+Private Windows file publication retains the same inode and never overwrites
+an existing destination. The current implementation requires hardlinks on the same
+local filesystem. Unsupported filesystems reject with `helper-unavailable`;
+there is no copy-to-destination fallback. On Windows the owner overlaps a
+verified destination descriptor with the creation descriptor before removing
+the temporary name. Requested read-only attributes are finalized through the
+retained destination descriptor after that handoff.
+
+On Windows, native `auto` uses available capabilities; native `off` and
+missing-capability `auto` use the packaged system-command security bridge. Native `require`
+rejects unavailable required capabilities instead of starting a command. The
+private-file capability check runs before creating parents or staging entries;
+directory-only operations require only their directory capabilities. The
+[Windows security fallback prerequisites](install.md#windows-security-fallback)
+apply. All command mutations report unconfirmed outcomes when their reply or
+termination cannot establish completion.
+
+## Authority and failure outcomes
+
+`assertBeforeMutation?: () => void` is a synchronous current-authority check.
+It runs after preparation and immediately before creation or publication;
+thenables reject before mutation. Parent and file identity checks are repeated
+after the callback. Final permission checks, descriptor settlement and cleanup
+retain the operation's cleanup ownership after publication.
+
+Failure does not always mean the final path is absent. Staged private-file errors
+after publication or ambiguous publication preserve the destination and carry
+`details.publication.status` (`published` or `indeterminate`), the target path and
+staging cleanup outcome. Cleanup and close failures retain the original error
+in the cause chain. When `stageDirectory` is present, `cleanup` describes that
+stage's settlement; it does not mean the published destination was removed.
+If a directory is created but its subsequent admission fails, the error records
+its published path and preserves it. A private file whose staging directory
+cannot be admitted reports `not-published` and identifies the preserved stage.
+Observed replacement paths are preserved. Existing
+`createPrivateDirectory()` retains its Windows-only compatibility contract;
+new portable callers should use the ordinary creation operations with
+`private: true`.

package/node_modules/@openclaw/fs-safe/docs/directory-identity.md

@@ -0,0 +1,85 @@
+---
+title: Directory identity
+description: "Exact directory observations and synchronous identity assertions for application-owned workflows."
+---
+
+# Directory identity
+
+Use `readDirectoryIdentity()` and `assertDirectoryIdentitySync()` from
+`@openclaw/fs-safe/advanced` when an application owns a staging or recovery flow
+and needs to verify that a pathname still identifies an observed directory.
+
+```ts
+import {
+  readDirectoryIdentity,
+  assertDirectoryIdentitySync,
+} from "@openclaw/fs-safe/advanced";
+
+const expected = await readDirectoryIdentity(directoryPath);
+await prepareOutput();
+assertDirectoryIdentitySync(directoryPath, expected);
+```
+
+`readDirectoryIdentity(path)` returns a frozen `DirectoryIdentity`:
+
+```ts
+type DirectoryIdentity = Readonly<{
+  dev: bigint;
+  ino: bigint;
+  realPath: string;
+}>;
+```
+
+Both operations reject a final symlink or a non-directory, including paths with
+one or more trailing separators. Filesystem, drive, and UNC roots remain valid.
+Parent aliases and `..` retain their filesystem traversal meaning; POSIX
+backslashes and whitespace remain literal filename characters. These helpers do
+not confine a path to a root or reject every symlink ancestor. Keep the
+application's path policy, or use the [Root API](root.md) for paths that must
+remain beneath a root.
+
+## Checking the selected path
+
+`assertDirectoryIdentitySync(observedPath, expected)` reads the supplied path
+and compares its exact `dev` and `ino` against the expected bigint values. It
+returns `undefined` on success and throws synchronously on failure.
+
+If `expected.realPath` is present, the current canonical path must also match
+that string exactly. Pass the complete observation to keep both checks:
+
+```ts
+assertDirectoryIdentitySync(newlyOpenedRootPath, expected);
+```
+
+For a directory intentionally moved to another name, omit `realPath` while
+retaining the expected identity:
+
+```ts
+assertDirectoryIdentitySync(movedPath, { dev: expected.dev, ino: expected.ino });
+```
+
+Only `dev`, `ino`, and optional `realPath` participate in the assertion. A
+`MovePathPublicationReceipt` can supply the identity after a move; its `path`
+does not implicitly require the previous pathname to remain current.
+
+## Errors and ownership
+
+| Condition | Result |
+|---|---|
+| Final symlink or non-directory | `FsSafeError("not-file")` |
+| Different expected identity or supplied canonical path | `FsSafeError("path-mismatch")` |
+| Numeric expected identity or persistently unknown Windows identity | `FsSafeError("path-mismatch")` |
+| Filesystem failure such as `ENOENT` or `EACCES` | The original error, unchanged |
+
+Windows can temporarily report a zero device or inode. The shared identity
+owner permits one re-inspection, retaining every known component so a later
+observation cannot erase a definite mismatch. It rejects identities that remain
+unknown and does not retry operational filesystem errors.
+
+These helpers observe directory identity. They do not open a retained handle,
+hold a lock, create or remove directories, change permissions, or authorize
+application work. A pathname can change after an assertion; continue to use
+guarded mutation APIs and recheck application authority at the operation's
+existing submission point. Keep publication, rollback, and cleanup decisions
+with the caller. Use [pinned directories](durability.md#pinned-directories) when
+the operation specifically needs the directory synchronization lifecycle.

package/node_modules/@openclaw/fs-safe/docs/durability.md

@@ -53,6 +53,14 @@ propagate.
 discard both unsupported outcomes and failures. Use them only when the primary
 write remains useful without a crash-durability promise.
 
+On Windows, pathname inputs and supplied directory receipts reject NTFS
+alternate-stream and directory-index namespace spellings before opening,
+creating, hashing, or publishing anything. This applies to directory
+durability, `publishFileExclusive()`, and the pathname overloads of
+`sha256File()` and `sha256FileSync()`; the already-open `FileHandle` and
+borrowed numeric file-descriptor overloads are unchanged. Ordinary colon-bearing
+POSIX paths remain valid.
+
 ## Pinned directories
 
 `pinDirectory()` rejects final symlinks and non-directories. On POSIX it opens
@@ -61,6 +69,49 @@ descriptor, pathname identity, and canonical path. `assertCurrent()` repeats
 those checks. This prevents a pathname replacement from turning a later sync
 into proof for a different directory.
 
+Pathname and descriptor checks compare exact bigint device and inode values.
+Each inspection allows one retry for unknown Windows identity components,
+retaining known components and rejecting definite mismatches immediately.
+Persistent unknown identity fails closed with `path-mismatch`, including on an
+otherwise usable directory. A failed preflight identity check never syncs the
+descriptor; a replacement discovered after sync still rejects the operation.
+
+`DirectoryReceipt.identity` remains a numeric Node `Stats` object for metadata
+compatibility, projected from the same exact observation as the private
+identity. Library-created receipts and their identity objects retain a
+private exact snapshot; mutating their public fields cannot change the
+directory authorized by that snapshot. Each returned receipt owns a mutable
+numeric metadata copy. Later admissions retain the original metadata snapshot
+even if advisory fields such as mode or timestamps were edited; changed paths
+or identity components reject. Pass the receipt or its original
+identity object through to later operations to retain this evidence. A copied
+or reconstructed numeric identity is accepted only when both components are
+safe integers and, on Windows, nonzero. Rounded or unknown caller identities
+fail with `path-mismatch` rather than authorizing a different directory.
+
+Caller-supplied receipts may use `DirectoryReceipt<BigIntStats>` with the result
+of `lstat(path, { bigint: true })`. `pinDirectory()`, `syncDirectory()`,
+`syncDirectorySync()`, `publishFileExclusive()`'s `parentReceipt`, and
+`stageFileInDirectory()` accept both numeric and bigint receipt inputs.
+`DirectoryReceipt` without a type argument and all returned durability receipts
+still expose numeric `Stats`, including working type predicates and Date
+properties. Bigint metadata is projected from the supplied observation, retaining
+fractional timestamps and the private exact device/inode identity.
+
+```ts
+import { lstatSync, realpathSync, type BigIntStats } from "node:fs";
+import { syncDirectorySync, type DirectoryReceipt } from "@openclaw/fs-safe/durability";
+
+const directoryPath = "/srv/backups/sqlite";
+const receipt: DirectoryReceipt<BigIntStats> = {
+  path: directoryPath,
+  realPath: realpathSync(directoryPath),
+  identity: lstatSync(directoryPath, { bigint: true }),
+};
+// Keep this receipt across the application's publication operation.
+const outcome = syncDirectorySync(receipt);
+```
+
 Call `close()` in `finally`. Closing is idempotent; using a closed pin fails.
 
 These checks intentionally reject a moved or replaced pathname. For one file's
@@ -86,6 +137,10 @@ accepted.
 `expectedExistingIdentity` binds an existing target to an identity observed by
 the caller before a separate permission or policy check. A missing or replaced
 target fails with `FsSafeError("path-mismatch")`.
+Use bigint `dev` and `ino` from `lstat(path, { bigint: true })` or
+[`readDirectoryIdentity()`](directory-identity.md) for caller-owned observations
+that may exceed the numeric safe-integer range. An original library receipt's
+`identity` object also retains its private exact identity for this option.
 
 ## Exclusive file publication
 
@@ -94,6 +149,12 @@ target. It pins the source with nonblocking `O_NOFOLLOW`, optionally verifies
 `expectedSourceIdentity`, tries a hardlink first, then synchronizes the target
 parent directory.
 
+Trusted relative source and target paths are resolved to absolute paths before
+authority checks. On Windows, ordinary drive-relative operands are anchored at
+entry before namespace-alias admission. A caller-supplied `parentReceipt` must
+still name the resolved target parent and is not relaxed by this compatibility
+rule.
+
 For example, a backup archive is complete before publication. If directory
 sync fails, keeping that complete file is more useful than conditionally
 deleting it by pathname:
@@ -199,7 +260,7 @@ import { sha256File } from "@openclaw/fs-safe/durability";
 const snapshot = await open(stagedArchive, "r");
 try {
   const before = await snapshot.stat();
-  const hash = await sha256File(snapshot);
+  const hash = await sha256File(snapshot, { maxBytes: before.size });
   if (hash.bytes !== before.size || hash.digest !== manifest.sha256) {
     throw new Error("staged backup does not match its manifest");
   }
@@ -209,6 +270,21 @@ try {
 ```
 
 The result is `{ bytes, digest }`, where `digest` is lowercase hexadecimal.
+The optional `Sha256FileOptions` argument supports `maxBytes` and `signal`.
+`maxBytes` accepts a non-negative safe integer (including zero), or
+`Infinity` for no limit, which is also the default. Oversized files reject with
+`FsSafeError("too-large")`; reads stay bounded to at most `maxBytes + 1` bytes,
+even if the file grows after its initial size check. Hashing never silently
+truncates to the limit.
+
+Pass `signal` to cancel. A pre-aborted signal rejects before file I/O or native
+loading. In-flight cancellation is cooperative between reads and rejects with
+the signal's original reason only after the pending read or native task stops.
+Callers may close their handle after awaiting rejection; do not close it while
+the operation is pending. A signal can be shared by successive or concurrent
+hashes. Neither mode provides a snapshot of concurrently modified contents;
+callers requiring stable content must also fence identity and metadata.
+
 The handle overload never closes the caller's descriptor and uses positioned
 reads, so it does not alter the descriptor's current offset. The path overload
 rejects symbolic links and non-regular files, compares lossless bigint identities
@@ -223,14 +299,56 @@ pathname without reopening the file and repeat the symlink and file-type checks.
 POSIX opens are nonblocking, so a raced FIFO or device is rejected after
 descriptor inspection rather than waiting for a writer.
 
+A pathname hash reports failure to close its owned descriptor after successful
+hashing. If hashing, admission, or cancellation already failed, that original
+failure remains primary even when close also fails. This also applies to
+`sha256FileSync()`; borrowed handles and descriptors remain caller-owned.
+
 When the optional binding is active, hashing runs as an async native task and
 does not occupy the JavaScript event loop with digest updates. With native mode
 `off`, or in `auto` when no binding loads, the fallback performs asynchronous
-positioned reads in 64 KiB chunks but updates Node's `Hash` on the JavaScript
-thread. Both paths stream constant-size buffers rather than loading the file
-into memory. Native mode `require` keeps its usual fail-closed loader semantics.
+positioned reads in chunks of up to 256 KiB but updates Node's `Hash` on the JavaScript
+thread. Both paths stream bounded buffers rather than loading the file into memory.
+The fallback sizes its scratch buffer to small files and grows it if a stale
+size hint is exceeded, while still probing for actual EOF and byte-limit overflow.
+Native mode `require` keeps its usual fail-closed loader semantics.
+
+### Synchronous hashing
+
+`sha256FileSync()` accepts a pathname or a borrowed numeric file descriptor and
+returns the same `{ bytes, digest }` result. It shares `Sha256FileOptions`,
+including the default unlimited byte budget and `too-large` errors for growth
+beyond `maxBytes`. It always reads from offset zero with bounded positional
+`readSync` calls and leaves a borrowed descriptor open at its original position.
+Path inputs use the same regular-file, final-symlink, nonblocking-open, and exact
+bigint admission checks described above, then close their owned descriptor.
+These checks do not provide ancestor confinement or a snapshot of concurrent edits.
+
+```ts
+import { closeSync, openSync } from "node:fs";
+import { sha256FileSync } from "@openclaw/fs-safe/durability";
 
-If publication fails after this call created the target, it throws an
+const fd = openSync(stagedArchive, "r");
+try {
+  const hash = sha256FileSync(fd, { maxBytes: manifest.sizeBytes });
+  if (hash.bytes !== manifest.sizeBytes || hash.digest !== manifest.sha256) {
+    throw new Error("staged backup does not match its manifest");
+  }
+} finally {
+  closeSync(fd);
+}
+```
+
+The synchronous API uses Node's crypto implementation in every native mode,
+including `require`; it never loads a native binding. It blocks the calling
+thread until hashing finishes or throws. A pre-aborted signal fails before I/O,
+and synchronous signal changes are checked between operations with the original
+reason preserved. Timers and other JavaScript callbacks cannot run while the
+hash is executing; use `sha256File()` when responsive cancellation is needed.
+
+## Publication failure receipts
+
+If `publishFileExclusive()` fails after creating the target, it throws an
 `FsSafeError` with a `details` receipt:
 
 ```ts
@@ -257,6 +375,13 @@ this receipt instead of inferring ownership from path existence. The original
 failure remains available as `cause`. Failures before target creation retain
 their existing error shape and do not claim a cleanup result.
 
+Source and target identities are checked again after successful or unsupported
+directory synchronization, while their descriptors remain owned. A late
+verification failure retains its strategy's verification phase and is not a
+directory-sync failure. Completed copied targets stay pinned during conditional
+cleanup; substituted entries remain untouched. Returned numeric metadata comes
+from the retained target descriptor and grants no continuing pathname authority.
+
 ### Directory-sync failure policy
 
 `onSyncFailure` applies only after target creation and content/identity fencing