@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/archive.js

@@ -1,39 +1,37 @@
-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 { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 import { createPipelineTimeoutError, waitForDeadline, withExtractionDeadline, } from "./archive-deadline.js";
-import { assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, createExtractBudgetTransform, resolveExtractLimits, resolveTarMeterLimits, } from "./archive-limits.js";
+import { assertArchiveEntryCountWithinLimit, createByteBudgetTracker, createExtractBudgetTransform, resolveExtractLimits, resolveTarMeterLimits, } from "./archive-limits.js";
 import { resolveArchiveKind } from "./archive-kind.js";
-import { prepareArchiveDestinationGuard, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
-import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
+import { prepareArchiveDestinationGuard, preparePrivateArchiveOutputPath, } from "./archive-staging.js";
+import { withStagedArchivePublication } from "./archive-merge.js";
 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 { FsSafeError } from "./errors.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, shouldExtractArchiveEntry, } from "./archive-policy.js";
+import { getNativeBinding, } from "./native.js";
 import { writeSiblingTempFile } from "./sibling-temp.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
-import { realpathSync } from "./realpath.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 |
@@ -48,26 +46,6 @@ async function readZipEntryStream(entry) {
     const buf = await entry.async("nodebuffer");
     return Readable.from(buf);
 }
-function resolveZipOutputPath(params) {
-    validateArchiveEntryPath(params.entryPath);
-    const canonicalPath = stripArchivePath(params.entryPath, 0);
-    if (!canonicalPath)
-        return null;
-    const relPath = params.strip === 0 ? canonicalPath : stripArchivePath(canonicalPath, params.strip);
-    if (!relPath) {
-        return null;
-    }
-    validateArchiveEntryPath(relPath);
-    return {
-        canonicalPath,
-        relPath,
-        outPath: resolveArchiveOutputPath({
-            rootDir: params.destinationDir,
-            relPath,
-            originalPath: params.entryPath,
-        }),
-    };
-}
 async function writeZipFileEntry(params) {
     params.deadline.check();
     params.budget.startEntry();
@@ -118,93 +96,48 @@ async function writeZipFileEntry(params) {
     }
 }
 async function extractZip(params) {
-    const limits = resolveExtractLimits(params.limits);
-    const stagedArchive = await stageArchiveFileForExtraction({
-        archivePath: params.archivePath,
-        limits,
-        deadline: params.deadline,
+    const { limits, deadline } = params;
+    const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
+    deadline.check();
+    const buffer = await fs.readFile(params.archivePath, { signal: deadline.signal });
+    deadline.check();
+    const zip = await waitForDeadline(loadZipArchiveWithPreflight(buffer, limits), deadline);
+    deadline.check();
+    const entries = admittedZipEntries(zip);
+    assertArchiveEntryCountWithinLimit(entries.length, limits);
+    const budget = createByteBudgetTracker(limits);
+    await withStagedArchivePublication({ ...params, destinationGuard }, async (stagingDir) => {
+        const { select } = createArchiveEntrySelector({ ...params, rootDir: stagingDir });
+        const acceptedEntries = [];
+        for (const entry of entries) {
+            deadline.check();
+            const entryKind = zipEntryKind(entry);
+            const relPath = select({ path: entry.name, kind: entryKind, size: zipEntryDeclaredSize(entry) });
+            if (relPath === null)
+                continue;
+            if (entryKind === "symlink") {
+                throw new ArchiveSecurityError("entry-link", `zip entry is a link: ${entry.name}`);
+            }
+            if (entryKind === "other")
+                continue;
+            const mode = zipEntryMode(entry, params.entryModes);
+            acceptedEntries.push({ path: relPath, kind: entry.dir ? "directory" : "file", mode });
+            const outPath = path.join(stagingDir, relPath);
+            await preparePrivateArchiveOutputPath({
+                destinationDir: stagingDir,
+                destinationRealDir: stagingDir,
+                relPath,
+                outPath,
+                originalPath: entry.name,
+                isDirectory: entry.dir,
+                deadline,
+            });
+            if (!entry.dir) {
+                await writeZipFileEntry({ entry, outPath, budget, deadline });
+            }
+        }
+        return acceptedEntries;
     });
-    try {
-        const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
-        const destinationRealDir = destinationGuard.realPath;
-        params.deadline.check();
-        const buffer = await fs.readFile(stagedArchive.path, { signal: params.deadline.signal });
-        params.deadline.check();
-        const zip = await waitForDeadline(loadZipArchiveWithPreflight(buffer, limits), params.deadline);
-        params.deadline.check();
-        const entries = admittedZipEntries(zip);
-        const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
-        assertArchiveEntryCountWithinLimit(entries.length, limits);
-        const budget = createByteBudgetTracker(limits);
-        const trackOutputPath = createArchiveOutputPathTracker();
-        await withStagedArchiveDestination({
-            destinationRealDir,
-            run: async (stagingDir) => {
-                const stagingRealDir = realpathSync.native(stagingDir);
-                const acceptedEntries = [];
-                for (const entry of entries) {
-                    params.deadline.check();
-                    const output = resolveZipOutputPath({
-                        entryPath: entry.name,
-                        strip,
-                        destinationDir: stagingRealDir,
-                    });
-                    if (!output) {
-                        continue;
-                    }
-                    assertArchiveEntryPathComponentsWithinLimit(output.relPath, limits);
-                    trackOutputPath(output.relPath, entry.name);
-                    const entryKind = zipEntryKind(entry);
-                    const entrySize = zipEntryDeclaredSize(entry);
-                    if (!shouldExtractArchiveEntry({
-                        filter: params.entryFilter,
-                        onFiltered: params.onFiltered,
-                        entry: { path: output.canonicalPath, kind: entryKind, size: entrySize },
-                    })) {
-                        continue;
-                    }
-                    if (entryKind === "symlink") {
-                        throw new ArchiveSecurityError("entry-link", `zip entry is a link: ${entry.name}`);
-                    }
-                    if (entryKind === "other")
-                        continue;
-                    const mode = zipEntryMode(entry, params.entryModes);
-                    acceptedEntries.push({ path: output.relPath, kind: entry.dir ? "directory" : "file", mode });
-                    await preparePrivateArchiveOutputPath({
-                        destinationDir: stagingRealDir,
-                        destinationRealDir: stagingRealDir,
-                        relPath: output.relPath,
-                        outPath: output.outPath,
-                        originalPath: entry.name,
-                        isDirectory: entry.dir,
-                        deadline: params.deadline,
-                    });
-                    if (entry.dir) {
-                        continue;
-                    }
-                    await writeZipFileEntry({
-                        entry,
-                        outPath: output.outPath,
-                        budget,
-                        deadline: params.deadline,
-                    });
-                }
-                params.deadline.check();
-                await mergePlannedArchiveIntoDestination({
-                    entries: acceptedEntries,
-                    durable: params.durable,
-                    entryUmask: params.entryUmask,
-                    sourceDir: stagingRealDir,
-                    destinationGuard,
-                    deadline: params.deadline,
-                });
-                params.deadline.check();
-            },
-        });
-    }
-    finally {
-        await stagedArchive.cleanup();
-    }
 }
 export async function extractArchive(params) {
     const archivePath = params.archivePath;
@@ -232,62 +165,165 @@ export async function extractArchive(params) {
         stripComponents: params.stripComponents, limits,
         entryModes: params.entryModes, entryUmask, entryFilter: params.entryFilter, onFiltered,
     };
-    if (native) {
-        await withExtractionDeadline(params.timeoutMs, label, async (deadline) => extractNativeArchive({ ...options, binding: native, kind, tarLimits, deadline }));
-        return;
-    }
-    if (kind !== "zip") {
-        await withExtractionDeadline(params.timeoutMs, label, async (deadline) => {
-            const stagedArchive = await stageArchiveFileForExtraction({
-                archivePath: options.archivePath,
-                limits,
-                deadline,
-            });
-            try {
-                await extractWasmTar({ archivePath: stagedArchive.path, kind, options, limits, tarLimits, deadline });
-            }
-            finally {
-                await stagedArchive.cleanup();
-            }
-        });
-        return;
-    }
-    await withExtractionDeadline(params.timeoutMs, label, async (deadline) => extractZip({ ...options, deadline }));
+    await withExtractionDeadline(params.timeoutMs, label, async (deadline) => {
+        const stagedArchive = await stageArchiveFileForExtraction({ archivePath, limits, deadline });
+        try {
+            deadline.check();
+            const stagedOptions = { ...options, archivePath: stagedArchive.path, deadline };
+            if (native)
+                await extractNativeArchive({ ...stagedOptions, binding: native, kind, tarLimits });
+            else if (kind === "zip")
+                await extractZip(stagedOptions);
+            else
+                await extractWasmTar({ ...stagedOptions, kind, tarLimits });
+        }
+        finally {
+            await stagedArchive.cleanup();
+        }
+    });
 }
 async function extractWasmTar(params) {
-    const { options, deadline, tarLimits } = params;
+    const { deadline, tarLimits } = params;
     const manifest = [];
     await inspectTar({ archivePath: params.archivePath, kind: params.kind, limits: tarLimits, signal: deadline.signal,
         onMember: (entry) => { manifest.push(entry); } });
     deadline.check();
-    const destinationGuard = await prepareArchiveDestinationGuard(options.destDir);
-    const destinationRealDir = destinationGuard.realPath;
-    await withStagedArchiveDestination({ destinationRealDir, run: async (stagingPath) => {
-            const stagingDir = realpathSync.native(stagingPath);
-            const planEntry = createTarEntryPlanner({ ...options, rootDir: destinationRealDir, limits: params.limits });
-            const accepted = manifest.flatMap((entry) => {
+    const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
+    await withStagedArchivePublication({ ...params, destinationGuard }, async (stagingDir) => {
+        const planEntry = createTarEntryPlanner({ ...params, rootDir: destinationGuard.realPath });
+        const accepted = manifest.flatMap((entry) => {
+            deadline.check();
+            const planned = planEntry(entry);
+            return planned ? [{ ...entry, ...planned }] : [];
+        });
+        await replayTar({ archivePath: params.archivePath, kind: params.kind, limits: tarLimits, signal: deadline.signal, members: accepted,
+            async consume(member, payload) {
                 deadline.check();
-                const planned = planEntry(entry);
-                return planned ? [{ ...entry, ...planned }] : [];
-            });
-            await replayTar({ archivePath: params.archivePath, kind: params.kind, limits: tarLimits, signal: deadline.signal, members: accepted,
-                async consume(member, payload) {
+                await preparePrivateArchiveOutputPath({ destinationDir: stagingDir, destinationRealDir: stagingDir,
+                    relPath: member.path, outPath: path.join(stagingDir, member.path), originalPath: member.path,
+                    isDirectory: member.kind === "directory", deadline });
+                if (member.kind === "file") {
+                    await runPinnedWriteHelper({ rootPath: stagingDir, relativeParentPath: path.posix.dirname(member.path),
+                        basename: path.posix.basename(member.path), mkdir: false, mode: 0o600, overwrite: false,
+                        sync: false,
+                        maxBytes: member.size, input: { kind: "stream", stream: Readable.from(payload) } });
+                }
+                deadline.check();
+            },
+        });
+        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();
-                    await preparePrivateArchiveOutputPath({ destinationDir: stagingDir, destinationRealDir: stagingDir,
-                        relPath: member.path, outPath: path.join(stagingDir, member.path), originalPath: member.path,
-                        isDirectory: member.kind === "directory", deadline });
-                    if (member.kind === "file") {
-                        await runPinnedWriteHelper({ rootPath: stagingDir, relativeParentPath: path.posix.dirname(member.path),
-                            basename: path.posix.basename(member.path), mkdir: false, mode: 0o600, overwrite: false,
-                            sync: false,
-                            maxBytes: member.size, input: { kind: "stream", stream: Readable.from(payload) } });
-                    }
+                    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();
-                },
-            });
-            deadline.check();
-            await mergePlannedArchiveIntoDestination({ entries: accepted, sourceDir: stagingDir, destinationGuard,
-                deadline, durable: options.durable, entryUmask: options.entryUmask });
+                    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/async-lock.d.ts

@@ -1,2 +1 @@
 export declare function createAsyncLock(): <T>(fn: () => Promise<T>) => Promise<T>;
-//# sourceMappingURL=async-lock.d.ts.map

package/dist/atomic.d.ts

@@ -1,5 +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";
-//# sourceMappingURL=atomic.d.ts.map

package/dist/bounded-read-stream.d.ts

@@ -1,3 +1,2 @@
 import { Transform } from "node:stream";
 export declare function createByteLimitTransform(maxBytes: number, overflowError: (bytes: number) => Error): Transform;
-//# sourceMappingURL=bounded-read-stream.d.ts.map

package/dist/bounded-read.d.ts

@@ -23,4 +23,3 @@ export declare function readBoundedSync(maxBytes: number, readChunk: (scratch: B
 /** Sync bounded read from a numeric descriptor. The caller owns the descriptor. */
 export declare function readFileDescriptorBoundedSync(fd: number, maxBytes: number): Buffer;
 export {};
-//# sourceMappingURL=bounded-read.d.ts.map

package/dist/byte-budget.d.ts

@@ -1,4 +1,3 @@
 export declare function normalizeMaxBytes(value: number | undefined, options?: {
     defaultValue?: number;
 }): number | undefined;
-//# sourceMappingURL=byte-budget.d.ts.map

package/dist/byte-view.d.ts

@@ -1,3 +1,2 @@
 /** Snapshot intrinsic view bounds without copying the borrowed payload. */
 export declare function snapshotByteView(bytes: Uint8Array): Uint8Array;
-//# sourceMappingURL=byte-view.d.ts.map

package/dist/clone-metadata.d.ts

@@ -17,4 +17,3 @@ export type CloneFileMetadata = {
  * These are point-in-time facts, not authorization or a guarantee against later edits.
  */
 export declare function readCloneFileMetadata(files: readonly string[]): Promise<(CloneFileMetadata | undefined)[]>;
-//# sourceMappingURL=clone-metadata.d.ts.map

package/dist/config.d.ts

@@ -1,3 +1,2 @@
 export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, type FsSafePythonConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
-//# sourceMappingURL=config.d.ts.map

package/dist/containment.d.ts

@@ -1,2 +1 @@
 export type ContainmentGuarantee = "kernel-atomic" | "best-effort";
-//# sourceMappingURL=containment.d.ts.map

package/dist/copy-file-input.d.ts

@@ -19,4 +19,3 @@ export declare function assertCopySourceCurrent(source: {
 export declare function writeCopyFileToFd(fd: number, input: CopyFileInput, maxBytes?: number, assertBeforeMutation?: () => void): Promise<void>;
 export declare function createNativeCopyFile(native: NativeBinding, input: CopyFileInput, parentFd: number, basename: string, maxBytes: number | undefined, sync: boolean): Promise<NativeFileCopyResult | undefined>;
 export declare function assertNativeCopyCompleted(input: CopyFileInput, copied?: NativeFileCopyResult): void;
-//# sourceMappingURL=copy-file-input.d.ts.map

package/dist/copy-policy.d.ts

@@ -1,3 +1,2 @@
 export type CopyCloneMode = "auto" | "always" | "never";
 export declare function resolveCopyCloneMode(mode: CopyCloneMode | undefined, defaultMode: CopyCloneMode): CopyCloneMode;
-//# sourceMappingURL=copy-policy.d.ts.map

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;
@@ -18,4 +18,3 @@ export type CopyPublicationOptions = {
         verify(): void;
     };
 };
-//# sourceMappingURL=copy-publication.d.ts.map

package/dist/copy-tree-portable.d.ts

@@ -6,4 +6,3 @@ export declare function copyOwnedTree(source: ReturnType<typeof openStagedDirect
     concurrency: number;
     copyFileContents?: NativeBinding["copyFileContents"];
 }): Promise<void>;
-//# sourceMappingURL=copy-tree-portable.d.ts.map

package/dist/copy-tree-portable.js

@@ -11,7 +11,7 @@ function timestampSeconds(nanoseconds) {
 }
 /** Byte-copy adapter for the shared immutable-source, caller-owned namespace contract. */
 export async function copyOwnedTree(source, destination, options) {
-    options.signal?.throwIfAborted();
+    const callerSignal = options.signal ? AbortSignal.any([options.signal]) : undefined;
     const cancellation = new AbortController();
     const signal = cancellation.signal;
     setMaxListeners(options.concurrency, signal);
@@ -23,8 +23,8 @@ export async function copyOwnedTree(source, destination, options) {
         failure ??= { value };
         cancellation.abort(failure);
     }
-    const abort = () => recordFailure(options.signal?.reason);
-    options.signal?.addEventListener("abort", abort, { once: true });
+    if (callerSignal)
+        callerSignal.onabort = () => recordFailure(callerSignal.reason);
     async function schedule(operation, children) {
         signal.throwIfAborted();
         const task = operation()
@@ -51,8 +51,8 @@ export async function copyOwnedTree(source, destination, options) {
             }
             output = await fsp.open(to, "wx", 0o600);
             if (options.copyFileContents) {
-                // napi-rs owns onabort. Each admitted file gets a separate signal so
-                // concurrent native copies cannot replace one another's cancellation.
+                // napi-rs owns onabort. Each admitted file gets a separate signal; the
+                // shared failure signal is private, so callers cannot intercept its relay.
                 const fileCancellation = new AbortController();
                 const abortFile = () => fileCancellation.abort();
                 signal.addEventListener("abort", abortFile, { once: true });
@@ -62,6 +62,7 @@ export async function copyOwnedTree(source, destination, options) {
                 }
                 finally {
                     signal.removeEventListener("abort", abortFile);
+                    fileCancellation.signal.onabort = null;
                 }
             }
             else {
@@ -224,6 +225,7 @@ export async function copyOwnedTree(source, destination, options) {
         signal.throwIfAborted();
     }
     try {
+        callerSignal?.throwIfAborted();
         await copyDirectory(source.receipt.realPath, destination);
         await Promise.all(finishing);
         signal.throwIfAborted();
@@ -233,7 +235,8 @@ export async function copyOwnedTree(source, destination, options) {
     }
     finally {
         await Promise.all(finishing);
-        options.signal?.removeEventListener("abort", abort);
+        if (callerSignal)
+            callerSignal.onabort = null;
     }
     if (failure)
         throw failure.value;

package/dist/copy.d.ts

@@ -13,4 +13,3 @@ export declare function probeTreeClone(parentPath: string): TreeCloneBackend | u
 export declare function createCloneSource(destination: string, options?: Pick<CopyTreeOptions, "signal">): Promise<void>;
 /** Copy an immutable, caller-owned tree, preferring native cloning unless configured otherwise. */
 export declare function copyTree(source: string, destination: string, options?: CopyTreeOptions): Promise<void>;
-//# sourceMappingURL=copy.d.ts.map

package/dist/copy.js

@@ -94,12 +94,11 @@ async function materializeTree(source, destination, options, policy) {
         let cloned = false;
         // napi-rs uses the supplied signal's onabort property. Give it a private
         // signal so caller handlers and other admitted native operations stay intact.
-        const cancellation = options.signal && supported ? new AbortController() : undefined;
-        const abort = () => cancellation?.abort();
-        options.signal?.addEventListener("abort", abort, { once: true });
+        const nativeSignal = options.signal && supported ? AbortSignal.any([options.signal]) : undefined;
         try {
             if (native && supported) {
-                await native.cloneTree(original?.fd ?? null, parent.fd, name, concurrency, cancellation?.signal);
+                nativeSignal?.throwIfAborted();
+                await native.cloneTree(original?.fd ?? null, parent.fd, name, concurrency, nativeSignal);
                 cloned = true;
             }
         }
@@ -113,7 +112,8 @@ async function materializeTree(source, destination, options, policy) {
             }
         }
         finally {
-            options.signal?.removeEventListener("abort", abort);
+            if (nativeSignal)
+                nativeSignal.onabort = null;
         }
         options.signal?.throwIfAborted();
         assertStagedDirectoryCurrent(parent.receipt);

package/dist/create-owned-file.d.ts

@@ -5,4 +5,3 @@ export type OwnedFileDescriptorSync = {
 };
 /** Capture the descriptor's creator-owned closer before it can be reused. */
 export declare function ownFileDescriptorSync(fd: number, closeFd?: (fd: number) => void): OwnedFileDescriptorSync;
-//# sourceMappingURL=create-owned-file.d.ts.map

package/dist/create.d.ts

@@ -1,4 +1,17 @@
-export { createDirectory, createDirectorySync, createDirectoryWithAdmission, createDirectorySyncWithAdmission, 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";
-//# sourceMappingURL=create.d.ts.map
+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;