@openclaw/fs-safe 0.18.0 → 0.18.2

package/dist/file-lock-sync.d.ts

@@ -1,28 +1,11 @@
-import type { Root } from "./root-impl.js";
 import { type SidecarLockStaleSnapshot } from "./sidecar-lock-reclaim.js";
-import type { SidecarLockCompromisedInfo, SidecarLockRetryOptions, SidecarLockStaleRecovery } from "./sidecar-lock-types.js";
-export type FileLockSyncAcquireOptions<TPayload extends Record<string, unknown>> = {
-    lockPath?: string;
+import type { SidecarLockCommonAcquireOptions, SidecarLockOptionFields, SidecarLockReclaimParams } from "./sidecar-lock-types.js";
+export type FileLockSyncAcquireOptions<TPayload extends Record<string, unknown>> = SidecarLockOptionFields<SidecarLockCommonAcquireOptions & {
     staleMs?: number;
-    timeoutMs?: number;
-    retry?: SidecarLockRetryOptions;
-    staleRecovery?: SidecarLockStaleRecovery;
-    reentrantOwner?: string;
     payload: () => TPayload;
-    shouldReclaim?: (params: {
-        lockPath: string;
-        normalizedTargetPath: string;
-        payload: unknown;
-        staleMs: number;
-        nowMs: number;
-        heldByThisProcess: false;
-    }) => boolean;
+    shouldReclaim?: (params: SidecarLockReclaimParams<false>) => boolean;
     shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean;
-    parsePayload?: (raw: string) => unknown;
-    lockRoot?: Root;
-    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
-    compromiseCheckIntervalMs?: number;
-};
+}>;
 export type FileLockSyncHandle = {
     lockPath: string;
     normalizedTargetPath: string;

package/dist/file-store-boundary.d.ts

@@ -29,3 +29,10 @@ export declare function ensureStoreDirectorySync(params: {
     mode: number;
     messagePrefix: "private store" | "store";
 }): SyncParentGuard;
+export declare function assertRelativePath(relativePath: string): string;
+export declare function resolveStorePath(rootDir: string, relativePath: string): string;
+export declare function assertFileStoreMaxBytes(size: number, limit: number | undefined): void;
+export declare function readFileStoreCopySource(params: {
+    sourcePath: string;
+    maxBytes: number;
+}): Promise<Buffer>;

package/dist/file-store-boundary.js

@@ -5,13 +5,15 @@ import { createByteLimitTransform } from "./bounded-read-stream.js";
 import { pipeline } from "node:stream/promises";
 import { FsSafeError } from "./errors.js";
 import { assertSyncStoreDirectoryReceipt, ensureSyncStoreDirectory, } from "./file-store-sync-directory.js";
-import { isPathInside } from "./path.js";
+import { isPathInside, splitSafeRelativePath } from "./path.js";
 import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
 import { ensureTrailingSep } from "./root-context.js";
 import { RootHandle } from "./root-impl.js";
 import { prepareSecretFileWrite } from "./secret-file.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { readRegularFile } from "./regular-file.js";
+import { errorCauseOptions } from "./root-errors.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export async function ensureParentInRoot(scopedRoot, relativePath, mode) {
     const parent = path.posix.dirname(relativePath);
@@ -118,3 +120,58 @@ export function ensureStoreDirectorySync(params) {
     assertSyncStoreDirectoryReceipt(guard);
     return guard;
 }
+export function assertRelativePath(relativePath) {
+    const raw = relativePath.trim();
+    if (!raw || raw !== relativePath) {
+        throw new FsSafeError("invalid-path", "store key must be non-empty and unpadded");
+    }
+    const segments = splitSafeRelativePath(raw);
+    if (segments.length === 0 ||
+        segments.join("/") !== raw ||
+        raw.normalize("NFC") !== raw ||
+        segments.some((segment) => /[ .]$/u.test(segment))) {
+        throw new FsSafeError("invalid-path", "store key must use one canonical relative spelling");
+    }
+    return raw;
+}
+export function resolveStorePath(rootDir, relativePath) {
+    const key = assertRelativePath(relativePath);
+    // FileStore constructors snapshot an absolute root before this helper runs.
+    // Do not re-resolve it: Node drops the trailing separator from an exact
+    // Windows namespace drive root such as `\\?\C:\`.
+    const root = path.isAbsolute(rootDir) ? rootDir : path.resolve(rootDir);
+    // The immutable key already passed segment validation; keep the containment check.
+    const target = path.resolve(root, key);
+    if (!isPathInside(root, target)) {
+        throw new FsSafeError("outside-workspace", "relative path escapes root");
+    }
+    return target;
+}
+// Store operation boundaries admit the primitive limit before reaching this helper.
+export function assertFileStoreMaxBytes(size, limit) {
+    if (limit !== undefined && size > limit) {
+        throw new FsSafeError("too-large", `file exceeds maximum size of ${limit} bytes`);
+    }
+}
+export async function readFileStoreCopySource(params) {
+    assertNoWindowsPathAlias(params.sourcePath, "filesystem", "source path uses a Windows filesystem namespace alias");
+    const sourceStat = syncFs.lstatSync(params.sourcePath);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+        throw new FsSafeError("not-file", "source path is not a file");
+    }
+    assertFileStoreMaxBytes(sourceStat.size, params.maxBytes);
+    try {
+        return (await readRegularFile({ filePath: params.sourcePath, maxBytes: params.maxBytes }))
+            .buffer;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("regular file") || message.includes("not a regular file")) {
+            throw new FsSafeError("not-file", "source path is not a file", errorCauseOptions(error));
+        }
+        if (message.includes(`exceeds ${params.maxBytes} bytes`)) {
+            throw new FsSafeError("too-large", `file exceeds maximum size of ${params.maxBytes} bytes`, errorCauseOptions(error));
+        }
+        throw error;
+    }
+}

