@openclaw/fs-safe 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 ## Unreleased
 
+## 0.18.0 - 2026-09-21
+
+### Highlights
+
+- **Security hardening for Root arguments:** explicit paths, payloads, and copy sources take precedence over matching properties in wider options objects. A supplied source Root retains its admission and read policy; directory creation and writable opens keep their internal controls. ([#577](https://github.com/openclaw/fs-safe/pull/577))
+- **More reliable cancellation and failure reporting:** tree-copy workers receive cancellation even when caller abort handlers stop event propagation. Secret reads and asynchronous atomic operations preserve their selected failures when best-effort descriptor cleanup also fails. ([#561](https://github.com/openclaw/fs-safe/pull/561), [#566](https://github.com/openclaw/fs-safe/pull/566), [#545](https://github.com/openclaw/fs-safe/pull/545), [#554](https://github.com/openclaw/fs-safe/pull/554))
+- **Reliable Windows publication and ownership checks:** keep missing buffered-write destinations absent until complete content is published, including across process interruption, and preserve write-only access when admitting a destination that appears during staging. Permission-query results must explicitly verify owner locality. ([#573](https://github.com/openclaw/fs-safe/pull/573), [#547](https://github.com/openclaw/fs-safe/pull/547))
+- **Less repeated work in targeted workloads:** reduce metadata observations and Promise scheduling in secret reads, Root path resolution, and durable queues; reuse bounded, cleared scratch storage for fallback SHA-256. Measurements show gains in selected Linux read workloads, with workload-specific costs retained in the linked PRs. ([#535](https://github.com/openclaw/fs-safe/pull/535), [#536](https://github.com/openclaw/fs-safe/pull/536), [#549](https://github.com/openclaw/fs-safe/pull/549), [#550](https://github.com/openclaw/fs-safe/pull/550))
+- **Smaller npm installs with intact TypeScript declarations:** stop shipping declaration maps that point to unpublished source files. Public declarations and exports remain available. Thanks @vincentkoc. ([#570](https://github.com/openclaw/fs-safe/pull/570))
+
+### Compatibility and upgrade notes
+
+- Explicit Root arguments remain authoritative even when JavaScript callers or structurally wider TypeScript options include `relativePath`, `data`, or `source`. Enumerable option getters still run and can throw; supported defaults and policy options keep their precedence. This fixes argument selection within the existing filesystem capability contract. ([#577](https://github.com/openclaw/fs-safe/pull/577), [Root contract](https://github.com/openclaw/fs-safe/blob/v0.18.0/docs/root.md))
+- Injected Windows permission executors must return valid owner/current-user SIDs, an explicit boolean `remote`, and complete DACL facts. Missing or nonboolean locality leaves both inspectors unverified; `remote: true` retains the ACL report but does not grant trusted ownership. ([#547](https://github.com/openclaw/fs-safe/pull/547), [permission-query contract](https://github.com/openclaw/fs-safe/blob/v0.18.0/docs/permissions.md))
+- Descriptor-close behavior remains operation-specific. Synchronous secret readers report a lone close failure before trimming or empty-content validation, while an earlier read or identity failure retains precedence. Atomic best-effort cleanup now treats synchronous adapter throws like rejected close promises; synchronous successful admission, parent-mode admission, and retained descriptor-owner closes keep their existing failure reporting. ([#566](https://github.com/openclaw/fs-safe/pull/566), [#545](https://github.com/openclaw/fs-safe/pull/545), [#554](https://github.com/openclaw/fs-safe/pull/554), [atomic cleanup contract](https://github.com/openclaw/fs-safe/blob/v0.18.0/docs/atomic.md))
+- Root path properties are readonly metadata. Each Root retains its originally admitted canonical directory and identity; create another Root to select a different directory. Values in the supplied defaults object remain live for later operations. ([#546](https://github.com/openclaw/fs-safe/pull/546))
+
+### Security hardening and correctness
+
+- Preserve positional paths and payloads across Root reads, writable opens, writes, creates, appends, removals, and copies, including JSON and streamed wrappers. Keep Root-scoped copy sources authoritative instead of allowing an options property to substitute a raw path. `mkdir()` and `ensureRoot()` retain their distinct root-directory rules, and internal removal or writable-open fields cannot replace their caller-owned controls. ([#577](https://github.com/openclaw/fs-safe/pull/577))
+- Keep missing destinations absent until buffered Windows `Root.write()` publishes complete content; existing destinations retain their previous bytes during staging. Re-admit raced destinations before replacement, preserving write-only access, link rejection, final authority checks, and cleanup. ([#573](https://github.com/openclaw/fs-safe/pull/573))
+- Isolate tree-copy cancellation from caller event handlers across native cloning and portable byte-copy fallback. Preserve caller handlers, first-failure selection, and per-file cancellation; join admitted work before releasing descriptors and native signal handlers. Dispatched APFS/Btrfs bulk operations remain uninterruptible, and failed or cancelled copies can leave caller-owned output. ([#561](https://github.com/openclaw/fs-safe/pull/561), [copy cancellation contract](https://github.com/openclaw/fs-safe/blob/v0.18.0/docs/copy.md))
+- Preserve synchronous secret-read and identity-validation errors, including their causes, when closing the descriptor also fails. Make one close attempt and retain the existing lone-close failure behavior. ([#566](https://github.com/openclaw/fs-safe/pull/566))
+- Preserve asynchronous copy-source results and destination-admission failures when custom filesystem adapters throw synchronously during best-effort close. Apply the same handling to atomic admission pins, best-effort parent synchronization, and replacement pins that were not adopted, without changing filesystem identity checks or retained-owner close policy. ([#545](https://github.com/openclaw/fs-safe/pull/545), [#554](https://github.com/openclaw/fs-safe/pull/554))
+- Reject unverified Windows owner locality while retaining valid local/remote classification, SID-validation precedence, bounded diagnostics, and exact rejected values. Share permission-report metadata across native and command inspection without sharing mutable public results or changing ACL policy. ([#547](https://github.com/openclaw/fs-safe/pull/547), [#567](https://github.com/openclaw/fs-safe/pull/567))
+
+### Performance and package size
+
+- Reduce redundant metadata observations and scheduling in secret reads, regular-file admission, and staged publication. An isolated Linux comparison measured `readSecretFileSync()` about 11% faster; five other measured calls were roughly unchanged. Exact identity and mutation checks remain. ([#535](https://github.com/openclaw/fs-safe/pull/535))
+- Share Root metadata traversal and reuse normalized missing-path suffixes instead of rebuilding per-component arrays. An isolated Linux/native-off comparison measured roughly 3–4% lower resolver medians, with a slightly higher maximum synchronous sample average. Preserve async/sync canonicalization routes, Windows alias rejection, dangling-link behavior, and observation receipts. ([#536](https://github.com/openclaw/fs-safe/pull/536), [#562](https://github.com/openclaw/fs-safe/pull/562))
+- Consolidate durable-queue directory and metadata ownership while retaining asynchronous file I/O, path admission, exact identities, and recovery synchronization. Small and 64 KiB reads measured 8.68% and 13.78% faster in a balanced Linux comparison; durable medians stayed within −1.09% to +1.21%, with isolated higher maxima documented. ([#549](https://github.com/openclaw/fs-safe/pull/549))
+- Reuse scratch storage between fallback SHA-256 operations, retaining at most four idle buffers of up to 256 KiB each. Clear used contents before retention and keep each pending read's storage exclusive until settlement, including cancellation; preserve byte limits and borrowed descriptor cursors. ([#550](https://github.com/openclaw/fs-safe/pull/550))
+- Share Windows drive and namespace syntax checks without rewriting whole inputs during network classification. Predicate measurements showed gains for normal Windows paths under Linux with explicit Windows rules and a small rooted-alias cost; they do not establish end-to-end Windows throughput. ([#539](https://github.com/openclaw/fs-safe/pull/539))
+- Omit `.d.ts.map` output and package entries whose targets are unpublished TypeScript sources, and make package validation reject those maps. The PR's baseline/candidate comparison measured a 5.8% smaller compressed package and 7.8% smaller unpacked package; declarations and public exports remain intact. Thanks @vincentkoc. ([#570](https://github.com/openclaw/fs-safe/pull/570))
+
+### Maintenance and platform validation
+
+- Consolidate archive staging, directory admission, temporary ownership, synchronous store receipt chains, lock registration and acquisition, and ordered mutation-denial policy. Preserve authority boundaries, exact identity checks, callback ordering, stale recovery, and publication/cleanup ownership. These are maintenance changes; measured raw-lock overhead and other control tradeoffs remain documented in their PRs. ([#535](https://github.com/openclaw/fs-safe/pull/535), [#537](https://github.com/openclaw/fs-safe/pull/537), [#538](https://github.com/openclaw/fs-safe/pull/538), [#542](https://github.com/openclaw/fs-safe/pull/542))
+- Specialize private lock, store, JSON retry, filename, rename, and move-cleanup helpers to their existing callers; remove unused descriptor projections and native lock-handle methods. Preserve public defaults, shared validators, Windows device-name protection, root replacement checks, and trash fallback behavior. Share write-policy callback types without changing emitted JavaScript or public type semantics. ([#551](https://github.com/openclaw/fs-safe/pull/551), [#552](https://github.com/openclaw/fs-safe/pull/552), [#556](https://github.com/openclaw/fs-safe/pull/556), [#558](https://github.com/openclaw/fs-safe/pull/558), [#546](https://github.com/openclaw/fs-safe/pull/546), [#543](https://github.com/openclaw/fs-safe/pull/543))
+- Share guest Python operand admission and descriptor cleanup, retain native POSIX beneath-open descriptors until handoff, and use the shared Windows handle owner for process tokens. Simplify native task settlement, SHA-256 worker state, and Unix cleanup forwarding while preserving containment, positioned reads, cancellation checks, handle ownership, and error precedence. ([#540](https://github.com/openclaw/fs-safe/pull/540), [#541](https://github.com/openclaw/fs-safe/pull/541), [#535](https://github.com/openclaw/fs-safe/pull/535), [#555](https://github.com/openclaw/fs-safe/pull/555), [#565](https://github.com/openclaw/fs-safe/pull/565))
+- Use existing Windows SDK declarations for native syscalls and verify the built addon's imports in installed npm and pnpm consumers. Share native link/rename admission and the archive entry schema; simplify Windows relative-open policy while preserving source-before-target errors, manifest snapshots, reparse checks, exact created-directory ownership, and hardlink access. ([#563](https://github.com/openclaw/fs-safe/pull/563), [#560](https://github.com/openclaw/fs-safe/pull/560), [#564](https://github.com/openclaw/fs-safe/pull/564), [#559](https://github.com/openclaw/fs-safe/pull/559))
+- Keep filesystem fixtures and backend settings alive until timed-out operations settle, make the in-flight archive deadline regression deterministic, and exercise queue recovery where directory synchronization is unsupported. Send guest-test stdin only to operations that consume it and give the durable copy-restoration regression its instrumented Windows budget. Expand public mutation proof selection to shared policy/path owners without weakening runtime deadlines or settlement assertions. ([#553](https://github.com/openclaw/fs-safe/pull/553), [#556](https://github.com/openclaw/fs-safe/pull/556), [#549](https://github.com/openclaw/fs-safe/pull/549), [#543](https://github.com/openclaw/fs-safe/pull/543), [#540](https://github.com/openclaw/fs-safe/pull/540), [#538](https://github.com/openclaw/fs-safe/pull/538))
+
 ## 0.17.0 - 2026-09-20
 
 ### Highlights

package/dist/absolute-path.d.ts

@@ -30,4 +30,3 @@ export declare function resolveAbsolutePathForRead(filePath: string, options?: {
 export declare function resolveAbsolutePathForWrite(filePath: string, options?: {
     symlinks?: AbsolutePathSymlinkPolicy;
 }): Promise<ResolvedWritableAbsolutePath>;
-//# sourceMappingURL=absolute-path.d.ts.map

package/dist/advanced.d.ts

@@ -33,4 +33,3 @@ export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularF
 export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
 export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionCommandFailure, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions.js";
-//# sourceMappingURL=advanced.d.ts.map

package/dist/archive-crc32.d.ts

@@ -1,2 +1 @@
 export declare function updateCrc32(previous: number, buffer: Buffer): number;
-//# sourceMappingURL=archive-crc32.d.ts.map

package/dist/archive-deadline.d.ts

@@ -9,4 +9,3 @@ export declare function ownExtractionDestinationMutation<T>(deadline: Extraction
 export declare function createPipelineTimeoutError(err: unknown, deadline: ExtractionDeadline): unknown;
 export declare function waitForDeadline<T>(promise: Promise<T>, deadline: ExtractionDeadline): Promise<T>;
 export declare function withExtractionDeadline<T>(timeoutMs: number, label: string, run: (deadline: ExtractionDeadline) => Promise<T>): Promise<T>;
-//# sourceMappingURL=archive-deadline.d.ts.map

package/dist/archive-durability.d.ts

@@ -21,4 +21,3 @@ export declare function finalizeArchivePublication(params: {
     durable: boolean;
     deadline?: ExtractionDeadline;
 }): Promise<void>;
-//# sourceMappingURL=archive-durability.d.ts.map

package/dist/archive-entry.d.ts

@@ -11,4 +11,3 @@ export declare function resolveArchiveOutputPath(params: {
     originalPath: string;
     escapeLabel?: string;
 }): string;
-//# sourceMappingURL=archive-entry.d.ts.map

package/dist/archive-errors.d.ts

@@ -10,4 +10,3 @@ export declare class ArchiveFormatError extends Error {
 }
 export declare function isArchiveFormatErrorMessage(message: string): boolean;
 export declare function isArchiveTarPathErrorMessage(message: string): boolean;
-//# sourceMappingURL=archive-errors.d.ts.map

package/dist/archive-gzip-tail.d.ts

@@ -18,4 +18,3 @@ export declare class GzipInput extends Writable {
 /** Check the immutable staged suffix from the first unused physical byte,
  * including later chunks the decoder may have consumed, before returning. */
 export declare function validateGzipContainerTail(filePath: string, consumed: number, signal?: AbortSignal): Promise<void>;
-//# sourceMappingURL=archive-gzip-tail.d.ts.map

package/dist/archive-input.d.ts

@@ -16,4 +16,3 @@ export declare function stageArchiveFileForExtraction(params: {
     limits: ResolvedArchiveExtractLimits;
     deadline: ExtractionDeadline;
 }): Promise<StagedArchiveFile>;
-//# sourceMappingURL=archive-input.d.ts.map

package/dist/archive-kind.d.ts

@@ -5,4 +5,3 @@ type ResolvePackedRootDirOptions = {
 };
 export declare function resolvePackedRootDir(extractDir: string, options?: ResolvePackedRootDirOptions): Promise<string>;
 export {};
-//# sourceMappingURL=archive-kind.d.ts.map

package/dist/archive-limits.d.ts

@@ -54,4 +54,3 @@ export declare function createByteBudgetTracker(limits: ResolvedArchiveExtractLi
 export declare function createExtractBudgetTransform(params: {
     onChunkBytes: (bytes: number) => void;
 }): Transform;
-//# sourceMappingURL=archive-limits.d.ts.map

package/dist/archive-merge.d.ts

@@ -14,11 +14,9 @@ type MergeParams = {
 type GuardedMergeParams = Pick<MergeParams, "sourceDir" | "deadline"> & {
     destinationGuard: ArchiveDirectoryGuard;
 };
-export declare function mergePlannedArchiveIntoDestination(params: GuardedMergeParams & {
-    entries: readonly ArchivePublicationEntry[];
+export declare function withStagedArchivePublication(params: Omit<GuardedMergeParams, "sourceDir"> & {
     durable?: boolean;
     entryUmask?: number;
-}): Promise<void>;
+}, extract: (stagingDir: string) => Promise<readonly ArchivePublicationEntry[]>): Promise<void>;
 export declare function mergeExtractedTreeIntoDestination(params: MergeParams): Promise<void>;
 export {};
-//# sourceMappingURL=archive-merge.d.ts.map

package/dist/archive-merge.js

@@ -2,7 +2,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { ownExtractionDestinationMutation } from "./archive-deadline.js";
-import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, } from "./archive-staging.js";
+import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
 import {} from "./directory-mode-owner.js";
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
 import { assertSyncDirectoryGuard, inspectDirectoryIdentitySync } from "./directory-guard.js";
@@ -18,9 +18,19 @@ import { syncFileBestEffortSync } from "./file-sync.js";
 import { finalizeArchivePublication } from "./archive-durability.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
-export async function mergePlannedArchiveIntoDestination(params) {
-    assertMergePathInputs(params);
-    await mergeTree(params, params.entries, params.durable === true, params.entryUmask);
+export async function withStagedArchivePublication(params, extract) {
+    await withStagedArchiveDestination({
+        destinationRealDir: params.destinationGuard.realPath,
+        run: async (stagingPath) => {
+            const sourceDir = realpathSync.native(stagingPath);
+            const entries = await extract(sourceDir);
+            params.deadline?.check();
+            const mergeParams = { ...params, sourceDir };
+            assertMergePathInputs(mergeParams);
+            await mergeTree(mergeParams, entries, params.durable === true, params.entryUmask);
+            params.deadline?.check();
+        },
+    });
 }
 export async function mergeExtractedTreeIntoDestination(params) {
     const sourceDir = params.sourceDir;

package/dist/archive-native.d.ts

@@ -1,22 +1,10 @@
-import type { ExtractionDeadline } from "./archive-deadline.js";
 import type { ArchiveKind } from "./archive-kind.js";
-import { type ResolvedArchiveExtractLimits, type TarMeterLimits } from "./archive-limits.js";
-import type { ExtractArchiveOptions } from "./archive-options.js";
+import { type TarMeterLimits } from "./archive-limits.js";
+import type { StagedArchiveExtractOptions } from "./archive-options.js";
 import type { NativeBinding } from "./native.js";
 export declare function throwMappedNativeArchiveError(error: unknown): never;
-export declare function extractNativeArchive(params: {
-    durable?: boolean;
+export declare function extractNativeArchive(params: StagedArchiveExtractOptions & {
     binding: NativeBinding;
-    archivePath: string;
-    destDir: string;
     kind: ArchiveKind;
-    stripComponents?: number;
-    limits: ResolvedArchiveExtractLimits;
     tarLimits: TarMeterLimits;
-    deadline: ExtractionDeadline;
-    entryModes?: ExtractArchiveOptions["entryModes"];
-    entryUmask?: number;
-    entryFilter?: ExtractArchiveOptions["entryFilter"];
-    onFiltered?: ExtractArchiveOptions["onFiltered"];
 }): Promise<void>;
-//# sourceMappingURL=archive-native.d.ts.map

package/dist/archive-native.js

@@ -4,10 +4,9 @@ import fs from "node:fs/promises";
 import { ArchiveFormatError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
 import { validateArchiveEntryPath } from "./archive-entry.js";
 import { createArchiveEntryPlanner } from "./archive-plan.js";
-import { stageArchiveFileForExtraction } from "./archive-input.js";
 import { assertArchiveEntryCountWithinLimit, } from "./archive-limits.js";
-import { prepareArchiveDestinationGuard, withStagedArchiveDestination, } from "./archive-staging.js";
-import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
+import { prepareArchiveDestinationGuard } from "./archive-staging.js";
+import { withStagedArchivePublication } from "./archive-merge.js";
 import { admitZipFile } from "./archive-zip-admission.js";
 import { validateNativeZipManifest } from "./archive-zip-manifest.js";
 export function throwMappedNativeArchiveError(error) {
@@ -25,74 +24,50 @@ export function throwMappedNativeArchiveError(error) {
     throw error;
 }
 export async function extractNativeArchive(params) {
-    const { limits, tarLimits } = params;
-    const stagedArchive = await stageArchiveFileForExtraction({
-        archivePath: params.archivePath,
-        limits,
-        deadline: params.deadline,
-    });
-    try {
-        const zipEntries = [];
+    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") {
-            await admitZipFile(stagedArchive.path, limits, params.deadline, (entry) => { zipEntries.push(entry); });
+            validateNativeZipManifest(manifest, zipEntries);
         }
-        const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
-        const destinationRealDir = destinationGuard.realPath;
-        await withStagedArchiveDestination({
-            destinationRealDir,
-            run: async (stagingDir) => {
-                params.deadline.check();
-                // N-API retains completed task state on its signal; each pass needs its own.
-                const manifest = await params.binding
-                    .inspectArchiveNative(stagedArchive.path, params.kind, tarLimits, AbortSignal.any([params.deadline.signal]))
-                    .catch(throwMappedNativeArchiveError);
-                params.deadline.check();
-                assertArchiveEntryCountWithinLimit(manifest.length, limits);
-                if (params.kind === "zip") {
-                    validateNativeZipManifest(manifest, zipEntries);
-                }
-                // Recheck the native manifest at the shared policy boundary 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) {
-                    params.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 {
-                    params.deadline.check();
-                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan.map((entry) => ({ ...entry, mode: entry.kind === "directory" ? 0o700 : 0o600 })), tarLimits, AbortSignal.any([params.deadline.signal])).catch(throwMappedNativeArchiveError);
-                }
-                finally {
-                    await directory.close().catch(() => undefined);
-                }
-                params.deadline.check();
-                await mergePlannedArchiveIntoDestination({
-                    entries: plan,
-                    durable: params.durable,
-                    entryUmask: params.entryUmask,
-                    sourceDir: stagingDir,
-                    destinationGuard,
-                    deadline: params.deadline,
-                });
-                params.deadline.check();
-            },
-        });
-    }
-    finally {
-        await stagedArchive.cleanup();
-    }
+        // 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;
+    });
 }

package/dist/archive-options.d.ts

@@ -1,5 +1,6 @@
 import type { ArchiveKind } from "./archive-kind.js";
-import type { ArchiveExtractLimits } from "./archive-limits.js";
+import type { ExtractionDeadline } from "./archive-deadline.js";
+import type { ArchiveExtractLimits, ResolvedArchiveExtractLimits } from "./archive-limits.js";
 import type { ArchiveEntryFilter, ArchiveEntryModePolicy, ArchiveFilteredEntryPolicy } from "./archive-policy.js";
 export type ArchiveLogger = {
     info?: (message: string) => void;
@@ -22,4 +23,8 @@ export type ExtractArchiveOptions = {
     entryFilter?: ArchiveEntryFilter;
     onFiltered?: ArchiveFilteredEntryPolicy;
 };
-//# sourceMappingURL=archive-options.d.ts.map
+/** 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-parser-errors.d.ts

@@ -1,2 +1 @@
 export declare function classifyArchiveParserError(message: string, options?: ErrorOptions): Error | undefined;
-//# sourceMappingURL=archive-parser-errors.d.ts.map

package/dist/archive-plan.d.ts

@@ -1,5 +1,7 @@
 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";
 export type ArchiveMemberKind = "file" | "directory" | "symlink" | "hardlink" | "blocked" | "sparse" | "other";
 export type ArchivePlanEntry = {
     path: string;
@@ -11,10 +13,17 @@ export type ArchivePlanOptions = Pick<ExtractArchiveOptions, "stripComponents" |
     rootDir?: string;
     escapeLabel?: string;
 };
+export declare function createArchiveEntrySelector(params: ArchivePlanOptions): {
+    limits: ResolvedArchiveExtractLimits;
+    select(entry: {
+        path: string;
+        kind: ArchiveEntryKind;
+        size: number;
+    }): string | null;
+};
 export declare function createArchiveEntryPlanner(params: ArchivePlanOptions, archiveKind: ArchiveKind): (entry: {
     path: string;
     kind: ArchiveMemberKind;
     size: number;
     mode?: number;
 }) => ArchivePlanEntry | null;
-//# sourceMappingURL=archive-plan.d.ts.map

package/dist/archive-plan.js

@@ -3,34 +3,44 @@ import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchiveP
 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";
-// Inspection and both executors decide over the same admitted identities.
-// A destination is optional only for inspection; writers still prove containment.
-export function createArchiveEntryPlanner(params, archiveKind) {
+// Portable ZIP selects each entry immediately before streaming its payload;
+// manifest-backed routes add declared-byte admission through the planner below.
+export function createArchiveEntrySelector(params) {
     const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
     const limits = resolveExtractLimits(params.limits);
-    const budget = createByteBudgetTracker(limits);
     const trackOutputPath = createArchiveOutputPathTracker();
     let entryCount = 0;
+    return { limits, select(entry) {
+            assertArchiveEntryCountWithinLimit(++entryCount, limits);
+            validateArchiveEntryPath(entry.path, { escapeLabel: params.escapeLabel });
+            const canonicalPath = stripArchivePath(entry.path, 0);
+            if (!canonicalPath)
+                return null;
+            const relPath = strip === 0 ? canonicalPath : stripArchivePath(canonicalPath, strip);
+            if (!relPath)
+                return null;
+            validateArchiveEntryPath(relPath, { escapeLabel: params.escapeLabel });
+            assertArchiveEntryPathComponentsWithinLimit(relPath, limits);
+            trackOutputPath(relPath, entry.path);
+            if (params.rootDir !== undefined) {
+                resolveArchiveOutputPath({ rootDir: params.rootDir, relPath, originalPath: entry.path,
+                    escapeLabel: params.escapeLabel });
+            }
+            if (!shouldExtractArchiveEntry({ filter: params.entryFilter, onFiltered: params.onFiltered,
+                entry: { path: canonicalPath, kind: entry.kind, size: entry.size } }))
+                return null;
+            return relPath;
+        } };
+}
+// A destination is optional only for inspection; writers still prove containment.
+export function createArchiveEntryPlanner(params, archiveKind) {
+    const { select, limits } = createArchiveEntrySelector(params);
+    const budget = createByteBudgetTracker(limits);
     return (entry) => {
-        assertArchiveEntryCountWithinLimit(++entryCount, limits);
-        validateArchiveEntryPath(entry.path, { escapeLabel: params.escapeLabel });
-        const canonicalPath = stripArchivePath(entry.path, 0);
-        if (!canonicalPath)
-            return null;
-        const relPath = strip === 0 ? canonicalPath : stripArchivePath(canonicalPath, strip);
-        if (!relPath)
-            return null;
-        validateArchiveEntryPath(relPath, { escapeLabel: params.escapeLabel });
-        assertArchiveEntryPathComponentsWithinLimit(relPath, limits);
-        trackOutputPath(relPath, entry.path);
-        if (params.rootDir !== undefined) {
-            resolveArchiveOutputPath({ rootDir: params.rootDir, relPath, originalPath: entry.path,
-                escapeLabel: params.escapeLabel });
-        }
         const kind = entry.kind === "file" || entry.kind === "directory" ? entry.kind
             : entry.kind === "symlink" || entry.kind === "hardlink" ? "symlink" : "other";
-        if (!shouldExtractArchiveEntry({ filter: params.entryFilter, onFiltered: params.onFiltered,
-            entry: { path: canonicalPath, kind, size: entry.size } }))
+        const relPath = select({ path: entry.path, kind, size: entry.size });
+        if (relPath === null)
             return null;
         if (entry.kind === "sparse") {
             throw new ArchiveFormatError(`GNU sparse archive entry is not supported: ${formatErrorDetail(entry.path)}`);

package/dist/archive-policy.d.ts

@@ -19,4 +19,3 @@ export declare function shouldExtractArchiveEntry(params: {
     onFiltered?: ArchiveFilteredEntryPolicy;
     entry: Parameters<ArchiveEntryFilter>[0];
 }): boolean;
-//# sourceMappingURL=archive-policy.d.ts.map

package/dist/archive-read.d.ts

@@ -3,4 +3,3 @@ export declare function readArchiveEntry(archivePath: string, entryPath: string,
     maxBytes: number;
     kind?: ArchiveKind;
 }): Promise<Buffer>;
-//# sourceMappingURL=archive-read.d.ts.map

package/dist/archive-staging.d.ts

@@ -31,4 +31,3 @@ export declare function withStagedArchiveDestination<T>(params: {
 }): Promise<T>;
 export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
-//# sourceMappingURL=archive-staging.d.ts.map

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

@@ -4,4 +4,3 @@ export type InspectTarArchiveOptions = Pick<ExtractArchiveOptions, "archivePath"
 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[]>;
-//# sourceMappingURL=archive-tar-inspect.d.ts.map

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

@@ -25,4 +25,3 @@ export declare function replayTar<T extends AdmittedTarMember>(params: TarInput
     consume(member: T, payload: AsyncIterable<Buffer>): Promise<void>;
 }): Promise<void>;
 export {};
-//# sourceMappingURL=archive-tar-stream.d.ts.map

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

@@ -27,4 +27,3 @@ export declare class TarParserStream extends Transform {
     _flush(callback: TransformCallback): void;
     _destroy(error: Error | null, callback: (error: Error | null) => void): void;
 }
-//# sourceMappingURL=archive-tar-wasm.d.ts.map

package/dist/archive-tar.d.ts

@@ -16,4 +16,3 @@ export declare function createTarEntryPreflightChecker(params: {
     entryFilter?: ArchiveEntryFilter;
     onFiltered?: ArchiveFilteredEntryPolicy;
 }): (entry: TarEntryInfo) => boolean;
-//# sourceMappingURL=archive-tar.d.ts.map

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

@@ -5,4 +5,3 @@ import { type ZipDirectoryEntry } from "./archive-zip-directory.js";
 export declare function admitZipBuffer(input: Uint8Array, limits: ResolvedArchiveExtractLimits, onEntry?: (entry: ZipDirectoryEntry) => void): number;
 /** The extraction input is private and immutable; read bounded metadata windows. */
 export declare function admitZipFile(archivePath: string, limits: ResolvedArchiveExtractLimits, deadline: ExtractionDeadline, onEntry?: (entry: ZipDirectoryEntry) => void): Promise<number>;
-//# sourceMappingURL=archive-zip-admission.d.ts.map

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

@@ -1,2 +1 @@
 export declare function readZipCentralDirectoryEntryCount(buffer: Buffer | Uint8Array): number | null;
-//# sourceMappingURL=archive-zip-count.d.ts.map

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

@@ -19,4 +19,3 @@ export type ZipDirectoryEntry = {
     kind: ArchiveEntryKind;
 };
 export declare function scanZipDirectory(size: number, limits: ResolvedArchiveExtractLimits, onEntry?: (entry: ZipDirectoryEntry) => void): ZipScan;
-//# sourceMappingURL=archive-zip-directory.d.ts.map

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

@@ -22,4 +22,3 @@ export declare function isZipSymlinkEntry(entry: ZipEntry): boolean;
 export declare function zipEntryKind(entry: ZipEntry): ArchiveEntryKind;
 export declare function zipEntryMode(entry: ZipEntry, policy: ArchiveEntryModePolicy | undefined): number;
 export declare function zipEntryDeclaredSize(entry: ZipEntry): number;
-//# sourceMappingURL=archive-zip-entry.d.ts.map

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

@@ -2,4 +2,3 @@ import { Transform } from "node:stream";
 import { type ZipEntry } from "./archive-zip-entry.js";
 export declare function normalizeZipIntegrityError(error: unknown): Error;
 export declare function createZipIntegrityTransform(entry: ZipEntry): Transform;
-//# sourceMappingURL=archive-zip-integrity.d.ts.map

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

@@ -6,4 +6,3 @@ export type ZipArchiveWithFiles = {
 export declare function admittedZipEntries(archive: ZipArchiveWithFiles): readonly ZipEntry[];
 /** Internal: the caller has admitted these unchanged bytes and their metadata. */
 export declare function loadAdmittedZipArchive(buffer: Buffer | Uint8Array, admitted: ZipDirectoryEntry[]): Promise<ZipArchiveWithFiles>;
-//# sourceMappingURL=archive-zip-loader.d.ts.map

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

@@ -2,4 +2,3 @@ import type { NativeArchiveEntry } from "./native-binding.js";
 import type { ZipDirectoryEntry } from "./archive-zip-directory.js";
 /** Associate all native entries with physical admission before exposing any. */
 export declare function validateNativeZipManifest(manifest: NativeArchiveEntry[], admitted: ZipDirectoryEntry[]): void;
-//# sourceMappingURL=archive-zip-manifest.d.ts.map

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

@@ -15,4 +15,3 @@ export declare function admitZipNames(params: {
     portableDirectory: boolean;
     directory: boolean;
 };
-//# sourceMappingURL=archive-zip-names.d.ts.map

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

@@ -3,4 +3,3 @@ import { type ZipArchiveWithFiles } from "./archive-zip-loader.js";
 export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
 export type { ZipArchiveWithFiles } from "./archive-zip-loader.js";
 export declare function loadZipArchiveWithPreflight(buffer: Buffer | Uint8Array, limits?: ArchiveExtractLimits): Promise<ZipArchiveWithFiles>;
-//# sourceMappingURL=archive-zip-preflight.d.ts.map

package/dist/archive.d.ts

@@ -12,4 +12,3 @@ export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination,
 export { createTarEntryPreflightChecker, type TarEntryInfo } from "./archive-tar.js";
 export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, type ZipArchiveWithFiles, } from "./archive-zip-preflight.js";
 export declare function extractArchive(params: ExtractArchiveOptions): Promise<void>;
-//# sourceMappingURL=archive.d.ts.map