@openclaw/fs-safe 0.6.0 → 0.7.1

package/dist/sidecar-lock-acquire.js

@@ -1,9 +1,12 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { readFileHandleBounded } from "./bounded-read.js";
+import { openSidecarRoot } from "./sidecar-lock-root.js";
 import { createNativeExclusiveFile } from "./native-operations.js";
-import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, } from "./sidecar-lock-policy.js";
-import { readSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
+import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
+import { readSidecarLockRawSnapshot, parseSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
+import { createSuppressedError } from "./suppressed-error.js";
 async function resolveNormalizedTargetPath(targetPath) {
     const resolved = path.resolve(targetPath);
     const dir = path.dirname(resolved);
@@ -16,19 +19,34 @@ async function resolveNormalizedTargetPath(targetPath) {
     }
 }
 export async function acquireSidecarLock(options, context) {
+    const retry = options.retry ?? {};
+    validateSidecarLockRetryOptions(retry);
+    validateSidecarLockTimeoutMs(options.timeoutMs);
     context.ensureExitCleanupRegistered();
     const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath);
     const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
-    const held = context.held.get(normalizedTargetPath);
+    let held = context.held.get(normalizedTargetPath);
     if (held &&
         options.reentrantOwner !== undefined &&
         held.reentrantOwner !== undefined &&
         options.reentrantOwner === held.reentrantOwner) {
-        held.refCount += 1;
-        return context.handleForHeldLock(normalizedTargetPath, held);
+        // A final release may already have decremented the count to zero and be
+        // removing the sidecar. Do not admit a new reentrant handle until that
+        // cleanup settles: successful cleanup requires a fresh acquisition, while
+        // failed cleanup leaves the existing sidecar held for a retry.
+        if (held.releasePromise) {
+            await held.releasePromise.catch(() => undefined);
+            held = context.held.get(normalizedTargetPath);
+        }
+        if (held &&
+            options.reentrantOwner !== undefined &&
+            held.reentrantOwner !== undefined &&
+            options.reentrantOwner === held.reentrantOwner) {
+            held.refCount += 1;
+            return context.handleForHeldLock(normalizedTargetPath, held);
+        }
     }
     const startedAt = Date.now();
-    const retry = options.retry ?? {};
     const maxRetries = options.timeoutMs === Number.POSITIVE_INFINITY ? undefined : retry.retries;
     const reclaimGuardPath = `${lockPath}.reclaim`;
     let ownsReclaimGuard = false;
@@ -77,13 +95,14 @@ export async function acquireSidecarLock(options, context) {
             let handle = null;
             let createdSnapshot = null;
             let lockFileCreateDenied = false;
+            const payload = await options.payload();
+            const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
             try {
-                const payload = await options.payload();
-                const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
                 if (options.lockRoot) {
-                    const relativeLockPath = relativeSidecarLockPath(options.lockRoot, lockPath);
+                    const lockRoot = options.lockRoot;
+                    const relativeLockPath = relativeSidecarLockPath(lockRoot, lockPath);
                     try {
-                        await options.lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 });
+                        await lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 });
                     }
                     catch (error) {
                         if (error instanceof FsSafeError && error.code === "already-exists") {
@@ -92,7 +111,23 @@ export async function acquireSidecarLock(options, context) {
                         throw error;
                     }
                     createdSnapshot = { raw, payload, ownershipToken };
-                    handle = (await options.lockRoot.open(relativeLockPath)).handle;
+                    const opened = await openSidecarRoot(lockRoot, relativeLockPath, "unlinked");
+                    if (!opened) {
+                        await waitForRetry();
+                        continue;
+                    }
+                    try {
+                        // Root.open admits the current file, not necessarily the one we created.
+                        const currentRaw = await readFileHandleBounded(opened.handle, Buffer.byteLength(raw));
+                        if (!currentRaw.equals(Buffer.from(raw))) {
+                            throw new FsSafeError("path-mismatch", "created sidecar lock changed before admission");
+                        }
+                    }
+                    catch (error) {
+                        await opened.handle.close().catch(() => undefined);
+                        throw error;
+                    }
+                    handle = opened.handle;
                 }
                 else {
                     try {
@@ -107,6 +142,12 @@ export async function acquireSidecarLock(options, context) {
                     await handle.writeFile(raw, "utf8");
                 }
                 const snapshot = { raw, payload, stat: await handle.stat(), ownershipToken };
+                if (snapshot.stat.nlink === 0) {
+                    await handle.close();
+                    handle = null;
+                    await waitForRetry();
+                    continue;
+                }
                 const createdHeld = {
                     refCount: 1,
                     reentrantOwner: options.reentrantOwner,
@@ -149,31 +190,36 @@ export async function acquireSidecarLock(options, context) {
                 return returnedHandle;
             }
             catch (err) {
-                if (handle) {
-                    const failedSnapshot = { payload: null };
-                    try {
-                        failedSnapshot.stat = await handle.stat();
-                    }
-                    catch {
-                        // Best-effort cleanup of a failed exclusive create.
+                try {
+                    if (handle) {
+                        const failedSnapshot = createdSnapshot ?? { payload: null };
+                        try {
+                            failedSnapshot.stat = await handle.stat();
+                        }
+                        catch {
+                            // Best-effort cleanup of a failed exclusive create.
+                        }
+                        const current = context.held.get(normalizedTargetPath);
+                        if (current?.handle === handle) {
+                            context.held.delete(normalizedTargetPath);
+                        }
+                        await handle.close().catch(() => undefined);
+                        // 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,
+                            parsePayload: options.parsePayload,
+                        });
                     }
-                    const current = context.held.get(normalizedTargetPath);
-                    if (current?.handle === handle) {
-                        context.held.delete(normalizedTargetPath);
+                    else if (createdSnapshot) {
+                        await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        });
                     }
-                    await handle.close().catch(() => undefined);
-                    // The file may be empty or partial JSON, so remove by the identity
-                    // captured from our exclusive handle rather than by pathname alone.
-                    await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    });
                 }
-                else if (createdSnapshot) {
-                    await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    });
+                catch (cleanupError) {
+                    throw createSuppressedError(cleanupError, err, "file lock acquisition and cleanup both failed");
                 }
                 if (lockFileCreateDenied && withinDenialBudget()) {
                     await retryOrRethrowDenial(err);
@@ -185,24 +231,29 @@ export async function acquireSidecarLock(options, context) {
                 if (ownsReclaimGuard) {
                     await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
                     ownsReclaimGuard = false;
+                    await waitForRetry();
                     continue;
                 }
                 const nowMs = Date.now();
-                let snapshot;
+                let rawSnapshot;
+                let lockFileOpenDenied = false;
                 try {
-                    snapshot = await readSidecarLockSnapshot(lockPath, {
+                    rawSnapshot = await readSidecarLockRawSnapshot(lockPath, {
                         lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
                         rejectNonFile: true,
+                        discardObservation: "changed",
+                        onOpenFailure: (error) => { lockFileOpenDenied = isTransientLockFileDenial(error, lockPath); },
                     });
                 }
                 catch (readErr) {
-                    if (!isTransientLockFileDenial(readErr, lockPath) || !withinDenialBudget())
+                    if (!lockFileOpenDenied || !withinDenialBudget())
                         throw readErr;
                     await retryOrRethrowDenial(readErr);
                     continue;
                 }
+                const snapshot = parseSidecarLockSnapshot(rawSnapshot, options.parsePayload);
                 if (!snapshot) {
+                    await waitForRetry();
                     continue;
                 }
                 if (context.held.has(normalizedTargetPath)) {
@@ -222,6 +273,7 @@ export async function acquireSidecarLock(options, context) {
                         lockRoot: options.lockRoot,
                         parsePayload: options.parsePayload,
                     }))) {
+                        await waitForRetry();
                         continue;
                     }
                     const staleRecovery = options.staleRecovery ?? "fail-closed";
@@ -240,6 +292,8 @@ export async function acquireSidecarLock(options, context) {
                             parsePayload: options.parsePayload,
                         });
                         if (removal === "removed" || removal === "changed") {
+                            if (removal === "changed")
+                                await waitForRetry();
                             continue;
                         }
                         await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);

package/dist/sidecar-lock-handle.d.ts

@@ -5,7 +5,9 @@ export declare function createSidecarLockHandle(params: {
     lockPath: string;
     normalizedTargetPath: string;
     verifyStillHeld: () => Promise<boolean>;
-    release: () => Promise<unknown>;
+    release: (options?: {
+        retry?: boolean;
+    }) => Promise<unknown>;
 }): SidecarLockHandle;
 export declare function createHeldSidecarLockHandle(params: {
     normalizedTargetPath: string;
@@ -15,6 +17,8 @@ export declare function createHeldSidecarLockHandle(params: {
         lockRoot?: Root;
         parsePayload?: (raw: string) => unknown;
     };
-    release: () => Promise<unknown>;
+    release: (options?: {
+        retry?: boolean;
+    }) => Promise<unknown>;
 }): SidecarLockHandle;
 //# sourceMappingURL=sidecar-lock-handle.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-handle.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC,GAAG,iBAAiB,CAcpB;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,QAAQ,CAAC,EAAE,IAAI,CAAC;QAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;KACzC,CAAC;IACF,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC,GAAG,iBAAiB,CAWpB"}
+{"version":3,"file":"sidecar-lock-handle.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D,GAAG,iBAAiB,CA2BpB;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,QAAQ,CAAC,EAAE,IAAI,CAAC;QAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;KACzC,CAAC;IACF,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D,GAAG,iBAAiB,CAWpB"}

package/dist/sidecar-lock-handle.js

@@ -1,11 +1,25 @@
 import { sidecarLockSnapshotStillPresent, } from "./sidecar-lock-reclaim.js";
 export function createSidecarLockHandle(params) {
     let released = false;
+    let releasePromise;
+    let releaseStarted = false;
     const release = async () => {
         if (released)
             return;
-        released = true;
-        await params.release();
+        if (!releasePromise) {
+            const retry = releaseStarted;
+            releaseStarted = true;
+            releasePromise = (async () => {
+                await params.release({ retry });
+                released = true;
+            })();
+        }
+        try {
+            await releasePromise;
+        }
+        finally {
+            releasePromise = undefined;
+        }
     };
     return {
         lockPath: params.lockPath,
@@ -23,6 +37,6 @@ export function createHeldSidecarLockHandle(params) {
             lockRoot: params.held.lockRoot,
             parsePayload: params.held.parsePayload,
         }),
-        release: params.release,
+        release: (options) => params.release(options),
     });
 }

package/dist/sidecar-lock-policy.d.ts

@@ -1,4 +1,6 @@
 import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
+export declare function validateSidecarLockRetryOptions(retry: SidecarLockRetryOptions): void;
+export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefined): void;
 export declare function computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAGT;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}
