pi-background-tasks 2.5.0 → 2.6.0

package/dist/src/core/durable-fs.js

@@ -0,0 +1,372 @@
+import { randomBytes } from 'node:crypto';
+import { open as nodeOpen, rename as nodeRename, rm as nodeRm } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+export class DurableFileCancellationError extends Error {
+    code = 'durable_file_cancelled';
+    path;
+    reason;
+    cleanupFailures;
+    targetPath;
+    temporaryPath;
+    renameCompleted;
+    constructor(input) {
+        const reasonText = describeCause(input.reason);
+        const cleanupText = input.cleanupFailures.length === 0
+            ? ''
+            : ` Cleanup failures: ${input.cleanupFailures.map(formatFailureForMessage).join('; ')}`;
+        const commitText = input.renameCompleted
+            ? ` Replacement may already be visible at ${input.targetPath ?? input.path}.`
+            : '';
+        super(`Durable file operation cancelled for ${input.path}: ${reasonText}.${commitText}${cleanupText}`);
+        this.name = 'DurableFileCancellationError';
+        this.path = input.path;
+        this.reason = input.reason;
+        this.cleanupFailures = [...input.cleanupFailures];
+        this.targetPath = input.targetPath;
+        this.temporaryPath = input.temporaryPath;
+        this.renameCompleted = input.renameCompleted;
+    }
+}
+export class DurableFileError extends Error {
+    operation;
+    path;
+    nativeCode;
+    primaryCause;
+    cleanupFailures;
+    targetPath;
+    temporaryPath;
+    renameCompleted;
+    constructor(input) {
+        super(formatDurableMessage(input));
+        this.name = 'DurableFileError';
+        this.operation = input.operation;
+        this.path = input.path;
+        this.nativeCode = nativeCodeForCause(input.cause);
+        this.primaryCause = input.cause;
+        this.cleanupFailures = [...input.cleanupFailures];
+        this.targetPath = input.targetPath;
+        this.temporaryPath = input.temporaryPath;
+        this.renameCompleted = input.renameCompleted;
+    }
+}
+function failure(operation, path, cause) {
+    return { operation, path, cause };
+}
+function durableError(input) {
+    return new DurableFileError(input);
+}
+function nativeCodeForCause(cause) {
+    if (typeof cause !== 'object' || cause === null)
+        return undefined;
+    const code = Reflect.get(cause, 'code');
+    return typeof code === 'string' ? code : undefined;
+}
+function describeCause(cause) {
+    if (cause instanceof Error) {
+        const message = cause.message.length > 0 ? cause.message : String(cause);
+        return `${cause.name}: ${message}`;
+    }
+    return String(cause);
+}
+function formatFailureForMessage(entry) {
+    const code = nativeCodeForCause(entry.cause);
+    const codeText = code === undefined ? '' : ` (code ${code})`;
+    return `${entry.operation} ${entry.path}${codeText}: ${describeCause(entry.cause)}`;
+}
+function formatDurableMessage(input) {
+    const primary = formatFailureForMessage({
+        operation: input.operation,
+        path: input.path,
+        cause: input.cause,
+    });
+    const segments = [`Durable file operation failed: ${primary}`];
+    if (input.targetPath !== undefined)
+        segments.push(`target: ${input.targetPath}`);
+    if (input.temporaryPath !== undefined)
+        segments.push(`temporary: ${input.temporaryPath}`);
+    if (input.renameCompleted) {
+        const target = input.targetPath ?? input.path;
+        segments.push(`Replacement may already be visible at ${target}.`);
+    }
+    if (input.cleanupFailures.length > 0) {
+        const cleanupText = input.cleanupFailures.map(formatFailureForMessage).join('; ');
+        segments.push(`Cleanup failures: ${cleanupText}`);
+    }
+    return segments.join(' ');
+}
+async function writeSyncClose(handle, path, data, signal) {
+    const cleanupFailures = [];
+    let primaryFailure;
+    let cancelled = signal?.aborted === true;
+    if (!cancelled) {
+        try {
+            await handle.writeFile(data);
+        }
+        catch (error) {
+            primaryFailure = failure('write_file', path, error);
+        }
+        cancelled = signal?.aborted === true;
+    }
+    if (primaryFailure === undefined && !cancelled) {
+        try {
+            await handle.sync();
+        }
+        catch (error) {
+            primaryFailure = failure('sync_file', path, error);
+        }
+        cancelled = signal?.aborted === true;
+    }
+    try {
+        await handle.close();
+    }
+    catch (error) {
+        const closeFailure = failure('close_file', path, error);
+        if (primaryFailure === undefined)
+            primaryFailure = closeFailure;
+        else
+            cleanupFailures.push(closeFailure);
+    }
+    cancelled ||= signal?.aborted === true;
+    return { primaryFailure, cleanupFailures, cancelled };
+}
+async function syncCloseDirectory(handle, path) {
+    const cleanupFailures = [];
+    let primaryFailure;
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        primaryFailure = failure('sync_directory', path, error);
+    }
+    try {
+        await handle.close();
+    }
+    catch (error) {
+        const closeFailure = failure('close_directory', path, error);
+        if (primaryFailure === undefined)
+            primaryFailure = closeFailure;
+        else
+            cleanupFailures.push(closeFailure);
+    }
+    return { primaryFailure, cleanupFailures, cancelled: false };
+}
+function cancellationReason(signal) {
+    return signal.reason ?? new Error('operation aborted');
+}
+function throwCancellation(signal, path, cleanupFailures, targetPath, temporaryPath, renameCompleted) {
+    const reason = cancellationReason(signal);
+    if (cleanupFailures.length === 0 && !renameCompleted && reason instanceof Error)
+        throw reason;
+    throw new DurableFileCancellationError({
+        path,
+        reason,
+        cleanupFailures,
+        targetPath,
+        temporaryPath,
+        renameCompleted,
+    });
+}
+function throwDurable(primaryFailure, cleanupFailures, targetPath, temporaryPath, renameCompleted) {
+    throw durableError({
+        operation: primaryFailure.operation,
+        path: primaryFailure.path,
+        cause: primaryFailure.cause,
+        cleanupFailures,
+        targetPath,
+        temporaryPath,
+        renameCompleted,
+    });
+}
+async function removeTemporary(operations, temporaryPath, cleanupFailures) {
+    try {
+        await operations.remove(temporaryPath);
+    }
+    catch (error) {
+        cleanupFailures.push(failure('remove_temp', temporaryPath, error));
+    }
+}
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+async function writeWithOperations(operations, path, data, options) {
+    const signal = options.signal;
+    if (signal !== undefined && isAborted(signal))
+        throwCancellation(signal, path, [], path, undefined, false);
+    let handle;
+    try {
+        handle = await operations.openWritable(path, 'w');
+    }
+    catch (error) {
+        if (signal !== undefined && isAborted(signal))
+            throwCancellation(signal, path, [], path, undefined, false);
+        throwDurable(failure('open_file', path, error), [], path, undefined, false);
+    }
+    const result = await writeSyncClose(handle, path, data, signal);
+    if (result.primaryFailure !== undefined) {
+        throwDurable(result.primaryFailure, result.cleanupFailures, path, undefined, false);
+    }
+    if (result.cancelled && signal !== undefined) {
+        throwCancellation(signal, path, result.cleanupFailures, path, undefined, false);
+    }
+}
+async function syncDirectoryAfterRename(operations, targetPath, temporaryPath) {
+    if (operations.platform === 'win32')
+        return;
+    const directoryPath = dirname(targetPath);
+    let handle;
+    try {
+        handle = await operations.openDirectory(directoryPath);
+    }
+    catch (error) {
+        throwDurable(failure('open_directory', directoryPath, error), [], targetPath, temporaryPath, true);
+    }
+    const result = await syncCloseDirectory(handle, directoryPath);
+    if (result.primaryFailure !== undefined) {
+        throwDurable(result.primaryFailure, result.cleanupFailures, targetPath, temporaryPath, true);
+    }
+}
+async function replaceWithOperations(operations, path, data, options) {
+    const signal = options.signal;
+    if (signal !== undefined && isAborted(signal))
+        throwCancellation(signal, path, [], path, undefined, false);
+    const temporaryPath = operations.temporaryPath(path);
+    let handle;
+    try {
+        handle = await operations.openWritable(temporaryPath, 'wx', 0o600);
+    }
+    catch (error) {
+        if (signal !== undefined && isAborted(signal))
+            throwCancellation(signal, temporaryPath, [], path, temporaryPath, false);
+        throwDurable(failure('open_file', temporaryPath, error), [], path, temporaryPath, false);
+    }
+    const writeResult = await writeSyncClose(handle, temporaryPath, data, signal);
+    if (writeResult.primaryFailure !== undefined) {
+        await removeTemporary(operations, temporaryPath, writeResult.cleanupFailures);
+        throwDurable(writeResult.primaryFailure, writeResult.cleanupFailures, path, temporaryPath, false);
+    }
+    if (writeResult.cancelled && signal !== undefined) {
+        await removeTemporary(operations, temporaryPath, writeResult.cleanupFailures);
+        throwCancellation(signal, temporaryPath, writeResult.cleanupFailures, path, temporaryPath, false);
+    }
+    const renameResult = await renameWithWindowsContention(operations, temporaryPath, path, signal);
+    if (renameResult.cancelled && signal !== undefined) {
+        const cleanupFailures = [];
+        await removeTemporary(operations, temporaryPath, cleanupFailures);
+        throwCancellation(signal, temporaryPath, cleanupFailures, path, temporaryPath, false);
+    }
+    if (renameResult.error !== undefined) {
+        const cleanupFailures = [];
+        await removeTemporary(operations, temporaryPath, cleanupFailures);
+        throwDurable(failure('rename_file', path, renameResult.error), cleanupFailures, path, temporaryPath, false);
+    }
+    await syncDirectoryAfterRename(operations, path, temporaryPath);
+    if (signal !== undefined && isAborted(signal)) {
+        throwCancellation(signal, path, [], path, temporaryPath, true);
+    }
+}
+/**
+ * Windows sharing-violation codes for a replace-rename.
+ *
+ * POSIX `rename(2)` atomically replaces the target. Windows `MoveFileEx` fails
+ * with a sharing violation when another process momentarily holds the target
+ * open, including transient scanners, indexers, and concurrent writers. The
+ * operation is legitimate and simply needs to be reattempted.
+ */
+const WINDOWS_RENAME_CONTENTION_CODES = new Set([
+    'EPERM',
+    'EACCES',
+    'EBUSY',
+]);
+const WINDOWS_RENAME_ATTEMPTS = 10;
+const WINDOWS_RENAME_RETRY_DELAY_MS = 20;
+function delay(ms, signal) {
+    if (isAborted(signal))
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', aborted);
+            resolve();
+        }, ms);
+        const aborted = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal?.addEventListener('abort', aborted, { once: true });
+    });
+}
+/**
+ * Rename the temporary file over the target, retrying only Windows sharing
+ * violations.
+ *
+ * This is a bounded retry of a transient OS condition, not a fallback: the
+ * final failure is still returned and raised loudly, no alternative write path
+ * is taken, and no other platform or error code is retried.
+ *
+ * Returns an explicit success/error/cancellation sequence result.
+ */
+async function renameWithWindowsContention(operations, temporaryPath, targetPath, signal) {
+    const attempts = operations.platform === 'win32' ? WINDOWS_RENAME_ATTEMPTS : 1;
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        if (isAborted(signal))
+            return { error: undefined, cancelled: true };
+        try {
+            await operations.rename(temporaryPath, targetPath);
+            return { error: undefined, cancelled: false };
+        }
+        catch (error) {
+            lastError = error;
+            if (isAborted(signal))
+                return { error: undefined, cancelled: true };
+            const code = nativeCodeForCause(error);
+            const retryable = operations.platform === 'win32' &&
+                code !== undefined &&
+                WINDOWS_RENAME_CONTENTION_CODES.has(code);
+            if (!retryable || attempt === attempts)
+                return { error, cancelled: false };
+            await delay(WINDOWS_RENAME_RETRY_DELAY_MS * attempt, signal);
+        }
+    }
+    return { error: lastError, cancelled: false };
+}
+function temporaryPathForTarget(target) {
+    return join(dirname(target), `.${basename(target)}.${String(process.pid)}.${randomBytes(6).toString('hex')}.tmp`);
+}
+const nodeOperations = {
+    platform: process.platform,
+    async openWritable(path, flag, mode) {
+        if (mode === undefined)
+            return nodeOpen(path, flag);
+        return nodeOpen(path, flag, mode);
+    },
+    async openDirectory(path) {
+        return nodeOpen(path, 'r');
+    },
+    async rename(source, target) {
+        await nodeRename(source, target);
+    },
+    async remove(path) {
+        // `force` ignores a missing path only. Permission and other failures still
+        // throw and are surfaced as `remove_temp` cleanup failures.
+        await nodeRm(path, { force: true });
+    },
+    temporaryPath: temporaryPathForTarget,
+};
+const defaultWriter = createDurableFileWriter(nodeOperations);
+export function createDurableFileWriter(operations) {
+    return {
+        async write(path, data, options = {}) {
+            await writeWithOperations(operations, path, data, options);
+        },
+        async replace(path, data, options = {}) {
+            await replaceWithOperations(operations, path, data, options);
+        },
+    };
+}
+export async function writeFileDurable(path, data, options = {}) {
+    await defaultWriter.write(path, data, options);
+}
+export async function replaceFileDurable(path, data, options = {}) {
+    await defaultWriter.replace(path, data, options);
+}
+//# sourceMappingURL=durable-fs.js.map

