@openclaw/fs-safe 0.20.0 → 0.21.0

package/dist/watch.js

@@ -0,0 +1,502 @@
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
+import { rootHandleContext } from "./root-handle-context.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+import { admittedNativeChanges } from "./watch-alias.js";
+import { changedEntries, guardedHintChanges, scopedChanges } from "./watch-hints.js";
+import { watchBinding, NativeWatchBackend } from "./watch-native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { isWatchPathError, scanWatch, watchScopes } from "./watch-scan.js";
+function deferred() {
+    let settled = false;
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+    // Ownership exists even when a consumer closes without awaiting startup.
+    void promise.catch(() => { });
+    return { promise, get settled() { return settled; },
+        resolve() { settled = true; resolve(); },
+        reject(error) { settled = true; reject(error); },
+    };
+}
+function budget(value, fallback, name, max = 1_000_000) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 1 || result > max)
+        throw new RangeError("invalid watch " + name);
+    return result;
+}
+const retired = () => new DOMException("Watch generation retired", "AbortError");
+const coalesceMs = 25;
+/** Advisory observation only. Hints never grant filesystem authority. */
+export function watch(root, input) {
+    const context = rootHandleContext(root);
+    const options = { ...input };
+    const persistent = options.persistent !== false;
+    if (!["auto", "events", "poll"].includes(options.mode))
+        throw new TypeError("invalid watch mode");
+    let binding;
+    let selectionFailure;
+    try {
+        binding = watchBinding(options.mode);
+    }
+    catch (error) {
+        selectionFailure = error;
+    }
+    let mode = binding || options.mode === "events" ? "events" : "poll";
+    let intervalMs = budget(options.intervalMs, mode === "events" ? 30_000 : 1000, "intervalMs", 2_147_483_647);
+    if (intervalMs < 20)
+        throw new RangeError("watch intervalMs must be at least 20");
+    const maxDirectories = budget(options.maxDirectories, 4096, "maxDirectories");
+    const maxEntries = budget(options.maxEntries, 100_000, "maxEntries");
+    const maxPendingPaths = budget(options.maxPendingPaths, 256, "maxPendingPaths", 4096);
+    if (typeof options.onInvalidate !== "function")
+        throw new TypeError("watch requires onInvalidate");
+    const makeGeneration = (scopes) => ({
+        scopes: watchScopes(scopes), abort: new AbortController(), waiter: deferred(),
+    });
+    let current = makeGeneration(options.scopes);
+    const ready = current.waiter.promise;
+    let state = "starting";
+    let terminal = false;
+    let failure;
+    let failureInfo;
+    let retirementFailure;
+    const retirementErrors = new Set();
+    let closing;
+    let active;
+    let backend;
+    const registered = new Map();
+    let observedDirectories = 0;
+    let snapshot;
+    let resetRequested = false;
+    let refreshBackend = false;
+    let pending = false;
+    let pendingWaiter;
+    let runningWaiter;
+    let pendingHint = false;
+    let pendingChanges = new Map();
+    let timer;
+    let hintTimer;
+    const combinedFailure = () => {
+        if (!retirementFailure)
+            return failure;
+        const error = retirementFailure.error;
+        if (failure === undefined || error === failure || error?.suppressed === failure)
+            return error;
+        return createSuppressedError(error, failure, "watch observation and retirement failed");
+    };
+    const retainRetirement = (error) => {
+        if (retirementErrors.has(error))
+            return;
+        retirementErrors.add(error);
+        retirementFailure = { error: retirementFailure
+                ? createSuppressedError(error, retirementFailure.error, "watch retirement failed more than once") : error };
+    };
+    const health = () => Object.freeze({
+        state, mode, directories: observedDirectories,
+        ...(failure === undefined && !retirementFailure ? {} : {
+            failure: retirementFailure ? Object.freeze({ operation: "close", error: combinedFailure() }) : failureInfo,
+        }),
+    });
+    const check = (g) => {
+        g.abort.signal.throwIfAborted();
+        if (terminal || current !== g)
+            throw retired();
+        if (failure !== undefined)
+            throw failure;
+        if (retirementFailure)
+            throw retirementFailure.error;
+    };
+    const clearTimers = () => {
+        clearTimeout(timer);
+        clearTimeout(hintTimer);
+        timer = undefined;
+        hintTimer = undefined;
+        pending = false;
+        pendingHint = false;
+        pendingChanges = new Map();
+    };
+    const notifyHealth = () => {
+        try {
+            const result = options.onHealth?.(health());
+            assertSynchronousCallbackResult(result, "watch onHealth");
+        }
+        catch (cause) {
+            throw new FsSafeError("helper-failed", "watch health callback failed", { cause, details: { operation: "callback" } });
+        }
+    };
+    const dirty = (g, reason, changes) => {
+        check(g);
+        try {
+            const result = options.onInvalidate(Object.freeze({ reason, changes: changes && Object.freeze(changes) }));
+            assertSynchronousCallbackResult(result, "watch onInvalidate");
+        }
+        catch (cause) {
+            throw new FsSafeError("helper-failed", "watch dirty callback failed", { cause, details: { operation: "callback" } });
+        }
+        check(g);
+    };
+    const retain = (error) => {
+        if (failure === undefined) {
+            failure = error;
+            failureInfo = Object.freeze({ operation: "close", error });
+        }
+        else if (error !== failure)
+            failure = createSuppressedError(error, failure, "watch and retirement both failed");
+    };
+    const retireBackend = async () => {
+        const old = backend;
+        try {
+            await old?.close();
+        }
+        catch (error) {
+            retainRetirement(error);
+        }
+        if (backend === old) {
+            backend = undefined;
+            registered.clear();
+            observedDirectories = 0;
+        }
+        if (retirementFailure)
+            throw retirementFailure.error;
+    };
+    const lose = (error, operation = "scan") => {
+        if (terminal || failure !== undefined)
+            return;
+        if (error === undefined)
+            error = new FsSafeError("helper-failed", "watch operation failed without an error value", { details: { operation } });
+        retain(error);
+        const details = error instanceof FsSafeError ? error.details : undefined;
+        const code = details?.code ?? error?.code;
+        failureInfo = Object.freeze({ error, operation: details?.operation === "watch" ? "watch" : details?.operation === "callback" ? "callback" : details?.operation === "close" ? "close" : operation, ...(typeof code === "string" ? { code } : {}) });
+        current.abort.abort(error);
+        current.waiter.reject(error);
+        pendingWaiter?.reject(error);
+        runningWaiter?.reject(error);
+        pendingWaiter = undefined;
+        runningWaiter = undefined;
+        clearTimers();
+        state = "unavailable";
+        // Stop backend admission before notifying. Its join remains owned by active/close.
+        try {
+            backend?.close();
+        }
+        catch (error) {
+            retainRetirement(error);
+        }
+        try {
+            notifyHealth();
+        }
+        catch (callbackError) {
+            retain(callbackError);
+        }
+    };
+    const scheduleInterval = () => {
+        if (terminal || failure !== undefined)
+            return;
+        timer = setTimeout(() => { timer = undefined; void request().catch(() => { }); }, intervalMs);
+        if (!persistent)
+            timer.unref();
+    };
+    const onHint = (g, batch) => {
+        if (terminal || current !== g || g.abort.signal.aborted || failure !== undefined)
+            return;
+        if (batch.error === "ESTALE")
+            refreshBackend = true;
+        else if (batch.error) {
+            lose(new FsSafeError("helper-failed", "native watch failed", { details: { operation: "watch", code: batch.error } }));
+            return;
+        }
+        if (batch.overflow)
+            pendingChanges = undefined;
+        else if (pendingChanges)
+            for (const hint of batch.hints) {
+                const key = JSON.stringify([hint.directory, hint.name]);
+                if (!pendingChanges.has(key) && pendingChanges.size >= maxPendingPaths) {
+                    pendingChanges = undefined;
+                    break;
+                }
+                const previous = pendingChanges.get(key);
+                pendingChanges.set(key, previous?.event === "rename" ? previous : hint);
+            }
+        pendingHint = true;
+        pending = true;
+        if (hintTimer)
+            return;
+        hintTimer = setTimeout(() => {
+            hintTimer = undefined;
+            if (terminal || current !== g || failure !== undefined)
+                return;
+            // Raw backend filenames stay private. Reconcile before publishing detail.
+            void request().catch(() => { });
+        }, coalesceMs);
+        if (!persistent)
+            hintTimer.unref();
+    };
+    const fallBack = (error) => {
+        if (options.mode !== "auto" || getFsSafeNativeConfig().mode === "require" ||
+            !(error instanceof FsSafeError) || error.code !== "helper-unavailable")
+            return false;
+        mode = "poll";
+        binding = undefined;
+        intervalMs = options.intervalMs ?? 1000;
+        return true;
+    };
+    const observe = async (g) => {
+        check(g);
+        if (selectionFailure !== undefined)
+            throw new FsSafeError("helper-unavailable", "native watch events are unavailable", { cause: selectionFailure, details: { operation: "watch" } });
+        if (refreshBackend) {
+            await retireBackend();
+            check(g);
+            refreshBackend = false;
+        }
+        if (resetRequested) {
+            await retireBackend();
+            check(g);
+            snapshot = undefined;
+            resetRequested = false;
+        }
+        state = snapshot ? "reconciling" : "starting";
+        notifyHealth();
+        check(g);
+        const started = performance.now();
+        const hadHints = pendingHint;
+        const hints = pendingChanges;
+        pendingHint = false;
+        pendingChanges = new Map();
+        clearTimeout(hintTimer);
+        hintTimer = undefined;
+        if (mode === "events" && !backend && g.scopes.length) {
+            try {
+                const candidate = new NativeWatchBackend(binding, context, batch => {
+                    if (backend === candidate)
+                        onHint(g, batch);
+                }, maxPendingPaths, persistent);
+                backend = candidate;
+                const hookResult = getFsSafeTestHooks()?.afterWatchBackendCreated?.(context.rootReal, batch => {
+                    if (backend === candidate)
+                        onHint(g, batch);
+                }, (path, flags) => candidate.testEvent(path, flags));
+                assertSynchronousCallbackResult(hookResult, "afterWatchBackendCreated");
+            }
+            catch (error) {
+                if (!fallBack(error))
+                    throw error;
+            }
+            check(g);
+        }
+        const next = await scanWatch(context, g.scopes, { exclude: options.exclude, maxDirectories, maxEntries, maxPendingPaths, admitting: !snapshot }, g.abort.signal, async (name, identity, guard) => {
+            check(g);
+            const existing = registered.get(name);
+            const acquire = !existing || existing.dev !== identity.dev || existing.ino !== identity.ino;
+            await getFsSafeTestHooks()?.beforeWatchRegistration?.(guard.realPath);
+            check(g);
+            if (acquire) {
+                try {
+                    backend?.add(name, identity);
+                }
+                catch (error) {
+                    if (snapshot || !fallBack(error))
+                        throw error;
+                    await retireBackend();
+                    check(g);
+                }
+            }
+            await getFsSafeTestHooks()?.afterWatchRegistration?.(guard.realPath);
+            check(g);
+            if (acquire)
+                registered.set(name, identity);
+        }, retainRetirement);
+        check(g);
+        // Retire stale inventory before the next pass; that crawl installs fresh anchors first.
+        if ([...registered.keys()].some(name => !next.directories.has(name))) {
+            refreshBackend = true;
+        }
+        observedDirectories = next.directories.size;
+        const initial = !snapshot;
+        let observed = next.overflow ? undefined : changedEntries(snapshot, next, maxPendingPaths);
+        if (observed) {
+            const changes = new Map(observed.map(change => [change.path, change]));
+            for (const name of next.structural ?? [])
+                for (const change of scopedChanges(g.scopes, { path: name, type: "structural" }))
+                    changes.set(change.path, change);
+            observed = changes.size > maxPendingPaths ? undefined : [...changes.values()];
+        }
+        let admittedHints = [];
+        try {
+            if (hadHints)
+                admittedHints = await admittedNativeChanges(context, g.scopes, snapshot, next, {
+                    hints: hints ? [...hints.values()] : [], overflow: !hints,
+                }, g.abort.signal, maxPendingPaths);
+        }
+        catch (error) {
+            check(g);
+            await assertRootIdentityCurrent(context);
+            if (!isWatchPathError(error))
+                throw error;
+            admittedHints = undefined;
+        }
+        check(g);
+        await assertRootIdentityCurrent(context);
+        check(g);
+        let details = hadHints
+            ? guardedHintChanges(g.scopes, snapshot, next, admittedHints, observed, maxPendingPaths)
+            : observed;
+        const behind = (hadHints || pendingHint) && performance.now() - started > coalesceMs;
+        if (behind)
+            details = undefined;
+        snapshot = next;
+        // Publish before readiness; callbacks may synchronously retire this generation.
+        if (initial || !details || details.length)
+            dirty(g, initial ? "reconcile" : !details ? "overflow" : hadHints ? "event" : "reconcile", initial ? undefined : details);
+        check(g);
+        state = "ready";
+        notifyHealth();
+        check(g);
+    };
+    const pump = () => {
+        if (active || terminal || failure !== undefined)
+            return;
+        // Enroll before any callback. There is one active pass and one coalesced request.
+        active = Promise.resolve().then(async () => {
+            do {
+                const g = current;
+                pending = false;
+                if (pendingWaiter) {
+                    // A scope replacement keeps reconcile requests alive until its baseline completes.
+                    const previous = runningWaiter;
+                    runningWaiter = pendingWaiter;
+                    pendingWaiter = undefined;
+                    if (previous)
+                        void runningWaiter.promise.then(() => previous.resolve(), error => previous.reject(error));
+                }
+                try {
+                    await observe(g);
+                    check(g);
+                    g.waiter.resolve();
+                    runningWaiter?.resolve();
+                    runningWaiter = undefined;
+                }
+                catch (error) {
+                    g.waiter.reject(error);
+                    if (!g.abort.signal.aborted && current === g && !terminal)
+                        lose(error);
+                    try {
+                        await retireBackend();
+                    }
+                    catch (closeError) {
+                        retainRetirement(closeError);
+                    }
+                }
+                if (current !== g) {
+                    await retireBackend();
+                    snapshot = undefined;
+                    pending = true;
+                }
+            } while (pending && !terminal && failure === undefined);
+        }).catch(lose).finally(() => {
+            active = undefined;
+            if (!terminal && failure === undefined) {
+                if (pending || !current.waiter.settled)
+                    pump();
+                else
+                    scheduleInterval();
+            }
+        });
+    };
+    const request = () => {
+        if (terminal)
+            return Promise.reject(retired());
+        if (failure !== undefined)
+            return Promise.reject(failure);
+        clearTimeout(timer);
+        timer = undefined;
+        pending = true;
+        pendingWaiter ??= deferred();
+        const result = pendingWaiter.promise;
+        pump();
+        return result;
+    };
+    const close = () => {
+        if (closing)
+            return closing;
+        terminal = true;
+        current.abort.abort(retired());
+        current.waiter.reject(retired());
+        pendingWaiter?.reject(retired());
+        runningWaiter?.reject(retired());
+        pendingWaiter = undefined;
+        runningWaiter = undefined;
+        clearTimers();
+        options.signal?.removeEventListener("abort", abort);
+        // Start physical stop immediately, without waiting behind an in-flight scan.
+        try {
+            backend?.close();
+        }
+        catch (error) {
+            retainRetirement(error);
+        }
+        closing = Promise.resolve().then(async () => {
+            await active;
+            try {
+                await retireBackend();
+            }
+            catch (error) {
+                retainRetirement(error);
+            }
+            state = "closed";
+            if (retirementFailure)
+                throw combinedFailure();
+        });
+        void closing.catch(() => { });
+        return closing;
+    };
+    const abort = () => { void close(); };
+    const subscription = {
+        ready, health, close, [Symbol.asyncDispose]: close,
+        reconcile: request,
+        setScopes(scopes) {
+            if (terminal)
+                return Promise.reject(retired());
+            if (failure !== undefined)
+                return Promise.reject(failure);
+            const previous = current;
+            const next = makeGeneration(scopes);
+            // Scope accessors may synchronously close this owner during validation.
+            if (terminal || failure !== undefined || current !== previous) {
+                next.waiter.reject(failure ?? retired());
+                return next.waiter.promise;
+            }
+            current.abort.abort(retired());
+            current.waiter.reject(retired());
+            current = next;
+            resetRequested = true;
+            try {
+                backend?.close();
+            }
+            catch (error) {
+                retainRetirement(error);
+            }
+            clearTimers();
+            state = "starting";
+            // If idle, retire the old backend before the next scan can admit anything.
+            if (!active) {
+                active = retireBackend().catch(error => lose(error, "close")).finally(() => {
+                    active = undefined;
+                    snapshot = undefined;
+                    pump();
+                });
+            }
+            return next.waiter.promise;
+        },
+    };
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    else
+        pump();
+    return subscription;
+}

