@poe-platform/safe-fs 0.1.721 → 0.1.723

package/README.md

@@ -23,9 +23,11 @@ await fs.appendFile("note.txt", " world", "utf8");
 console.log(await fs.readFile("note.txt", "utf8"));
 ```
 
-Output: `hello`, then `hello world`. Nothing touches the host filesystem. Raw adapters exchange `Uint8Array` values; the Node bridge adds strings, encodings, `Buffer` results, and stat predicates. Its `cwd` is both the relative-path base and the confinement boundary.
+Output: `hello`, then `hello world`. Nothing touches the host filesystem. Raw adapters exchange `Uint8Array` values; the Node bridge adds strings, encodings, `Buffer` results, and stat predicates. Its `cwd` is the relative-path base and, by default, the confinement boundary. Set an explicit `root` to use a different boundary, for example `{ cwd: "/work", root: "/" }` to address a complete provider namespace. The bridge supports `unlink` when the provider offers atomic file removal; unsupported methods fail without host fallback. `createHostFileSystem()` provides trusted, unrestricted native host access when a rooted adapter is not desired.
 
-For host storage, use `await createRealFileSystem({ root: "/absolute/existing/directory" })` instead. The root must already exist; virtual `/` maps to that directory. Read the safety boundary below before exposing it to untrusted code.
+For host storage, use `await createRealFileSystem({ root: "/absolute/existing/directory" })` instead. The root must already exist; virtual `/` maps to that directory. ZIP creation and updates can use this adapter's private owned staging in an isolated host tree. Unzip extraction requires atomic ancestry verification, currently supported by MemoryFileSystem; the real adapter and mount views refuse it. Its `trustedOwnedStaging` capability checks original entries before publication and cleanup, and preserves foreign staging children. It does not advertise atomic conditional mutations: keep external writers and other in-flight writes away from the tree during these operations. Read the safety boundary below before exposing it to untrusted code.
+
+To create new outputs with Safe Bash's `dos2unix`, `unix2dos`, or compression commands, host adapters need atomic no-replace publication. Supply `createRealFileSystem({ root, renameNoReplace })` only when that callback binds a qualified native primitive such as Linux `renameat2` with `RENAME_NOREPLACE`. It receives resolved absolute host paths and an optional signal in its third argument. Existing destinations must reject `EEXIST` atomically; existence checks followed by rename and copy/delete are insufficient. Without this binding the adapter explicitly refuses those operations. See the [no-replace contract](src/contracts/filesystem.md#atomic-no-replace-rename).
 
 ## Entry points and shared identity
 
@@ -47,6 +49,10 @@ Existing `@poe-platform/safe-js/fs`, `/fs/core`, and `/fs/node` imports remain
 re-exports, so `FsError` identity is shared; do not copy its implementation or the
 `FileSystem` declaration. `FileSystem` is an interface, not a runtime class.
 
+Custom filesystem views can use `registerEntryView(view, async path => ({ filesystem: backing, path }))`
+from `/core` so `compareEntries` recognizes their backing entries in either direction.
+The resolver can also return `readOnly: true`; each view can be registered once.
+
 Legacy `poe-code/safe-fs` imports still use the CLI's bundled runtime. Keep an
 application's factories, shell, and errors in one import family. At a host-owned
 legacy adapter boundary, normalize foreign filesystem failures with `toFsError`
@@ -64,6 +70,7 @@ cause. Preserve cancellation/control exceptions separately. Cross-family
 | Remove an empty directory | Optional `rmdir`; never a recursive-delete fallback |
 | Links and metadata | Optional `readlink`, `symlink`, `link`, `chmod`, `utimes`, `truncate` |
 | Stream bytes | Optional `readStream`, `writeStream`, using async iterables of byte chunks |
+| Retain an open file | Optional `open` with positioned I/O and synchronization; memory and real backends support `noFollow: true` to atomically refuse a final symlink |
 | Publish immutable objects atomically | Optional `publishFileConditional` with opaque identity/version stats and authoritative compare-and-publish |
 | Compare backing entries | Optional `compareEntry`, returning `same`, `distinct`, or `unknown` |
 
@@ -76,7 +83,7 @@ writes when the host supplies `store.createStaging`: private externally backed
 pages keep working memory bounded without publishing the growing file after
 every write. Conditional publication still occurs at sync/close, and retained
 readers keep their old versions. Without that optional backend primitive, the
-default 8 MiB dirty-page budget still limits unflushed output. See the
+optional dirty-page budget limits unflushed output only when configured. See the
 [object descriptor and spill contract](src/contracts/object-publication.md) for
 backend methods, failure semantics and qualification; no provider storage is
 configured automatically.
@@ -93,7 +100,7 @@ before implementing the host operation; ordinary writes do not provide it.
 
 | Backend or wrapper | Use it for |
 | --- | --- |
-| `createMemoryFileSystem()` | Isolated, nonpersistent storage with links, permissions, timestamps, and streams |
+| `createMemoryFileSystem()` | Isolated, nonpersistent storage with links, permissions, timestamps, and streams; each path resolution admits at most 65,536 cumulative UTF-16 code units across the input and followed symlink targets, rejecting excess with `ENAMETOOLONG` before component allocation |
 | `createRealFileSystem({ root })` | An existing host directory, with virtual paths rooted inside it; Node only |
 | `new S3FileSystem({ transport, bucket, … })` | Bucket/prefix storage through an explicitly supplied transport; Node only |
 | `new WebDavFileSystem({ baseUrl, fetch, … })` | A WebDAV namespace through an explicitly supplied Fetch implementation |
@@ -102,7 +109,7 @@ before implementing the host operation; ordinary writes do not provide it.
 | `createOverlayFileSystem({ upper, lower })` | Reading through to a lower layer and writing changes to an upper layer |
 | `withFileSystemQuota(filesystem, { maxBytes })` | Enforcing a cumulative logical-byte ceiling across every write path |
 
-`createNodeFsBridge` offers a promises-shaped subset, including recursive `cp` and `mkdtemp`. The portable `createFsBridge` from `@poe-platform/safe-fs/core` instead requires a caller-supplied text codec and returns `Uint8Array` values.
+`createNodeFsBridge` offers a promises-shaped subset, including recursive `cp` and `mkdtemp`. A trusted `reserveReadFile` callback can reserve host resources and return a release function; cancellation retains the reservation until the backend read settles. The portable `createFsBridge` from `@poe-platform/safe-fs/core` instead requires a caller-supplied text codec and returns `Uint8Array` values.
 
 ## Write an adapter
 
@@ -219,15 +226,15 @@ There are no package environment variables, implicit credentials, or automatic `
 
 | API | Options and defaults |
 | --- | --- |