+{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAQvE,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAkBpF;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGhF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAGT;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}

package/dist/sidecar-lock-policy.js

@@ -1,5 +1,34 @@
 import fs from "node:fs/promises";
+function assertFiniteNonNegative(value, label) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${label} must be a finite non-negative number`);
+    }
+}
+export function validateSidecarLockRetryOptions(retry) {
+    if (retry.retries !== undefined && (!Number.isSafeInteger(retry.retries) || retry.retries < 0)) {
+        throw new RangeError("lock retry.retries must be a non-negative safe integer");
+    }
+    if (retry.factor !== undefined)
+        assertFiniteNonNegative(retry.factor, "lock retry.factor");
+    if (retry.minTimeout !== undefined) {
+        assertFiniteNonNegative(retry.minTimeout, "lock retry.minTimeout");
+    }
+    if (retry.maxTimeout !== undefined) {
+        assertFiniteNonNegative(retry.maxTimeout, "lock retry.maxTimeout");
+    }
+    if (retry.minTimeout !== undefined &&
+        retry.maxTimeout !== undefined &&
+        retry.minTimeout > retry.maxTimeout) {
+        throw new RangeError("lock retry.minTimeout must not exceed retry.maxTimeout");
+    }
+}
+export function validateSidecarLockTimeoutMs(timeoutMs) {
+    if (timeoutMs === undefined || timeoutMs === Number.POSITIVE_INFINITY)
+        return;
+    assertFiniteNonNegative(timeoutMs, "lock timeoutMs");
+}
 export function computeSidecarLockDelayMs(retry, attempt) {
+    validateSidecarLockRetryOptions(retry);
     const minTimeout = retry.minTimeout ?? 50;
     const maxTimeout = retry.maxTimeout ?? 1000;
     const factor = retry.factor ?? 1;

package/dist/sidecar-lock-reclaim.d.ts

@@ -12,6 +12,10 @@ export type SidecarLockSnapshot = {
     stat?: Stats;
     ownershipToken?: string;
 };
+type SidecarLockRawSnapshot = Omit<SidecarLockSnapshot, "payload"> & {
+    raw: string;
+};
+export declare function parseSidecarLockSnapshot(snapshot: SidecarLockRawSnapshot | null, parser?: (raw: string) => unknown): SidecarLockSnapshot | null;
 export declare function readSidecarLockOwnershipToken(raw: string): string | undefined;
 export declare function serializeSidecarLockPayload(payload: Record<string, unknown>): {
     raw: string;
@@ -19,15 +23,21 @@ export declare function serializeSidecarLockPayload(payload: Record<string, unkn
 };
 export declare function relativeSidecarLockPath(lockRoot: Root, lockPath: string): string;
 export declare function parseSidecarLockPayload(raw: string, parser?: (raw: string) => unknown): unknown;
-export declare function readSidecarLockSnapshot(lockPath: string, options?: {
-    lockRoot?: Root;
+export declare function readSidecarLockSnapshot(lockPath: string, options?: Parameters<typeof readSidecarLockRawSnapshot>[1] & {
     parsePayload?: (raw: string) => unknown;
+}): Promise<SidecarLockSnapshot | null>;
+export declare function readSidecarLockRawSnapshot(lockPath: string, options?: {
+    lockRoot?: Root;
     rejectNonFile?: boolean;
     allowDescriptorIdentityDrift?: boolean;
-}): Promise<SidecarLockSnapshot | null>;
-export declare function readSidecarLockSnapshotSync(lockPath: string, parsePayload?: (raw: string) => unknown, options?: {
+    discardObservation?: "unlinked" | "changed";
+    onOpenFailure?: (error: unknown) => void;
+}): Promise<SidecarLockRawSnapshot | null>;
+export declare function readSidecarLockSnapshotSync(lockPath: string, parsePayload?: (raw: string) => unknown, options?: Parameters<typeof readSidecarLockRawSnapshotSync>[1]): SidecarLockSnapshot | null;
+export declare function readSidecarLockRawSnapshotSync(lockPath: string, options?: {
     rejectNonFile?: boolean;
-}): SidecarLockSnapshot | null;
+    onOpenFailure?: (error: unknown) => void;
+}): SidecarLockRawSnapshot | null;
 export declare function removeSidecarLockIfUnchangedSync(lockPath: string, observed: SidecarLockSnapshot): boolean;
 export declare function sidecarLockSnapshotMatches(current: SidecarLockSnapshot, observed: SidecarLockSnapshot): boolean;
 export declare function removeSidecarLockIfUnchanged(lockPath: string, observed: SidecarLockSnapshot | null, options?: {
@@ -49,4 +59,5 @@ export declare function removeStaleSidecarLockIfAllowed(params: {
     lockRoot?: Root;
     parsePayload?: (raw: string) => unknown;
 }): Promise<"removed" | "changed" | "not-approved">;
+export {};
 //# sourceMappingURL=sidecar-lock-reclaim.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-reclaim.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-reclaim.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sidecar-lock-reclaim.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-reclaim.ts"],"names":[],"mappings":"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"}

package/dist/sidecar-lock-reclaim.js

@@ -5,12 +5,17 @@ import path from "node:path";
 import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { openSidecarRoot } from "./sidecar-lock-root.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const MAX_LOCK_PAYLOAD_BYTES = 1024 * 1024;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES = 16;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_BITS = SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES * 8;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX = "\t".repeat(8);
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_PATTERN = new RegExp(`\\n(${SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX}[ \\t]{${SIDECAR_LOCK_OWNERSHIP_TOKEN_BITS}})\\n$`);
+export function parseSidecarLockSnapshot(snapshot, parser) {
+    return snapshot && { ...snapshot, payload: parseSidecarLockPayload(snapshot.raw, parser) };
+}
 function createSidecarLockOwnershipToken() {
     let token = SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX;
     for (const byte of randomBytes(SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES)) {
@@ -55,16 +60,27 @@ export function parseSidecarLockPayload(raw, parser) {
         return null;
     }
 }
+function missingSnapshotPath(error) {
+    if (error.code === "ENOENT")
+        return null;
+    throw error;
+}
 export async function readSidecarLockSnapshot(lockPath, options = {}) {
+    return parseSidecarLockSnapshot(await readSidecarLockRawSnapshot(lockPath, options), options.parsePayload);
+}
+export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
     let handle;
     try {
         if (options.lockRoot) {
-            const opened = await options.lockRoot.open(relativeSidecarLockPath(options.lockRoot, lockPath));
+            const lockRoot = options.lockRoot;
+            const relative = relativeSidecarLockPath(lockRoot, lockPath);
+            const opened = await openSidecarRoot(lockRoot, relative, options.discardObservation, options.onOpenFailure);
+            if (!opened)
+                return null;
             try {
                 const raw = (await readFileHandleBounded(opened.handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
                 return {
                     raw,
-                    payload: parseSidecarLockPayload(raw, options.parsePayload),
                     stat: opened.stat,
                 };
             }
@@ -72,7 +88,9 @@ export async function readSidecarLockSnapshot(lockPath, options = {}) {
                 await opened.handle.close().catch(() => undefined);
             }
         }
-        const before = await fs.lstat(lockPath);
+        const before = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        if (!before)
+            return null;
         if (!before.isFile() || before.isSymbolicLink()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
@@ -89,11 +107,14 @@ export async function readSidecarLockSnapshot(lockPath, options = {}) {
                 (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0));
         }
         catch (error) {
+            if (error.code === "ENOENT")
+                return null;
             if (options.rejectNonFile && error.code === "ELOOP") {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`, {
                     cause: error,
                 });
             }