package/docs/advanced.md

@@ -77,6 +77,7 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | `overwriteFileHandle`, `OverwriteFileHandleOptions` | [in-place-write.md](in-place-write.md) | Overwrite a borrowed read/write handle with prefix-only preparation and best-effort rollback; preserves its inode, cursor, and caller-owned lifetime. |
 | `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `symlinks: "follow-parents-within-root"` for contained parent aliases or `"follow-within-root"` for final links too. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
+| `retainFileInDirectory`, `RetainedFile`, related receipt/result types | [Retained Windows files](retained-file.md) | Existing-file native handle custody and explicit removal; local NTFS, producer authority required, no persistence guarantee. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `readDirectoryIdentity`, `assertDirectoryIdentitySync`, `DirectoryIdentity` | [directory-identity.md](directory-identity.md) | Observe exact bigint directory identity and synchronously check a caller-selected path, optionally retaining its canonical path. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |

package/docs/atomic.md

@@ -60,6 +60,8 @@ type ReplaceFileAtomicOptions = {
   syncTempFile?: boolean;           // fsync(temp) before rename, or the final file after copy fallback; default false
   syncParentDir?: boolean;          // fsync(parent) after rename, POSIX only; default false
   throwOnCleanupError?: boolean;    // report temp cleanup failure; default false
+  assertBeforeMutation?: () => void;
+  onDestinationState?: (state: ReplaceFileAtomicDestinationState) => void;
   beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
   fileSystem?: ReplaceFileAtomicFileSystem; // injectable fs for tests
 };
@@ -108,6 +110,65 @@ descriptor is still closed, and a close failure remains reportable.
 
 Identity checks and pathname rename/unlink remain separate syscalls, not atomic conditional mutations. Use an approved writable parent plus cooperative locking or OS isolation when arbitrary concurrent namespace mutation is in scope.
 
+### Atomic write authority and destination state
+
+Use `assertBeforeMutation` when a write depends on a lease or other revocable
+application authority. Both atomic variants capture the callback at entry and
+run it synchronously before directory creation or mode changes, compatibility
+lock acquisition, staging creation and writes, each rename attempt, and fallback
+removal, destination acquisition, truncation, and each content write. Asynchronous destination identity checks
+finish before the final authority check; no await separates that check from the
+write dispatch. A dispatched operation still owns its completion.
+
+`onDestinationState` captures facts that a caller may need if the operation later
+rejects:
+
+```ts
+type ReplaceFileAtomicDestinationState =
+  | Readonly<{ state: "removed"; path: string }>
+  | Readonly<{
+      state: "writing" | "published";
+      path: string;
+      dev: bigint;
+      ino: bigint;
+    }>;
+```
+
+- `removed` follows successful removal of an existing fallback destination.
+- `writing` records the fallback's retained descriptor after exclusive creation
+  or the first successful truncation of an existing `restore-original` target.
+  Opening an existing target leaves it untouched and emits no receipt. This state
+  does not claim that all requested bytes were written.
+- `published` follows successful rename and destination identity verification,
+  before parent synchronization or descriptor close can fail. Copy fallback
+  reports it after its content, mode, and requested file synchronization complete.
+  The explicit `verify-content-with-lock` policy first applies its existing
+  locked content verification to admit the replacement descriptor.
+
+Receipts are frozen and use the destination spelling captured by the operation.
+File identities come from retained descriptors, never from reopening a pathname
+after a failed copy. Failed or indeterminate admission can leave no identity
+receipt; a rename followed by replacement before verification also has no
+publication receipt. Do not infer ownership from a fresh post-failure stat. A later writer
+can replace the pathname, so compare the recorded identity with the current
+entry and recheck application authority before compensation. Receipts do not
+promise durable storage or authorize rollback.
+
+Both callbacks must complete synchronously; Promise and thenable results are
+rejected, and ordinary return values are ignored. The first callback refusal
+is terminal, including falsy thrown values; an `EPERM`, `EEXIST`, or `EBUSY` code
+from a callback never starts fallback or retry. Refusal during an in-place
+fallback also stops new restoration writes. Final mode, synchronization, close,
+and private-stage cleanup may still settle against owned identities after
+revocation. Callback refusal does not delete a published destination or a
+competing file at a staging name. An observer that throws must retain its receipt
+first if recovery needs it.
+
+`beforeRename` remains the hook for preparing backups. Effects performed inside
+that hook remain the caller's responsibility; the authority option guards the
+atomic writer's own effects. Omitting both new callbacks preserves existing
+write, fallback, restoration, result, and cleanup behavior.
+
 ### FUSE, Windows exFAT/FAT32, and unstable rename identity
 
 Strict source-to-destination identity is the default. Some FUSE mounts assign a different inode to the destination during rename even without concurrency. Set `renameIdentity: "verify-content-with-lock"` to accept that boundary only when the re-opened no-follow destination has the exact requested SHA-256 content under an exclusive hashed sidecar lock in the destination parent. The newly accepted descriptor and identity remain pinned through parent sync and final verification. The synchronous helper provides the same policy with the synchronous lock implementation.

package/docs/contributing.md

@@ -167,6 +167,11 @@ pnpm check
 This runs the filesystem boundary checks, build, tests, and package
 tarball/import validation.
 
+The native watch lane requires events on Linux, macOS, and Windows and reports
+actual edit latency. Run `FS_SAFE_TEST_SERIAL=1 pnpm check` to isolate local timing
+checks from the other filesystem stress suites. Watch fixtures use normal OS
+temporary storage; session scratch trees may suppress macOS filesystem events.
+
 ### Method benchmarks
 
 `pnpm benchmark:methods` measures the callable library surface against synthetic

package/docs/durability.md

@@ -436,3 +436,10 @@ owning product boundary.
 - [Migrating to 0.5](migrating-to-0.5.md) — choosing a publication policy during upgrade.
 - [Native architecture](native.md) — clone/copy/hash mechanisms and fallback guarantees.
 - [Errors](errors.md) — typed operational failure handling.
+
+## Existing Windows file retirement
+
+[`retainFileInDirectory`](retained-file.md) describes identity-bound native
+disposition and resource settlement separately from persistence. Its result is
+always `persistence: "not-proven"`; neither accepted disposition nor observed
+namespace absence is a directory/volume barrier or an application commit.

package/docs/index.md

@@ -65,6 +65,7 @@ await fs.remove("notes/archive/today.txt");
 | [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for private JSON/text state at 0600 under 0700 dirs. |
 | [`tempWorkspace`](temp.md) | 0700 scratch dir with auto-cleanup. |
 | [`readSecureFile`](secure-file.md) | Absolute file reads with fd pinning, permissions, owner, size, and timeout checks. |
+| [`watch`](watch.md) | Guarded filesystem observation with advisory native hints and polling. |
 | [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
 | [`Root.entries`](entries.md) | Guarded nonrecursive entries, bounded name collection, and caller-owned symlink validation. |
 | [`extractArchive`](archive.md) | Policy-driven ZIP/TAR extraction with clamp/filter, metadata/path-depth, link, count, and byte limits. |

package/docs/native-helper.md

@@ -182,3 +182,12 @@ consumer performs its 0.5 upgrade.
 - [Durability](durability.md)
 - [Migrating to 0.5](migrating-to-0.5.md)
 - [Migrating to 0.6](migrating-to-0.6.md)
+
+### Retained existing Windows file
+
+The maintained Windows helper supports the public
+[`retainFileInDirectory`](retained-file.md) lifecycle on fixed local NTFS.
+Private native handles, exact identity/generation checks, writable-section
+admission and explicit close results stay behind that public API. Older helpers
+without this capability are unsupported; there is no pathname deletion fallback.
+No Windows namespace persistence barrier is provided.