@openclaw/fs-safe 0.18.1 → 0.19.0

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

@@ -1,6 +1,6 @@
 import syncFs, { type BigIntStats } from "node:fs";
 import fs, { type FileHandle } from "node:fs/promises";
-import { type DirectoryModeOwner } from "./directory-mode-owner.js";
+import { type DirectoryModeOwner } from "./directory-mode-node.js";
 type AsyncTempFileSystem = Pick<typeof fs, "lstat" | "open" | "writeFile">;
 type SyncTempFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "lstatSync" | "openSync" | "writeFileSync">;
 export type SyncFchmod = (fd: number, mode: number) => void;
@@ -12,11 +12,8 @@ export declare function pinDirectoryForMode(params: {
     /** Compatibility for best-effort directory modes; admission and close still fail closed. */
     ignoreChmodError?: boolean;
 }): Promise<DirectoryModeOwner | undefined>;
-export declare function applyDirectoryMode(params: {
-    fsModule: AsyncTempFileSystem;
-    dirPath: string;
+export declare function applyDirectoryMode(params: Parameters<typeof pinDirectoryForMode>[0] & {
     mode: number;
-    ignoreChmodError?: boolean;
 }): Promise<void>;
 export declare function applyDirectoryModeSync(params: {
     fsModule: SyncTempFileSystem;
@@ -35,14 +32,9 @@ export declare function writeTempFile(params: {
     handle: FileHandle;
     identity: BigIntStats;
 }>;
-export declare function writeTempFileSync(params: {
+export declare function writeTempFileSync(params: Omit<Parameters<typeof writeTempFile>[0], "fsModule"> & {
     fsModule: SyncTempFileSystem;
-    tempPath: string;
-    content: string | Uint8Array;
-    mode: number;
     fchmodSync?: SyncFchmod;
-    sync: boolean;
-    onIdentity?: (identity: BigIntStats) => void;
 }): {
     fd: number;
     identity: BigIntStats;

package/dist/replace-file-descriptor.js

@@ -3,7 +3,7 @@ import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
-import { ownDirectoryMode } from "./directory-mode-owner.js";
+import { ownDirectoryMode } from "./directory-mode-node.js";
 export async function syncDirectoryBestEffort(fsModule, dirPath) {
     let handle;
     try {

package/dist/retained-directory-replacement.d.ts

@@ -6,6 +6,7 @@ export type RetainedReplacementParent = Readonly<{
     realPath: string;
     identity: Pick<BigIntStats, "dev" | "ino">;
 }>;
+export declare function copyOperationalCode(target: Error, source: unknown): void;
 export declare class RetainedDirectoryReplacement {
     #private;
     private constructor();

package/dist/retained-directory-replacement.js

@@ -7,7 +7,7 @@ function helperUnavailable(message, cause) {
         ...(cause instanceof Error ? { cause } : {}),
     });
 }
-function copyOperationalCode(target, source) {
+export function copyOperationalCode(target, source) {
     const code = source?.code;
     if (typeof code === "string") {
         Object.defineProperty(target, "code", { configurable: true, value: code });

package/dist/root-context.js

@@ -107,7 +107,7 @@ export function rootRelativeReadPath(root, filePath) {
                 resolveCandidateRoot: base === root.rootDir && root.rootDir !== root.rootReal,
             });
             if (admitted)
-                return admitted.relativePath;
+                return `.${path.sep}${admitted.relativePath}`;
             continue;
         }
         const prefix = ensureTrailingSep(base);
@@ -116,7 +116,8 @@ export function rootRelativeReadPath(root, filePath) {
             let start = prefix.length;
             while (raw[start] === path.sep)
                 start += 1;
-            return raw.slice(start);
+            // An admitted absolute tail stays literal, including a leading home marker.
+            return `.${path.sep}${raw.slice(start)}`;
         }
     }
     return raw;

package/dist/root-file-final-admission.d.ts

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import type { PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
+import { type PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
 export type RootFileAdmissionFs = Pick<typeof fs, "lstatSync" | "realpathSync">;
 type ExactIdentity = Readonly<{
     dev: bigint;

package/dist/root-file-final-admission.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
+import { isExpectedPathError } from "./pinned-open.js";
 import { realpathSync } from "./realpath.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { hardlinkedPathNotAllowedError } from "./root-errors.js";
@@ -8,12 +9,6 @@ import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-pa
 function rootIdentityMismatch(cause) {
     return new FsSafeError("path-mismatch", "canonical root directory identity changed or could not be verified", cause === undefined ? {} : { cause });
 }
-function isExpectedPathError(error) {
-    const code = typeof error === "object" && error !== null && "code" in error
-        ? String(error.code)
-        : "";
-    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
-}
 function inspectCanonicalRoot(ioFs, rootPath, expected) {
     try {
         assertNoWindowsPathAlias(rootPath);

package/dist/root-file.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveRootPathSyncWithCanonicalRootObservation, resolveRootPathWithCanonicalRootObservation, } from "./root-path.js";
 import { readSymlinkResolution } from "./root-symlink-policy.js";
-import { openPinnedFileSync, } from "./pinned-open.js";
+import { isExpectedPathError, openPinnedFileSync, } from "./pinned-open.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { FsSafeError } from "./errors.js";
 import { createRootFileFinalAdmission, observeCanonicalRoot, } from "./root-file-final-admission.js";
@@ -198,10 +198,7 @@ function snapshotAsyncResolution(params, absolutePath) {
 function toRootObservationError(error) {
     if (error instanceof FsSafeError)
         return toBoundaryValidationError(error);
-    const code = typeof error === "object" && error !== null && "code" in error
-        ? String(error.code)
-        : "";
-    if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP") {
+    if (isExpectedPathError(error)) {
         return { ok: false, reason: "path", error };
     }
     return { ok: false, reason: "io", error };

package/dist/root-move-noreplace.d.ts

@@ -1,13 +1,8 @@
 import { type BigIntStats, type Stats } from "node:fs";
-import { type DenyMutationPolicy } from "./deny-mutations.js";
+import type { RootMoveOptions } from "./root-options.js";
 import { type RootContext } from "./root-context.js";
-import { type MutationSymlinkPolicy } from "./root-symlink-policy.js";
 export declare function admitMoveSourceStat<T extends Stats | BigIntStats>(stat: T, overwrite?: boolean): T;
-export declare function movePathNoReplaceNative(root: RootContext, params: {
-    assertBeforeMutation?: () => void;
-    denyMutations?: DenyMutationPolicy;
-    mutationSymlinks?: MutationSymlinkPolicy;
-}, paths: {
+export declare function movePathNoReplaceNative(root: RootContext, params: Pick<RootMoveOptions, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">, paths: {
     sourcePath: string;
     sourceParentPath: string;
     targetPath: string;

package/dist/root-paths.d.ts

@@ -1,3 +1,4 @@
+import { type ResolvePathWithinRootParams } from "./path-scope-lexical.js";
 import { type DirectoryResult } from "./root-directory.js";
 export { resolvePathWithinRoot } from "./root-paths-lexical.js";
 export { ensureDirectoryWithinRoot } from "./root-directory.js";
@@ -44,12 +45,7 @@ export type PathScope = {
         mode?: number;
     }): Promise<DirectoryResult>;
 };
-export declare function resolveWritablePathWithinRoot(params: {
-    rootDir: string;
-    requestedPath: string;
-    scopeLabel: string;
-    defaultFileName?: string;
-}): Promise<{
+export declare function resolveWritablePathWithinRoot(params: ResolvePathWithinRootParams): Promise<{
     ok: true;
     path: string;
 } | {

package/dist/root-remove-identity.d.ts

@@ -1,9 +1,7 @@
 import type { BigIntStats } from "node:fs";
 type ExactDirectoryIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
-export type RemovalDirectoryAssertion = Readonly<{
+export type RemovalDirectoryAssertion = ExactDirectoryIdentity & Readonly<{
     path: string;
-    dev: bigint;
-    ino: bigint;
     numericDev?: number;
     numericIno?: number;
     platform: NodeJS.Platform;

package/dist/root-walk.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { expandRelativePathWithHome } from "./root-context.js";
 import { resolveRootPath, ROOT_PATH_ALIAS_POLICIES } from "./root-path.js";
 import { createSuppressedError } from "./suppressed-error.js";
 function validateBudget(name, value) {
@@ -65,9 +66,10 @@ export async function* walkRoot(root, relativePath, options) {
         options.signal?.throwIfAborted();
         let listing;
         try {
+            const expandedDirectory = depth === 0 ? await expandRelativePathWithHome(directory) : directory;
             const skipChildSymlinks = depth > 0 && options.symlinkPolicy === "skip";
             const resolvedDirectory = await resolveRootPath({
-                absolutePath: path.resolve(root.rootReal, directory),
+                absolutePath: path.resolve(root.rootReal, expandedDirectory),
                 rootPath: root.rootReal,
                 rootCanonicalPath: root.rootReal,
                 boundaryLabel: "root walk",
@@ -87,7 +89,10 @@ export async function* walkRoot(root, relativePath, options) {
                 .relative(root.rootReal, resolvedDirectory.canonicalPath)
                 .split(path.sep)
                 .join(path.posix.sep);
-            listing = await root.list(listingDirectory, {
+            if (depth === 0 && expandedDirectory !== directory)
+                directory = listingDirectory;
+            // Resolved filesystem names are literal, not caller home-directory shorthand.
+            listing = await root.list(`./${listingDirectory}`, {
                 order: options.order ?? "sorted",
                 signal: options.signal,
                 snapshot: maxEntries === Number.POSITIVE_INFINITY,
@@ -139,7 +144,7 @@ export async function* walkRoot(root, relativePath, options) {
                     if (!resolved.exists) {
                         continue;
                     }
-                    const target = await root.stat(path.relative(root.rootReal, resolved.canonicalPath));
+                    const target = await root.stat(`./${path.relative(root.rootReal, resolved.canonicalPath)}`);
                     kind = target.isDirectory ? "directory" : target.isFile ? "file" : "other";
                     size = target.size;
                 }

package/dist/root-write-admission.js

@@ -14,7 +14,7 @@ import { mutationSymlinkResolution, } from "./root-symlink-policy.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { realpathSync } from "./realpath.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { assertPreparedRootWriteParentCurrent, } from "./root-write-complete-parent.js";
+import { assertPreparedRootWriteParentCurrent, writeSelectionChanged, } from "./root-write-complete-parent.js";
 export function createRootWriteSelectionForFd(selection, fd) {
     const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }));
     return Object.freeze({
@@ -22,9 +22,6 @@ export function createRootWriteSelectionForFd(selection, fd) {
         identity: Object.freeze({ dev: stat.dev, ino: stat.ino }),
     });
 }
-function writeSelectionChanged(cause) {
-    return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
-}
 function inspectRegularSelectionPath(pathname, expected, follow) {
     let observed;
     try {

package/dist/root-write-complete-parent.d.ts

@@ -1,5 +1,6 @@
 import type { BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
 import type { RootContext } from "./root-context.js";
 import type { GuardedRootWriteTarget } from "./root-write-admission.js";
 type PreparedWriteTargetObservation = Readonly<{
@@ -36,6 +37,7 @@ export type SharedRootWriteTarget = Readonly<{
     mutationAdmission: GuardedRootWriteTarget["mutationAdmission"];
     preparedParent?: PreparedRootWriteParent;
 }>;
+export declare function writeSelectionChanged(cause?: unknown): FsSafeError;
 export declare function assertPreparedRootWriteParentCurrent(prepared: PreparedRootWriteParent, verifyTarget?: boolean): void;
 export declare function prepareSharedRootWriteTarget(root: RootContext, params: SharedRootWriteTargetParams): Promise<SharedRootWriteTarget>;
 export {};

package/dist/root-write-complete-parent.js

@@ -12,7 +12,7 @@ import { errorCauseOptions } from "./root-errors.js";
 import { canReuseParentWithMutationAssertion } from "./root-write-lock-binding.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-function writeSelectionChanged(cause) {
+export function writeSelectionChanged(cause) {
     return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
 }
 function ordinarySharedWriteRoute(root, relativePath, operationTargetPath) {

package/dist/secret-file.d.ts

@@ -13,7 +13,11 @@ type SecretFileWriteParams = {
     dirMode?: number;
     durable?: boolean;
 };
-export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParams, "content">): Promise<{
+type SecretFileCreateParams = Omit<SecretFileWriteParams, "durable"> & {
+    /** "file" requires file synchronization; directory synchronization remains best effort. */
+    durable?: boolean | "file";
+};
+export declare function prepareSecretFileWrite(params: Pick<SecretFileWriteParams, "rootDir" | "filePath" | "mode" | "dirMode">): Promise<{
     mode: number;
     rootGuard: AsyncDirectoryGuard<BigIntStats>;
     parentGuard: AsyncDirectoryGuard<BigIntStats>;
@@ -21,5 +25,5 @@ export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParam
     finalFilePath: string;
 }>;
 export declare function writeSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
-export declare function createSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
+export declare function createSecretFileAtomic(params: SecretFileCreateParams): Promise<void>;
 export {};

package/dist/secret-file.js

@@ -5,8 +5,7 @@ import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
-import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
-import { assertOwnedDirectory } from "./directory-mode-owner.js";
+import { pinNodeDirectoryForMode, assertOwnedDirectory } from "./directory-mode-node.js";
 import { FsSafeError } from "./errors.js";
 import { openPinnedFileSync } from "./pinned-open.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
@@ -199,7 +198,11 @@ async function ensurePrivateDirectory(rootDir, targetDir, mode) {
     }
     return { rootGuard, parentGuard: targetGuard };
 }
-function snapshotSecretFileWriteParams(params, rootDir, filePath) {
+function snapshotSecretFileWriteParams(params) {
+    const rootDir = params.rootDir;
+    const filePath = params.filePath;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     return {
         rootDir,
         filePath,
@@ -282,6 +285,7 @@ async function materializeSecretFileAtomic(params, createOnly) {
         mode,
         verifyPosixMode: true,
         sync: params.durable !== false,
+        strictFileSync: createOnly && params.durable === "file",
         overwrite: !createOnly,
         input: { kind: "buffer", data: typeof params.content === "string" ? params.content : Buffer.from(params.content) },
         rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },
@@ -305,31 +309,23 @@ async function materializeSecretFileAtomic(params, createOnly) {
     });
 }
 export async function writeSecretFileAtomic(params) {
-    const rootDir = params.rootDir;
-    const filePath = params.filePath;
-    assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
-    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
-    const ownedParams = snapshotSecretFileWriteParams(params, rootDir, filePath);
-    const canonicalPath = await secretFileWriteQueueKey(filePath);
+    const ownedParams = snapshotSecretFileWriteParams(params);
+    const canonicalPath = await secretFileWriteQueueKey(ownedParams.filePath);
     await serializePathWrite(canonicalPath, async () => {
         await materializeSecretFileAtomic(ownedParams, false);
     });
 }
 export async function createSecretFileAtomic(params) {
     try {
-        const rootDir = params.rootDir;
-        const filePath = params.filePath;
-        assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
-        assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
-        const ownedParams = snapshotSecretFileWriteParams(params, rootDir, filePath);
-        const canonicalPath = await secretFileWriteQueueKey(filePath);
+        const ownedParams = snapshotSecretFileWriteParams(params);
+        const canonicalPath = await secretFileWriteQueueKey(ownedParams.filePath);
         await serializePathWrite(canonicalPath, async () => {
             await materializeSecretFileAtomic(ownedParams, true);
         });
     }
     catch (error) {
         if ((error instanceof FsSafeError && error.code === "already-exists") ||
-            error.code === "EEXIST") {
+            error?.code === "EEXIST") {
             throw new FsSafeError("secret-exists", "Private secret file already exists.", { cause: error });
         }
         throw error;

package/dist/secret-read-policy.js

@@ -7,7 +7,7 @@ import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
 export function secretPathErrorCode(error) {
-    const code = error.code;
+    const code = error?.code;
     return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
 }
 export function secretReadError(code, action, label, resolvedPath, error) {

package/dist/secure-file-windows.js

@@ -1,29 +1,20 @@
-import { FsSafeError } from "./errors.js";
-import { recordFileObservationFailure } from "./file-observation.js";
+import { fileIdentityMismatchError } from "./strict-file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
 import { warnNativeFallback } from "./native-fallback-warning.js";
 import { inspectWindowsDescriptorCommand } from "./windows-security-command.js";
-import { validateSecureWindowsSecurityFacts } from "./windows-security-facts.js";
+import { unverified as permissionUnverified, validateSecureWindowsSecurityFacts } from "./windows-security-facts.js";
 const IDENTITY_RE = /^([0-9a-f]{8}):([0-9a-f]{16})$/;
 const TRUSTED_OWNER_CLASSES = new Set(["current-user", "system", "administrators"]);
-function permissionUnverified(message, cause) {
-    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
-}
-function identityMismatch() {
-    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
-    recordFileObservationFailure(error, "identity");
-    throw error;
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
 function parseIdentity(value) {
     if (typeof value !== "string")
-        identityMismatch();
+        throw fileIdentityMismatchError();
     const match = IDENTITY_RE.exec(value);
     if (!match)
-        identityMismatch();
+        throw fileIdentityMismatchError();
     return {
         dev: BigInt(`0x${match[1]}`),
         ino: BigInt(`0x${match[2]}`),
@@ -34,7 +25,7 @@ function inspectDescriptorResult(params, result, mechanism) {
         permissionUnverified("Windows descriptor ACL facts were malformed");
     const observed = parseIdentity(result.identity);
     if (observed.dev !== params.identity.dev || observed.ino !== params.identity.ino) {
-        identityMismatch();
+        throw fileIdentityMismatchError();
     }
     const facts = validateSecureWindowsSecurityFacts(result.security);
     return {

package/dist/secure-temp-dir.js

@@ -3,15 +3,10 @@ import { tmpdir as getOsTmpDir } from "node:os";
 import path from "node:path";
 import { directoryEntryPath } from "./directory-entry-path.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { hasNodeErrorCode } from "./path.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
 import { captureSecureTempRepairAdapter, repairSecureTempDirectory, secureTempDirectoryReceipt, } from "./secure-temp-repair.js";
-function isNodeErrorWithCode(err, code) {
-    return (typeof err === "object" &&
-        err !== null &&
-        "code" in err &&
-        err.code === code);
-}
 export function resolveSecureTempRoot(options) {
     const { fallbackPrefix: prefix, accessSync: suppliedAccess, lstatSync: suppliedLstat, mkdirSync: suppliedMkdir, descriptor: suppliedDescriptor, getuid: suppliedGetuid, tmpdir: suppliedTmpdir, platform: suppliedPlatform, preferredDir, skipPreferredOnWindows, warn: suppliedWarn, warningPrefix: suppliedWarningPrefix, unsafeFallbackLabel: suppliedFallbackLabel, } = options;
     const platform = suppliedPlatform ?? process.platform;
@@ -87,7 +82,7 @@ export function resolveSecureTempRoot(options) {
             candidate = lstatSync(candidatePath);
         }
         catch (error) {
-            return { kind: isNodeErrorWithCode(error, "ENOENT") ? "missing" : "invalid", error };
+            return { kind: hasNodeErrorCode(error, "ENOENT") ? "missing" : "invalid", error };
         }
         let receipt;
         try {

package/dist/sidecar-lock-acquire.js

@@ -102,7 +102,7 @@ export async function acquireSidecarLock(options, context) {
             await waitForRetry();
         }
         catch (waitError) {
-            if (waitError.code === "file_lock_timeout")
+            if (waitError?.code === "file_lock_timeout")
                 throw denial;
             throw waitError;
         }

package/dist/sidecar-lock-admission-parser.d.ts

@@ -1,7 +1,7 @@
 import type { Root } from "./root-impl.js";
 import type { HeldSidecarLock } from "./sidecar-lock-admission.js";
 import { readSidecarLockRawSnapshot, type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
-type SidecarAdmissionRunner = {
+export type SidecarAdmissionRunner = {
     hasToken(): boolean;
     run<T>(callback: () => T): T;
 };
@@ -39,4 +39,3 @@ export declare function observeHeldSidecarParser(params: {
     parserAccessor(): ((raw: string) => unknown) | undefined;
     isTransientDenial(error: unknown): boolean;
 }): Promise<HeldSidecarParserObservation>;
-export {};

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

@@ -1,5 +1,4 @@
-import type { Root } from "./root-impl.js";
-import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+import type { HeldSidecarLock } from "./sidecar-lock-admission.js";
 import type { SidecarLockHandle } from "./sidecar-lock-types.js";
 export declare function stopSidecarLockMonitoring(held: {
     compromiseTimer?: NodeJS.Timeout;
@@ -14,12 +13,7 @@ export declare function createSidecarLockHandle(params: {
 }): SidecarLockHandle;
 export declare function createHeldSidecarLockHandle(params: {
     normalizedTargetPath: string;
-    held: {
-        lockPath: string;
-        snapshot: SidecarLockSnapshot;
-        lockRoot?: Root;
-        parsePayload?: (raw: string) => unknown;
-    };
+    held: Pick<HeldSidecarLock, "lockPath" | "snapshot" | "lockRoot" | "parsePayload">;
     release: (options?: {
         retry?: boolean;
     }) => Promise<unknown>;

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

@@ -1,4 +1,4 @@
-import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
+import type { SidecarLockReclaimParams, SidecarLockRetryOptions } from "./sidecar-lock-types.js";
 export declare function validateSidecarLockRetryOptions(retry: SidecarLockRetryOptions): void;
 export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefined): void;
 export declare function validateSidecarLockStaleMs(staleMs: number | undefined): void;
@@ -11,9 +11,4 @@ export declare function sidecarLockRetryDelay(retry: SidecarLockRetryOptions, ti
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;
 export declare function sidecarLockPayloadCreatedAtMs(payload: unknown): number | null;
-export declare function defaultSidecarLockShouldReclaim(params: {
-    lockPath: string;
-    payload: unknown;
-    staleMs: number;
-    nowMs: number;
-}): Promise<boolean>;
+export declare function defaultSidecarLockShouldReclaim(params: Pick<SidecarLockReclaimParams, "lockPath" | "payload" | "staleMs" | "nowMs">): Promise<boolean>;

package/dist/sidecar-lock-reclaim.js

@@ -357,13 +357,12 @@ export async function removeStaleSidecarLockIfAllowed(params) {
     if (params.assertGuardHeld)
         await params.assertGuardHeld();
     params.assertAuthorized?.();
+    if (params.lockRoot) {
+        await params.lockRoot.remove(relativeSidecarLockPath(params.lockRoot, params.lockPath), { assertBeforeMutation: params.assertAuthorized });
+        return "removed";
+    }
     try {
-        if (params.lockRoot) {
-            await params.lockRoot.remove(relativeSidecarLockPath(params.lockRoot, params.lockPath), { assertBeforeMutation: params.assertAuthorized });
-        }
-        else {
-            await fs.rm(params.lockPath);
-        }
+        await fs.rm(params.lockPath);
         return "removed";
     }
     catch (err) {

package/dist/sidecar-lock-stale-admission.d.ts

@@ -1,11 +1,7 @@
 import { type SidecarReclaimGuard } from "./sidecar-lock-reclaim.js";
-import { type SidecarLockParserState } from "./sidecar-lock-admission-parser.js";
+import { type SidecarLockParserState, type SidecarAdmissionRunner } from "./sidecar-lock-admission-parser.js";
 import type { Root } from "./root-impl.js";
 import type { SidecarLockAcquireOptions } from "./sidecar-lock-types.js";
-type SidecarAdmissionRunner = {
-    hasToken(): boolean;
-    run<T>(callback: () => T): T;
-};
 type StaleOptions = Pick<SidecarLockAcquireOptions<Record<string, unknown>>, "shouldReclaim" | "shouldRemoveStaleLock" | "staleRecovery">;
 export type SidecarLockStaleOptionsState = {
     shouldReclaimObserved?: boolean;

package/dist/stat-observation.js

@@ -1,11 +1,4 @@
-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;
-}
+import { fileIdentityMismatchError, inspectFileIdentitySync } from "./strict-file-identity.js";
 function safeNumber(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 }
@@ -35,7 +28,7 @@ function observeStatSync(inspect, expected, initial, platform = process.platform
     const ino = numericIno ? BigInt(rawIno) : typeof rawIno === "bigint" ? rawIno : undefined;
     if (expected && ((dev !== undefined && dev !== expected.dev) ||
         (ino !== undefined && ino !== expected.ino)))
-        identityMismatch();
+        throw fileIdentityMismatchError();
     if (numericDev && numericIno) {
         return (captureIdentity
             ? { stat, identity: expected ?? { dev: dev, ino: ino } }
@@ -47,7 +40,7 @@ function observeStatSync(inspect, expected, initial, platform = process.platform
         const current = inspect(true);
         if ((dev !== undefined && current.dev !== dev) ||
             (ino !== undefined && current.ino !== ino))
-            identityMismatch();
+            throw fileIdentityMismatchError();
         return current;
     }, expected, platform);
     return (captureIdentity

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

@@ -1,5 +1,7 @@
 import type { BigIntStats } from "node:fs";
+import { FsSafeError } from "./errors.js";
 type ExactFileIdentity = Pick<BigIntStats, "dev" | "ino">;
+export declare function fileIdentityMismatchError(): FsSafeError;
 export declare function inspectFileIdentity<T extends ExactFileIdentity>(inspect: () => T | Promise<T>, expected?: ExactFileIdentity, platform?: NodeJS.Platform): Promise<T>;
 export declare function inspectFileIdentitySync<T extends ExactFileIdentity>(inspect: () => T, expected?: ExactFileIdentity, platform?: NodeJS.Platform, mismatch?: () => Error): T;
 export {};

package/dist/strict-file-identity.js

@@ -1,6 +1,6 @@
 import { FsSafeError } from "./errors.js";
 import { recordFileObservationFailure } from "./file-observation.js";
-function identityMismatch() {
+export function fileIdentityMismatchError() {
     const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
     recordFileObservationFailure(error, "identity");
     return error;
@@ -13,20 +13,20 @@ function identityCheck(expected, platform) {
             const value = stat[field];
             // Numeric receipts cannot recover identity bits already lost to rounding.
             if (typeof value !== "bigint")
-                throw identityMismatch();
+                throw fileIdentityMismatchError();
             if (platform === "win32" && value === 0n) {
                 complete = false;
             }
             else {
                 if (known[field] !== undefined && known[field] !== value)
-                    throw identityMismatch();
+                    throw fileIdentityMismatchError();
                 known[field] = value;
             }
         }
         return complete;
     };
     if (expected && !check(expected))
-        throw identityMismatch();
+        throw fileIdentityMismatchError();
     return check;
 }
 // Retry only unknown Windows identities, retaining every known component so a
@@ -38,9 +38,9 @@ export async function inspectFileIdentity(inspect, expected, platform = process.
         if (check(stat))
             return stat;
     }
-    throw identityMismatch();
+    throw fileIdentityMismatchError();
 }
-export function inspectFileIdentitySync(inspect, expected, platform = process.platform, mismatch = identityMismatch) {
+export function inspectFileIdentitySync(inspect, expected, platform = process.platform, mismatch = fileIdentityMismatchError) {
     let knownDev;
     let knownIno;
     if (expected) {