@openclaw/fs-safe 0.19.0 → 0.21.0

package/dist/replace-file-mutation.js

@@ -0,0 +1,47 @@
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+export class AtomicMutation {
+    active;
+    #assertion;
+    #observer;
+    #refusal;
+    #writingReported = false;
+    constructor(options) {
+        this.#assertion = options.assertBeforeMutation;
+        this.#observer = options.onDestinationState;
+        this.active = Boolean(this.#assertion || this.#observer);
+    }
+    rethrowRefusal() {
+        if (this.#refusal)
+            throw this.#refusal.error;
+    }
+    refuse(error) {
+        this.#refusal ??= { error };
+        throw this.#refusal.error;
+    }
+    #invoke(operation, name) {
+        this.rethrowRefusal();
+        try {
+            const result = operation();
+            assertSynchronousCallbackResult(result, name);
+        }
+        catch (error) {
+            this.refuse(error);
+        }
+    }
+    assert() {
+        this.#invoke(() => this.#assertion?.(), "assertBeforeMutation");
+    }
+    destination(state, path, identity) {
+        if (state === "writing") {
+            if (this.#writingReported)
+                return;
+            this.#writingReported = true;
+        }
+        this.#invoke(() => this.#observer?.(Object.freeze({
+            state, path, dev: identity.dev, ino: identity.ino,
+        })), "onDestinationState");
+    }
+    removed(path) {
+        this.#invoke(() => this.#observer?.(Object.freeze({ state: "removed", path })), "onDestinationState");
+    }
+}

package/dist/replace-file-temp-owner.d.ts

@@ -26,7 +26,7 @@ export declare class AsyncAtomicTempOwner extends AtomicTempOwner<FileHandle> {
         identity: BigIntStats;
     }): void;
     assertCurrent(fsModule: AsyncOwnerFileSystem, pathname?: string): Promise<void>;