package/dist/file-store-sync-write.js

@@ -10,6 +10,7 @@ import { isPathInside } from "./path.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { writeTempFileSync } from "./replace-file-descriptor.js";
 import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
+import { errorCauseOptions } from "./root-errors.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 function verifyStoreFile(fd, expected, filePath) {
@@ -108,9 +109,7 @@ export function writeFileSyncAtomic(params) {
             if (error instanceof FsSafeError) {
                 throw error;
             }
-            throw new FsSafeError("path-mismatch", "store target changed after write", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("path-mismatch", "store target changed after write", errorCauseOptions(error));
         }
         assertSyncStoreDirectoryReceipt(parentGuard);
         if (params.durable) {

package/dist/file-store.js

@@ -1,13 +1,9 @@
 import syncFs from "node:fs";
-import fs from "node:fs/promises";
-import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
-import { assertFileStoreMaxBytes } from "./file-store-limit.js";
-import { assertRelativePath, resolveStorePath } from "./file-store-path.js";
 import { pruneExpiredStoreEntries } from "./file-store-prune.js";
-import { ensureParentInRoot, openPrivateStoreLockRoot, openWritableStoreRoot, writeStreamToTempSource, } from "./file-store-boundary.js";
+import { assertFileStoreMaxBytes, assertRelativePath, ensureParentInRoot, openPrivateStoreLockRoot, openWritableStoreRoot, readFileStoreCopySource, resolveStorePath, writeStreamToTempSource, } from "./file-store-boundary.js";
 import { writeFileSyncAtomic } from "./file-store-sync-write.js";
 import { createJsonStore } from "./json-document-store.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
@@ -18,7 +14,6 @@ import { DEFAULT_ROOT_MAX_BYTES } from "./root-impl.js";
 import { matchRootFileOpenFailure, openRootFileSync } from "./root-file.js";
 import { writeSecretFileAtomic } from "./secret-file.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
-import { readFileStoreCopySource } from "./file-store-copy-source.js";
 function snapshotWriteOptions(options, durabilityFirst = true) {
     if (options == null)
         return undefined;

package/dist/guarded-mkdir.d.ts

@@ -1,6 +1,6 @@
 import { type RootBoundaryIdentity } from "./root-boundary.js";
 import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
-import type { PinnedCreatedDirectoryReceipt, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken } from "./pinned-write.js";
+import type { PinnedCreatedDirectoryReceipt, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken } from "./pinned-write-types.js";
 /**
  * Creates each missing path component from `rootReal` down to `targetPath`,
  * guarding every step. Returns the real (symlink-resolved) path of the final

package/dist/index.d.ts

@@ -1,6 +1,9 @@
-export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, type FsSafeErrorDetails, } from "./errors.js";
-export { DEFAULT_ROOT_MAX_BYTES, root, type DenyMutationPolicy, type HardlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCopyPublicationReceipt, type CopyCloneMode, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootEntriesOptions, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type RootWalkDataEntry, type RootWalkDataEntryKind, type RootWalkDirectoryErrorBehavior, type RootWalkEntry, type RootWalkEntryFilter, type RootWalkEntryFilterResult, type RootWalkEntryKind, type RootWalkLimitBehavior, type RootWalkOptions, type RootWalkSymlinkPolicy, type SymlinkPolicy, type MutationSymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
-export type { ContainmentGuarantee } from "./containment.js";
-export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, type FsSafePythonConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
-export { writeExternalFileWithinRoot, type ExternalFileWriteOptions, type ExternalFileWriteResult, } from "./output.js";
-export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
+export { FsSafeError, categorizeFsSafeError, } from "./errors.js";
+export type * from "./errors.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, type Root, } from "./root.js";
+export type * from "./root-public-types.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
+export type * from "./config.js";
+export { writeExternalFileWithinRoot, } from "./output.js";
+export type * from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

package/dist/json-durable-queue-ownership.d.ts

@@ -4,11 +4,7 @@ export type DurableQueueEntryPathsLike = {
     deliveredPath: string;
     processingPath?: string;
 };
-export type ValidatedDurableQueueEntryPaths = Readonly<{
-    jsonPath: string;
-    deliveredPath: string;
-    processingPath: string;
-}>;
+export type ValidatedDurableQueueEntryPaths = Readonly<Required<DurableQueueEntryPathsLike>>;
 export declare function validateDurableQueueEntryPaths(paths: DurableQueueEntryPathsLike): ValidatedDurableQueueEntryPaths;
 export declare function claimDurableQueueEntry(paths: DurableQueueEntryPathsLike, options?: {
     skipUnowned?: boolean;

package/dist/json-durable-queue-read.js

@@ -43,6 +43,7 @@ export async function withJsonDurableQueueEntry(filePath, options, run) {
     const handle = await fs.promises.open(filePath, resolveReadOpenFlags());
     let closePromise;
     const releaseReadPin = () => closePromise ??= (async () => { await handle.close(); })();
+    let result;
     try {
         const openedStat = inspectQueueEntry(() => fs.fstatSync(handle.fd, { bigint: true }), maxBytes, initialStat);
         inspectQueueEntry(inspectPath, maxBytes, openedStat);
@@ -53,9 +54,12 @@ export async function withJsonDurableQueueEntry(filePath, options, run) {
         });
         // The migration owner may release this pin only at the verified publication
         // boundary; until then an unlinked inode cannot be recycled into a new claim.
-        return await run(JSON.parse(bytes.toString("utf8")), openedStat, releaseReadPin);
+        result = await run(JSON.parse(bytes.toString("utf8")), openedStat, releaseReadPin);
     }
-    finally {
-        await releaseReadPin();
+    catch (error) {
+        await releaseReadPin().catch(() => undefined);
+        throw error;
     }
+    await releaseReadPin();
+    return result;
 }

package/dist/json-durable-queue.d.ts

@@ -1,4 +1,3 @@
-export { DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES } from "./json-durable-queue-read.js";
 export type JsonDurableQueueEntryPaths = {
     jsonPath: string;
     deliveredPath: string;

package/dist/json-durable-queue.js

@@ -7,9 +7,7 @@ import { withJsonDurableQueueEntry } from "./json-durable-queue-read.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { replaceFileAtomicWithDirectorySync } from "./replace-file.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
-import { assertNoWindowsPathAlias, hasWindowsPathAlias, } from "./windows-path-alias.js";
-export { DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES } from "./json-durable-queue-read.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias, hasWindowsPathAlias, } from "./windows-path-alias.js";
 function assertSafeQueueEntryId(id) {
     assertSafePathSegment(id, { label: "queue entry id" });
 }

package/dist/json-store.js

@@ -1,8 +1,7 @@
 import path from "node:path";
 import { fileStore } from "./file-store.js";
 import {} from "./json-document-store.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export function jsonStore(options) {
     const filePathInput = admitStandalonePublicationPath(options.filePath);
     const filePath = path.resolve(filePathInput);

package/dist/json.js

@@ -9,10 +9,9 @@ import { openRootFileSync } from "./root-file.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { writeTempFileSync } from "./replace-file-descriptor.js";
 import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { writeTextAtomic } from "./text-atomic.js";
 import { sleep } from "./timing.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 const READ_RETRY_MAX_ATTEMPTS = 5;
 const READ_RETRY_BASE_DELAY_MS = 50;
 function isRetryableReadError(err) {

package/dist/move-path.js

@@ -10,8 +10,7 @@ import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { realpathSync } from "./realpath.js";
 import { cleanupPinnedFilePath } from "./file-cleanup.js";
 import { createMoveStageOwner } from "./move-path-stage.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export function moveCopyFallbackReasonForRenameError(error, platform = process.platform) {
     const code = error?.code;
     if (code === "EXDEV") {

package/dist/native-operations.js

@@ -1,7 +1,6 @@
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";

package/dist/native-pinned-write-windows.d.ts

@@ -2,5 +2,5 @@ import type { FileHandle } from "node:fs/promises";
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
 import type { NativeBinding } from "./native.js";
-import type { PinnedWriteParams } from "./pinned-write.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
 export declare function runPinnedWriteWindows(binding: NativeBinding, params: PinnedWriteParams, root: FileHandle, parentFd: number, parentGuard: AnyAsyncDirectoryGuard): Promise<FileIdentityStat>;

package/dist/native-pinned-write-windows.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import fsSync, {} from "node:fs";
 import path from "node:path";
 import { createFileHandle } from "./create.js";
-import { hasPreservedCreationArtifacts } from "./creation-file-state.js";
+import { hasPreservedCreationArtifacts } from "./creation-boundary.js";
 import { assertSyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { nativeOpenFlags, removeNativeCreatedFileIfStillPinned, } from "./native-operations.js";

package/dist/native-pinned-write.d.ts

@@ -1,4 +1,4 @@
 import type { FileIdentityStat } from "./file-identity.js";
 import type { NativeBinding } from "./native.js";
-import type { PinnedWriteParams } from "./pinned-write.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
 export declare function runPinnedWriteNative(binding: NativeBinding, params: PinnedWriteParams): Promise<FileIdentityStat>;

package/dist/native-pinned-write.js

@@ -63,6 +63,7 @@ import { NativePolicyDirectoryMismatch } from "./native-policy-directory-observa
 import { assertPolicyStagedDirectoryCurrent, assertStagedDirectoryCurrent, describePolicyStagedDirectory, describeStagedDirectory, refreshPolicyStagedDirectoryObservation, } from "./staged-directory.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { realpathSync } from "./realpath.js";
+import { errorCauseOptions } from "./root-errors.js";
 import { isNotFoundPathError, isSymlinkOpenError } from "./path.js";
 import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
 import { createPathSegmentRoute, joinPathSegmentRoute } from "./path-segment-route.js";
@@ -95,12 +96,8 @@ function normalizePolicyParentOpenError(error, params) {
     if (!isSymlinkOpenError(error))
         return error;
     return params.mutationAdmission?.rejectParentSymlinks
-        ? new FsSafeError("symlink", "symlink path component not allowed", {
-            cause: error instanceof Error ? error : undefined,
-        })
-        : new FsSafeError("path-mismatch", "native write parent changed during policy admission", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        ? new FsSafeError("symlink", "symlink path component not allowed", errorCauseOptions(error))
+        : new FsSafeError("path-mismatch", "native write parent changed during policy admission", errorCauseOptions(error));
 }
 async function describePosixParent(parentFd, pathname) {
     const parentPath = realpathSync.native(pathname);

package/dist/native-policy-parent-windows.d.ts

@@ -2,7 +2,7 @@ import { type BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type NativeRootAdmission } from "./native-parent-admission.js";
 import type { NativeBinding } from "./native.js";
-import type { PinnedWriteParams } from "./pinned-write.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
 import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
 type PolicyParent = {
     fd: number;

package/dist/native-staged-file.d.ts

@@ -3,7 +3,7 @@ import { type BigIntStats, type Stats } from "node:fs";
 import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
 import { type NativeBinding } from "./native-binding.js";
-import type { PinnedWriteInput, PinnedWriteParams } from "./pinned-write.js";
+import type { PinnedWriteInput, PinnedWriteParams } from "./pinned-write-types.js";
 import type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, StagedFileReceipt } from "./staged-file-types.js";
 export type NativeStagingBinding = NativeBinding & Required<Pick<NativeBinding, "createStagedFile" | "stagedFileMatches" | "removeStagedFile">>;
 export declare function assertNativeStaging(binding: NativeBinding): asserts binding is NativeStagingBinding;
@@ -36,10 +36,10 @@ declare class NativeStagedFile implements StagedFile {
 }
 export declare const createNativeStage: (...args: Parameters<typeof NativeStagedFile.create>) => Promise<StagedFile>;
 export declare const writeNativeStage: typeof NativeStagedFile.write;
-export type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, StagedFileFailureDetails, StagedFilePublication, StagedFileReceipt, } from "./staged-file-types.js";
 export declare function stageFileInDirectory(options: {
     directory: string | DirectoryReceipt<Stats | BigIntStats>;
     content: string | Uint8Array;
     /** Published mode; the unpublished stage stays at 0600. Defaults to 0600. */
     mode?: number;
 }): Promise<StagedFile>;
+export {};

package/dist/native-staged-file.js

@@ -50,8 +50,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { assertDarwinCreationAcl } from "./creation-darwin.js";
-import { assertPrivateCreationFile } from "./creation-file-state.js";
+import { assertDarwinCreationAcl, assertPrivateCreationFile } from "./creation-boundary.js";
 import { requireNativeBinding } from "./native.js";
 import { syncFileBestEffortSync } from "./file-sync.js";
 import { randomUUID } from "node:crypto";

package/dist/permission-exec.d.ts

@@ -7,6 +7,12 @@ export type PermissionCommandFailure = {
     signal: string | null;
     stderr: string;
 };
+export type PermissionFailureFields = {
+    error?: string;
+    errorDetail?: PermissionCommandFailure;
+    /** Original inspection failure, retained separately from serializable diagnostics. */
+    errorCause?: unknown;
+};
 export declare function formatPermissionErrorDetail(value: string): string;
 /** Formats only caught permission-query failures without invoking user code. */
 export declare function formatCaughtPermissionFailure(error: unknown): string;

package/dist/permissions-public.d.ts

@@ -1,3 +1,4 @@
-export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, safeStat, type PermissionCheck, type PermissionCheckOptions, type PermissionCommandFailure, type SafeStatResult, } from "./permissions.js";
+export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, safeStat, type PermissionCheck, type PermissionCheckOptions, type SafeStatResult, } from "./permissions.js";
+export type { PermissionCommandFailure } from "./permission-exec.js";
 export { createPrivateDirectory, type CreatePrivateDirectoryOptions, } from "./private-directory.js";
 export { readOwnerAndDacl, type OwnerAndDaclResult, type WindowsAccessControlEntry, type WindowsAceFlags, } from "./owner-dacl.js";

