@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/permission-exec.js

@@ -8,7 +8,6 @@ export function formatPermissionErrorDetail(value) {
     const formatted = formatErrorDetail(value);
     return formatted.length > 400 ? `${formatted.slice(0, 399)}…` : formatted;
 }
-const MISSING_DATA_PROPERTY = Object.freeze({ found: false });
 const MAX_CAUGHT_FAILURE_PROTOTYPES = 4;
 const primitiveString = String;
 const isUint8Array = utilTypes.isUint8Array;
@@ -36,32 +35,28 @@ function isInspectableCaughtObject(value) {
     }
 }
 function dataProperty(value, name) {
-    if (!isInspectableCaughtObject(value))
-        return MISSING_DATA_PROPERTY;
     let current = value;
     for (let depth = 0; current !== null && depth < MAX_CAUGHT_FAILURE_PROTOTYPES; depth += 1) {
         if (!isInspectableCaughtObject(current))
-            return MISSING_DATA_PROPERTY;
+            return undefined;
         let descriptor;
         try {
             descriptor = Object.getOwnPropertyDescriptor(current, name);
         }
         catch {
-            return MISSING_DATA_PROPERTY;
+            return undefined;
         }
         if (descriptor) {
-            return Object.hasOwn(descriptor, "value")
-                ? { found: true, value: descriptor.value }
-                : MISSING_DATA_PROPERTY;
+            return Object.hasOwn(descriptor, "value") ? descriptor : undefined;
         }
         try {
             current = Object.getPrototypeOf(current);
         }
         catch {
-            return MISSING_DATA_PROPERTY;
+            return undefined;
         }
     }
-    return MISSING_DATA_PROPERTY;
+    return undefined;
 }
 function caughtPrimitiveDisplay(value) {
     if (value !== null && (typeof value === "object" || typeof value === "function"))
@@ -78,9 +73,9 @@ export function formatCaughtPermissionFailure(error) {
     }
     const message = dataProperty(error, "message");
     const name = dataProperty(error, "name");
-    const rawMessage = message.found && typeof message.value === "string"
+    const rawMessage = typeof message?.value === "string"
         ? message.value : "";
-    const rawName = name.found && typeof name.value === "string"
+    const rawName = typeof name?.value === "string"
         ? name.value : "";
     const messageText = rawMessage.slice(0, 400);
     const nameText = rawName.slice(0, 400);
@@ -123,12 +118,11 @@ function commandFailureFields(error) {
     const signal = dataProperty(error, "signal");
     const stderr = dataProperty(error, "stderr");
     return {
-        found: killed.found || code.found || signal.found || stderr.found,
-        timedOut: killed.found && killed.value === true &&
-            signal.found && signal.value === "SIGKILL",
-        exitCode: code.found && typeof code.value === "number" ? code.value : null,
-        signal: signal.found && typeof signal.value === "string" ? signal.value : null,
-        stderr: stderr.found ? safeStderr(stderr.value) : "",
+        found: !!(killed || code || signal || stderr),
+        timedOut: killed?.value === true && signal?.value === "SIGKILL",
+        exitCode: typeof code?.value === "number" ? code.value : null,
+        signal: typeof signal?.value === "string" ? signal.value : null,
+        stderr: stderr ? safeStderr(stderr.value) : "",
     };
 }
 export class PermissionCommandError extends Error {
@@ -155,20 +149,20 @@ export class PermissionCommandError extends Error {
 export function getPermissionCommandFailure(error, command, durationMs) {
     if (isInspectableCaughtObject(error) && utilTypes.isNativeError(error)) {
         const name = dataProperty(error, "name");
-        if (name.found && name.value === "PermissionCommandError") {
+        if (name?.value === "PermissionCommandError") {
             const wrappedCommand = dataProperty(error, "command");
             const wrappedDuration = dataProperty(error, "durationMs");
             const wrappedTimedOut = dataProperty(error, "timedOut");
             const wrappedExitCode = dataProperty(error, "exitCode");
             const wrappedSignal = dataProperty(error, "signal");
             const wrappedStderr = dataProperty(error, "stderr");
-            if (wrappedCommand.found && typeof wrappedCommand.value === "string" &&
-                wrappedDuration.found && typeof wrappedDuration.value === "number" &&
+            if (typeof wrappedCommand?.value === "string" &&
+                typeof wrappedDuration?.value === "number" &&
                 Number.isSafeInteger(wrappedDuration.value) && wrappedDuration.value >= 0 &&
-                wrappedTimedOut.found && typeof wrappedTimedOut.value === "boolean" &&
-                wrappedExitCode.found && (wrappedExitCode.value === null || typeof wrappedExitCode.value === "number") &&
-                wrappedSignal.found && (wrappedSignal.value === null || typeof wrappedSignal.value === "string") &&
-                wrappedStderr.found) {
+                typeof wrappedTimedOut?.value === "boolean" &&
+                wrappedExitCode && (wrappedExitCode.value === null || typeof wrappedExitCode.value === "number") &&
+                wrappedSignal && (wrappedSignal.value === null || typeof wrappedSignal.value === "string") &&
+                wrappedStderr) {
                 return {
                     command: wrappedCommand.value,
                     durationMs: wrappedDuration.value,

package/dist/permissions-public.d.ts

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

package/dist/permissions-windows.d.ts

@@ -1,5 +1,5 @@
 import { type PermissionCommandFailure } from "./permission-exec.js";
-import { type PermissionCheck, type PermissionCheckOptions, type SafeStatResult } from "./permissions.js";
+import { type PermissionCheck, type PermissionCheckOptions } from "./permissions.js";
 export type PermissionExec = (command: string, args: string[]) => Promise<{
     stdout: string;
     stderr: string;
@@ -31,14 +31,7 @@ export type IcaclsResetCommandOptions = {
     env?: NodeJS.ProcessEnv;
     userInfo?: WindowsUserInfoProvider;
 };
-export declare function inspectWindowsPermissions(params: {
-    targetPath: string;
-    stat: SafeStatResult;
-    effectiveIsDir: boolean;
-    effectiveMode: number | null;
-    bits: number | null;
-    opts?: PermissionCheckOptions;
-}): Promise<PermissionCheck>;
+export declare function inspectWindowsPermissions(targetPath: string, unverified: Readonly<PermissionCheck>, opts?: PermissionCheckOptions): Promise<PermissionCheck>;
 export declare function resolveWindowsUserPrincipal(env?: NodeJS.ProcessEnv, userInfo?: WindowsUserInfoProvider): string | null;
 export declare function parseIcaclsOutput(output: string, targetPath: string): WindowsAclEntry[];
 export declare function summarizeWindowsAcl(entries: WindowsAclEntry[], env?: NodeJS.ProcessEnv): Pick<WindowsAclSummary, "trusted" | "untrustedWorld" | "untrustedGroup">;
@@ -56,4 +49,3 @@ export declare function createIcaclsResetCommand(targetPath: string, opts: Icacl
     args: string[];
     display: string;
 } | null;
-//# sourceMappingURL=permissions-windows.d.ts.map

package/dist/permissions-windows.js

@@ -39,20 +39,16 @@ const TRUSTED_BASE_ASCII = new Set([...TRUSTED_BASE].map(stripDiacritics));
 const normalize = (value) => normalizeLowercaseStringOrEmpty(value);
 const defaultWindowsUserInfo = () => os.userInfo();
 const defaultPermissionExec = executePermissionCommand;
-function inspectWindowsPermissionsNative(params) {
+function inspectWindowsPermissionsNative(targetPath, unverified) {
     const native = getNativeBinding();
     if (!native)
         return undefined;
     try {
-        const facts = native.readOwnerAndDacl(params.targetPath);
+        const facts = native.readOwnerAndDacl(targetPath);
         if (facts.fallbackRequired)
             return undefined;
         return {
-            ok: true,
-            isSymlink: params.stat.isSymlink,
-            isDir: params.effectiveIsDir,
-            mode: params.effectiveMode,
-            bits: params.bits,
+            ...unverified,
             source: "windows-acl",
             worldWritable: facts.worldWritable,
             groupWritable: facts.groupWritable,
@@ -69,32 +65,20 @@ function inspectWindowsPermissionsNative(params) {
         return undefined;
     }
 }
-export async function inspectWindowsPermissions(params) {
-    const unverified = {
-        ok: true,
-        isSymlink: params.stat.isSymlink,
-        isDir: params.effectiveIsDir,
-        mode: params.effectiveMode,
-        bits: params.bits,
-        source: "unknown",
-        worldWritable: false,
-        groupWritable: false,
-        worldReadable: false,
-        groupReadable: false,
-    };
-    if (hasWindowsPathAlias(params.targetPath, "filesystem", "win32")) {
+export async function inspectWindowsPermissions(targetPath, unverified, opts) {
+    if (hasWindowsPathAlias(targetPath, "filesystem", "win32")) {
         return {
             ...unverified,
             error: "Path uses a Windows filesystem namespace alias",
         };
     }
-    const native = inspectWindowsPermissionsNative(params);
+    const native = inspectWindowsPermissionsNative(targetPath, unverified);
     if (native)
         return native;
     const owner = await inspectWindowsOwner({
-        targetPath: params.targetPath,
-        env: params.opts?.env,
-        exec: params.opts?.exec ?? defaultPermissionExec,
+        targetPath,
+        env: opts?.env,
+        exec: opts?.exec ?? defaultPermissionExec,
     });
     if (owner.error !== undefined) {
         const error = `Windows owner inspection failed: ${owner.error}`;
@@ -109,11 +93,7 @@ export async function inspectWindowsPermissions(params) {
     if (!acl.ok)
         return { ...unverified, ...ownerFields, error: acl.error, errorDetail: acl.errorDetail, errorCause: acl.errorCause };
     return {
-        ok: true,
-        isSymlink: params.stat.isSymlink,
-        isDir: params.effectiveIsDir,
-        mode: params.effectiveMode,
-        bits: params.bits,
+        ...unverified,
         source: "windows-acl",
         worldWritable: acl.untrustedWorld.some((entry) => entry.canWrite),
         groupWritable: acl.untrustedGroup.some((entry) => entry.canWrite),

package/dist/permissions.d.ts

@@ -57,4 +57,3 @@ export declare function isGroupWritable(bits: number | null): boolean;
 export declare function isWorldReadable(bits: number | null): boolean;
 export declare function isGroupReadable(bits: number | null): boolean;
 export declare function formatPosixMode(mode: number): string;
-//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.js

@@ -71,28 +71,20 @@ export async function inspectPathPermissions(targetPath, opts) {
     }
     const bits = modeBits(effectiveMode);
     const platform = opts?.platform ?? process.platform;
-    if (platform === "win32") {
-        return await inspectWindowsPermissions({
-            targetPath,
-            stat: st,
-            effectiveIsDir,
-            effectiveMode,
-            bits,
-            opts,
-        });
-    }
-    return {
+    const windows = platform === "win32";
+    const permissions = {
         ok: true,
         isSymlink: st.isSymlink,
         isDir: effectiveIsDir,
         mode: effectiveMode,
         bits,
-        source: "posix",
-        worldWritable: isWorldWritable(bits),
-        groupWritable: isGroupWritable(bits),
-        worldReadable: isWorldReadable(bits),
-        groupReadable: isGroupReadable(bits),
+        source: windows ? "unknown" : "posix",
+        worldWritable: !windows && isWorldWritable(bits),
+        groupWritable: !windows && isGroupWritable(bits),
+        worldReadable: !windows && isWorldReadable(bits),
+        groupReadable: !windows && isGroupReadable(bits),
     };
+    return windows ? await inspectWindowsPermissions(targetPath, permissions, opts) : permissions;
 }
 export function formatPermissionDetail(targetPath, perms) {
     if (perms.source === "windows-acl") {

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;
@@ -22,4 +22,3 @@ export declare function preparePinnedWriteMutationAdmission(params: {
     relativeParentPath: string;
     mutationAdmission?: PinnedWriteMutationAdmission;
 }>;
-//# sourceMappingURL=pinned-mutation-admission.d.ts.map

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

@@ -36,4 +36,3 @@ export declare function mutationObservationCurrent(observation: MutationPathObse
 export declare function mutationObservationsCurrent(observations: readonly MutationPathObservation[], directories: readonly MutationDirectoryObservation[]): boolean;
 export declare function advanceMutationObservation(observation: MutationPathObservation, parent: MutationDirectoryObservation, child: MutationDirectoryObservation): MutationPathObservation | undefined;
 export {};
-//# sourceMappingURL=pinned-mutation-observation.d.ts.map

package/dist/pinned-mutation-shared-route.d.ts

@@ -22,4 +22,3 @@ export declare function simpleSharedRoute(params: {
     rootIdentity: ExactRootIdentity;
 } | undefined;
 export {};
-//# sourceMappingURL=pinned-mutation-shared-route.d.ts.map

package/dist/pinned-open.d.ts

@@ -5,6 +5,7 @@ export type PinnedOpenSyncResult = {
     path: string;
     fd: number;
     stat: fs.Stats;
+    identity: fs.BigIntStats;
 } | {
     ok: false;
     reason: PinnedOpenSyncFailureReason;
@@ -27,4 +28,3 @@ export declare function openPinnedFileSync(params: {
     ioFs?: PinnedOpenSyncFs;
     finalAdmission?: PinnedOpenSyncFinalAdmission;
 }): PinnedOpenSyncResult;
-//# sourceMappingURL=pinned-open.d.ts.map

package/dist/pinned-open.js

@@ -63,7 +63,7 @@ export function openPinnedFileSync(params) {
             preRealpathIdentity: pathIdentity,
             descriptorIdentity: identity,
         }) ?? realPath;
-        const opened = { ok: true, path: admittedPath, fd, stat: openedStat };
+        const opened = { ok: true, path: admittedPath, fd, stat: openedStat, identity };
         fd = null;
         return opened;
     }
@@ -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,2 +1 @@
-export declare function validatePinnedOperationPayload(payload: Record<string, unknown>): void;
-//# sourceMappingURL=pinned-operation.d.ts.map
+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-input.d.ts

@@ -1,4 +1,3 @@
 import type { FileHandle } from "node:fs/promises";
 import type { PinnedWriteInput } from "./pinned-write-types.js";
 export declare function writePinnedInput(target: FileHandle | number, input: PinnedWriteInput, maxBytes?: number, assertBeforeMutation?: () => void): Promise<void>;
-//# sourceMappingURL=pinned-write-input.d.ts.map

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

@@ -2,4 +2,3 @@ import type { FileHandle } from "node:fs/promises";
 export declare function assertPinnedWriteMode(fd: number, mode: number, privateCreation?: boolean): void;
 export declare function preparePinnedWriteMode(handle: FileHandle, createdMode: number, assertBeforeMutation?: () => void, privateCreation?: boolean): Promise<(() => void) | undefined>;
 export declare function pinnedWriteModeAssertion(fd: number, mode: number, assertBeforeMutation?: () => void, privateCreation?: boolean): () => void;
-//# sourceMappingURL=pinned-write-mode.d.ts.map

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.d.ts

@@ -3,4 +3,3 @@ import type { AsyncDirectoryGuard } from "./directory-guard.js";
 import { type FileIdentityStat } from "./file-identity.js";
 import type { PinnedWriteParams } from "./pinned-write-types.js";
 export declare function runPinnedStagedWrite(params: PinnedWriteParams, parentPath: string, parentGuard: AsyncDirectoryGuard<BigIntStats>): Promise<FileIdentityStat>;
-//# sourceMappingURL=pinned-write-staged.d.ts.map

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-types.d.ts

@@ -24,18 +24,15 @@ export type PinnedCreatedDirectoryReceipt = Readonly<{
     parent: MutationDirectoryObservation;
     child: MutationDirectoryObservation;
 }>;
+export type PinnedMutationParentRequest = {
+    targetPath: string;
+    mutationPath: string;
+    phase: "parent" | "parent-create";
+};
 export type PinnedMutationParentWalkSession = Readonly<{
     retainedTargetPath: string;
-    tryAuthorizeAtParent(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
-    authorize(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>): Promise<PinnedMutationAdmissionReceipt | undefined>;
+    tryAuthorizeAtParent(request: Readonly<PinnedMutationParentRequest>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
+    authorize(request: Readonly<PinnedMutationParentRequest>): Promise<PinnedMutationAdmissionReceipt | undefined>;
     advanceCreatedDirectory(receipt: PinnedCreatedDirectoryReceipt): PinnedMutationAuthorizationToken | undefined;
     dispose(): void;
 }>;
@@ -44,16 +41,8 @@ export type PinnedWriteMutationAdmission = Readonly<{
     beginParentWalk?(): string | undefined;
     beginSharedParentWalk?(): PinnedMutationParentWalkSession | undefined;
     beginNativeParentWalk?(): PinnedMutationParentWalkSession | undefined;
-    tryAuthorizeAtParent?(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
-    authorize(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>): Promise<PinnedMutationAdmissionReceipt | undefined>;
+    tryAuthorizeAtParent?(request: Readonly<PinnedMutationParentRequest>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
+    authorize(request: Readonly<PinnedMutationParentRequest>): Promise<PinnedMutationAdmissionReceipt | undefined>;
     advanceCreatedDirectory?(receipt: PinnedCreatedDirectoryReceipt): PinnedMutationAuthorizationToken | undefined;
 }>;
 export type PinnedWriteParams = {
@@ -77,4 +66,3 @@ export type PinnedWriteParams = {
     onPublished?: (identity: PublishedWriteIdentity) => void;
     verifyPublished?: (fd: number, identity: PublishedWriteIdentity, parentGuard: AnyAsyncDirectoryGuard) => Promise<void>;
 };
-//# sourceMappingURL=pinned-write-types.d.ts.map

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;
@@ -11,4 +10,3 @@ export declare function withPinnedWriteRenameIdentityLock<T>(params: {
     targetPath: string;
     relativeTargetPath: string;
 }, run: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=pinned-write.d.ts.map

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");

package/dist/positional-read.d.ts

@@ -6,4 +6,3 @@ export type ReadFileWindowOptions = {
 export declare function readFileWindowFully(handle: FileHandle, buffer: Buffer, position: number, { signal }?: ReadFileWindowOptions): Promise<number>;
 /** Synchronous positional read; neither variant advances or closes its descriptor. */
 export declare function readFileWindowFullySync(fd: number, buffer: Buffer, position: number): number;
-//# sourceMappingURL=positional-read.d.ts.map

package/dist/private-directory.d.ts

@@ -2,4 +2,3 @@ export type CreatePrivateDirectoryOptions = {
     platform?: NodeJS.Platform;
 };
 export declare function createPrivateDirectory(targetPath: string, options?: CreatePrivateDirectoryOptions): Promise<void>;
-//# sourceMappingURL=private-directory.d.ts.map

package/dist/private-producer-handoff-sync.d.ts

@@ -1,14 +1,3 @@
-import { type BigIntStats } from "node:fs";
 import { type OwnedFileDescriptorSync } from "./create-owned-file.js";
-export declare function handoffCreatedFileSync(params: {
-    source: OwnedFileDescriptorSync;
-    sourcePath: string;
-    targetPath: string;
-    identity: BigIntStats;
-    assertSourceParent: () => void;
-    assertTargetParent: () => void;
-    assertBeforeMutation?: () => void;
-    verifyDescriptor?: (fd: number, path: string, links: number) => void;
-    onPublished?: () => void;
-}): OwnedFileDescriptorSync;
-//# sourceMappingURL=private-producer-handoff-sync.d.ts.map
+import { type CreatedHandoffParams } from "./private-producer-handoff.js";
+export declare function handoffCreatedFileSync(params: CreatedHandoffParams<OwnedFileDescriptorSync, void>): OwnedFileDescriptorSync;

package/dist/private-producer-handoff-sync.js

@@ -1,16 +1,13 @@
-import fs, {} from "node:fs";
+import fs from "node:fs";
 import { ownFileDescriptorSync } from "./create-owned-file.js";
-import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult } from "./mutation-authority.js";
-import { assertInitialSource, assertParents, inspectLinkedFile, normalizeLinkError, } from "./private-producer-handoff.js";
+import { assertInitialSource, FileHandoff, inspectLinkedFile, } from "./private-producer-handoff.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 export function handoffCreatedFileSync(params) {
     let retained = params.source;
     const owners = new Set([retained]);
     const failures = [];
-    let publication = "not-published";
-    let cleanup = "preserved";
-    let closeFailed = false;
+    const state = new FileHandoff(params, params.identity, true);
     function close(owner) {
         // A throwing close may already have released the descriptor for reuse.
         owners.delete(owner);
@@ -18,42 +15,20 @@ export function handoffCreatedFileSync(params) {
             owner.close();
         }
         catch (error) {
-            closeFailed = true;
+            state.closeFailed = true;
             throw error;
         }
     }
-    function assertIdentityCurrent(owner, links) {
-        assertParents(params);
-        inspectLinkedFile(() => fs.fstatSync(owner.fd, { bigint: true }), params.identity, links, "created file descriptor");
-        if (cleanup !== "removed") {
-            inspectLinkedFile(() => fs.lstatSync(params.sourcePath, { bigint: true }), params.identity, links, "created file stage");
-        }
-        if (publication === "published") {
-            inspectLinkedFile(() => fs.lstatSync(params.targetPath, { bigint: true }), params.identity, links, "created file destination");
-        }
-    }
     function verifyCurrent(owner, descriptorPath, links) {
-        assertIdentityCurrent(owner, links);
+        state.inspect(owner, links);
         params.verifyDescriptor?.(owner.fd, descriptorPath, Number(links));
     }
     try {
         assertInitialSource(params.identity);
         verifyCurrent(retained, params.sourcePath, 1n);
         assertSynchronousCallbackResult(params.assertBeforeMutation?.(), "assertBeforeMutation");
-        assertIdentityCurrent(retained, 1n);
-        publication = "indeterminate";
-        try {
-            fs.linkSync(params.sourcePath, params.targetPath);
-        }
-        catch (error) {
-            const normalized = normalizeLinkError(error);
-            if (normalized instanceof FsSafeError &&
-                (normalized.code === "already-exists" || normalized.code === "helper-unavailable")) {
-                publication = "not-published";
-            }
-            throw normalized;
-        }
-        publication = "published";
+        state.inspect(retained, 1n);
+        state.publish();
         try {
             params.onPublished?.();
         }
@@ -74,12 +49,10 @@ export function handoffCreatedFileSync(params) {
         const descriptorPath = process.platform === "win32" ? params.targetPath : params.sourcePath;
         verifyCurrent(retained, descriptorPath, 2n);
         assertSynchronousCallbackResult(params.assertBeforeMutation?.(), "assertBeforeMutation");
-        assertIdentityCurrent(retained, 2n);
-        cleanup = "failed";
+        state.inspect(retained, 2n);
         // Link and unlink stay in one JS turn. Only the verified stage is removed;
         // publication has committed and the destination is never rollback cleanup.
-        fs.unlinkSync(params.sourcePath);
-        cleanup = "removed";
+        state.retireSource();
         verifyCurrent(retained, params.targetPath, 1n);
     }
     catch (error) {
@@ -95,20 +68,5 @@ export function handoffCreatedFileSync(params) {
             failures.push(error);
         }
     }
-    const primary = failures[0];
-    // Collision-as-no-op callers must still observe a failed settlement.
-    const code = closeFailed || failures.length > 1
-        ? "helper-failed"
-        : primary instanceof FsSafeError ? primary.code : "helper-failed";
-    throw new FsSafeError(code, "created file publication failed", {
-        cause: failures.length === 1 ? primary : new AggregateError(failures, "created file publication and settlement failed"),
-        details: {
-            publication: { status: publication },
-            cleanup,
-            resources: closeFailed ? "close-failed" : "closed",
-            path: params.targetPath,
-            dev: params.identity.dev,
-            ino: params.identity.ino,
-        },
-    });
+    throw state.failure(failures, "created file publication and settlement failed");
 }