-| `createFileSystem(config, { registry })` | Required `config.type`; `config.options` defaults to an empty record. `registry` is required. Built-in `memory` accepts no options; built-in `real` requires `root`. |
+| `createFileSystem(config, { registry })` | Required `config.type`; `config.options` defaults to an empty record. `registry` is required. Built-in `memory` accepts optional file, retained-byte, metadata and total-byte quotas; built-in `real` requires `root`. |
 | `createNodeFileSystemAdapterRegistry(extensions?)` | Optional map of additional adapter descriptors; defaults to only `memory` and `real`. |
-| Memory / read-only | Memory takes no options. Read-only takes the backing filesystem, without an options object. |
+| Memory / read-only | Memory accepts independent optional `maxFileBytes`, `maxRetainedBytes`, `maxMetadataUnits` and `maxBytes` quotas, all unlimited by default. Read-only takes the backing filesystem, without an options object. |
 | Real | Required `root`: existing absolute host directory; the constructor/factory also accepts the root string directly. |
 | Mount | Required `root`: fallback filesystem. `mounts` defaults to `{}` and maps absolute virtual paths to filesystems. |
-| Overlay | Required `upper` and `lower`; `maxBufferBytes` defaults to 64 MiB. |
+| Overlay | Required `upper` and `lower`; `maxBufferBytes` is unlimited unless configured. |
 | Quota | `withFileSystemQuota` requires a nonnegative safe-integer `maxBytes`. It serializes mutations and counts files, symlinks, copies, hard links, truncation, and streaming writes. |
-| Node bridge | `cwd` defaults to `/`, must be an absolute virtual path; optional lifetime `signal`. |
-| Portable bridge | Same `cwd` and `signal`, plus required `codec` with `isEncoding`, `encode`, and `decode` functions. |
+| Node bridge | `cwd` defaults to `/`, must be an absolute virtual path; optional lifetime `signal` and trusted `readFileMaxBytes` cap forwarded to backend reads before copy/decode. |
+| Portable bridge | Same `cwd`, `signal` and `readFileMaxBytes`, plus required `codec` with `isEncoding`, `encode`, and `decode` functions. |
 | Catalog example | Required `files`: a plain record of single-component filenames to text strings; no other options. |
 
 ### Per-operation options
@@ -246,6 +253,8 @@ Every raw filesystem operation accepts an optional `signal`. Additional fields a
 
 `access` takes a separate mode bitmask from `ACCESS_MODES`. `chmod` takes a mode, `utimes` takes millisecond timestamps, and `truncate` takes a byte length (default 0). Backend limits still apply. Node-shaped bridge methods translate their own options rather than accepting these raw option objects; see the [bridge signatures](src/bridge/filesystem.ts).
 
+`collectBytes(source, { maxBytes, maxMemoryBytes, signal })` snapshots streamed chunks into one growing buffer. `maxMemoryBytes` limits owned capacity, the current input's full backing buffer, and overlapping allocations during growth; exhaustion throws `EFBIG`. Browser and Worker bundles additionally share a fixed 32 MiB budget across active collectors, even when byte limits are omitted. The returned view may retain geometric spare capacity. This budget covers collection, not caller-retained results, transport buffering, archive decoding, strings, or the rest of the runtime; use streaming APIs and limit concurrent workloads for larger inputs.
+
 <details>
 <summary>S3 filesystem and HTTP transport options</summary>
 