package/dist/permissions-windows.d.ts

@@ -1,4 +1,4 @@
-import { type PermissionCommandFailure } from "./permission-exec.js";
+import { type PermissionFailureFields } from "./permission-exec.js";
 import { type PermissionCheck, type PermissionCheckOptions } from "./permissions.js";
 export type PermissionExec = (command: string, args: string[]) => Promise<{
     stdout: string;
@@ -13,16 +13,13 @@ export type WindowsAclEntry = {
     canRead: boolean;
     canWrite: boolean;
 };
-export type WindowsAclSummary = {
+export type WindowsAclSummary = Omit<PermissionFailureFields & {
     ok: boolean;
     entries: WindowsAclEntry[];
     untrustedWorld: WindowsAclEntry[];
     untrustedGroup: WindowsAclEntry[];
     trusted: WindowsAclEntry[];
-    error?: string;
-    errorDetail?: PermissionCommandFailure;
-    errorCause?: unknown;
-};
+}, never>;
 export type WindowsUserInfoProvider = () => {
     username?: string | null;
 };

package/dist/permissions.d.ts

@@ -1,9 +1,6 @@
-import type { PermissionCommandFailure } from "./permission-exec.js";
+import type { PermissionFailureFields } from "./permission-exec.js";
 import { type PermissionExec } from "./permissions-windows.js";
-export type { PermissionCommandFailure } from "./permission-exec.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
-export type { IcaclsResetCommandOptions, PermissionExec, WindowsAclEntry, WindowsAclSummary, WindowsUserInfoProvider, } from "./permissions-windows.js";
-export type PermissionCheck = {
+export type PermissionCheck = Omit<PermissionFailureFields & {
     ok: boolean;
     isSymlink: boolean;
     isDir: boolean;
@@ -21,11 +18,7 @@ export type PermissionCheck = {
     /** Owner-query failure detail when Windows ownership could not be verified. */
     ownerError?: string;
     aclSummary?: string;
-    error?: string;
-    errorDetail?: PermissionCommandFailure;
-    /** Original inspection failure, retained separately from serializable diagnostics. */
-    errorCause?: unknown;
-};
+}, never>;
 export type PermissionCheckOptions = {
     platform?: NodeJS.Platform;
     env?: NodeJS.ProcessEnv;

package/dist/permissions.js

@@ -1,7 +1,6 @@
 import fsSync from "node:fs";
 import { formatIcaclsResetCommand, inspectWindowsPermissions, } from "./permissions-windows.js";
 import { hasWindowsPathAlias, pathForWindowsFilesystem, } from "./windows-path-alias.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
 function failedSafeStat(error) {
     return {
         ok: false,

package/dist/pinned-mutation-admission.d.ts

@@ -1,6 +1,6 @@
 import { type DenyMutationPolicy } from "./deny-mutations.js";
 import { type RootBoundaryIdentity } from "./root-boundary.js";
-import type { PinnedWriteMutationAdmission } from "./pinned-write.js";
+import type { PinnedWriteMutationAdmission } from "./pinned-write-types.js";
 import type { MutationSymlinkPolicy } from "./root-symlink-policy.js";
 export type PinnedMutationPolicySnapshot = Readonly<{
     denyMutations?: DenyMutationPolicy;

package/dist/pinned-open.d.ts

@@ -18,6 +18,7 @@ export type PinnedOpenSyncFinalAdmission = (params: {
     descriptorIdentity: fs.BigIntStats;
 }) => string;
 export type PinnedOpenSyncFs = Pick<typeof fs, "constants" | "lstatSync" | "realpathSync" | "openSync" | "fstatSync" | "closeSync">;
+export declare function isExpectedPathError(error: unknown): boolean;
 export declare function openPinnedFileSync(params: {
     filePath: string;
     resolvedPath?: string;

package/dist/pinned-open.js

@@ -5,7 +5,7 @@ import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { realpathSync } from "./realpath.js";
-function isExpectedPathError(error) {
+export function isExpectedPathError(error) {
     const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
     return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
 }
@@ -77,7 +77,12 @@ export function openPinnedFileSync(params) {
     }
     finally {
         if (fd !== null) {
-            ioFs.closeSync(fd);
+            try {
+                ioFs.closeSync(fd);
+            }
+            catch {
+                // Preserve the failed admission result; success transfers fd above.
+            }
         }
     }
 }

package/dist/pinned-operation.d.ts

@@ -1 +1 @@
-export declare function validatePinnedOperationPayload(payload: Record<string, unknown>): void;
+export declare function validatePinnedRelativePath(relativePath: unknown): void;

package/dist/pinned-operation.js

@@ -1,19 +1,7 @@
 import { FsSafeError } from "./errors.js";
-export function validatePinnedOperationPayload(payload) {
-    if (typeof payload.relativePath === "string") {
-        validatePinnedRelativePath(payload.relativePath);
-    }
-    if (typeof payload.relativeParentPath === "string") {
-        validatePinnedRelativePath(payload.relativeParentPath);
-    }
-    if (typeof payload.from === "string") {
-        validatePinnedRelativePath(payload.from);
-    }
-    if (typeof payload.to === "string") {
-        validatePinnedRelativePath(payload.to);
-    }
-}
-function validatePinnedRelativePath(relativePath) {
+export function validatePinnedRelativePath(relativePath) {
+    if (typeof relativePath !== "string")
+        return;
     if (relativePath.length === 0 || relativePath === ".") {
         return;
     }
@@ -21,7 +9,6 @@ function validatePinnedRelativePath(relativePath) {
         throw new FsSafeError("invalid-path", "relative path contains a NUL byte");
     }
     if (relativePath.startsWith("/") ||
-        relativePath.startsWith("//") ||
         relativePath === ".." ||
         relativePath.startsWith("../") ||
         relativePath.startsWith("..\\")) {

package/dist/pinned-write-mode.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult } from "./mutation-authority.js";
-import { assertPrivateCreationFile } from "./creation-file-state.js";
+import { assertPrivateCreationFile } from "./creation-boundary.js";
 export function assertPinnedWriteMode(fd, mode, privateCreation = false) {
     if (process.platform === "win32")
         return;

package/dist/pinned-write-staged.js

@@ -3,8 +3,7 @@ import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import path from "node:path";
 import { createFileHandle } from "./create.js";
-import { hasPreservedCreationArtifacts } from "./creation-file-state.js";
-import { creationAdmissionFromParent } from "./creation-path.js";
+import { hasPreservedCreationArtifacts, creationAdmissionFromParent } from "./creation-boundary.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity, sha256Hex } from "./file-identity.js";

package/dist/pinned-write.d.ts

@@ -1,6 +1,5 @@
 import type { FileIdentityStat } from "./file-identity.js";
 import type { PinnedWriteParams, RenameIdentityPolicy } from "./pinned-write-types.js";
-export type { PinnedWriteInput, RenameIdentityPolicy, PublishedWriteIdentity, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken, PinnedCreatedDirectoryReceipt, PinnedMutationParentWalkSession, PinnedWriteMutationAdmission, PinnedWriteParams, } from "./pinned-write-types.js";
 export declare function runPinnedWriteHelper(params: PinnedWriteParams): Promise<FileIdentityStat>;
 export declare function runPinnedWriteWithRenamePolicy(params: PinnedWriteParams & {
     targetPath: string;

package/dist/pinned-write.js

@@ -3,7 +3,7 @@ import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createFileHandle } from "./create.js";
-import { creationAdmissionFromParent } from "./creation-path.js";
+import { creationAdmissionFromParent } from "./creation-boundary.js";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
@@ -13,7 +13,7 @@ import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { runPinnedWriteNative } from "./native-pinned-write.js";
 import { getNativeBinding } from "./native.js";
-import { validatePinnedOperationPayload } from "./pinned-operation.js";
+import { validatePinnedRelativePath } from "./pinned-operation.js";
 import { cleanupPinnedFilePath } from "./file-cleanup.js";
 import { withSidecarLock } from "./sidecar-lock.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
@@ -71,9 +71,7 @@ export async function runPinnedWriteHelper(params) {
         rootIdentity,
     };
     assertSafeBasename(normalizedParams.basename);
-    validatePinnedOperationPayload({
-        relativeParentPath: normalizedParams.relativeParentPath,
-    });
+    validatePinnedRelativePath(normalizedParams.relativeParentPath);
     assertNoWindowsPathAlias(normalizedParams.rootPath, "filesystem", "pinned write root uses a Windows filesystem namespace alias");
     assertNoWindowsPathAlias(normalizedParams.relativeParentPath, "relative", "pinned write parent uses a Windows filesystem namespace alias");
     assertNoWindowsPathAlias(normalizedParams.basename, "relative", "pinned write basename uses a Windows filesystem namespace alias");