+            options.onOpenFailure?.(error);
             throw error;
         }
         const opened = await handle.stat();
@@ -106,53 +127,64 @@ export async function readSidecarLockSnapshot(lockPath, options = {}) {
         if (!options.allowDescriptorIdentityDrift && !sameFileIdentity(before, opened))
             return null;
         const raw = (await readFileHandleBounded(handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
-        const after = await fs.lstat(lockPath);
-        if (!after.isFile() || !sameFileIdentity(before, after))
+        const after = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        if (!after || !after.isFile() || !sameFileIdentity(before, after))
             return null;
-        return { raw, payload: parseSidecarLockPayload(raw, options.parsePayload), stat: after };
-    }
-    catch (err) {
-        if (err.code === "ENOENT" ||
-            (err instanceof FsSafeError && err.code === "not-found")) {
-            return null;
-        }
-        throw err;
+        return { raw, stat: after };
     }
     finally {
         await handle?.close().catch(() => undefined);
     }
 }
+function lstatSidecarLockSync(lockPath) {
+    try {
+        return fsSync.lstatSync(lockPath);
+    }
+    catch (error) {
+        return missingSnapshotPath(error);
+    }
+}
 export function readSidecarLockSnapshotSync(lockPath, parsePayload, options = {}) {
+    return parseSidecarLockSnapshot(readSidecarLockRawSnapshotSync(lockPath, options), parsePayload);
+}
+export function readSidecarLockRawSnapshotSync(lockPath, options = {}) {
     let fd;
     try {
-        const before = fsSync.lstatSync(lockPath);
+        const before = lstatSidecarLockSync(lockPath);
+        if (!before)
+            return null;
         if (!before.isFile() || before.isSymbolicLink()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
             }
             return null;
         }
-        const noFollow = process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
-            ? fsSync.constants.O_NOFOLLOW
-            : 0;
-        fd = fsSync.openSync(lockPath, fsSync.constants.O_RDONLY | noFollow);
+        try {
+            fd = fsSync.openSync(lockPath, resolveReadOpenFlags());
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            options.onOpenFailure?.(error);
+            throw error;
+        }
         const opened = fsSync.fstatSync(fd);
+        if (!opened.isFile()) {
+            if (options.rejectNonFile) {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
+            }
+            return null;
+        }
         const raw = readFileDescriptorBoundedSync(fd, MAX_LOCK_PAYLOAD_BYTES).toString("utf8");
-        const after = fsSync.lstatSync(lockPath);
-        if (!sameFileIdentity(before, opened) || !sameFileIdentity(opened, after))
+        const after = lstatSidecarLockSync(lockPath);
+        if (!after || !sameFileIdentity(before, opened) || !sameFileIdentity(opened, after))
             return null;
         return {
             raw,
-            payload: parseSidecarLockPayload(raw, parsePayload),
             stat: after,
             ownershipToken: readSidecarLockOwnershipToken(raw),
         };
     }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return null;
-        throw error;
-    }
     finally {
         if (fd !== undefined)
             fsSync.closeSync(fd);
@@ -191,10 +223,10 @@ export async function removeSidecarLockIfUnchanged(lockPath, observed, options =
         return false;
     }
     if (options.lockRoot) {
-        await options.lockRoot.remove(relativeSidecarLockPath(options.lockRoot, lockPath)).catch(() => undefined);
+        await options.lockRoot.remove(relativeSidecarLockPath(options.lockRoot, lockPath));
     }
     else {
-        await fs.rm(lockPath, { force: true }).catch(() => undefined);
+        await fs.rm(lockPath, { force: true });
     }
     return true;
 }

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

