@openclaw/fs-safe 0.12.0 → 0.13.1

package/dist/sidecar-lock-acquire.js

@@ -13,8 +13,16 @@ import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransient
 import { readSidecarLockRawSnapshot, parseSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { sleep } from "./timing.js";
-async function resolveNormalizedTargetPath(targetPath, lockRoot) {
-    const resolved = path.resolve(targetPath);
+import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
+function isCwdIndependentAbsolutePath(filePath) {
+    if (!path.isAbsolute(filePath))
+        return false;
+    // A leading separator on Windows is rooted on the process's current drive.
+    // Drive-qualified, UNC, and namespace roots are longer and need no cwd state.
+    return process.platform !== "win32" || path.parse(filePath).root.length > 1;
+}
+async function resolveNormalizedTargetPath(resolved, lockRoot) {
+    assertNoWindowsPathAlias(resolved);
     const dir = path.dirname(resolved);
     if (lockRoot) {
         // The target is an arbitration key, not necessarily inside the lock Root.
@@ -22,15 +30,23 @@ async function resolveNormalizedTargetPath(targetPath, lockRoot) {
         await lockRoot.resolve(".");
         const parent = await canonicalPathFromExistingAncestor(dir);
         await lockRoot.resolve(".");
-        return path.join(parent, path.basename(resolved));
+        assertNoWindowsPathAlias(parent);
+        const normalized = path.join(parent, path.basename(resolved));
+        assertNoWindowsPathAlias(normalized);
+        return normalized;
     }
     await fs.mkdir(recursiveMkdirPath(dir), { recursive: true });
+    let parent;
     try {
-        return path.join(realpathSync.native(dir), path.basename(resolved));
+        parent = realpathSync.native(dir);
     }
     catch {
         return resolved;
     }
+    assertNoWindowsPathAlias(parent);
+    const normalized = path.join(parent, path.basename(resolved));
+    assertNoWindowsPathAlias(normalized);
+    return normalized;
 }
 export async function acquireSidecarLock(options, context) {
     const retry = options.retry ?? {};
@@ -38,9 +54,24 @@ export async function acquireSidecarLock(options, context) {
     validateSidecarLockTimeoutMs(options.timeoutMs);
     validateSidecarLockStaleMs(options.staleMs);
     validateSidecarLockCompromiseCheckIntervalMs(options.compromiseCheckIntervalMs);
+    const targetPath = options.targetPath;
+    const explicitLockPath = options.lockPath;
+    const anchoredTargetPath = anchorWindowsDriveRelativePath(targetPath);
+    assertNoWindowsPathAlias(anchoredTargetPath);
+    const resolvedTargetPath = path.resolve(anchoredTargetPath);
+    let resolvedLockPath;
+    if (explicitLockPath !== undefined) {
+        const anchoredLockPath = anchorWindowsDriveRelativePath(explicitLockPath);
+        assertNoWindowsPathAlias(anchoredLockPath);
+        resolvedLockPath = isCwdIndependentAbsolutePath(explicitLockPath)
+            ? explicitLockPath
+            : path.resolve(anchoredLockPath);
+    }
     context.ensureExitCleanupRegistered();
-    const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath, options.lockRoot);
-    const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
+    const lockRoot = options.lockRoot;
+    const normalizedTargetPath = await resolveNormalizedTargetPath(resolvedTargetPath, lockRoot);
+    const lockPath = resolvedLockPath ?? `${normalizedTargetPath}.lock`;
+    assertNoWindowsPathAlias(lockPath);
     let held = context.held.get(normalizedTargetPath);
     if (held &&
         options.reentrantOwner !== undefined &&
@@ -118,8 +149,7 @@ export async function acquireSidecarLock(options, context) {
             const payload = await options.payload();
             const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
             try {
-                if (options.lockRoot) {
-                    const lockRoot = options.lockRoot;
+                if (lockRoot) {
                     const relativeLockPath = relativeSidecarLockPath(lockRoot, lockPath);
                     const observation = fileObservation();
                     try {
@@ -180,7 +210,7 @@ export async function acquireSidecarLock(options, context) {
                     snapshot,
                     acquiredAt: Date.now(),
                     metadata: options.metadata ?? {},
-                    lockRoot: options.lockRoot,
+                    lockRoot,
                     retainOnExit: options.retainOnExit,
                     parsePayload: options.parsePayload,
                 };
@@ -239,13 +269,13 @@ export async function acquireSidecarLock(options, context) {
                         // Root-created records retain the creator's byte/token receipt;
                         // partial direct writes use the exclusive descriptor's identity.
                         await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
-                            lockRoot: options.lockRoot,
+                            lockRoot,
                             parsePayload: options.parsePayload,
                         });
                     }
                     else if (createdSnapshot) {
                         await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
-                            lockRoot: options.lockRoot,
+                            lockRoot,
                             parsePayload: options.parsePayload,
                         });
                     }
@@ -271,7 +301,7 @@ export async function acquireSidecarLock(options, context) {
                 let lockFileOpenDenied = false;
                 try {
                     rawSnapshot = await readSidecarLockRawSnapshot(lockPath, {
-                        lockRoot: options.lockRoot,
+                        lockRoot,
                         rejectNonFile: true,
                         discardObservation: "changed",
                         onOpenFailure: (error) => { lockFileOpenDenied = isTransientLockFileDenial(error, lockPath); },
@@ -302,7 +332,7 @@ export async function acquireSidecarLock(options, context) {
                     heldByThisProcess: context.held.has(normalizedTargetPath),
                 })) {
                     if (!(await sidecarLockSnapshotStillPresent(lockPath, snapshot, {
-                        lockRoot: options.lockRoot,
+                        lockRoot,
                         parsePayload: options.parsePayload,
                     }))) {
                         await waitForRetry();
@@ -320,7 +350,7 @@ export async function acquireSidecarLock(options, context) {
                             normalizedTargetPath,
                             snapshot,
                             shouldRemoveStaleLock: options.shouldRemoveStaleLock,
-                            lockRoot: options.lockRoot,
+                            lockRoot,
                             parsePayload: options.parsePayload,
                         });
                         if (removal === "removed" || removal === "changed") {

package/dist/sidecar-lock-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-root.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-root.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAGvD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,IAAI,EACd,QAAQ,EAAE,MAAM,EAChB,kBAAkB,CAAC,EAAE,UAAU,GAAG,SAAS,EAC3C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACvC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAuD5B"}
+{"version":3,"file":"sidecar-lock-root.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-root.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAGvD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,IAAI,EACd,QAAQ,EAAE,MAAM,EAChB,kBAAkB,CAAC,EAAE,UAAU,GAAG,SAAS,EAC3C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACvC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAyD5B"}

package/dist/sidecar-lock-root.js

@@ -53,13 +53,15 @@ export async function openSidecarRoot(lockRoot, relative, discardObservation, on
         if (!discardObservation || (!missing && (!completeParents || !discardable)))
             throw error;
         try {
+            const probe = fileObservation();
             try {
-                const current = await lockRoot.stat(relative);
+                const current = await probe.run(() => lockRoot.stat(relative));
                 if (!current.isFile || current.isSymbolicLink || current.nlink !== 1)
                     throw error;
             }
             catch (probeError) {
-                if (!(probeError instanceof FsSafeError && probeError.code === "not-found"))
+                if (!(probeError instanceof FsSafeError && probeError.code === "not-found") &&
+                    !probe.has(probeError, `stat-leaf-missing:${expectedRealPath}`))
                     throw probeError;
             }
             for (const { dir, stat } of parents)

package/dist/staged-directory.d.ts

@@ -1,16 +1,25 @@
+import { type BigIntStats } from "node:fs";
 import type { DirectoryReceipt } from "./directory-durability.js";
 import type { FileIdentityStat } from "./file-identity.js";
+import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
 import type { StagedFileReceipt } from "./staged-file-types.js";
-type DirectorySnapshot = StagedFileReceipt["directory"];
+export type StagedDirectorySnapshot = StagedFileReceipt["directory"];
+export type PolicyStagedDirectory = Readonly<{
+    directory: StagedDirectorySnapshot;
+    observation: MutationDirectoryObservation;
+    stat: BigIntStats;
+}>;
 export declare function exactIdentityMatches(expected: FileIdentityStat, actual: Readonly<{
     dev: bigint;
     ino: bigint;
 }>): boolean;
-export declare function describeStagedDirectory(fd: number, pathname: string): DirectorySnapshot;
-export declare function assertStagedDirectoryCurrent(receipt: DirectorySnapshot): void;
+export declare function describeStagedDirectory(fd: number, pathname: string): StagedDirectorySnapshot;
+export declare function assertStagedDirectoryCurrent(receipt: StagedDirectorySnapshot): BigIntStats;
+export declare function describePolicyStagedDirectory(fd: number, pathname: string): PolicyStagedDirectory;
+export declare function assertPolicyStagedDirectoryCurrent(captured: PolicyStagedDirectory): BigIntStats;
+export declare function refreshPolicyStagedDirectoryObservation(captured: PolicyStagedDirectory): MutationDirectoryObservation;
 export declare function openStagedDirectory(directory: string | DirectoryReceipt): {
     fd: number;
-    receipt: DirectorySnapshot;
+    receipt: StagedDirectorySnapshot;
 };
-export {};
 //# sourceMappingURL=staged-directory.d.ts.map

package/dist/staged-directory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,KAAK,iBAAiB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAExD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAYvF;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAQ7E;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CA+BA"}
+{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAY7F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAS1F;AASD,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAwBvB;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,qBAAqB,GAC9B,WAAW,CAOb;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,qBAAqB,GAC9B,4BAA4B,CAU9B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAiCA"}

package/dist/staged-directory.js

@@ -1,7 +1,10 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
 import { realpathSync } from "./realpath.js";
+import { resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
 export function exactIdentityMatches(expected, actual) {
     return ["dev", "ino"].every((key) => {
         const value = expected[key];
@@ -14,7 +17,7 @@ export function describeStagedDirectory(fd, pathname) {
         throw new FsSafeError("not-file", "staging parent must be a directory");
     }
     const receipt = Object.freeze({
-        path: path.resolve(pathname),
+        path: resolvePathPreservingWindowsRoot(pathname),
         realPath: realpathSync(pathname),
         identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
     });
@@ -27,10 +30,58 @@ export function assertStagedDirectoryCurrent(receipt) {
         realpathSync(receipt.path) !== receipt.realPath) {
         throw new FsSafeError("path-mismatch", "staging directory pathname changed");
     }
+    return current;
+}
+function sameDirectoryMetadata(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.nlink === right.nlink;
+}
+// The policy hot path is Node/POSIX-only. It deliberately uses native
+// canonicalization so a successful capture contains no JS realpath work.
+export function describePolicyStagedDirectory(fd, pathname) {
+    const resolved = path.resolve(pathname);
+    const descriptor = fs.fstatSync(fd, { bigint: true });
+    if (!descriptor.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a directory");
+    }
+    const before = inspectDirectoryIdentitySync(resolved);
+    const canonicalPath = path.resolve(realpathSync.native(resolved));
+    const after = inspectDirectoryIdentitySync(resolved, descriptor);
+    if (canonicalPath !== resolved || !sameDirectoryMetadata(descriptor, before) ||
+        !sameDirectoryMetadata(descriptor, after) ||
+        path.resolve(realpathSync.native(resolved)) !== canonicalPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+    const directory = Object.freeze({
+        path: resolved,
+        realPath: canonicalPath,
+        identity: Object.freeze({ dev: descriptor.dev, ino: descriptor.ino }),
+    });
+    return Object.freeze({
+        directory,
+        observation: checkedMutationDirectory(resolved, canonicalPath, after),
+        stat: after,
+    });
+}
+export function assertPolicyStagedDirectoryCurrent(captured) {
+    const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
+    if (!sameDirectoryMetadata(captured.stat, current) ||
+        path.resolve(realpathSync.native(captured.directory.path)) !== captured.directory.realPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+    return current;
+}
+export function refreshPolicyStagedDirectoryObservation(captured) {
+    const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
+    const canonicalPath = path.resolve(realpathSync.native(captured.directory.path));
+    if (canonicalPath !== captured.directory.realPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+    return checkedMutationDirectory(captured.directory.path, canonicalPath, current);
 }
 export function openStagedDirectory(directory) {
     // Copy supplied facts before any asynchronous work; receipts are not authority.
-    const pathname = path.resolve(typeof directory === "string" ? directory : directory.path);
+    const pathname = resolvePathPreservingWindowsRoot(typeof directory === "string" ? directory : directory.path);
     const expected = typeof directory === "string" ? undefined : {
         realPath: directory.realPath, dev: directory.identity.dev, ino: directory.identity.ino,
     };

package/dist/standalone-publication-path.d.ts

@@ -0,0 +1,2 @@
+export declare function admitStandalonePublicationPath(value: string, message?: string): string;
+//# sourceMappingURL=standalone-publication-path.d.ts.map

package/dist/standalone-publication-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone-publication-path.d.ts","sourceRoot":"","sources":["../src/standalone-publication-path.ts"],"names":[],"mappings":"AAKA,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAItF"}

package/dist/standalone-publication-path.js

@@ -0,0 +1,6 @@
+import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias, } from "./windows-path-alias.js";
+export function admitStandalonePublicationPath(value, message) {
+    const admittedPath = anchorWindowsDriveRelativePath(value);
+    assertNoWindowsPathAlias(admittedPath, "filesystem", message);
+    return admittedPath;
+}

package/dist/stat-observation.d.ts

@@ -0,0 +1,11 @@
+import type { BigIntStats, Stats } from "node:fs";
+export type ExactStatIdentity = Pick<BigIntStats, "dev" | "ino">;
+export type StatObservationReceipt = {
+    stat: Stats | BigIntStats;
+    identity: ExactStatIdentity;
+};
+/** Operation-local metadata plus exact identity; never use projected PathStat IDs. */
+export declare function inspectStatObservationSync(inspect: (bigint: boolean) => Stats | BigIntStats, expected?: ExactStatIdentity, initial?: Stats | BigIntStats, platform?: NodeJS.Platform): StatObservationReceipt;
+/** Revalidate an exact identity without allocating a receipt that the caller will discard. */
+export declare function assertStatObservationSync(inspect: (bigint: boolean) => Stats | BigIntStats, expected: ExactStatIdentity, initial?: Stats | BigIntStats, platform?: NodeJS.Platform): Stats | BigIntStats;
+//# sourceMappingURL=stat-observation.d.ts.map

package/dist/stat-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stat-observation.d.ts","sourceRoot":"","sources":["../src/stat-observation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAKlD,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AACjE,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,KAAK,GAAG,WAAW,CAAC;IAC1B,QAAQ,EAAE,iBAAiB,CAAC;CAC7B,CAAC;AAqEF,sFAAsF;AACtF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,GAAG,WAAW,EACjD,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,OAAO,CAAC,EAAE,KAAK,GAAG,WAAW,EAC7B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,sBAAsB,CAExB;AAED,8FAA8F;AAC9F,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,GAAG,WAAW,EACjD,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,CAAC,EAAE,KAAK,GAAG,WAAW,EAC7B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,KAAK,GAAG,WAAW,CAErB"}

package/dist/stat-observation.js

@@ -0,0 +1,64 @@
+import { FsSafeError } from "./errors.js";
+import { recordFileObservationFailure } from "./file-observation.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+function identityMismatch() {
+    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+    recordFileObservationFailure(error, "identity");
+    throw error;
+}
+function safeNumber(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function safeExpected(identity) {
+    return typeof identity.dev === "bigint" && typeof identity.ino === "bigint" &&
+        identity.dev >= 0n && identity.ino >= 0n &&
+        identity.dev <= 9007199254740991n && identity.ino <= 9007199254740991n;
+}
+function observeStatSync(inspect, expected, initial, platform = process.platform, captureIdentity) {
+    if (platform === "win32" || (!initial && expected && !safeExpected(expected))) {
+        // Preserve the strict Windows unknown-ID retry, including known components
+        // and validation of the expected identity before the first observation.
+        const stat = inspectFileIdentitySync(() => {
+            const current = initial;
+            initial = undefined;
+            return (current ?? inspect(true));
+        }, expected, platform);
+        return (captureIdentity
+            ? { stat, identity: expected ?? { dev: stat.dev, ino: stat.ino } }
+            : stat);
+    }
+    const stat = initial ?? inspect(false);
+    const { dev: rawDev, ino: rawIno } = stat;
+    const numericDev = safeNumber(rawDev);
+    const numericIno = safeNumber(rawIno);
+    const dev = numericDev ? BigInt(rawDev) : typeof rawDev === "bigint" ? rawDev : undefined;
+    const ino = numericIno ? BigInt(rawIno) : typeof rawIno === "bigint" ? rawIno : undefined;
+    if (expected && ((dev !== undefined && dev !== expected.dev) ||
+        (ino !== undefined && ino !== expected.ino)))
+        identityMismatch();
+    if (numericDev && numericIno) {
+        return (captureIdentity
+            ? { stat, identity: expected ?? { dev: dev, ino: ino } }
+            : stat);
+    }
+    // An unsafe numeric component is unknown, not a rounded identity. Retain
+    // every exact component from this observation while obtaining the full ID.
+    const exact = inspectFileIdentitySync(() => {
+        const current = inspect(true);
+        if ((dev !== undefined && current.dev !== dev) ||
+            (ino !== undefined && current.ino !== ino))
+            identityMismatch();
+        return current;
+    }, expected, platform);
+    return (captureIdentity
+        ? { stat: exact, identity: expected ?? { dev: exact.dev, ino: exact.ino } }
+        : exact);
+}
+/** Operation-local metadata plus exact identity; never use projected PathStat IDs. */
+export function inspectStatObservationSync(inspect, expected, initial, platform = process.platform) {
+    return observeStatSync(inspect, expected, initial, platform, true);
+}
+/** Revalidate an exact identity without allocating a receipt that the caller will discard. */
+export function assertStatObservationSync(inspect, expected, initial, platform = process.platform) {
+    return observeStatSync(inspect, expected, initial, platform, false);
+}

package/dist/strict-file-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA+B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7B,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAOH"}
+{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA+B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7B,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAmCH"}

package/dist/strict-file-identity.js

@@ -41,10 +41,47 @@ export async function inspectFileIdentity(inspect, expected, platform = process.
     throw identityMismatch();
 }
 export function inspectFileIdentitySync(inspect, expected, platform = process.platform) {
-    const check = identityCheck(expected, platform);
+    let knownDev;
+    let knownIno;
+    if (expected) {
+        knownDev = expected.dev;
+        if (typeof knownDev !== "bigint")
+            throw identityMismatch();
+        knownIno = expected.ino;
+        if (typeof knownIno !== "bigint")
+            throw identityMismatch();
+        // An unknown expected device must not bypass observation of its inode.
+        if (platform === "win32" && (knownDev === 0n || knownIno === 0n))
+            throw identityMismatch();
+    }
     for (let attempt = 0; attempt < 2; attempt++) {
         const stat = inspect();
-        if (check(stat))
+        let complete = true;
+        // Keep dev-before-ino access and early mismatch errors without allocating
+        // a checker closure, known-component object, or field array per inspection.
+        const dev = stat.dev;
+        if (typeof dev !== "bigint")
+            throw identityMismatch();
+        if (platform === "win32" && dev === 0n) {
+            complete = false;
+        }
+        else {
+            if (knownDev !== undefined && knownDev !== dev)
+                throw identityMismatch();
+            knownDev = dev;
+        }
+        const ino = stat.ino;
+        if (typeof ino !== "bigint")
+            throw identityMismatch();
+        if (platform === "win32" && ino === 0n) {
+            complete = false;
+        }
+        else {
+            if (knownIno !== undefined && knownIno !== ino)
+                throw identityMismatch();
+            knownIno = ino;
+        }
+        if (complete)
             return stat;
     }
     throw identityMismatch();

package/dist/symlink-parents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAyBF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA6BN"}
+{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAqCF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA6BN"}

package/dist/symlink-parents.js

@@ -2,9 +2,14 @@ import fsSync from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { hasNodeErrorCode, isPathRelativeEscape } from "./path.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 function resolvePathWalk(params) {
-    const root = path.resolve(params.rootDir);
-    const target = path.resolve(params.targetPath);
+    const rawRootDir = params.rootDir;
+    assertNoWindowsPathAlias(rawRootDir, "filesystem", "root dir uses a Windows filesystem namespace alias");
+    const rawTargetPath = params.targetPath;
+    assertNoWindowsPathAlias(rawTargetPath, "filesystem", "target path uses a Windows filesystem namespace alias");
+    const root = resolvePathPreservingWindowsRoot(rawRootDir);
+    const target = resolvePathPreservingWindowsRoot(rawTargetPath);
     const relative = path.relative(root, target);
     if (isPathRelativeEscape(relative)) {
         if (params.allowOutsideRoot) {

package/dist/temp-target.d.ts

@@ -1,4 +1,5 @@
 import fsSync from "node:fs";
+import type { TempWorkspaceCleanupSafety } from "./temp-workspace-owner.js";
 export type TempFile = {
     dir: string;
     path: string;
@@ -11,6 +12,7 @@ type TempFileOptions = {
     prefix: string;
     fileName?: string;
     onCleanupError?: (error: unknown) => void;
+    cleanupSafety?: TempWorkspaceCleanupSafety;
 };
 export declare function sanitizeTempFileName(fileName: string): string;
 export declare function buildRandomTempFilePath(params: {

package/dist/temp-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,SAAS,CAAC;AAS7B,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyCD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC;IAC1E,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;CAC7D,CAAC,CA2BD;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEzE;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,SAAS,CAAC;AAa7B,OAAO,KAAK,EAEV,0BAA0B,EAC3B,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C,aAAa,CAAC,EAAE,0BAA0B,CAAC;CAC5C,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAeT;AAwDD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC;IAC1E,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;CAC7D,CAAC,CAmID;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEzE;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -7,6 +7,7 @@ import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { assertSafePathSegment, sanitizeSafePathSegment, trimHyphenEdges } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 const HYPHEN_CHAR_CODE = 0x2d;
 const DOT_CHAR_CODE = 0x2e;
 const NUMBER_ZERO_CHAR_CODE = 0x30;
@@ -74,7 +75,9 @@ export function buildRandomTempFilePath(params) {
     const uuid = params.uuid
         ? assertSafePathSegment(params.uuid.trim(), { label: "temp uuid" })
         : crypto.randomUUID();
-    return path.join(rootDir, `${prefix}-${now}-${uuid}${extension}`);
+    const filePath = path.join(rootDir, `${prefix}-${now}-${uuid}${extension}`);
+    assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+    return filePath;
 }
 function isNodeErrorWithCode(err, code) {
     return (typeof err === "object" &&
@@ -106,17 +109,141 @@ async function cleanupTempDir(dir, identity, onCleanupError) {
     }
 }
 function resolveTempRoot(rootDir) {
-    return path.resolve(rootDir ?? resolveSecureTempRoot({ fallbackPrefix: "fs-safe" }));
+    if (rootDir !== undefined) {
+        assertNoWindowsPathAlias(rootDir, "filesystem", "temp root uses a Windows filesystem namespace alias");
+    }
+    const selectedRoot = rootDir ?? resolveSecureTempRoot({ fallbackPrefix: "fs-safe" });
+    assertNoWindowsPathAlias(selectedRoot, "filesystem", "temp root uses a Windows filesystem namespace alias");
+    const resolvedRoot = resolvePathPreservingWindowsRoot(selectedRoot);
+    assertNoWindowsPathAlias(resolvedRoot, "filesystem", "temp root uses a Windows filesystem namespace alias");
+    return resolvedRoot;
+}
+function resolveTempFileCleanupSafety(value) {
+    if (value === undefined || value === "compatible")
+        return "compatible";
+    if (value === "require-bounded")
+        return value;
+    throw new TypeError("cleanupSafety must be compatible or require-bounded");
 }
 export async function createOwnedTempFile(params) {
+    const cleanupSafety = resolveTempFileCleanupSafety(params.cleanupSafety);
     const rootDir = resolveTempRoot(params.rootDir);
     const prefix = `${sanitizePrefix(params.prefix)}-`;
+    if (cleanupSafety === "require-bounded") {
+        const initialFileName = sanitizeTempFileName(params.fileName ?? "download.bin");
+        const [{ TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner }, { admitExistingTempWorkspaceRoot }, { TempWorkspaceRetainedChild }, { validateInitialTempWorkspaceChild, admitRetainedTempWorkspaceChild }, { inspectDirectoryIdentitySync },] = await Promise.all([
+            import("./temp-workspace-owner.js"),
+            import("./temp-workspace-admission.js"),
+            import("./temp-workspace-descriptor.js"),
+            import("./temp-workspace-child-admission.js"),
+            import("./directory-guard.js"),
+        ]);
+        const admission = admitExistingTempWorkspaceRoot(rootDir);
+        const childPrefix = path.join(admission.dir, prefix);
+        assertNoWindowsPathAlias(childPrefix, "filesystem", "temp directory uses a Windows filesystem namespace alias");
+        const capability = new TempWorkspaceCleanupCapability(admission.dir, cleanupSafety, admission, 0o700);
+        let dir;
+        let initialPath;
+        let identity;
+        let retainedChild;
+        let cleanupOwner;
+        let unregisterTempDir;
+        try {
+            capability.prepareChildCreation();
+            dir = await fs.mkdtemp(childPrefix);
+            assertNoWindowsPathAlias(dir, "filesystem", "temp directory uses a Windows filesystem namespace alias");
+            initialPath = path.join(dir, initialFileName);
+            assertNoWindowsPathAlias(initialPath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+            capability.assertCurrent();
+            const initial = inspectDirectoryIdentitySync(dir);
+            identity = Object.freeze({ dev: initial.dev, ino: initial.ino });
+            const needsModeInitialization = validateInitialTempWorkspaceChild(initial, admission.ownerUid, 0o700);
+            retainedChild = TempWorkspaceRetainedChild.retain(dir, identity);
+            const modeInitialization = admitRetainedTempWorkspaceChild(retainedChild, needsModeInitialization, admission, 0o700);
+            if (modeInitialization)
+                await modeInitialization;
+            const retainDescriptor = capability.admitChildDescriptor(retainedChild.ensureReadable());
+            capability.assertAncestryCurrent();
+            retainedChild.finalizeAdmission(admission.ownerUid, 0o700);
+            cleanupOwner = new TempWorkspaceCleanupOwner(retainedChild, capability, retainDescriptor);
+            retainedChild = undefined;
+            unregisterTempDir = registerTempPathForExit(dir, {
+                cleanupSync: () => cleanupOwner.cleanupSync(),
+            });
+        }
+        catch (error) {
+            try {
+                if (cleanupOwner)
+                    cleanupOwner.cleanupSync();
+                else {
+                    const closeErrors = [];
+                    try {
+                        retainedChild?.close();
+                    }
+                    catch (closeError) {
+                        closeErrors.push(closeError);
+                    }
+                    try {
+                        capability.close();
+                    }
+                    catch (closeError) {
+                        closeErrors.push(closeError);
+                    }
+                    if (closeErrors.length === 1)
+                        throw closeErrors[0];
+                    if (closeErrors.length > 1) {
+                        throw new AggregateError(closeErrors, "temp file admission descriptor close failed");
+                    }
+                }
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], "temp file creation and cleanup both failed");
+            }
+            throw error;
+        }
+        const owner = cleanupOwner;
+        const file = (fileName) => {
+            const filePath = path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
+            assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+            return filePath;
+        };
+        const cleanup = async () => {
+            try {
+                try {
+                    await owner.cleanup();
+                }
+                catch (err) {
+                    if (!isNodeErrorWithCode(err, "ENOENT")) {
+                        params.onCleanupError?.(err);
+                    }
+                }
+            }
+            finally {
+                unregisterTempDir();
+            }
+        };
+        return {
+            target: {
+                dir,
+                path: initialPath,
+                file,
+                cleanup,
+                [Symbol.asyncDispose]: cleanup,
+            },
+            identity,
+        };
+    }
     const dir = await fs.mkdtemp(path.join(rootDir, prefix));
+    assertNoWindowsPathAlias(dir, "filesystem", "temp directory uses a Windows filesystem namespace alias");
     // Windows file indexes can exceed Number.MAX_SAFE_INTEGER. Cleanup receipts
     // must retain the exact identity or adjacent directories can compare equal.
     const identity = fsSync.lstatSync(dir, { bigint: true });
     const unregisterTempDir = registerTempPathForExit(dir, { recursive: true, identity });
-    const file = (fileName) => path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
+    const file = (fileName) => {
+        const filePath = path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
+        assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+        return filePath;
+    };
     const cleanup = async () => {
         try {
             await cleanupTempDir(dir, identity, params.onCleanupError);