package/dist/src/core/durable-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-fs.js","sourceRoot":"","sources":["../../../src/core/durable-fs.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomBytes } from 'node:crypto';\nimport { open as nodeOpen, rename as nodeRename, rm as nodeRm } from 'node:fs/promises';\nimport { basename, dirname, join } from 'node:path';\n\nexport type DurableData = Buffer | string;\nexport type DurableWriteFlag = 'w' | 'wx';\nexport type DurableOperation =\n  | 'open_file'\n  | 'write_file'\n  | 'sync_file'\n  | 'close_file'\n  | 'rename_file'\n  | 'remove_temp'\n  | 'open_directory'\n  | 'sync_directory'\n  | 'close_directory';\n\nexport interface DurableFailure {\n  operation: DurableOperation;\n  path: string;\n  cause: unknown;\n}\n\nexport interface DurableWritableHandle {\n  writeFile(data: DurableData): Promise<void>;\n  sync(): Promise<void>;\n  close(): Promise<void>;\n}\n\nexport interface DurableDirectoryHandle {\n  sync(): Promise<void>;\n  close(): Promise<void>;\n}\n\nexport interface DurableFileOperations {\n  platform: NodeJS.Platform;\n  openWritable(\n    path: string,\n    flag: DurableWriteFlag,\n    mode?: number,\n  ): Promise<DurableWritableHandle>;\n  openDirectory(path: string): Promise<DurableDirectoryHandle>;\n  rename(source: string, target: string): Promise<void>;\n  remove(path: string): Promise<void>;\n  temporaryPath(target: string): string;\n}\n\nexport interface DurableWriteOptions {\n  readonly signal?: AbortSignal | undefined;\n}\n\nexport interface DurableFileWriter {\n  write(path: string, data: DurableData, options?: DurableWriteOptions): Promise<void>;\n  replace(path: string, data: DurableData, options?: DurableWriteOptions): Promise<void>;\n}\n\ninterface DurableErrorInput {\n  operation: DurableOperation;\n  path: string;\n  cause: unknown;\n  cleanupFailures: readonly DurableFailure[];\n  targetPath: string | undefined;\n  temporaryPath: string | undefined;\n  renameCompleted: boolean;\n}\n\ninterface WritableSequenceResult {\n  primaryFailure: DurableFailure | undefined;\n  cleanupFailures: DurableFailure[];\n  cancelled: boolean;\n}\n\ninterface RenameSequenceResult {\n  error: unknown | undefined;\n  cancelled: boolean;\n}\n\nexport class DurableFileCancellationError extends Error {\n  readonly code = 'durable_file_cancelled';\n  readonly path: string;\n  readonly reason: unknown;\n  readonly cleanupFailures: readonly DurableFailure[];\n  readonly targetPath: string | undefined;\n  readonly temporaryPath: string | undefined;\n  readonly renameCompleted: boolean;\n\n  constructor(input: {\n    path: string;\n    reason: unknown;\n    cleanupFailures: readonly DurableFailure[];\n    targetPath: string | undefined;\n    temporaryPath: string | undefined;\n    renameCompleted: boolean;\n  }) {\n    const reasonText = describeCause(input.reason);\n    const cleanupText =\n      input.cleanupFailures.length === 0\n        ? ''\n        : ` Cleanup failures: ${input.cleanupFailures.map(formatFailureForMessage).join('; ')}`;\n    const commitText = input.renameCompleted\n      ? ` Replacement may already be visible at ${input.targetPath ?? input.path}.`\n      : '';\n    super(`Durable file operation cancelled for ${input.path}: ${reasonText}.${commitText}${cleanupText}`);\n    this.name = 'DurableFileCancellationError';\n    this.path = input.path;\n    this.reason = input.reason;\n    this.cleanupFailures = [...input.cleanupFailures];\n    this.targetPath = input.targetPath;\n    this.temporaryPath = input.temporaryPath;\n    this.renameCompleted = input.renameCompleted;\n  }\n}\n\nexport class DurableFileError extends Error {\n  readonly operation: DurableOperation;\n  readonly path: string;\n  readonly nativeCode: string | undefined;\n  readonly primaryCause: unknown;\n  readonly cleanupFailures: readonly DurableFailure[];\n  readonly targetPath: string | undefined;\n  readonly temporaryPath: string | undefined;\n  readonly renameCompleted: boolean;\n\n  constructor(input: {\n    operation: DurableOperation;\n    path: string;\n    cause: unknown;\n    cleanupFailures: readonly DurableFailure[];\n    targetPath: string | undefined;\n    temporaryPath: string | undefined;\n    renameCompleted: boolean;\n  }) {\n    super(formatDurableMessage(input));\n    this.name = 'DurableFileError';\n    this.operation = input.operation;\n    this.path = input.path;\n    this.nativeCode = nativeCodeForCause(input.cause);\n    this.primaryCause = input.cause;\n    this.cleanupFailures = [...input.cleanupFailures];\n    this.targetPath = input.targetPath;\n    this.temporaryPath = input.temporaryPath;\n    this.renameCompleted = input.renameCompleted;\n  }\n}\n\nfunction failure(operation: DurableOperation, path: string, cause: unknown): DurableFailure {\n  return { operation, path, cause };\n}\n\nfunction durableError(input: DurableErrorInput): DurableFileError {\n  return new DurableFileError(input);\n}\n\nfunction nativeCodeForCause(cause: unknown): string | undefined {\n  if (typeof cause !== 'object' || cause === null) return undefined;\n  const code = Reflect.get(cause, 'code');\n  return typeof code === 'string' ? code : undefined;\n}\n\nfunction describeCause(cause: unknown): string {\n  if (cause instanceof Error) {\n    const message = cause.message.length > 0 ? cause.message : String(cause);\n    return `${cause.name}: ${message}`;\n  }\n  return String(cause);\n}\n\nfunction formatFailureForMessage(entry: DurableFailure): string {\n  const code = nativeCodeForCause(entry.cause);\n  const codeText = code === undefined ? '' : ` (code ${code})`;\n  return `${entry.operation} ${entry.path}${codeText}: ${describeCause(entry.cause)}`;\n}\n\nfunction formatDurableMessage(input: DurableErrorInput): string {\n  const primary = formatFailureForMessage({\n    operation: input.operation,\n    path: input.path,\n    cause: input.cause,\n  });\n  const segments = [`Durable file operation failed: ${primary}`];\n  if (input.targetPath !== undefined) segments.push(`target: ${input.targetPath}`);\n  if (input.temporaryPath !== undefined) segments.push(`temporary: ${input.temporaryPath}`);\n  if (input.renameCompleted) {\n    const target = input.targetPath ?? input.path;\n    segments.push(`Replacement may already be visible at ${target}.`);\n  }\n  if (input.cleanupFailures.length > 0) {\n    const cleanupText = input.cleanupFailures.map(formatFailureForMessage).join('; ');\n    segments.push(`Cleanup failures: ${cleanupText}`);\n  }\n  return segments.join(' ');\n}\n\nasync function writeSyncClose(\n  handle: DurableWritableHandle,\n  path: string,\n  data: DurableData,\n  signal?: AbortSignal,\n): Promise<WritableSequenceResult> {\n  const cleanupFailures: DurableFailure[] = [];\n  let primaryFailure: DurableFailure | undefined;\n  let cancelled = signal?.aborted === true;\n  if (!cancelled) {\n    try {\n      await handle.writeFile(data);\n    } catch (error) {\n      primaryFailure = failure('write_file', path, error);\n    }\n    cancelled = signal?.aborted === true;\n  }\n  if (primaryFailure === undefined && !cancelled) {\n    try {\n      await handle.sync();\n    } catch (error) {\n      primaryFailure = failure('sync_file', path, error);\n    }\n    cancelled = signal?.aborted === true;\n  }\n  try {\n    await handle.close();\n  } catch (error) {\n    const closeFailure = failure('close_file', path, error);\n    if (primaryFailure === undefined) primaryFailure = closeFailure;\n    else cleanupFailures.push(closeFailure);\n  }\n  cancelled ||= signal?.aborted === true;\n  return { primaryFailure, cleanupFailures, cancelled };\n}\n\nasync function syncCloseDirectory(\n  handle: DurableDirectoryHandle,\n  path: string,\n): Promise<WritableSequenceResult> {\n  const cleanupFailures: DurableFailure[] = [];\n  let primaryFailure: DurableFailure | undefined;\n  try {\n    await handle.sync();\n  } catch (error) {\n    primaryFailure = failure('sync_directory', path, error);\n  }\n  try {\n    await handle.close();\n  } catch (error) {\n    const closeFailure = failure('close_directory', path, error);\n    if (primaryFailure === undefined) primaryFailure = closeFailure;\n    else cleanupFailures.push(closeFailure);\n  }\n  return { primaryFailure, cleanupFailures, cancelled: false };\n}\n\nfunction cancellationReason(signal: AbortSignal): unknown {\n  return signal.reason ?? new Error('operation aborted');\n}\n\nfunction throwCancellation(\n  signal: AbortSignal,\n  path: string,\n  cleanupFailures: readonly DurableFailure[],\n  targetPath: string | undefined,\n  temporaryPath: string | undefined,\n  renameCompleted: boolean,\n): never {\n  const reason = cancellationReason(signal);\n  if (cleanupFailures.length === 0 && !renameCompleted && reason instanceof Error) throw reason;\n  throw new DurableFileCancellationError({\n    path,\n    reason,\n    cleanupFailures,\n    targetPath,\n    temporaryPath,\n    renameCompleted,\n  });\n}\n\nfunction throwDurable(\n  primaryFailure: DurableFailure,\n  cleanupFailures: readonly DurableFailure[],\n  targetPath: string | undefined,\n  temporaryPath: string | undefined,\n  renameCompleted: boolean,\n): never {\n  throw durableError({\n    operation: primaryFailure.operation,\n    path: primaryFailure.path,\n    cause: primaryFailure.cause,\n    cleanupFailures,\n    targetPath,\n    temporaryPath,\n    renameCompleted,\n  });\n}\n\nasync function removeTemporary(\n  operations: DurableFileOperations,\n  temporaryPath: string,\n  cleanupFailures: DurableFailure[],\n): Promise<void> {\n  try {\n    await operations.remove(temporaryPath);\n  } catch (error) {\n    cleanupFailures.push(failure('remove_temp', temporaryPath, error));\n  }\n}\n\nfunction isAborted(signal: AbortSignal | undefined): boolean {\n  return signal?.aborted === true;\n}\n\nasync function writeWithOperations(\n  operations: DurableFileOperations,\n  path: string,\n  data: DurableData,\n  options: DurableWriteOptions,\n): Promise<void> {\n  const signal = options.signal;\n  if (signal !== undefined && isAborted(signal))\n    throwCancellation(signal, path, [], path, undefined, false);\n  let handle: DurableWritableHandle;\n  try {\n    handle = await operations.openWritable(path, 'w');\n  } catch (error) {\n    if (signal !== undefined && isAborted(signal))\n      throwCancellation(signal, path, [], path, undefined, false);\n    throwDurable(failure('open_file', path, error), [], path, undefined, false);\n  }\n  const result = await writeSyncClose(handle, path, data, signal);\n  if (result.primaryFailure !== undefined) {\n    throwDurable(result.primaryFailure, result.cleanupFailures, path, undefined, false);\n  }\n  if (result.cancelled && signal !== undefined) {\n    throwCancellation(signal, path, result.cleanupFailures, path, undefined, false);\n  }\n}\n\nasync function syncDirectoryAfterRename(\n  operations: DurableFileOperations,\n  targetPath: string,\n  temporaryPath: string,\n): Promise<void> {\n  if (operations.platform === 'win32') return;\n  const directoryPath = dirname(targetPath);\n  let handle: DurableDirectoryHandle;\n  try {\n    handle = await operations.openDirectory(directoryPath);\n  } catch (error) {\n    throwDurable(failure('open_directory', directoryPath, error), [], targetPath, temporaryPath, true);\n  }\n  const result = await syncCloseDirectory(handle, directoryPath);\n  if (result.primaryFailure !== undefined) {\n    throwDurable(result.primaryFailure, result.cleanupFailures, targetPath, temporaryPath, true);\n  }\n}\n\nasync function replaceWithOperations(\n  operations: DurableFileOperations,\n  path: string,\n  data: DurableData,\n  options: DurableWriteOptions,\n): Promise<void> {\n  const signal = options.signal;\n  if (signal !== undefined && isAborted(signal))\n    throwCancellation(signal, path, [], path, undefined, false);\n  const temporaryPath = operations.temporaryPath(path);\n  let handle: DurableWritableHandle;\n  try {\n    handle = await operations.openWritable(temporaryPath, 'wx', 0o600);\n  } catch (error) {\n    if (signal !== undefined && isAborted(signal))\n      throwCancellation(signal, temporaryPath, [], path, temporaryPath, false);\n    throwDurable(failure('open_file', temporaryPath, error), [], path, temporaryPath, false);\n  }\n  const writeResult = await writeSyncClose(handle, temporaryPath, data, signal);\n  if (writeResult.primaryFailure !== undefined) {\n    await removeTemporary(operations, temporaryPath, writeResult.cleanupFailures);\n    throwDurable(writeResult.primaryFailure, writeResult.cleanupFailures, path, temporaryPath, false);\n  }\n  if (writeResult.cancelled && signal !== undefined) {\n    await removeTemporary(operations, temporaryPath, writeResult.cleanupFailures);\n    throwCancellation(\n      signal,\n      temporaryPath,\n      writeResult.cleanupFailures,\n      path,\n      temporaryPath,\n      false,\n    );\n  }\n  const renameResult = await renameWithWindowsContention(\n    operations,\n    temporaryPath,\n    path,\n    signal,\n  );\n  if (renameResult.cancelled && signal !== undefined) {\n    const cleanupFailures: DurableFailure[] = [];\n    await removeTemporary(operations, temporaryPath, cleanupFailures);\n    throwCancellation(signal, temporaryPath, cleanupFailures, path, temporaryPath, false);\n  }\n  if (renameResult.error !== undefined) {\n    const cleanupFailures: DurableFailure[] = [];\n    await removeTemporary(operations, temporaryPath, cleanupFailures);\n    throwDurable(\n      failure('rename_file', path, renameResult.error),\n      cleanupFailures,\n      path,\n      temporaryPath,\n      false,\n    );\n  }\n  await syncDirectoryAfterRename(operations, path, temporaryPath);\n  if (signal !== undefined && isAborted(signal)) {\n    throwCancellation(signal, path, [], path, temporaryPath, true);\n  }\n}\n\n/**\n * Windows sharing-violation codes for a replace-rename.\n *\n * POSIX `rename(2)` atomically replaces the target. Windows `MoveFileEx` fails\n * with a sharing violation when another process momentarily holds the target\n * open, including transient scanners, indexers, and concurrent writers. The\n * operation is legitimate and simply needs to be reattempted.\n */\nconst WINDOWS_RENAME_CONTENTION_CODES: ReadonlySet<string> = new Set([\n  'EPERM',\n  'EACCES',\n  'EBUSY',\n]);\n\nconst WINDOWS_RENAME_ATTEMPTS = 10;\nconst WINDOWS_RENAME_RETRY_DELAY_MS = 20;\n\nfunction delay(ms: number, signal?: AbortSignal): Promise<void> {\n  if (isAborted(signal)) return Promise.resolve();\n  return new Promise((resolve) => {\n    const timer = setTimeout(() => {\n      signal?.removeEventListener('abort', aborted);\n      resolve();\n    }, ms);\n    const aborted = () => {\n      clearTimeout(timer);\n      resolve();\n    };\n    signal?.addEventListener('abort', aborted, { once: true });\n  });\n}\n\n/**\n * Rename the temporary file over the target, retrying only Windows sharing\n * violations.\n *\n * This is a bounded retry of a transient OS condition, not a fallback: the\n * final failure is still returned and raised loudly, no alternative write path\n * is taken, and no other platform or error code is retried.\n *\n * Returns an explicit success/error/cancellation sequence result.\n */\nasync function renameWithWindowsContention(\n  operations: DurableFileOperations,\n  temporaryPath: string,\n  targetPath: string,\n  signal?: AbortSignal,\n): Promise<RenameSequenceResult> {\n  const attempts = operations.platform === 'win32' ? WINDOWS_RENAME_ATTEMPTS : 1;\n  let lastError: unknown;\n  for (let attempt = 1; attempt <= attempts; attempt++) {\n    if (isAborted(signal)) return { error: undefined, cancelled: true };\n    try {\n      await operations.rename(temporaryPath, targetPath);\n      return { error: undefined, cancelled: false };\n    } catch (error) {\n      lastError = error;\n      if (isAborted(signal)) return { error: undefined, cancelled: true };\n      const code = nativeCodeForCause(error);\n      const retryable =\n        operations.platform === 'win32' &&\n        code !== undefined &&\n        WINDOWS_RENAME_CONTENTION_CODES.has(code);\n      if (!retryable || attempt === attempts) return { error, cancelled: false };\n      await delay(WINDOWS_RENAME_RETRY_DELAY_MS * attempt, signal);\n    }\n  }\n  return { error: lastError, cancelled: false };\n}\n\nfunction temporaryPathForTarget(target: string): string {\n  return join(\n    dirname(target),\n    `.${basename(target)}.${String(process.pid)}.${randomBytes(6).toString('hex')}.tmp`,\n  );\n}\n\nconst nodeOperations: DurableFileOperations = {\n  platform: process.platform,\n  async openWritable(path: string, flag: DurableWriteFlag, mode?: number) {\n    if (mode === undefined) return nodeOpen(path, flag);\n    return nodeOpen(path, flag, mode);\n  },\n  async openDirectory(path: string) {\n    return nodeOpen(path, 'r');\n  },\n  async rename(source: string, target: string) {\n    await nodeRename(source, target);\n  },\n  async remove(path: string) {\n    // `force` ignores a missing path only. Permission and other failures still\n    // throw and are surfaced as `remove_temp` cleanup failures.\n    await nodeRm(path, { force: true });\n  },\n  temporaryPath: temporaryPathForTarget,\n};\n\nconst defaultWriter = createDurableFileWriter(nodeOperations);\n\nexport function createDurableFileWriter(operations: DurableFileOperations): DurableFileWriter {\n  return {\n    async write(\n      path: string,\n      data: DurableData,\n      options: DurableWriteOptions = {},\n    ): Promise<void> {\n      await writeWithOperations(operations, path, data, options);\n    },\n    async replace(\n      path: string,\n      data: DurableData,\n      options: DurableWriteOptions = {},\n    ): Promise<void> {\n      await replaceWithOperations(operations, path, data, options);\n    },\n  };\n}\n\nexport async function writeFileDurable(\n  path: string,\n  data: DurableData,\n  options: DurableWriteOptions = {},\n): Promise<void> {\n  await defaultWriter.write(path, data, options);\n}\n\nexport async function replaceFileDurable(\n  path: string,\n  data: DurableData,\n  options: DurableWriteOptions = {},\n): Promise<void> {\n  await defaultWriter.replace(path, data, options);\n}\n"]}