@@ -261,11 +270,39 @@ For in-memory S3 simulations, `new MockS3Client({ buckets, pageSize?, now?, auth
 | `readOnly` | `false` |
 | `allowNonAtomicRename` | `true`; rename copies then deletes, without rollback guarantees |
 | `pageSize` | 1,000; range 1–1,000 |
-| `maxReadBytes` | 64 MiB |
-| `maxStreamBytes` | 5,000,000,000 bytes; also the maximum accepted value |
-| `maxListEntries` | 100,000 |
+| `maxReadBytes` | Unlimited unless configured |
+| `maxStreamBytes` | Unlimited unless configured |
+| `maxListEntries` | Unlimited unless configured |
+| `removalLimits.maxRequests` | 32 transport calls per `rm`, including lookup, listing, and deletes |
+| `removalLimits.maxListEntries` | 32 returned listing entries in aggregate per `rm`, including lookup |
+| `removalLimits.maxDeleteObjects` | 16 objects per `rm` |
 | `compareEntry` | Optional trusted backing-identity callback |
 
+Removal limits apply even when shell filesystem-call limits admit a recursive `rm` as one operation. Each limit accepts a positive safe integer. Traversal stops at the listing/request cap and rejects with `EFBIG`; all delete requests must fit the remaining request budget before the first mutation. Nonrecursive removal checks for children using pages of at most two entries. Configure larger `removalLimits` only where the deployment can afford the corresponding work. These limits count adapter transport calls; retries inside a supplied transport need their own limit. Remote failures or concurrent writers can still cause partial deletion after preflight.
+
+For larger trees, a trusted integration can process one bounded batch per request/job using its explicitly supplied transport. This example uses at most 17 transport calls and retains at most 16 summaries; repeat in a later job until `done`. The prefix must come from trusted deployment configuration, include the filesystem's configured prefix, and end in `/`. This deliberately bypasses filesystem collision checks and deletes directory markers as well as files; serialize it with writers when complete removal is required.
+
+```ts
+async function removeBatch(transport, bucket, trustedDirectoryPrefix, abortSignal) {
+  const options = { abortSignal };
+  const page = await transport.listObjectsV2({
+    Bucket: bucket, Prefix: trustedDirectoryPrefix, MaxKeys: 16,
+  }, options);
+  const objects = page.Contents ?? [];
+  if (objects.length > 16 || page.CommonPrefixes?.length
+    || objects.some(object => !object.Key?.startsWith(trustedDirectoryPrefix))
+    || typeof page.IsTruncated !== "boolean") {
+    throw new Error("Invalid batch listing");
+  }
+  for (const object of objects) {
+    await transport.deleteObject({ Bucket: bucket, Key: object.Key }, options);
+  }
+  return { deleted: objects.length, done: !page.IsTruncated };
+}
+```
+
+Each batch lists from the beginning because previous keys have been deleted; it does not reuse continuation tokens across mutations. A job runner should cap the number of batches and schedule remaining work separately.
+
 `createS3HttpTransport` requires `endpoint` (an origin without path or credentials), `region`, and `credentials`. Credentials contain `accessKeyId`, `secretAccessKey`, and optional `sessionToken`, or come from an async provider receiving `{ signal }`.
 
 | Optional field | Default / meaning |
@@ -273,9 +310,9 @@ For in-memory S3 simulations, `new MockS3Client({ buckets, pageSize?, now?, auth
 | `addressingStyle` | `path`; alternative `virtual-hosted` requires a DNS endpoint |
 | `listUrlEncoding` | `percent`; alternative `form` |
 | `allowInsecureHttp` | `false`; HTTPS required unless explicitly enabled |
-| `maxPutBytes`, `maxGetBytes` | 64 MiB each |
-| `maxXmlBytes` | 4 MiB; maximum 16 MiB |
-| `requestTimeoutMs` | 30,000 |
+| `maxPutBytes`, `maxGetBytes` | Unlimited unless configured |
+| `maxXmlBytes` | Unlimited unless configured |
+| `requestTimeoutMs` | Unlimited unless configured |
 | `enableCopy` | `true`; disabling uses a buffered GET/PUT fallback |
 | `verifiedConditionalOperations` | Optional `put`, `copy`, `delete` booleans, each defaulting to false; enable only after verifying the server's semantics |
 | `clock` | Current date/time function, used for signing |
@@ -292,14 +329,16 @@ For in-memory S3 simulations, `new MockS3Client({ buckets, pageSize?, now?, auth
 | --- | --- |
 | `headers` | Empty; explicit authentication/custom headers. Protocol-reserved headers are rejected; authorization and cookies require HTTPS. |
 | `requestStreamSupport` | `native` for global Fetch, otherwise false; accepts `native` or a boolean declaration for the injected transport |
-| `maxResponseBytes` | 64 MiB |
-| `maxXmlBytes` | 2 MiB |
-| `maxEntries` | 10,000 |
-| `timeoutMs` | 30,000 |
+| `maxResponseBytes` | 16 MiB; applies to decoded response bytes |
+| `maxXmlBytes` | 1 MiB before metadata decoding/parsing |
+| `maxEntries` | Unlimited unless configured |
+| `timeoutMs` | Unlimited unless configured |
 | `overwritePolicy` | `lock`; alternative `etag` uses conditional overwrites |
 | `atomicEmptyDirectory` | Optional trusted binding with the canonical `namespaceUrl` and `removeEmptyDirectory` callback; required for strict empty-only `rmdir` |
 | `compareEntry` | Optional trusted backing-identity callback on Node; unavailable under browser policy |
 
+Known identity Content-Length responses use one result buffer; other responses grow storage up to the configured ceiling and return a view without a final copy. Growth can temporarily retain the old and new buffers (up to three times the response size), plus transport chunks. These per-response defaults leave headroom in Workers; hosts must still budget for metadata parsing, text decoding, transport buffers, and concurrent reads, especially when raising the limits. Use streaming reads for large files.
+
 See the [binding types](src/fs/webdav/webdav.ts) before implementing atomic directory removal. A recursive WebDAV DELETE does not satisfy that contract.
 
 </details>
@@ -307,9 +346,16 @@ See the [binding types](src/fs/webdav/webdav.ts) before implementing atomic dire
 ## Safety boundary and limitations
 
 - **Not an OS sandbox.** Rooted storage and bridge confinement check paths and symlinks, but checks and host operations can race concurrent changes. Use a separate OS isolation boundary for hostile workloads. A custom adapter or transport is trusted code with its own host authority.
-- **A read-only view is not an immutable store.** Other references can still change the backing filesystem. Overlays are not transactions; cancellation and cleanup do not guarantee rollback. Cross-mount rename can fail with `EXDEV`.
+- **A read-only view is not an immutable store.** Mount views serialize guest symlink, rename, and removal operations against active path operations. Finish or close read streams before awaiting these namespace changes. Other references can still change the backing filesystem; this coordination applies only to operations through the same mount view. Overlay reads require retained handles and stable object and ancestor identities; unsupported backends or changed read admission fail with `ENOTSUP`. Overlays are not transactions; cancellation and cleanup do not guarantee rollback. Cross-mount rename can fail with `EXDEV`.
 - **Remote storage is not a POSIX disk.** S3 and WebDAV do not provide hardlinks or symlinks. S3 rename is non-atomic and may leave partial copies/deletions; `S3RenameError` reports the phase and affected keys. Strong empty-only removal and conditional writes depend on backend support, not a prior listing.
 - **The bridges are partial Node compatibility layers.** No synchronous/callback API, file handles, watchers, bigint stats, flush/retry support, or `cp` dereference/timestamp-preservation options. Missing optional operations fail rather than being approximated with destructive alternatives.
 - **Browser support is filesystem-only.** The `browser` export condition selects the portable surface: memory, mounts, overlays, read-only, WebDAV, and the codec-based bridge. Real storage, S3, the Node bridge, and the configuration registry are not browser exports. WebDAV still needs server CORS support; no OPFS or directory-handle adapter is included. This does not make the SafeJS runtime browser-compatible.
 - **Portable temporary names require secure randomness.** Browser overlay staging and portable bridge `mkdtemp` require `crypto.randomUUID` or `crypto.getRandomValues`; without either, they fail with `ENOTSUP` rather than use `Math.random`.
 - **Allocation and identity may be unknown.** Optional `FileStat.allocatedBytes` is provider-reported allocation, not logical length or reclaimable space. Do not infer identity from size, timestamps, or inode numbers across unrelated backends.
+
+`MemoryFileSystem.confineExtraction(roots)` returns a view for archive extraction.
+It retains each root directory and its ancestors, refuses symlink ancestry at
+mutation commit, and keeps streamed writes attached to the opened file node.
+Other adapters omit this operation unless they can enforce the same boundary.
+Trusted host decorators must explicitly preserve confinement when forwarding it;
+custom mutation hooks must preserve the atomic commit contract.

package/dist/safe-fs/bridge/filesystem.d.ts

@@ -14,7 +14,10 @@ export declare class FileSystemBridge<Binary extends Uint8Array> {
     #private;
     constructor(fs: FileSystem, options: {
         readonly cwd?: string;
+        readonly root?: string;
         readonly signal?: AbortSignal;
+        readonly readFileMaxBytes?: number;
+        readonly reserveReadFile?: () => () => void;
     }, primitives: BridgePrimitives<Binary>);
     readFile(path: unknown, options?: {
         encoding?: null | undefined;
@@ -65,6 +68,7 @@ export declare class FileSystemBridge<Binary extends Uint8Array> {
     }) | null): Promise<void>;
     mkdir(path: unknown, options?: Mode | MakeDirectoryOptions | null): Promise<string | undefined>;
     access(path: unknown, mode?: number): Promise<void>;
+    unlink(path: unknown): Promise<void>;
     rm(path: unknown, value?: unknown): Promise<void>;
     rmdir(path: unknown, value?: unknown): Promise<void>;
     rename(source: unknown, destination: unknown): Promise<void>;

package/dist/safe-fs/bridge/filesystem.js

@@ -42,7 +42,10 @@ function timeValue(value) {
 export class FileSystemBridge {
     #fs;
     #cwd;
+    #root;
     #signal;
+    #readFileMaxBytes;
+    #reserveReadFile;
     #primitives;
     #codec;
     constructor(fs, options, primitives) {
@@ -63,7 +66,16 @@ export class FileSystemBridge {
         });
         this.#fs = fs;
         this.#cwd = primitives.paths.resolve("/", cwd);
+        this.#root = primitives.paths.resolve("/", options.root ?? cwd);
+        assertBridgePath(this.#root, this.#cwd);
         this.#signal = options.signal;
+        const maximum = options.readFileMaxBytes;
+        if (maximum !== undefined && (!Number.isSafeInteger(maximum) || maximum < 0))
+            throw new TypeError("Invalid readFileMaxBytes");
+        this.#readFileMaxBytes = maximum;
+        if (options.reserveReadFile !== undefined && typeof options.reserveReadFile !== "function")
+            throw new TypeError("Invalid reserveReadFile");
+        this.#reserveReadFile = options.reserveReadFile;
     }
     #encoding(value, fallback, names = false) {
         const selected = value == null ? fallback : value;
@@ -83,7 +95,7 @@ export class FileSystemBridge {
             throw fsError("ENOENT", "path", path);
         checkSignal(this.#signal);
         const absolute = this.#primitives.paths.isAbsolute(path) ? path : childPath(this.#cwd, path);
-        assertBridgePath(this.#cwd, absolute);
+        assertBridgePath(this.#root, absolute);
         return absolute;
     }
     async #call(paths, operation, signal, noFollow = []) {
@@ -98,9 +110,9 @@ export class FileSystemBridge {
             return await withSignal(combined, async () => {
                 const absolute = paths.map((path) => this.#path(path));
                 const resolved = [...absolute];
-                if (this.#cwd !== "/") {
+                if (this.#root !== "/") {
                     for (let index = 0; index < absolute.length; index++) {
-                        resolved[index] = await checkedBridgePath(this.#fs, this.#cwd, absolute[index], options, !noFollow.includes(index));
+                        resolved[index] = await checkedBridgePath(this.#fs, this.#root, absolute[index], options, !noFollow.includes(index));
                     }
                 }
                 checkSignal(combined);
@@ -118,9 +130,29 @@ export class FileSystemBridge {
         if (options.encoding === "buffer")
             throw new TypeError("Invalid read encoding");
         const codec = this.#encoding(options.encoding, "buffer");
-        const bytes = await this.#call([path], (signal, resolved) => this.#fs.readFile(resolved[0], signal), options.signal);
-        const buffer = this.#primitives.copyBytes(bytes);
-        return codec === "buffer" ? buffer : this.#codec.decode(buffer, codec);
+        const maxBytes = this.#readFileMaxBytes;
+        const release = this.#reserveReadFile?.();
+        let pending;
+        try {
+            const bytes = await this.#call([path], (signal, resolved) => {
+                pending = this.#fs.readFile(resolved[0], { ...signal, ...(maxBytes === undefined ? {} : { maxBytes }) });
+                return pending;
+            }, options.signal);
+            if (maxBytes !== undefined && bytes.byteLength > maxBytes)
+                throw fsError("EFBIG", "readFile");
+            const buffer = this.#primitives.copyBytes(bytes);
+            return codec === "buffer" ? buffer : this.#codec.decode(buffer, codec);
+        }
+        finally {
+            // Cancellation may reject #call before a backend acknowledges it. Keep
+            // its reservation until the actual read settles, as well as through decode.
+            if (release !== undefined) {
+                if (pending === undefined)
+                    release();
+                else
+                    void pending.then(release, release);
+            }
+        }
     }
     async #write(path, data, value, fallback) {
         const options = optionsRecord(value, ["encoding", "flag", "mode", "flush", "signal"]);
@@ -208,7 +240,7 @@ export class FileSystemBridge {
                     if (!hasCode(error, "ENOENT"))
                         throw error;
                     firstCreated = candidate;
-                    if (candidate === this.#cwd)
+                    if (candidate === this.#root)
                         break;
                     const parent = this.#primitives.paths.dirname(candidate);
                     if (parent === candidate)
@@ -225,6 +257,13 @@ export class FileSystemBridge {
             throw new TypeError("Invalid access mode");
         await this.#call([path], (signal, resolved) => this.#fs.access(resolved[0], mode, signal));
     }
+    async unlink(path) {
+        await this.#call([path], async (signal, resolved) => {
+            if (!this.#fs.unlink)
+                unsupported("unlink");
+            await this.#fs.unlink(resolved[0], signal);
+        }, undefined, [0]);
+    }
     async rm(path, value) {
         const options = optionsRecord(value, ["force", "recursive", "maxRetries", "retryDelay"]);
         if (options.maxRetries !== undefined && options.maxRetries !== 0)
@@ -275,7 +314,7 @@ export class FileSystemBridge {
         const from = this.#path(source);
         const to = this.#path(destination);
         const canonicalFrom = await this.realpath(from);
-        let ancestor = to === this.#cwd ? to : this.#primitives.paths.dirname(to);
+        let ancestor = to === this.#root ? to : this.#primitives.paths.dirname(to);
         let canonicalAncestor;
         while (true) {
             try {
@@ -342,7 +381,7 @@ export class FileSystemBridge {
     async realpath(path, value) {
         const codec = this.#encoding(optionsRecord(value, ["encoding"]).encoding, "utf8", true);
         const target = await this.#call([path], (signal, resolved) => this.#fs.realpath(resolved[0], signal));
-        assertBridgePath(this.#cwd, target);
+        assertBridgePath(this.#root, target);
         return codec === "buffer" ? this.#textBytes(target) : this.#codec.decode(this.#textBytes(target), codec);
     }
     async mkdtemp(prefix, value) {
@@ -371,7 +410,7 @@ export class FileSystemBridge {
         const destination = this.#path(path);
         const absoluteTarget = this.#path(this.#primitives.paths.isAbsolute(linkTarget)
             ? linkTarget : childPath(this.#primitives.paths.dirname(destination), linkTarget));
-        if (this.#cwd !== "/" && this.#primitives.paths.isAbsolute(linkTarget)) {
+        if (this.#root !== "/" && this.#primitives.paths.isAbsolute(linkTarget)) {
             throw fsError("ENOTSUP", "symlink", destination);
         }
         const method = this.#fs.symlink;

package/dist/safe-fs/bridge/types.d.ts

@@ -7,7 +7,13 @@ export interface FsBridgeCodec {
 export interface FsBridgeOptions {
     readonly codec: FsBridgeCodec;
     readonly cwd?: string;
+    /** Optional confinement boundary; defaults to cwd. */
+    readonly root?: string;
     readonly signal?: AbortSignal;
+    /** Trusted per-read backend byte cap, enforced before copying or decoding. */
+    readonly readFileMaxBytes?: number;
+    /** Reserve host resources; release after decoding and actual backend settlement, including cancellation. */
+    readonly reserveReadFile?: () => () => void;
 }
 export interface FsBridgeFileSystem extends FileSystem {
     rmdir?(path: string, options?: FsOptions): Promise<void>;

package/dist/safe-fs/contracts/descriptor.d.ts

@@ -4,10 +4,15 @@ export interface OpenFileOptions extends FsOptions {
     readonly creation?: "never" | "ifMissing" | "exclusive";
     readonly truncate?: boolean;
     readonly append?: boolean;
+    /** Atomically reject a final symlink; parent symlinks still follow provider policy. */
+    readonly noFollow?: boolean;
     readonly mode?: number;
+    /** Apply mode exactly to new entries, without an additional host umask. */
+    readonly exactMode?: boolean;
     readonly synchronization?: "data" | "all";
 }
 export interface FileDescriptorCapabilities {
+    readonly noFollow?: boolean;
     readonly publication?: "conditional";
     readonly position?: boolean;
     readonly readObservation?: boolean;

package/dist/safe-fs/contracts/filesystem.d.ts

@@ -6,6 +6,8 @@ export type FileType = "file" | "directory" | "symlink" | "character";
 export type EntryComparison = "same" | "distinct" | "unknown";
 export interface FileStat {
     readonly type: FileType;
+    /** Backend-reported type of the containing filesystem; absence means unknown. */
+    readonly filesystemType?: string;
     readonly size: number;
     readonly allocatedBytes?: number;
     readonly ioBlockSize?: number;
@@ -65,7 +67,11 @@ export interface FileSystemCapabilities {
     readonly permissions?: boolean;
     readonly timestamps?: boolean;
     readonly atomicRename?: boolean;
+    /** Owned staging serialized within a trusted host; requires external tree isolation. */
+    readonly trustedOwnedStaging?: boolean;
     readonly atomicFileStaging?: boolean;
+    /** Atomically verifies every supplied root-to-parent directory identity at publication. */
+    readonly atomicStagingAncestry?: boolean;
     readonly atomicFilePublication?: boolean;
     readonly atomicFileMutation?: boolean;
     readonly atomicEntryRemoval?: boolean;
@@ -89,6 +95,7 @@ export interface OpenReadFileOptions extends FsOptions {
 }
 export interface CapabilityQueryOptions extends OpenReadFileOptions {
     readonly create?: boolean;
+    readonly creation?: OpenFileOptions["creation"];
 }
 export interface FileReadHandle {
     /** Exact operations on the same retained object; close owns both facets. */
@@ -150,6 +157,8 @@ export interface AppendFileOptions extends FsOptions {
     readonly mode?: number;
 }
 export interface MkdirOptions extends FsOptions {
+    /** Apply mode exactly to new entries, without an additional host umask. */
+    readonly exactMode?: boolean;
     readonly recursive?: boolean;
     readonly mode?: number;
 }
@@ -199,6 +208,7 @@ export interface CreateStagedFileOptions extends FsOptions {
     readonly mtimeMs?: number;
 }
 export interface PublishStagedFileOptions extends FsOptions {
+    readonly ancestors?: readonly FileStagingEntry[];
     readonly parent: FileStat;
     readonly destination: FileStat | null;
 }
@@ -217,6 +227,11 @@ export interface ConditionalFilePublicationOptions extends FsOptions {
     readonly mtimeMs?: number;
 }
 export interface FileSystem {
+    /** Retain each extraction root and enforce no-symlink ancestry atomically with
+     * every mutation (including metadata and both hardlink paths). Returned views
+     * must refuse unsupported mutations; no check-then-write emulation is allowed.
+     * Roots and their ancestors must remain the retained directories. */
+    confineExtraction?(roots: readonly string[], options?: FsOptions): Promise<FileSystem>;
     /** Explicit retained-object capability for qualified byte-path backends. */
     readonly objects?: ObjectFileSystem;
     /** Consume the complete source privately, then atomically compare/publish.

package/dist/safe-fs/contracts/io.d.ts

@@ -1,6 +1,8 @@
 export type ByteSource = AsyncIterable<Uint8Array>;
 export interface CollectOptions {
-    readonly maxBytes: number;
+    readonly maxBytes?: number;
+    /** Owned capacity, current input backing storage, and replacement allocation peak. */
+    readonly maxMemoryBytes?: number;
     readonly signal?: AbortSignal;
 }
 export declare function toByteSource(input: string | Uint8Array): ByteSource;

package/dist/safe-fs/contracts/io.js

@@ -1,5 +1,6 @@
 import { FsError } from "./errors.js";
 import { finishCleanup } from "./cleanup.js";
+import { platform } from "#safe-fs-platform";
 export function toByteSource(input) {
     if (typeof input !== "string" && !(input instanceof Uint8Array)) {
         throw new TypeError("Byte source input must be a string or Uint8Array");
@@ -10,29 +11,60 @@ export function toByteSource(input) {
             yield bytes;
     })();
 }
+let activeCollectionBytes = 0;
 export async function collectBytes(source, options) {
-    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0) {
+    if (options.maxBytes !== undefined && options.maxBytes !== Infinity && (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0)) {
         throw new RangeError("maxBytes must be a nonnegative safe integer");
     }
-    const chunks = [];
+    if (options.maxMemoryBytes !== undefined && (!Number.isSafeInteger(options.maxMemoryBytes) || options.maxMemoryBytes < 0)) {
+        throw new RangeError("maxMemoryBytes must be a nonnegative safe integer");
+    }
+    const memoryLimit = options.maxMemoryBytes ?? Infinity;
+    let reserved = 0;
+    let inputBytes = 0;
+    let buffer = new Uint8Array(0);
     let size = 0;
-    options.signal?.throwIfAborted();
-    for await (const chunk of readBytes(source, options.signal)) {
-        if (chunk.byteLength > options.maxBytes - size) {
-            throw new FsError("EFBIG", { syscall: "collectBytes", message: "output exceeds maxBytes" });
+    function reserve(bytes) {
+        if (bytes > memoryLimit - reserved || bytes > platform.maxCollectionBytes - activeCollectionBytes) {
+            throw new FsError("EFBIG", { syscall: "collectBytes", message: "collection exceeds memory budget" });
         }
-        if (chunk.byteLength > 0)
-            chunks.push(new Uint8Array(chunk));
-        size += chunk.byteLength;
+        reserved += bytes;
+        activeCollectionBytes += bytes;
     }
-    options.signal?.throwIfAborted();
-    const result = new Uint8Array(size);
-    let offset = 0;
-    for (const chunk of chunks) {
-        result.set(chunk, offset);
-        offset += chunk.byteLength;
+    try {
+        options.signal?.throwIfAborted();
+        for await (const chunk of readBytes(source, options.signal)) {
+            activeCollectionBytes -= inputBytes;
+            reserved -= inputBytes;
+            inputBytes = 0;
+            if (chunk.byteLength > (options.maxBytes ?? Infinity) - size) {
+                throw new FsError("EFBIG", { syscall: "collectBytes", message: "output exceeds maxBytes" });
+            }
+            // A small view can retain a large backing buffer. Keep this reservation
+            // while awaiting the next chunk, including while its source is suspended.
+            reserve(chunk.buffer.byteLength);
+            inputBytes = chunk.buffer.byteLength;
+            const nextSize = size + chunk.byteLength;
+            if (nextSize > buffer.byteLength) {
+                const capacity = Math.min(options.maxBytes ?? Infinity, Math.max(nextSize, buffer.byteLength * 2));
+                // Admit both generations before allocation. Do not fall back to repeated
+                // exact-size growth when geometric growth exceeds the budget.
+                reserve(capacity);
+                const replacement = new Uint8Array(capacity);
+                replacement.set(buffer.subarray(0, size));
+                activeCollectionBytes -= buffer.byteLength;
+                reserved -= buffer.byteLength;
+                buffer = replacement;
+            }
+            buffer.set(chunk, size);
+            size = nextSize;
+        }
+        options.signal?.throwIfAborted();
+        return buffer.subarray(0, size);
+    }
+    finally {
+        activeCollectionBytes -= reserved;
     }
-    return result;
 }
 async function abortable(operation, signal) {
     signal?.throwIfAborted();

package/dist/safe-fs/core.d.ts

@@ -17,7 +17,8 @@ export type { RetainedFileSystemCleanupView, RetainedFileSystemCleanupOptions }
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
-export { compareEntries } from "./fs/mount/comparison.js";
+export { compareEntries, registerEntryView } from "./fs/mount/comparison.js";
+export type { EntryViewResolver } from "./fs/mount/comparison.js";
 export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
 export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits } from "./xml.js";
 export * from "./contracts/object.js";

package/dist/safe-fs/core.js

@@ -15,7 +15,7 @@ export { scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
-export { compareEntries } from "./fs/mount/comparison.js";
+export { compareEntries, registerEntryView } from "./fs/mount/comparison.js";
 export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";

package/dist/safe-fs/fs/capabilities.js

@@ -108,7 +108,7 @@ export function readOnlyCapabilities(capabilities) {
         mkdir: false, recursiveMkdir: false, remove: false, removeDirectory: false, recursiveRemove: false,
         rename: false, copy: false, exclusiveCopy: false, truncate: false, streamingAppend: false,
         randomAccessWrite: false, hardlinks: false, permissions: false, timestamps: false,
-        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
+        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         atomicFilePublication: false, atomicRename: false, atomicRenameNoReplace: false, streamingWrite: false,
     });
 }
@@ -116,7 +116,7 @@ export function quotaCapabilities(capabilities) {
     const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, !capabilities.readOnly);
     const streamingAppend = requireCapabilities(capabilities.append, !capabilities.readOnly);
     const { streamingWrite: ignoredWrite, streamingAppend: ignoredAppend, ...rest } = capabilities;
-    return Object.freeze({ ...rest, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
+    return Object.freeze({ ...rest, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
@@ -136,12 +136,15 @@ export function ownedMutationCapabilities(filesystem, capabilities = filesystem.
         unavailable.atomicFileStaging = false;
     if (capabilities.atomicDirectoryMetadata === true && (capabilities.readOnly === true || typeof filesystem.prepareDirectory !== "function"))
         unavailable.atomicDirectoryMetadata = false;
+    if (capabilities.trustedOwnedStaging === true && (capabilities.readOnly === true
+        || ["createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory"].some(method => typeof filesystem[method] !== "function")))
+        unavailable.trustedOwnedStaging = false;
     return Object.keys(unavailable).length ? { ...capabilities, ...unavailable } : capabilities;
 }
 export async function requireOwnedMutation(filesystem, path, capability, options, create = false) {
     options.signal?.throwIfAborted();
     const capabilities = ownedMutationCapabilities(filesystem, await filesystem.capabilitiesFor?.(path, create ? { ...options, create: true } : options) ?? filesystem.capabilities);
     options.signal?.throwIfAborted();
-    if (capabilities[capability] !== true)
+    if (capabilities[capability] !== true && !(capabilities.trustedOwnedStaging === true && ["atomicFileStaging", "atomicFileMutation", "atomicDirectoryMetadata"].includes(capability)))
         throw new FsError("ENOTSUP", { path, syscall: capability });
 }

package/dist/safe-fs/fs/descriptor.js

@@ -2,6 +2,7 @@ import { FsError } from "../contracts/errors.js";
 import { finishCleanup } from "../contracts/cleanup.js";
 function admitCapabilities(path, options, capabilities) {
     if (![capabilities.positionedRead, capabilities.positionedWrite, capabilities.truncate].every(value => typeof value === "boolean")
+        || capabilities.noFollow !== undefined && typeof capabilities.noFollow !== "boolean"
         || capabilities.publication !== undefined && capabilities.publication !== "conditional"
         || capabilities.position !== undefined && typeof capabilities.position !== "boolean"
         || capabilities.readObservation !== undefined && typeof capabilities.readObservation !== "boolean"
@@ -10,7 +11,8 @@ function admitCapabilities(path, options, capabilities) {
         || capabilities.delegateZeroLengthWrite !== undefined && typeof capabilities.delegateZeroLengthWrite !== "boolean"
         || !["none", "volatile", "storage"].includes(capabilities.synchronization))
         throw new FsError("EINVAL", { syscall: "open", path });
-    if (options.truncate && !(capabilities.openTruncate ?? capabilities.truncate) || options.synchronization !== undefined && capabilities.synchronization === "none") {
+    if (options.noFollow && capabilities.noFollow !== true
+        || options.truncate && !(capabilities.openTruncate ?? capabilities.truncate) || options.synchronization !== undefined && capabilities.synchronization === "none") {
         throw new FsError("ENOTSUP", { syscall: "open", path });
     }
 }
@@ -68,6 +70,7 @@ class ManagedFileDescriptor {
         this.#backend = backend;
         const positionedAppendWrite = capabilities.positionedAppendWrite === true && capabilities.positionedWrite && options.access !== "read";
         this.capabilities = Object.freeze({
+            ...(capabilities.noFollow === undefined ? {} : { noFollow: capabilities.noFollow }),
             ...(capabilities.publication === undefined ? {} : { publication: capabilities.publication }),
             ...(capabilities.position === undefined ? {} : { position: capabilities.position }),
             ...(capabilities.readObservation === undefined ? {} : { readObservation: capabilities.readObservation }),
@@ -206,11 +209,13 @@ export async function openFileDescriptor(path, options, capabilities, acquire) {
         throw new FsError("EINVAL", { syscall: "open", path });
     const signal = options.signal;
     signal?.throwIfAborted();
-    const keys = ["access", "creation", "truncate", "append", "mode", "synchronization", "signal"];
+    const keys = ["access", "creation", "truncate", "append", "mode", "exactMode", "noFollow", "synchronization", "signal"];
     const { access, creation = "never", truncate = false, append = false, mode = 0o666, synchronization } = options;
     if (Object.keys(options).some(key => !keys.includes(key))
         || !["read", "write", "readwrite"].includes(access)
         || !["never", "ifMissing", "exclusive"].includes(creation)
+        || options.noFollow !== undefined && typeof options.noFollow !== "boolean"
+        || options.exactMode !== undefined && typeof options.exactMode !== "boolean"
         || typeof truncate !== "boolean" || typeof append !== "boolean"
         || access === "read" && (truncate || append)
         || synchronization !== undefined && !["data", "all"].includes(synchronization)
@@ -218,6 +223,8 @@ export async function openFileDescriptor(path, options, capabilities, acquire) {
         throw new FsError("EINVAL", { syscall: "open", path });
     }
     const admitted = Object.freeze({ access, creation, truncate, append, mode,
+        ...(options.noFollow === undefined ? {} : { noFollow: options.noFollow }),
+        ...(options.exactMode === undefined ? {} : { exactMode: options.exactMode }),
         ...(signal === undefined ? {} : { signal }), ...(synchronization === undefined ? {} : { synchronization }) });
     const admittedCapabilities = Object.freeze({ ...capabilities });
     admitCapabilities(path, admitted, admittedCapabilities);