@openclaw/fs-safe 0.18.0 → 0.18.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.18.1 - 2026-09-22
+
+### Fixes
+
+- **Durable queue errors:** preserve the original read, validation, callback, or migration failure when closing the read descriptor also fails.
+- **Secure temporary directories:** stop rejecting valid directories when Node reports negative device or inode IDs. Thanks @vincentkoc. ([#586](https://github.com/openclaw/fs-safe/pull/586))
+- **Root write hardening:** prevent extra properties in wider options objects from enabling private writer controls or applying streamed-create byte limits to buffered writes. ([#571](https://github.com/openclaw/fs-safe/pull/571))
+- **Error reporting:** preserve original errors from directory checks, secret reads, and Root opens when descriptor cleanup also fails. ([#574](https://github.com/openclaw/fs-safe/pull/574))
+- **Lock timeouts:** keep async and sync retry deadlines stable when the system clock changes. Preserve wall-clock lock timestamps and stale-age checks.
+
 ## 0.18.0 - 2026-09-21
 
 ### Highlights

package/dist/advanced.d.ts

@@ -7,7 +7,8 @@ export { probePathCaseInsensitiveSync, type ProbePathCaseOptions } from "./path-
 export { resolvePathPrefixSync, type ResolvedPathPrefix } from "./path-prefix.js";
 export { probePathSuffixAliasesSync, type ProbePathSuffixAliasesOptions } from "./path-suffix-aliases.js";
 export { readDirectoryIdentity, assertDirectoryIdentitySync, type DirectoryIdentity, } from "./directory-guard.js";
-export { stageFileInDirectory, type StagedFile, type StagedFileReceipt, type PublishedFileReceipt, type StagedFilePublication, type StagedFileCleanupReceipt, type StagedFileFailureDetails, } from "./native-staged-file.js";
+export { stageFileInDirectory, } from "./native-staged-file.js";
+export type { StagedFile, StagedFileReceipt, PublishedFileReceipt, StagedFilePublication, StagedFileCleanupReceipt, StagedFileFailureDetails, } from "./staged-file-types.js";
 export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
 export { readFileWindowFully, readFileWindowFullySync, type ReadFileWindowOptions, } from "./positional-read.js";
 export { writeFileWindowFully, type WriteFileWindowOptions } from "./write-file-handle.js";

package/dist/archive-durability.d.ts

@@ -1,6 +1,6 @@
 import { type ExtractionDeadline } from "./archive-deadline.js";
 import { type ArchiveDirectoryGuard } from "./archive-staging.js";
-import type { PublishedWriteIdentity } from "./pinned-write.js";
+import type { PublishedWriteIdentity } from "./pinned-write-types.js";
 import type { Root } from "./root.js";
 export type ArchivePublishedFile = {
     relativePath: string;

package/dist/archive-plan.d.ts

@@ -1,7 +1,6 @@
 import type { ArchiveKind } from "./archive-kind.js";
-import { type ResolvedArchiveExtractLimits } from "./archive-limits.js";
-import type { ExtractArchiveOptions } from "./archive-options.js";
-import { type ArchiveEntryKind } from "./archive-policy.js";
+import { type ResolvedArchiveExtractLimits, type ArchiveExtractLimits } from "./archive-limits.js";
+import type { ExtractionDeadline } from "./archive-deadline.js";
 export type ArchiveMemberKind = "file" | "directory" | "symlink" | "hardlink" | "blocked" | "sparse" | "other";
 export type ArchivePlanEntry = {
     path: string;
@@ -27,3 +26,65 @@ export declare function createArchiveEntryPlanner(params: ArchivePlanOptions, ar
     size: number;
     mode?: number;
 }) => ArchivePlanEntry | null;
+export type ArchiveEntryKind = "file" | "directory" | "symlink" | "other";
+export type ArchiveEntryModePolicy = "clamp" | "preserve";
+export type ArchiveFilteredEntryPolicy = "reject-archive" | "skip-entry";
+export type ArchiveEntryFilter = (entry: {
+    /** Validated canonical archive path before stripping: / separators, no empty or . components. */
+    path: string;
+    kind: ArchiveEntryKind;
+    size: number;
+}) => "extract" | "skip";
+export declare function archiveEntryKindFromTarType(type: string): ArchiveEntryKind;
+export declare function resolveArchiveEntryMode(params: {
+    kind: "file" | "directory";
+    archivedMode?: number | null;
+    policy?: ArchiveEntryModePolicy;
+}): number;
+export declare function resolveArchiveFilteredEntryPolicy(value: unknown): ArchiveFilteredEntryPolicy;
+export declare function shouldExtractArchiveEntry(params: {
+    filter?: ArchiveEntryFilter;
+    onFiltered?: ArchiveFilteredEntryPolicy;
+    entry: Parameters<ArchiveEntryFilter>[0];
+}): boolean;
+export type TarEntryInfo = {
+    path: string;
+    type: string;
+    size: number;
+    mode?: number;
+};
+export declare function createTarEntryPlanner(params: ArchivePlanOptions): (entry: TarEntryInfo) => ArchivePlanEntry | null;
+export declare function createTarEntryPreflightChecker(params: {
+    rootDir: string;
+    stripComponents?: number;
+    limits?: ArchiveExtractLimits;
+    escapeLabel?: string;
+    entryFilter?: ArchiveEntryFilter;
+    onFiltered?: ArchiveFilteredEntryPolicy;
+}): (entry: TarEntryInfo) => boolean;
+export type ArchiveLogger = {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+};
+export type ExtractArchiveOptions = {
+    archivePath: string;
+    destDir: string;
+    timeoutMs: number;
+    /** Sync published files and directories before returning. Defaults to false. */
+    durable?: boolean;
+    kind?: ArchiveKind;
+    stripComponents?: number;
+    tarGzip?: boolean;
+    limits?: ArchiveExtractLimits;
+    logger?: ArchiveLogger;
+    entryModes?: ArchiveEntryModePolicy;
+    /** Remove these rwx bits from final entry modes. Defaults to zero. */
+    entryUmask?: number;
+    entryFilter?: ArchiveEntryFilter;
+    onFiltered?: ArchiveFilteredEntryPolicy;
+};
+/** Private executors receive owned options and an already-staged archive path. */
+export type StagedArchiveExtractOptions = Pick<ExtractArchiveOptions, "archivePath" | "destDir" | "durable" | "stripComponents" | "entryModes" | "entryUmask" | "entryFilter" | "onFiltered"> & {
+    limits: ResolvedArchiveExtractLimits;
+    deadline: ExtractionDeadline;
+};

package/dist/archive-plan.js

@@ -1,7 +1,6 @@
 import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
 import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, resolveExtractLimits, } from "./archive-limits.js";
-import { resolveArchiveEntryMode, shouldExtractArchiveEntry } from "./archive-policy.js";
 import { formatErrorDetail } from "./error-detail.js";
 // Portable ZIP selects each entry immediately before streaming its payload;
 // manifest-backed routes add declared-byte admission through the planner below.
@@ -63,3 +62,58 @@ export function createArchiveEntryPlanner(params, archiveKind) {
             mode: resolveArchiveEntryMode({ kind, archivedMode: entry.mode, policy: params.entryModes }) };
     };
 }
+export function archiveEntryKindFromTarType(type) {
+    if (type === "Directory" || type === "GNUDumpDir")
+        return "directory";
+    if (type === "File" || type === "OldFile" || type === "ContiguousFile")
+        return "file";
+    if (type === "SymbolicLink" || type === "Link")
+        return "symlink";
+    return "other";
+}
+export function resolveArchiveEntryMode(params) {
+    const archivedMode = (params.archivedMode ?? 0) & 0o777;
+    if (params.policy === "preserve") {
+        return params.archivedMode == null ? (params.kind === "directory" ? 0o755 : 0o644) : archivedMode;
+    }
+    if (params.kind === "directory") {
+        return 0o755;
+    }
+    return archivedMode & 0o100 ? 0o755 : 0o644;
+}
+export function resolveArchiveFilteredEntryPolicy(value) {
+    if (value === undefined || value === "reject-archive")
+        return "reject-archive";
+    if (value === "skip-entry")
+        return "skip-entry";
+    throw new RangeError('archive onFiltered must be "reject-archive" or "skip-entry"');
+}
+export function shouldExtractArchiveEntry(params) {
+    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
+    if (!params.filter || params.filter(params.entry) === "extract") {
+        return true;
+    }
+    if (onFiltered === "reject-archive") {
+        throw new ArchiveSecurityError("entry-filtered", `archive entry rejected by filter: ${formatErrorDetail(params.entry.path)}`);
+    }
+    return false;
+}
+const BLOCKED_TAR_ENTRY_TYPES = new Set([
+    "BlockDevice",
+    "CharacterDevice",
+    "FIFO",
+    "Socket",
+]);
+export function createTarEntryPlanner(params) {
+    // Preserve inherited/getter-backed public options and per-entry policy reads.
+    const plan = createArchiveEntryPlanner(params, "tar");
+    return (entry) => {
+        const kind = BLOCKED_TAR_ENTRY_TYPES.has(entry.type) ? "blocked" : archiveEntryKindFromTarType(entry.type);
+        // The public checker accepts structural entry objects, including class getters.
+        return plan({ path: entry.path, kind, size: entry.size, mode: entry.mode });
+    };
+}
+export function createTarEntryPreflightChecker(params) {
+    const plan = createTarEntryPlanner(params);
+    return (entry) => plan(entry) !== null;
+}

package/dist/archive-tar-wasm.d.ts

@@ -1,6 +1,6 @@
 import { Transform, type TransformCallback } from "node:stream";
 import type { TarMeterLimits } from "./archive-limits.js";
-import type { TarEntryInfo } from "./archive-tar.js";
+import type { TarEntryInfo } from "./archive-plan.js";
 export type AdmittedTarMember = TarEntryInfo & {
     offset: number;
 };

package/dist/archive-zip-directory.d.ts

@@ -1,5 +1,5 @@
 import { type ResolvedArchiveExtractLimits } from "./archive-limits.js";
-import type { ArchiveEntryKind } from "./archive-policy.js";
+import type { ArchiveEntryKind } from "./archive-plan.js";
 export type ZipRead = {
     offset: number;
     length: number;

package/dist/archive-zip-entry.d.ts

@@ -1,4 +1,4 @@
-import { type ArchiveEntryModePolicy, type ArchiveEntryKind } from "./archive-policy.js";
+import { type ArchiveEntryModePolicy, type ArchiveEntryKind } from "./archive-plan.js";
 import type { ZipDirectoryEntry } from "./archive-zip-directory.js";
 export type ZipEntry = {
     name: string;

package/dist/archive-zip-entry.js

@@ -1,4 +1,4 @@
-import { resolveArchiveEntryMode, } from "./archive-policy.js";
+import { resolveArchiveEntryMode, } from "./archive-plan.js";
 const admittedMetadata = new WeakMap();
 /** Internal: register only after the complete decoder/admission association. */
 export function registerAdmittedZipEntry(entry, physical) {

package/dist/archive.d.ts

@@ -1,14 +1,17 @@
-import type { ExtractArchiveOptions } from "./archive-options.js";
-export type { ArchiveLogger, ExtractArchiveOptions } from "./archive-options.js";
-export type { ArchiveEntryFilter, ArchiveEntryKind, ArchiveEntryModePolicy, ArchiveFilteredEntryPolicy, } from "./archive-policy.js";
+import { type ExtractArchiveOptions, type ArchivePlanEntry } from "./archive-plan.js";
+export type { ArchiveLogger, ExtractArchiveOptions } from "./archive-plan.js";
+export type { ArchiveEntryFilter, ArchiveEntryKind, ArchiveEntryModePolicy, ArchiveFilteredEntryPolicy, } from "./archive-plan.js";
 export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 export { resolveArchiveKind, resolvePackedRootDir, type ArchiveKind } from "./archive-kind.js";
 export { readArchiveEntry } from "./archive-read.js";
-export { inspectTarArchive, type InspectTarArchiveOptions, type InspectedTarEntry } from "./archive-tar-inspect.js";
 export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ENTRY_PATH_COMPONENTS, type ArchiveExtractLimits, type ArchiveLimitErrorCode, } from "./archive-limits.js";
 export { ArchiveFormatError, type ArchiveFormatErrorCode } from "./archive-errors.js";
 export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-staging.js";
 export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
-export { createTarEntryPreflightChecker, type TarEntryInfo } from "./archive-tar.js";
+export { createTarEntryPreflightChecker, type TarEntryInfo } from "./archive-plan.js";
 export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, type ZipArchiveWithFiles, } from "./archive-zip-preflight.js";
 export declare function extractArchive(params: ExtractArchiveOptions): Promise<void>;
+export type InspectTarArchiveOptions = Pick<ExtractArchiveOptions, "archivePath" | "timeoutMs" | "limits" | "entryFilter" | "onFiltered">;
+export type InspectedTarEntry = Readonly<Pick<ArchivePlanEntry, "path" | "kind" | "size">>;
+/** Complete TAR/gzip admission and zero-strip extraction policy, without output writes. */
+export declare function inspectTarArchive(params: InspectTarArchiveOptions): Promise<readonly InspectedTarEntry[]>;

package/dist/archive.js

@@ -1,12 +1,11 @@
-import { createTarEntryPlanner } from "./archive-tar.js";
+import { createTarEntryPlanner, createArchiveEntrySelector, resolveArchiveFilteredEntryPolicy, createArchiveEntryPlanner, } from "./archive-plan.js";
 import { inspectTar, replayTar } from "./archive-tar-stream.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
 import { constants as fsConstants } from "node:fs";
-import fs from "node:fs/promises";
+import fs, {} from "node:fs/promises";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { createArchiveEntrySelector } from "./archive-plan.js";
 import { createPipelineTimeoutError, waitForDeadline, withExtractionDeadline, } from "./archive-deadline.js";
 import { assertArchiveEntryCountWithinLimit, createByteBudgetTracker, createExtractBudgetTransform, resolveExtractLimits, resolveTarMeterLimits, } from "./archive-limits.js";
 import { resolveArchiveKind } from "./archive-kind.js";
@@ -16,22 +15,23 @@ import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
 import { admittedZipEntries } from "./archive-zip-loader.js";
 import { zipEntryKind, zipEntryDeclaredSize, zipEntryMode, } from "./archive-zip-entry.js";
 import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
-import { ArchiveSecurityError } from "./archive-errors.js";
-import { extractNativeArchive } from "./archive-native.js";
+import { ArchiveSecurityError, ArchiveFormatError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
 import { stageArchiveFileForExtraction } from "./archive-input.js";
-import { getNativeBinding } from "./native.js";
-import { resolveArchiveFilteredEntryPolicy } from "./archive-policy.js";
+import { getNativeBinding, } from "./native.js";
 import { writeSiblingTempFile } from "./sibling-temp.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { classifyArchiveParserError } from "./archive-parser-errors.js";
+import { validateArchiveEntryPath } from "./archive-entry.js";
+import { admitZipFile } from "./archive-zip-admission.js";
+import { validateNativeZipManifest } from "./archive-zip-manifest.js";
 export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 export { resolveArchiveKind, resolvePackedRootDir } from "./archive-kind.js";
 export { readArchiveEntry } from "./archive-read.js";
-export { inspectTarArchive } from "./archive-tar-inspect.js";
 export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ENTRY_PATH_COMPONENTS, } from "./archive-limits.js";
 export { ArchiveFormatError } from "./archive-errors.js";
 export { ArchiveSecurityError } from "./archive-staging.js";
 export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
-export { createTarEntryPreflightChecker } from "./archive-tar.js";
+export { createTarEntryPreflightChecker } from "./archive-plan.js";
 export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, } from "./archive-zip-preflight.js";
 const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
 const OPEN_WRITE_CREATE_FLAGS = fsConstants.O_WRONLY |
@@ -214,3 +214,116 @@ async function extractWasmTar(params) {
         return accepted;
     });
 }
+function throwMappedNativeArchiveError(error) {
+    if (error instanceof Error) {
+        const mapped = classifyArchiveParserError(error.message, { cause: error });
+        if (mapped)
+            throw mapped;
+        if (isArchiveFormatErrorMessage(error.message)) {
+            throw new ArchiveFormatError(error.message, { cause: error });
+        }
+        if (error.code === "InvalidArg") {
+            throw new ArchiveFormatError(`invalid archive: ${error.message}`, { cause: error });
+        }
+    }
+    throw error;
+}
+async function extractNativeArchive(params) {
+    const { archivePath, limits, tarLimits, deadline } = params;
+    const zipEntries = [];
+    if (params.kind === "zip") {
+        await admitZipFile(archivePath, limits, deadline, (entry) => { zipEntries.push(entry); });
+    }
+    const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
+    await withStagedArchivePublication({ ...params, destinationGuard }, async (stagingDir) => {
+        deadline.check();
+        // N-API retains completed task state on its signal; each pass needs its own.
+        const manifest = await params.binding
+            .inspectArchiveNative(archivePath, params.kind, tarLimits, AbortSignal.any([deadline.signal]))
+            .catch(throwMappedNativeArchiveError);
+        deadline.check();
+        assertArchiveEntryCountWithinLimit(manifest.length, limits);
+        if (params.kind === "zip") {
+            validateNativeZipManifest(manifest, zipEntries);
+        }
+        // Recheck the native manifest before any caller callback observes an entry.
+        if (params.kind !== "zip") {
+            for (const entry of manifest)
+                validateArchiveEntryPath(entry.path);
+        }
+        const planEntry = createArchiveEntryPlanner({ ...params, rootDir: stagingDir }, params.kind);
+        const plan = [];
+        for (const entry of manifest) {
+            deadline.check();
+            const mode = params.kind === "zip"
+                ? zipEntries[entry.index].creatorSystem === 3
+                    ? zipEntries[entry.index].externalAttributes >>> 16
+                    : undefined
+                : entry.mode;
+            const accepted = planEntry({ ...entry, mode });
+            if (accepted)
+                plan.push({ ...accepted, index: entry.index });
+        }
+        const directory = await fs.open(stagingDir, fsConstants.O_RDONLY |
+            (typeof fsConstants.O_DIRECTORY === "number" ? fsConstants.O_DIRECTORY : 0));
+        try {
+            deadline.check();
+            await params.binding.extractArchiveNative(archivePath, params.kind, directory.fd, plan.map((entry) => ({ ...entry, mode: entry.kind === "directory" ? 0o700 : 0o600 })), tarLimits, AbortSignal.any([deadline.signal])).catch(throwMappedNativeArchiveError);
+        }
+        finally {
+            await directory.close().catch(() => undefined);
+        }
+        return plan;
+    });
+}
+/** Complete TAR/gzip admission and zero-strip extraction policy, without output writes. */
+export async function inspectTarArchive(params) {
+    const archivePath = params.archivePath;
+    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
+    const limits = resolveExtractLimits(params.limits);
+    const tarLimits = resolveTarMeterLimits(limits);
+    const native = getNativeBinding();
+    assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
+    return await withExtractionDeadline(params.timeoutMs, "inspect tar", async (deadline) => {
+        const staged = await stageArchiveFileForExtraction({ archivePath, limits, deadline });
+        try {
+            // Staging closes descriptors asynchronously; expiry there must not start a decoder.
+            deadline.check();
+            const entries = [];
+            const append = (entry) => {
+                if (entry)
+                    entries.push(Object.freeze({ path: entry.path, kind: entry.kind, size: entry.size }));
+            };
+            const policy = { limits, entryFilter: params.entryFilter, onFiltered };
+            if (native) {
+                const manifest = await native.inspectArchiveNative(staged.path, "tar", tarLimits, deadline.signal)
+                    .catch(throwMappedNativeArchiveError);
+                deadline.check();
+                // Match extraction's whole-manifest validation before caller policy runs.
+                for (const entry of manifest)
+                    validateArchiveEntryPath(entry.path);
+                const planEntry = createArchiveEntryPlanner(policy, "tar");
+                for (const entry of manifest) {
+                    deadline.check();
+                    append(planEntry(entry));
+                }
+            }
+            else {
+                const manifest = [];
+                await inspectTar({ archivePath: staged.path, limits: tarLimits, signal: deadline.signal,
+                    onMember: (entry) => { manifest.push(entry); } });
+                const planEntry = createTarEntryPlanner(policy);
+                for (const entry of manifest) {
+                    deadline.check();
+                    append(planEntry(entry));
+                }
+            }
+            deadline.check();
+            // This is bounded evidence about the staged bytes, not a reusable write plan.
+            return Object.freeze(entries);
+        }
+        finally {
+            await staged.cleanup();
+        }
+    });
+}

package/dist/atomic.d.ts

@@ -1,4 +1,6 @@
-export { replaceFileAtomic, replaceFileAtomicSync, type RenameIdentityPolicy, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicRestoreCleanup, type ReplaceFileAtomicRestoreFailureDetails, type ReplaceFileAtomicResult, type ReplaceFileCopyFallbackRestorePolicy, type ReplaceFileDestinationHardlinkPolicy, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
+export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicResult, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
+export type { RenameIdentityPolicy } from "./pinned-write-types.js";
+export type { ReplaceFileAtomicRestoreCleanup, ReplaceFileAtomicRestoreFailureDetails, ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy, } from "./replace-file-copy-fallback.js";
 export { writeTextAtomic, type WriteTextAtomicOptions } from "./text-atomic.js";
 export { replaceDirectoryAtomic, type ReplaceDirectoryAtomicOptions } from "./replace-directory.js";
 export { movePathWithCopyFallback, type MovePathPublicationReceipt, type MovePathWithCopyFallbackOptions, } from "./move-path.js";

package/dist/copy-publication.d.ts

@@ -1,5 +1,5 @@
 import type { BigIntStats } from "node:fs";
-import type { PinnedWriteParams, PublishedWriteIdentity } from "./pinned-write.js";
+import type { PinnedWriteParams, PublishedWriteIdentity } from "./pinned-write-types.js";
 export type RootCopyPublicationReceipt = Readonly<{
     path: string;
     dev: bigint;

package/dist/create.d.ts

@@ -1,3 +1,17 @@
-export { createDirectory, createDirectorySync, createDirectoryWithAdmission, type CreateDirectoryOptions, type CreationAdmission, } from "./create-directory.js";
-export { createFileSync, createFileHandle, type CreateFileOptions } from "./create-file.js";
+import { type FileHandle } from "node:fs/promises";
+import { type OwnedFileDescriptorSync } from "./create-owned-file.js";
+import { type CreationPermissions, type CreationParentIdentity } from "./creation-boundary.js";
 export type { OwnedFileDescriptorSync } from "./create-owned-file.js";
+export type CreateFileOptions = CreateDirectoryOptions;
+export declare function createFileSync(targetPath: string, options?: CreateFileOptions): OwnedFileDescriptorSync;
+/** Internal async writer; Windows preparation uses the nonblocking stage owner. */
+export declare function createFileHandle(targetPath: string, options?: CreateFileOptions, admission?: CreationAdmission): Promise<FileHandle>;
+export type CreateDirectoryOptions = CreationPermissions & {
+    assertBeforeMutation?: () => void;
+};
+export type CreationAdmission = {
+    expectedParentIdentity?: CreationParentIdentity;
+};
+export declare function createDirectory(targetPath: string, options?: CreateDirectoryOptions): Promise<void>;
+export declare function createDirectoryWithAdmission(targetPath: string, options?: CreateDirectoryOptions, admission?: CreationAdmission): Promise<void>;
+export declare function createDirectorySync(targetPath: string, options?: CreateDirectoryOptions): void;