-    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string): Promise<void>;
+    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string, onVerified?: (identity: BigIntStats) => void): Promise<void>;
     finish(params: {
         fsModule: AsyncOwnerFileSystem;
         originalFailure?: AtomicTempFailure;
@@ -39,7 +39,7 @@ export declare class SyncAtomicTempOwner extends AtomicTempOwner<number> {
         identity: BigIntStats;
     }): void;
     assertCurrent(fsModule: SyncOwnerFileSystem, pathname?: string): void;
-    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string): void;
+    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string, onVerified?: (identity: BigIntStats) => void): void;
     finish(params: {
         fsModule: SyncOwnerFileSystem;
         originalFailure?: AtomicTempFailure;

package/dist/replace-file-temp-owner.js

@@ -161,16 +161,21 @@ export class AsyncAtomicTempOwner extends AtomicTempOwner {
             throw error;
         }
     }
-    async assertPublished(fsModule, pathname, expectedHash) {
+    async assertPublished(fsModule, pathname, expectedHash, onVerified) {
+        let identityCurrent = false;
         try {
             await this.assertCurrent(fsModule, pathname);
-            return;
+            identityCurrent = true;
         }
         catch (error) {
             if (!(error instanceof FsSafeError) || !hasErrorCode(error, "path-mismatch") || !expectedHash) {
                 throw error;
             }
         }
+        if (identityCurrent) {
+            onVerified?.(this.identity);
+            return;
+        }
         let published;
         try {
             try {
@@ -199,6 +204,7 @@ export class AsyncAtomicTempOwner extends AtomicTempOwner {
             if (sha256Hex(await published.readFile()) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
+            onVerified?.(identity);
             const previousHandle = this.takeResource();
             await previousHandle?.close();
             this.resource = published;
@@ -269,16 +275,21 @@ export class SyncAtomicTempOwner extends AtomicTempOwner {
             throw error;
         }
     }
-    assertPublished(fsModule, pathname, expectedHash) {
+    assertPublished(fsModule, pathname, expectedHash, onVerified) {
+        let identityCurrent = false;
         try {
             this.assertCurrent(fsModule, pathname);
-            return;
+            identityCurrent = true;
         }
         catch (error) {
             if (!(error instanceof FsSafeError) || !hasErrorCode(error, "path-mismatch") || !expectedHash) {
                 throw error;
             }
         }
+        if (identityCurrent) {
+            onVerified?.(this.identity);
+            return;
+        }
         let publishedFd;
         try {
             try {
@@ -305,6 +316,7 @@ export class SyncAtomicTempOwner extends AtomicTempOwner {
             if (sha256Hex(fsModule.readFileSync(publishedFd)) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
+            onVerified?.(identity);
             const previousFd = this.takeResource();
             fsModule.closeSync(previousFd);
             this.resource = publishedFd;

package/dist/replace-file-types.d.ts

@@ -0,0 +1,55 @@
+import type syncFs from "node:fs";
+import type fs from "node:fs/promises";
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
+import type { AtomicMutationOptions } from "./replace-file-mutation.js";
+import type { ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy } from "./replace-file-copy-fallback.js";
+export type ReplaceFileAtomicFileSystem = {
+    promises: Pick<typeof fs, "mkdir" | "writeFile" | "rename" | "copyFile" | "unlink" | "rm" | "open" | "stat" | "lstat"> & {
+        /** @deprecated Accepted for adapter compatibility but never called. */
+        chmod?: typeof fs.chmod;
+    };
+};
+export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" | "readFileSync" | "writeFileSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync" | "openSync" | "fsyncSync" | "closeSync" | "fstatSync" | "statSync" | "lstatSync" | "ftruncateSync" | "readSync" | "writeSync"> & {
+    /** @deprecated Accepted for adapter compatibility but never called. */
+    chmodSync?: typeof syncFs.chmodSync;
+    fchmodSync?: typeof syncFs.fchmodSync;
+};
+export type ReplaceFileAtomicBaseOptions = AtomicMutationOptions & {
+    filePath: string;
+    content: string | Uint8Array;
+    dirMode?: number;
+    mode?: number;
+    /** Inherit only rwx bits from an existing non-symlink regular file. */
+    preserveExistingMode?: boolean;
+    tempPrefix?: string;
+    renameMaxRetries?: number;
+    renameRetryBaseDelayMs?: number;
+    copyFallbackOnPermissionError?: boolean;
+    copyFallbackRestore?: ReplaceFileCopyFallbackRestorePolicy;
+    maxRestoreBytes?: number;
+    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
+    /** Strict by default; locked content verification is an explicit FUSE compatibility policy. */
+    renameIdentity?: RenameIdentityPolicy;
+    syncTempFile?: boolean;
+    syncParentDir?: boolean;
+    throwOnCleanupError?: boolean;
+};
+export type ReplaceFileAtomicOptions = ReplaceFileAtomicBaseOptions & {
+    fileSystem?: ReplaceFileAtomicFileSystem;
+    /** Runs while the exact staged file is retained; replacing or hardlinking it is rejected. */
+    beforeRename?: (params: {
+        filePath: string;
+        tempPath: string;
+    }) => Promise<void>;
+};
+export type ReplaceFileAtomicSyncOptions = ReplaceFileAtomicBaseOptions & {
+    fileSystem?: ReplaceFileAtomicSyncFileSystem;
+    /** Runs while the exact staged file is retained; replacing or hardlinking it is rejected. */
+    beforeRename?: (params: {
+        filePath: string;
+        tempPath: string;
+    }) => void;
+};
+export type ReplaceFileAtomicResult = {
+    method: "rename" | "copy-fallback";
+};

package/dist/replace-file-types.js

@@ -0,0 +1 @@
+export {};

package/dist/replace-file.d.ts

@@ -1,58 +1,6 @@
-import syncFs from "node:fs";
-import fs from "node:fs/promises";
-import type { RenameIdentityPolicy } from "./pinned-write-types.js";
-import { type ReplaceFileCopyFallbackRestorePolicy, type ReplaceFileDestinationHardlinkPolicy } from "./replace-file-copy-fallback.js";
-export type ReplaceFileAtomicFileSystem = {
-    promises: Pick<typeof fs, "mkdir" | "writeFile" | "rename" | "copyFile" | "unlink" | "rm" | "open" | "stat" | "lstat"> & {
-        /** @deprecated Accepted for adapter compatibility but never called. */
-        chmod?: typeof fs.chmod;
-    };
-};
-export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" | "readFileSync" | "writeFileSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync" | "openSync" | "fsyncSync" | "closeSync" | "fstatSync" | "statSync" | "lstatSync" | "ftruncateSync" | "readSync" | "writeSync"> & {
-    /** @deprecated Accepted for adapter compatibility but never called. */
-    chmodSync?: typeof syncFs.chmodSync;
-    fchmodSync?: typeof syncFs.fchmodSync;
-};
-type ReplaceFileAtomicBaseOptions = {
-    filePath: string;
-    content: string | Uint8Array;
-    dirMode?: number;
-    mode?: number;
-    /** Inherit only rwx bits from an existing non-symlink regular file. */
-    preserveExistingMode?: boolean;
-    tempPrefix?: string;
-    renameMaxRetries?: number;
-    renameRetryBaseDelayMs?: number;
-    copyFallbackOnPermissionError?: boolean;
-    copyFallbackRestore?: ReplaceFileCopyFallbackRestorePolicy;
-    maxRestoreBytes?: number;
-    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
-    /** Strict by default; locked content verification is an explicit FUSE compatibility policy. */
-    renameIdentity?: RenameIdentityPolicy;
-    syncTempFile?: boolean;
-    syncParentDir?: boolean;
-    throwOnCleanupError?: boolean;
-};
-export type ReplaceFileAtomicOptions = ReplaceFileAtomicBaseOptions & {
-    fileSystem?: ReplaceFileAtomicFileSystem;
-    /** Runs while the exact staged file is retained; replacing or hardlinking it is rejected. */
-    beforeRename?: (params: {
-        filePath: string;
-        tempPath: string;
-    }) => Promise<void>;
-};
-export type ReplaceFileAtomicSyncOptions = ReplaceFileAtomicBaseOptions & {
-    fileSystem?: ReplaceFileAtomicSyncFileSystem;
-    /** Runs while the exact staged file is retained; replacing or hardlinking it is rejected. */
-    beforeRename?: (params: {
-        filePath: string;
-        tempPath: string;
-    }) => void;
-};
-export type ReplaceFileAtomicResult = {
-    method: "rename" | "copy-fallback";
-};
+import type { ReplaceFileAtomicOptions, ReplaceFileAtomicSyncOptions, ReplaceFileAtomicResult } from "./replace-file-types.js";
+export type { ReplaceFileAtomicDestinationState } from "./replace-file-mutation.js";
+export type { ReplaceFileAtomicFileSystem, ReplaceFileAtomicSyncFileSystem, ReplaceFileAtomicOptions, ReplaceFileAtomicSyncOptions, ReplaceFileAtomicResult, } from "./replace-file-types.js";
 export declare function replaceFileAtomic(options: ReplaceFileAtomicOptions): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicWithDirectorySync(options: ReplaceFileAtomicOptions, syncParent?: (directoryPath: string) => Promise<unknown>): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicSync(options: ReplaceFileAtomicSyncOptions): ReplaceFileAtomicResult;
-export {};

package/dist/replace-file.js

@@ -13,15 +13,18 @@ import { admitStandalonePublicationPath } from "./windows-path-alias.js";
 import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
 import { hasErrorCode, readErrorCode } from "./file-cleanup.js";
+import { AtomicMutation } from "./replace-file-mutation.js";
 async function renameWithRetry(params) {
     for (let attempt = 0; attempt <= params.maxRetries; attempt++) {
         if (attempt > 0)
             await params.assertSourceCurrent();
         try {
+            params.mutation.assert();
             await params.fsModule.rename(params.src, params.dest);
             return { method: "rename" };
         }
         catch (error) {
+            params.mutation.rethrowRefusal();
             const code = readErrorCode(error);
             if (code === "EBUSY" && attempt < params.maxRetries) {
                 await sleep(params.baseDelayMs * 2 ** attempt);
@@ -37,6 +40,7 @@ async function renameWithRetry(params) {
                     maxRestoreBytes: params.maxRestoreBytes,
                     expectedSourceIdentity: params.sourceIdentity,
                     sync: params.syncFallback,
+                    mutation: params.mutation,
                 });
                 return { method: "copy-fallback" };
             }
@@ -50,10 +54,12 @@ function renameWithRetrySync(params) {
         if (attempt > 0)
             params.assertSourceCurrent();
         try {
+            params.mutation.assert();
             params.fsModule.renameSync(params.src, params.dest);
             return { method: "rename" };
         }
         catch (error) {
+            params.mutation.rethrowRefusal();
             const code = readErrorCode(error);
             if (code === "EBUSY" && attempt < params.maxRetries) {
                 sleepSync(params.baseDelayMs * 2 ** attempt);
@@ -70,6 +76,7 @@ function renameWithRetrySync(params) {
                     expectedSourceIdentity: params.sourceIdentity,
                     fchmodSync: params.fchmodSync,
                     sync: params.syncFallback,
+                    mutation: params.mutation,
                 });
                 return { method: "copy-fallback" };
             }
@@ -142,24 +149,27 @@ export async function replaceFileAtomic(options) {
 }
 // Internal owner hook: keep directory durability inside publication verification and serialization.
 export async function replaceFileAtomicWithDirectorySync(options, syncParent) {
+    const mutation = new AtomicMutation(options);
     const filePath = validateReplaceFilePath(options.filePath);
     validateRestoreOptions(options);
     const renameIdentity = options.renameIdentity;
     validateRenameIdentity(renameIdentity);
     return await serializePathWrite(path.resolve(filePath), async () => {
         if (renameIdentity !== "verify-content-with-lock") {
-            return await replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent);
+            return await replaceFileAtomicUnserialized(options, filePath, renameIdentity, mutation, syncParent);
         }
         const fsModule = options.fileSystem?.promises ?? fs;
         const dir = path.dirname(filePath);
+        mutation.assert();
         await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, {
             recursive: true,
             mode: options.dirMode ?? 0o700,
         });
-        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent));
+        mutation.assert();
+        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options, filePath, renameIdentity, mutation, syncParent));
     });
 }
-async function replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent) {
+async function replaceFileAtomicUnserialized(options, filePath, renameIdentity, mutation, syncParent) {
     const fsModule = options.fileSystem?.promises ?? fs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
@@ -169,8 +179,9 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
     const tempOwner = new AsyncAtomicTempOwner(tempPath);
     let originalFailure;
     try {
+        mutation.assert();
         await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
-        await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode });
+        await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode, mutation });
         tempOwner.start();
         tempOwner.adopt(await writeTempFile({
             fsModule,
@@ -179,6 +190,7 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
             mode,
             sync: options.syncTempFile === true,
             onIdentity: tempOwner.onIdentity,
+            mutation,
         }));
         await tempOwner.assertCurrent(fsModule);
         if (options.beforeRename) {
@@ -202,10 +214,11 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
             sourceIdentity: tempOwner.identity,
             assertSourceCurrent: () => tempOwner.assertCurrent(fsModule),
             syncFallback: options.syncTempFile === true,
+            mutation,
         });
         if (result.method === "rename") {
             tempOwner.markRenamed();
-            await tempOwner.assertPublished(fsModule, filePath, expectedHash);
+            await tempOwner.assertPublished(fsModule, filePath, expectedHash, identity => mutation.destination("published", filePath, identity));
         }
         else {
             await tempOwner.assertCurrent(fsModule);
@@ -237,22 +250,25 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
     }
 }
 export function replaceFileAtomicSync(options) {
+    const mutation = new AtomicMutation(options);
     const filePath = validateReplaceFilePath(options.filePath);
     validateRestoreOptions(options);
     const renameIdentity = options.renameIdentity;
     validateRenameIdentity(renameIdentity);
     if (renameIdentity !== "verify-content-with-lock") {
-        return replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity);
+        return replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity, mutation);
     }
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
+    mutation.assert();
     fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, {
         recursive: true,
         mode: options.dirMode ?? 0o700,
     });
-    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity));
+    mutation.assert();
+    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity, mutation));
 }