@@ -0,0 +1,3 @@
+import type { OpenResult, Root } from "./root-impl.js";
+export declare function openSidecarRoot(lockRoot: Root, relative: string, discardObservation?: "unlinked" | "changed", onOpenFailure?: (error: unknown) => void): Promise<OpenResult | null>;
+//# sourceMappingURL=sidecar-lock-root.d.ts.map

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

@@ -0,0 +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"}

package/dist/sidecar-lock-root.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { inspectDirectoryIdentity } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { fileObservation } from "./file-observation.js";
+import { isNotFoundPathError } from "./path.js";
+import { resolveRootPath } from "./root-path.js";
+export async function openSidecarRoot(lockRoot, relative, discardObservation, onOpenFailure) {
+    const resolved = await lockRoot.resolve(relative);
+    const canonicalPath = async () => (await resolveRootPath({
+        absolutePath: resolved,
+        rootPath: lockRoot.rootReal,
+        rootCanonicalPath: lockRoot.rootReal,
+        boundaryLabel: "sidecar lock root",
+    })).canonicalPath;
+    const expectedRealPath = await canonicalPath();
+    if (expectedRealPath === lockRoot.rootReal)
+        throw new FsSafeError("not-file", "sidecar lock is a directory");
+    const parents = [];
+    let completeParents = true;
+    if (discardObservation) {
+        // Follow permitted in-root aliases first; receipts cover canonical ancestry.
+        for (let dir = path.dirname(expectedRealPath);; dir = path.dirname(dir)) {
+            try {
+                parents.push({ dir, stat: await inspectDirectoryIdentity(dir) });
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error))
+                    throw error;
+                completeParents = false;
+            }
+            if (dir === lockRoot.rootReal)
+                break;
+        }
+    }
+    const observation = fileObservation();
+    try {
+        const opened = await observation.run(() => lockRoot.open(relative));
+        if (opened.realPath !== expectedRealPath) {
+            await opened.handle.close().catch(() => undefined);
+            throw new FsSafeError("path-mismatch", "sidecar lock path changed during open");
+        }
+        return opened;
+    }
+    catch (error) {
+        const openFailed = observation.has(error, `open:${resolved}`);
+        if (openFailed)
+            onOpenFailure?.(error);
+        const missing = openFailed && error instanceof FsSafeError && error.code === "not-found";
+        if (missing && !discardObservation)
+            return null;
+        const discardable = observation.has(error, `unlinked:${resolved}`) ||
+            (discardObservation === "changed" && observation.has(error, `changed:${resolved}`));
+        if (!discardObservation || (!missing && (!completeParents || !discardable)))
+            throw error;
+        try {
+            try {
+                const current = await lockRoot.stat(relative);
+                if (!current.isFile || current.isSymbolicLink || current.nlink !== 1)
+                    throw error;
+            }
+            catch (probeError) {
+                if (!(probeError instanceof FsSafeError && probeError.code === "not-found"))
+                    throw probeError;
+            }
+            for (const { dir, stat } of parents)
+                await inspectDirectoryIdentity(dir, stat);
+            await lockRoot.resolve(relative);
+            if (await canonicalPath() === expectedRealPath)
+                return null;
+        }
+        catch {
+            // Keep the original failure when directory or confinement proof fails.
+        }
+        throw error;
+    }
+}