-function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
+function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity, mutation) {
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
@@ -269,8 +285,9 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
     const tempOwner = new SyncAtomicTempOwner(tempPath);
     let originalFailure;
     try {
+        mutation.assert();
         fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
-        applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync });
+        applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync, mutation });
         tempOwner.start();
         tempOwner.adopt(writeTempFileSync({
             fsModule,
@@ -280,6 +297,7 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
             fchmodSync,
             sync: options.syncTempFile === true,
             onIdentity: tempOwner.onIdentity,
+            mutation,
         }));
         tempOwner.assertCurrent(fsModule);
         if (options.beforeRename) {
@@ -304,10 +322,11 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
             assertSourceCurrent: () => tempOwner.assertCurrent(fsModule),
             fchmodSync,
             syncFallback: options.syncTempFile === true,
+            mutation,
         });
         if (result.method === "rename") {
             tempOwner.markRenamed();
-            tempOwner.assertPublished(fsModule, filePath, expectedHash);
+            tempOwner.assertPublished(fsModule, filePath, expectedHash, identity => mutation.destination("published", filePath, identity));
         }
         else {
             tempOwner.assertCurrent(fsModule);

package/dist/retained-file-types.d.ts

@@ -0,0 +1,61 @@
+/** Exact producer observations: never supply rounded Number identities. */
+export type RetainedFileExpected = Readonly<{
+    dev: bigint;
+    ino: bigint;
+    size: bigint;
+    mtimeNs: bigint;
+    ctimeNs: bigint;
+    /** Lowercase SHA-256 of the producer's expected bytes. */
+    sha256: string;
+}>;
+export type RetainedFileIssue = Readonly<{
+    phase: string;
+    code: string;
+    message: string;
+    cause?: unknown;
+}>;
+/** Descriptive facts, not a deletion capability or a durable transaction receipt. */
+export type RetainedFileResult = Readonly<{
+    status: "unsupported" | "not-attempted" | "preserved-mismatch" | "disposition-accepted" | "name-absent-after-settlement" | "failed" | "indeterminate";
+    phase: string;
+    /** Full native 64-bit volume serial and 128-bit file ID, when observed. */
+    identity?: string;
+    disposition: "not-attempted" | "accepted" | "rejected" | "indeterminate";
+    namespace: "not-observed" | "absent" | "original" | "foreign" | "unknown";
+    resources: "closed" | "close-failed";
+    persistence: "not-proven";
+    errors: readonly RetainedFileIssue[];
+}>;
+export type RetainedFileReceipt = Readonly<{
+    directory: string;
+    parent: Readonly<{
+        dev: bigint;
+        ino: bigint;
+    }>;
+    basename: string;
+    expected: RetainedFileExpected;
+    identity: string;
+}>;
+export interface RetainedFile extends Disposable {
+    readonly receipt: RetainedFileReceipt;
+    /** One-shot, synchronous authority admission; always settles owned resources. */
+    remove(): RetainedFileResult;
+    /** Closes only. Never requests deletion, including after an exception. */
+    dispose(): RetainedFileResult;
+}
+export type RetainedFileAdmission = Readonly<{
+    status: "retained";
+    file: RetainedFile;
+}> | RetainedFileResult;
+export type RetainFileInDirectoryOptions = Readonly<{
+    directory: string;
+    parent: Readonly<{
+        dev: bigint;
+        ino: bigint;
+    }>;
+    basename: string;
+    expected: RetainedFileExpected;
+    assertBeforeMutation: () => void;
+    /** Synchronous verification budget, default 16 MiB; maximum 64 MiB. */
+    maxBytes?: number;
+}>;

package/dist/retained-file-types.js

@@ -0,0 +1 @@
+export {};

package/dist/retained-file.d.ts

@@ -0,0 +1,3 @@
+import type { RetainedFileAdmission, RetainFileInDirectoryOptions } from "./retained-file-types.js";
+/** Retain one existing regular file on supported local Windows NTFS. No fallback. */
+export declare function retainFileInDirectory(options: RetainFileInDirectoryOptions): RetainedFileAdmission;

package/dist/retained-file.js

@@ -0,0 +1,121 @@
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+function freeze(result) {
+    return Object.freeze({ ...result, errors: Object.freeze(result.errors.map((error) => Object.freeze({ ...error }))) });
+}
+function unsupported(cause) {
+    return freeze({ status: "unsupported", phase: "admission", disposition: "not-attempted",
+        namespace: "not-observed", resources: "closed", persistence: "not-proven",
+        errors: [{ phase: "admission", code: "helper-unavailable",
+                message: "existing-file retention requires the maintained Windows native capability", cause }] });
+}
+function exact(value, name, zero = false) {
+    if (typeof value !== "bigint" || value < (zero ? 0n : 1n) || value > 0xffffffffffffffffn) {
+        throw new TypeError(`${name} must be an exact ${zero ? "nonnegative" : "positive"} unsigned 64-bit bigint`);
+    }
+    return value;
+}
+class Owner {
+    receipt;
+    #native;
+    #assert;
+    #result;
+    #running = false;
+    #reentered = false;
+    constructor(native, receipt, assertion) {
+        this.#native = native;
+        this.receipt = receipt;
+        this.#assert = assertion;
+        Object.freeze(this);
+    }
+    #settle(remove) {
+        if (this.#result)
+            return this.#result;
+        if (this.#running) {
+            this.#reentered = true;
+            throw new TypeError("retained-file settlement cannot be reentered");
+        }
+        this.#running = true;
+        let rejection;
+        if (remove) {
+            try {
+                assertSynchronousCallbackResult(this.#assert(), "assertBeforeMutation");
+                if (this.#reentered)
+                    throw new TypeError("retained-file authority reentered settlement");
+            }
+            catch (cause) {
+                rejection = { cause };
+            }
+        }
+        try {
+            const result = this.#native.settle(remove && !rejection);
+            this.#result = freeze(rejection ? { ...result, phase: "authority", errors: [
+                    { phase: "authority", code: "denied-path", message: "current mutation authority rejected removal", cause: rejection.cause },
+                    ...result.errors,
+                ] } : result);
+        }
+        catch (cause) {
+            // An unexpected binding exception cannot establish native effect or close.
+            // Do not retry or release a dependency on an unknown native outcome.
+            this.#result = freeze({ status: "indeterminate", phase: "binding", identity: this.receipt.identity,
+                disposition: remove && !rejection ? "indeterminate" : "not-attempted", namespace: "unknown",
+                resources: "close-failed", persistence: "not-proven", errors: [
+                    ...(rejection ? [{ phase: "authority", code: "denied-path", message: "current mutation authority rejected removal", cause: rejection.cause }] : []),
+                    { phase: "binding", code: "helper-failed", message: "native settlement did not return a result", cause },
+                ] });
+        }
+        return this.#result;
+    }
+    remove() { return this.#settle(true); }
+    dispose() { return this.#settle(false); }
+    [Symbol.dispose]() {
+        const result = this.dispose();
+        if (result.resources !== "closed") {
+            throw new FsSafeError("helper-failed", "retained-file resource settlement is uncertain", { details: { result } });
+        }
+    }
+}
+/** Retain one existing regular file on supported local Windows NTFS. No fallback. */
+export function retainFileInDirectory(options) {
+    // Snapshot once before any native resource admission or caller authority runs.
+    const directory = options.directory;
+    const basename = options.basename;
+    const sourceParent = options.parent;
+    const parent = Object.freeze({ dev: exact(sourceParent.dev, "parent.dev"), ino: exact(sourceParent.ino, "parent.ino") });
+    const source = options.expected;
+    const expected = Object.freeze({ dev: exact(source.dev, "expected.dev"), ino: exact(source.ino, "expected.ino"),
+        size: exact(source.size, "expected.size", true), mtimeNs: exact(source.mtimeNs, "expected.mtimeNs", true),
+        ctimeNs: exact(source.ctimeNs, "expected.ctimeNs", true), sha256: source.sha256 });
+    const assertion = options.assertBeforeMutation;
+    const maxBytes = options.maxBytes ?? 16 * 1024 * 1024;
+    if (typeof directory !== "string" || typeof basename !== "string" || typeof assertion !== "function"
+        || typeof expected.sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(expected.sha256)
+        || !Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > 64 * 1024 * 1024 || expected.size > BigInt(maxBytes)) {
+        throw new TypeError("invalid retained-file directory, authority or bounded expected-byte contract");
+    }
+    if (process.platform !== "win32")
+        return unsupported();
+    let binding;
+    try {
+        binding = getNativeBinding();
+    }
+    catch (cause) {
+        return unsupported(cause);
+    }
+    if (!binding?.retainWindowsFile)
+        return unsupported();
+    let native;
+    try {
+        native = binding.retainWindowsFile(directory, basename, parent.dev, parent.ino, expected.dev, expected.ino, expected.size, expected.mtimeNs, expected.ctimeNs, expected.sha256, maxBytes);
+    }
+    catch (cause) {
+        // Factory errors have no returned owner; never infer absence or deletion.
+        return freeze({ ...unsupported(cause), status: "indeterminate", resources: "close-failed" });
+    }
+    const admission = native.admission;
+    if (admission.status !== "retained")
+        return freeze(admission);
+    const receipt = Object.freeze({ directory, parent, basename, expected, identity: admission.identity });
+    return Object.freeze({ status: "retained", file: new Owner(native, receipt, assertion) });
+}

package/dist/root-directory-entry.d.ts

@@ -0,0 +1,9 @@
+import { type RootContext } from "./root-context.js";
+import { type RootDirectoryObservationGuard } from "./root-directory-list.js";
+import { type ExactStatIdentity } from "./stat-observation.js";
+import type { DirEntry } from "./types.js";
+/** One literal entry lookup under an operation-local admitted parent; never follow the leaf. */
+export declare function lookupRootDirectoryEntry(root: RootContext, guard: RootDirectoryObservationGuard, name: string): Promise<{
+    entry: DirEntry;
+    identity: ExactStatIdentity;
+} | undefined>;

package/dist/root-directory-entry.js

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { assertValidRootRelativePath } from "./root-context.js";
+import { assertRootDirectoryObservationGuard, pathStatFromStats } from "./root-directory-list.js";
+import { inspectStatObservationSync } from "./stat-observation.js";
+/** One literal entry lookup under an operation-local admitted parent; never follow the leaf. */
+export async function lookupRootDirectoryEntry(root, guard, name) {
+    if (!name || name === "." || name === ".." || path.basename(name) !== name || path.isAbsolute(name)) {
+        throw new FsSafeError("invalid-path", "directory lookup requires one literal name");
+    }
+    assertValidRootRelativePath(name);
+    await assertRootDirectoryObservationGuard(root, guard);
+    try {
+        const pathname = path.join(guard.realPath, name);
+        const observed = inspectStatObservationSync(bigint => bigint
+            ? fs.lstatSync(pathname, { bigint: true }) : fs.lstatSync(pathname));
+        await assertRootDirectoryObservationGuard(root, guard);
+        return { entry: { name, ...pathStatFromStats(observed.stat) }, identity: observed.identity };
+    }
+    catch (error) {
+        await assertRootDirectoryObservationGuard(root, guard);
+        if (isNotFoundPathError(error))
+            return undefined;
+        throw error;
+    }
+}