toolcraft 0.0.749 → 0.0.750

package/node_modules/@poe-code/safe-fs/README.md

@@ -0,0 +1,411 @@
+# safe-fs
+
+An asynchronous filesystem interface for memory, rooted host directories, S3, and WebDAV, with mounts, copy-on-write overlays, and Node-style bridges. Portable filesystem types and POSIX helpers compile without Node types. The `posixPath` export from `@poe-code/safe-fs/core` provides `basename`, `dirname`, `extname`, `join`, `isAbsolute`, `normalize`, `resolve`, `relative`, `sep`, and `delimiter`; `resolve` and `relative` use `/` as their working directory in every runtime.
+
+Under `workerd` and `browser` conditions, the root export includes portable filesystems, `S3FileSystem`, and `MockS3Client`. Supply an S3 transport to use object storage without Node globals.
+
+## Quickstart
+
+Install the standalone package; it does not depend on SafeJS, Safe Bash, or the `poe-code` CLI. These examples use TypeScript in a Node ESM application.
+
+```sh
+npm install @poe-platform/safe-fs
+```
+
+```ts
+import { createMemoryFileSystem, createNodeFsBridge } from "@poe-platform/safe-fs";
+
+const storage = createMemoryFileSystem();
+await storage.mkdir("/work");
+await storage.writeFile("/work/note.txt", new TextEncoder().encode("hello"));
+console.log(new TextDecoder().decode(await storage.readFile("/work/note.txt")));
+
+const fs = createNodeFsBridge(storage, { cwd: "/work" });
+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 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.
+
+Under the `workerd` export condition, `@poe-platform/safe-fs/fs/real` reads the
+native request-local filesystem, including retained `/tmp` file bytes.
+The restricted profile refuses generic descriptors, permission/timestamp
+changes, exact creation modes, and owned staging; it promises neither atomic
+rename nor inode/version identity from placeholder native metadata. Retained
+reads remain available, with native seek reporting `ENOTSUP`. Ordinary browser
+bundles cannot import this backend. Node keeps its POSIX host profile.
+
+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. Archive extraction requires atomic ancestry verification. MemoryFileSystem supports it, including a writable root composed with read-only mounts such as `/skills/.system`; the real adapter refuses it. Mount extraction delegates confinement to the root backend and keeps other mounts read-only in the extraction view. Extraction roots inside a separate mount are rejected because directory and metadata mutations cannot atomically guard ancestors on another backend. Staged file publication supports nested writable mounts when every ancestor provides authoritative validation. 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
+
+| Import | Use |
+| --- | --- |
+| `@poe-platform/safe-fs` | Full Node API; selects the portable core under the `browser` and `workerd` conditions. |
+| `@poe-platform/safe-fs/core` | Memory, mounts, overlays, read-only, WebDAV, portable bridges, types, and errors. Bundle with the `browser` condition for browsers and Workers. |
+| `@poe-platform/safe-fs/node` | Host filesystem, Node bridge, S3, and configuration helpers; unavailable in browsers. |
+| `@poe-platform/safe-fs/fs/*` | Individual adapters: `memory`, `readonly`, `mount`, `overlay`, `webdav`, `real`, `s3`, and `s3/http`. S3, its mock, and the signed `s3/http` transport work in browsers and Workers. |
+
+```ts
+import { createMemoryFileSystem, FsError, type FileSystem } from "@poe-platform/safe-fs/core";
+
+const fs: FileSystem = createMemoryFileSystem();
+```
+
+Matching scoped SafeJS and Safe Bash releases use this package's types and runtime.
+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`
+from the receiving runtime; it retains the code, operation paths, and original
+cause. Preserve cancellation/control exceptions separately. Cross-family
+`instanceof FsError` is not supported without normalization.
+
+## Supported operations
+
+| Operation | Interface |
+| --- | --- |
+| Read and write bytes | `readFile`, `writeFile`, `appendFile` |
+| Inspect entries | `stat`, `lstat`, `readdir`, `realpath`, `access` |
+| Change the namespace | `mkdir`, `rm`, `rename`, `copyFile` |
+| 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` |
+
+All required methods must exist, but a backend may reject an operation with `FsError`, such as `EROFS` for a write or `ENOTSUP` for unsupported semantics. Check optional methods and `capabilities` rather than assuming every backend behaves like a local disk. Errors expose `code` and may include `syscall`, `path`, `dest`, and `cause`.
+
+`readBytes` supports frozen host abort signals. The exported
+`listenForAbort(signal, listener)` returns a cleanup function for custom
+operations; if frozen host bookkeeping prevents registration, callers must
+check cancellation at operation boundaries, as `readBytes` does.
+
+`createDeviceFileSystem(fs)` adds portable `/dev/null` whole-file, stream, and descriptor I/O. Descriptor reads return EOF and writes discard bytes; stat remains a zero-size character device and descriptor position remains zero. Truncating opens are accepted, exclusive creation fails with `EEXIST`, and descriptor resizing and synchronization are unsupported. Access modes, cancellation, and closed handles use the normal descriptor checks. With an authoritative object store, use `createDeviceFileSystem(withObjectFileDescriptors(fs, store))` so null-device I/O never acquires or publishes an object version; ordinary files retain conditional publication. The device wrapper must be outermost for this composition.
+
+`PythonStatTranslator` and `createPythonRuntimeStatMapper` allocate stable guest device
+identities without a default device-count budget. Their optional `maxDevices` accepts
+`Infinity` or a positive safe integer. Explicit budgets remain enforced; device numbers
+must still fit the disjoint application/runtime ranges of the uint32 Python stat ABI.
+
+`withObjectFileDescriptors(fs, store)` supports large shell and Python descriptor
+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
+optional dirty-page budget limits unflushed output only when configured. Descriptor
+resource limits accept `Infinity` and are unlimited when omitted; `chunkBytes`
+remains a positive finite integer. 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.
+
+Immutable flat stores can supply `identityScope`, `opaqueIdentity` and an ABA-safe
+`opaqueVersion` on file stats, then expose `atomicFilePublication: true` with
+`publishFileConditional(path, source, { expected, parent, maxBytes, signal })`.
+The host consumes bytes privately and atomically creates an absent binding
+(`expected: null`) or replaces the observed generation. Failed producers,
+uploads and stale writers leave the old file intact. This supports Safe Bash ZIP
+creation and updates without inode numbers, staging directories or permission
+APIs. Read the [conditional publication contract](src/contracts/conditional-publication.md)
+before implementing the host operation; ordinary writes do not provide it.
+
+For temporary staging that must be cleaned up after its parent moves, adapters
+advertising `retainedStagingCleanup` accept `createStagedFile(..., { parent,
+retainCleanup: true })`. Use the returned `staging.cleanup.remove()` and always
+call `staging.cleanup.close()` in `finally`. Memory and its supported wrappers
+retain only the owned staging entries; replacement entries remain protected.
+Overlays backed by stock Memory filesystems support conditional file mutations,
+directory preparation, and confined staging. Publication may omit `ancestors`
+when the destination shares the staging parent; the overlay checks the ancestry
+retained before staging began.
+See the [staging contract](src/contracts/filesystem.md#atomic-owned-staging).
+
+Capture `retainFileSystemCleanup(scoped, callback, { maxOperations })` before
+cancellation to clean up through a bounded view after ordinary scoped operations
+close. Cleanup preserves its owning scope and limits across separately bundled
+command runtimes, including restrictions added by filesystem wrappers.
+Omit `maxOperations` or pass `Infinity` for unlimited cleanup operations.
+
+| Backend or wrapper | Use it for |
+| --- | --- |
+| `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 or qualified Workerd operations |
+| `new S3FileSystem({ transport, bucket, … })` | Bucket/prefix storage through an explicitly supplied transport in Node, browsers, and Workers |
+| `new WebDavFileSystem({ baseUrl, fetch, … })` | A WebDAV namespace through an explicitly supplied Fetch implementation |
+| `createReadOnlyFileSystem(filesystem)` | Rejecting writes through one view of an existing filesystem |
+| `createMountFileSystem({ root, mounts })` | Routing absolute virtual mount paths to different filesystems |
+| `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`. 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/bridge` instead requires a caller-supplied text codec and returns `Uint8Array` values.
+
+## Write an adapter
+
+A backend implements the exported [`FileSystem` interface](src/contracts/filesystem.ts). It needs every non-optional method, a truthful `capabilities` object, byte-safe reads/writes, and appropriate errors. A configuration adapter adds `validateOptions` and a `create` factory returning that filesystem, synchronously or asynchronously.
+
+This hypothetical `catalog` adapter presents a snapshot of named text documents as read-only files at `/`. It implements the full required interface without a host filesystem or network connection. Only the root directory and single-component filenames are supported; timestamps are synthetic and optional operations are absent.
+
+```ts
+import {
+  ACCESS_MODES, FsError, createFileSystem,
+  createNodeFileSystemAdapterRegistry, readConfigRecord, validatePath,
+  type FileStat, type FileSystem, type FileSystemAdapterDescriptor,
+  type FsOptions,
+} from "@poe-platform/safe-fs";
+
+const catalogAdapter = {
+  validateOptions(options) {
+    const config = readConfigRecord(options, "catalog option", ["files"]);
+    const files = readConfigRecord(config.files, "catalog files");
+    for (const [name, text] of Object.entries(files)) {
+      if (!name || name === "." || name === ".." || name.includes("/")
+        || name.includes("\0") || typeof text !== "string") {
+        throw new TypeError("files must map single-component names to strings");
+      }
+    }
+  },
+  create(options): FileSystem {
+    const files = new Map(Object.entries(readConfigRecord(options.files, "catalog files"))
+      .map(([name, text]) => [name, new TextEncoder().encode(text as string)]));
+
+    function lookup(path: string, options?: FsOptions) {
+      if (options?.signal?.aborted) throw new FsError("ECANCELED", { path });
+      validatePath(path);
+      let name = "";
+      let bytes: Uint8Array | undefined;
+      for (const part of path.split("/")) {
+        if (bytes !== undefined) throw new FsError("ENOTDIR", { path });
+        if (part === "" || part === "." || part === "..") continue;
+        bytes = files.get(part);
+        if (bytes === undefined) throw new FsError("ENOENT", { path });
+        name = part;
+      }
+      return { path: `/${name}`, bytes };
+    }
+
+    async function inspect(path: string, options?: FsOptions): Promise<FileStat> {
+      const { bytes } = lookup(path, options);
+      return {
+        type: bytes === undefined ? "directory" : "file",
+        size: bytes?.byteLength ?? 0,
+        mode: bytes === undefined ? 0o40555 : 0o100444,
+        atimeMs: 0, mtimeMs: 0, ctimeMs: 0,
+      };
+    }
+
+    async function denyWrite(): Promise<never> {
+      throw new FsError("EROFS");
+    }
+
+    return {
+      capabilities: { readOnly: true },
+      async readFile(path, options) {
+        const { bytes } = lookup(path, options);
+        if (bytes === undefined) throw new FsError("EISDIR", { path });
+        const limit = options?.maxBytes ?? Number.MAX_SAFE_INTEGER;
+        if (!Number.isSafeInteger(limit) || limit < 0) throw new FsError("EINVAL", { path });
+        if (bytes.byteLength > limit) throw new FsError("EFBIG", { path });
+        return bytes.slice();
+      },
+      stat: inspect,
+      lstat: inspect,
+      async readdir(path, options) {
+        if (lookup(path, options).bytes !== undefined) throw new FsError("ENOTDIR", { path });
+        return [...files.keys()].sort().map(name => ({ name, type: "file" as const }));
+      },
+      async realpath(path, options) {
+        const entry = lookup(path, options);
+        return entry.path;
+      },
+      async access(path, mode = ACCESS_MODES.F_OK, options) {
+        const entry = lookup(path, options);
+        if (!Number.isInteger(mode) || mode < 0 || mode > 7) throw new FsError("EINVAL", { path });
+        if (mode & ACCESS_MODES.W_OK) throw new FsError("EROFS", { path });
+        if ((mode & ACCESS_MODES.X_OK) && entry.bytes !== undefined) {
+          throw new FsError("EACCES", { path });
+        }
+      },
+      writeFile: denyWrite, appendFile: denyWrite, mkdir: denyWrite,
+      rm: denyWrite, rename: denyWrite, copyFile: denyWrite,
+    };
+  },
+} satisfies FileSystemAdapterDescriptor;
+
+const registry = createNodeFileSystemAdapterRegistry(new Map([["catalog", catalogAdapter]]));
+const catalog = await createFileSystem({
+  type: "catalog",
+  options: { files: { "welcome.txt": "Hello from the catalog" } },
+}, { registry });
+
+console.log(new TextDecoder().decode(await catalog.readFile("/welcome.txt")));
+```
+
+Output: `Hello from the catalog`. `readFile` returns a copy so callers cannot mutate the stored snapshot. Reads check cancellation and `maxBytes`; required mutations always reject with `EROFS`. `stat` and `lstat` share an implementation because this adapter has no symlinks.
+
+`createFileSystem` validates options before calling the factory. For Workers, import `createPortableFileSystemAdapterRegistry` and `createFileSystem` from `@poe-code/safe-fs/core`; the portable registry includes `memory` and caller-supplied adapters, without ambient filesystem access. The Node registry includes `memory` and `real`, accepts new names, and rejects attempts to replace those defaults. For an explicit allowlist without either default, pass `new Map([["catalog", catalogAdapter]])` directly as `registry`. Names select registered factories; they do not load modules from config.
+
+For a mutable backend, preserve exclusive-create behavior, return independent byte buffers, handle cancellation and size limits, and declare only capabilities you actually provide. Use `FsError` for filesystem failures. Do not invent entry identity from matching paths or metadata; omit `compareEntry` when identity is unknown.
+
+## Options
+
+There are no package environment variables, implicit credentials, or automatic `.env` loading. Applications supply configuration, transports, and credentials explicitly. Factories accept the same options as their corresponding classes.
+
+### Local storage, composition, and bridges
+
+| API | Options and defaults |
+| --- | --- |
+| `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, total-byte, `maxPathBytes` and `maxPathComponents` quotas (omitted, `undefined`, or `Infinity` disables each quota); built-in `real` requires `root`. |
+| `createNodeFileSystemAdapterRegistry(extensions?)` | Optional map of additional adapter descriptors; defaults to only `memory` and `real`. |
+| 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` is unlimited unless configured; it and per-read `maxBytes` accept explicit `Infinity`. |
+| 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` 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
+
+Every raw filesystem operation accepts an optional `signal`. Additional fields are:
+
+| Operation | Options |
+| --- | --- |
+| `readFile` | `maxBytes`: nonnegative safe-integer byte cap; `Infinity` adds no per-read cap |
+| `readdir` | `maxEntries`: nonnegative safe-integer entry cap; omission or `Infinity` preserves backend limits and ordering |
+| `writeFile`, `writeStream` | `flag`: `w` (default, replace), `wx` (exclusive create), `a` (append), or `ax` (exclusive append/create); optional `mode` |
+| `appendFile` | Optional `mode` |
+| `mkdir` | `recursive` (default false); optional `mode` |
+| `rm` | `recursive` and `force` (default false) |
+| `copyFile` | `exclusive` (default false) |
+| `readStream` | `start` (default 0), `endExclusive` (default end of file), `chunkSize` (built-in default 64 KiB) |
+
+`validatePath(path, { maxPathBytes, maxPathComponents })` accepts optional UTF-8 byte and component quotas; both default to `Infinity`. Memory accepts the same constructor options and counts cumulative symlink expansion. Device operations and WebDAV stat, access, and writes accept these quotas under `pathLimits`. WebDAV accepts `maxTimestampPropertyBytes` for timestamp metadata, also unlimited by default.
+
+`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). For conditional chmod, check `capabilitiesFor(path, { conditionalChmod: true })` (or `capabilities`) and require `conditionalChmod: true`; supply `parent`, `expected`, and complete root-to-parent `ancestors` together. An optional mutation-free `commitGuard` must return literal `true` synchronously. Memory validates at its metadata commit; mount and supported Memory overlays preserve wrapper ancestry. Real uses its existing externally isolated host-tree boundary and does not prevent races with other processes. 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. `maxBytes` and `maxMemoryBytes` accept explicit `Infinity`. `maxMemoryBytes` limits owned capacity, the current input's full backing buffer, and overlapping allocations during growth; exhaustion throws `EFBIG`. Collection limits are disabled by default on Node, browser, and Worker targets. Each call owns its budget; concurrent collections do not consume one another’s allowance. The returned view may retain geometric spare capacity. Configured budgets cover 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>
+
+`S3FileSystem` requires `transport` and `bucket`. A transport supplies `headObject`, `getObject`, `putObject`, `deleteObject`, `copyObject`, and `listObjectsV2`; see the [transport interface](src/fs/s3/transport.ts).
+
+`createS3NamespaceFileSystem` resource limits (`maxBytes`, `maxEntries`,
+`maxManifestBytes`, `maxAttempts`, and inherited descriptor limits) are unlimited
+when omitted or set to `Infinity`; positive safe integers enable finite limits.
+Namespace paths have no implicit length cap; configured manifest budgets still apply.
+
+`createS3Transport(client, capabilities?)` wraps a compatible client with explicit `streamingRead`, `streamingWrite`, `conditionalPut`, `conditionalCopy`, and `conditionalDelete` flags (all absent by default). Direct transport requests accept an optional `abortSignal`.
+
+For in-memory S3 simulations, `new MockS3Client({ buckets, pageSize?, now?, authorize? })` requires bucket names. `pageSize` defaults to 1,000 (range 1–1,000), `now` defaults to the current date/time, and optional `authorize(request)` can reject requests. It does not verify a real provider.
+
+| Optional field | Default / meaning |
+| --- | --- |
+| `prefix` | Empty; canonical relative object-key prefix |
+| `readOnly` | `false` |
+| `allowNonAtomicRename` | `true`; rename copies then deletes, without rollback guarantees |
+| `pageSize` | 1,000; range 1–1,000 |
+| `maxReadBytes` | Unlimited unless configured |
+| `maxStreamBytes` | Unlimited unless configured |
+| `maxListEntries` | Unlimited unless configured |
+| `removalLimits.maxRequests` | Unlimited unless configured; transport calls per `rm`, including lookup, listing, and deletes |
+| `removalLimits.maxListEntries` | Unlimited unless configured; returned listing entries in aggregate per `rm`, including lookup |
+| `removalLimits.maxDeleteObjects` | Unlimited unless configured; 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. Removal limits default to unlimited and accept a positive safe integer or `Infinity`. Read, stream, listing, and request limits also accept explicit `Infinity`. 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 finite `removalLimits` to bound the work in deployments that need them. 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 |
+| --- | --- |
+| `addressingStyle` | `path`; alternative `virtual-hosted` requires a DNS endpoint |
+| `listUrlEncoding` | `percent`; alternative `form` |
+| `allowInsecureHttp` | `false`; HTTPS required unless explicitly enabled |
+| `maxPutBytes`, `maxGetBytes` | Unlimited when omitted or `Infinity`; positive safe integers set byte caps |
+| `maxXmlBytes` | Unlimited when omitted or `Infinity`; positive safe integers set a byte cap |
+| `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 |
+| `request` | Optional Node HTTP request factory; Node defaults to HTTP(S), browsers and Workers use global fetch |
+
+</details>
+
+<details>
+<summary>WebDAV options</summary>
+
+`WebDavFileSystem` requires `baseUrl` and `fetch`.
+
+| Optional field | Default / meaning |
+| --- | --- |
+| `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` | Unlimited unless configured; applies to decoded response bytes |
+| `maxXmlBytes` | Unlimited unless configured; applies before metadata decoding/parsing |
+| `xmlLimits` | Optional `maxNodes`, `maxContentNodes`, `maxDepth`, and `maxAttributes`; each accepts a positive safe integer or `Infinity`, and is unlimited unless configured |
+| `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. Hosts can configure per-response limits to budget for metadata parsing, text decoding, transport buffers, and concurrent reads. Use streaming reads for large files.
+
+WebDAV `maxEntries`, `maxResponseBytes`, `maxXmlBytes`, and per-read `maxBytes` accept explicit `Infinity`. WebDAV metadata structure limits are disabled by default; configure `xmlLimits` independently of `maxEntries`. Text is bounded by `maxXmlBytes`. Exceeding a structural budget reports `EFBIG`; parsing yields cooperatively so caller cancellation and `timeoutMs` remain active.
+
+See the [binding types](src/fs/webdav/webdav.ts) before implementing atomic directory removal. A recursive WebDAV DELETE does not satisfy that contract.
+
+</details>
+
+## 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.** 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 with two stock MemoryFileSystem layers support race-safe patch publication, conditional file writes/removal, no-replace rename, and confined directory creation/removal and file writes. Compression file output, `mv -n`, `sed -i`, and ssconvert work with these layers. Upper-file writes retain file identity; lower-file writes copy up without changing lower bytes. Publication checks both layers, retains logical directory identity across copy-up, and leaves lower bytes intact; wrapped or customized layers remain unsupported. 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` and `workerd` export conditions select the portable surface: memory, mounts, overlays, read-only, WebDAV, and the codec-based bridge. S3 is available through `fs/s3` with an explicit transport, including its portable mock and `fs/s3/http`. The HTTP transport uses fetch in browsers and Workers and requires server CORS support in browsers. Fetch rejects keys containing dot segments that the URL parser would normalize, and never follows redirects. Node request factories are only supported in Node. Real storage, 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/node_modules/@poe-code/safe-fs/dist/bridge/confinement.d.ts

@@ -0,0 +1,3 @@
+import type { FileSystem, FsOptions } from "../contracts/filesystem.js";
+export declare function assertBridgePath(root: string, path: string): void;
+export declare function checkedBridgePath(fs: FileSystem, root: string, path: string, options: FsOptions, followFinal: boolean): Promise<string>;

package/node_modules/@poe-code/safe-fs/dist/bridge/confinement.js

@@ -0,0 +1,171 @@
+import { FsError, isFsError } from "../contracts/errors.js";
+import { dirname } from "../contracts/virtual-path.js";
+import { checkSignal } from "./values.js";
+function denied(path) {
+    throw new FsError("EACCES", { syscall: "resolve", path, message: "path escapes the bridge cwd" });
+}
+function relativeComponents(root, path) {
+    if (typeof path !== "string" || !path.startsWith("/") || path.includes("\0"))
+        denied(path);
+    const boundary = root.split("/").filter(Boolean);
+    const components = path.split("/").filter(Boolean);
+    let index = 0;
+    for (const component of boundary) {
+        while (components[index] === ".")
+            index++;
+        if (components[index] !== component)
+            denied(path);
+        index++;
+    }
+    const relative = components.slice(index);
+    let depth = 0;
+    for (const component of relative) {
+        if (component === ".")
+            continue;
+        if (component === "..") {
+            if (depth === 0)
+                denied(path);
+            depth--;
+        }
+        else
+            depth++;
+    }
+    if (path.endsWith("/"))
+        relative.push(".");
+    return relative;
+}
+export function assertBridgePath(root, path) {
+    if (root !== "/")
+        relativeComponents(root, path);
+}
+async function assertCanonicalPath(fs, root, path, options) {
+    checkSignal(options.signal);
+    const canonical = await fs.realpath(path, options);
+    checkSignal(options.signal);
+    assertBridgePath(root, canonical);
+    if (canonical !== path)
+        denied(path);
+}
+async function assertCanonicalOperand(fs, root, path, expected, options) {
+    let operand = path;
+    let target = expected;
+    while (true) {
+        checkSignal(options.signal);
+        try {
+            const canonical = await fs.realpath(operand, options);
+            checkSignal(options.signal);
+            assertBridgePath(root, canonical);
+            if (canonical !== target)
+                denied(path);
+            return;
+        }
+        catch (error) {
+            checkSignal(options.signal);
+            if (!isFsError(error) || error.code !== "ENOENT")
+                throw error;
+            let missing = false;
+            try {
+                await fs.lstat(operand, options);
+            }
+            catch (inspectionError) {
+                checkSignal(options.signal);
+                if (!isFsError(inspectionError) || inspectionError.code !== "ENOENT")
+                    throw inspectionError;
+                missing = true;
+            }
+            checkSignal(options.signal);
+            if (!missing || operand === root)
+                denied(path);
+            operand = dirname(operand);
+            target = dirname(target);
+            assertBridgePath(root, operand);
+            assertBridgePath(root, target);
+        }
+    }
+}
+export async function checkedBridgePath(fs, root, path, options, followFinal) {
+    if (root === "/")
+        return path;
+    let pending = relativeComponents(root, path);
+    let current = "";
+    for (const component of root.split("/").filter(Boolean)) {
+        current += `/${component}`;
+        checkSignal(options.signal);
+        try {
+            const stat = await fs.lstat(current, options);
+            checkSignal(options.signal);
+            if (stat.type === "symlink")
+                denied(current);
+            if (stat.type !== "directory")
+                throw new FsError("ENOTDIR", { syscall: "resolve", path: current });
+        }
+        catch (error) {
+            checkSignal(options.signal);
+            if (!isFsError(error) || error.code !== "ENOENT")
+                throw error;
+            if (current !== root)
+                denied(path);
+            if (pending.includes(".."))
+                throw error;
+            const parent = dirname(root);
+            await assertCanonicalPath(fs, parent, parent, options);
+            return path;
+        }
+    }
+    await assertCanonicalPath(fs, root, root, options);
+    let links = 0;
+    let finalLink = false;
+    let index = 0;
+    while (index < pending.length) {
+        const component = pending[index++];
+        checkSignal(options.signal);
+        if (component === ".")
+            continue;
+        if (component === "..") {
+            if (current === root)
+                denied(path);
+            current = dirname(current);
+            continue;
+        }
+        const candidate = `${current}/${component}`;
+        let stat;
+        try {
+            stat = await fs.lstat(candidate, options);
+        }
+        catch (error) {
+            checkSignal(options.signal);
+            if (!isFsError(error) || error.code !== "ENOENT")
+                throw error;
+            if (pending.slice(index).includes(".."))
+                throw error;
+            await assertCanonicalPath(fs, root, current, options);
+            const expected = [candidate, ...pending.slice(index)].join("/");
+            await assertCanonicalOperand(fs, root, path, expected, options);
+            return path;
+        }
+        checkSignal(options.signal);
+        if (stat.type === "symlink" && (followFinal || index < pending.length)) {
+            if (++links > 40)
+                throw new FsError("ELOOP", { syscall: "resolve", path });
+            if (typeof fs.readlink !== "function")
+                throw new FsError("ENOTSUP", { syscall: "readlink", path: candidate });
+            const target = await fs.readlink(candidate, options);
+            checkSignal(options.signal);
+            if (typeof target !== "string" || target.length === 0 || target.includes("\0"))
+                denied(candidate);
+            const absolute = target.startsWith("/") ? target : `${current}/${target}`;
+            pending = [...relativeComponents(root, absolute), ...pending.slice(index)];
+            index = 0;
+            current = root;
+            continue;
+        }
+        if (index < pending.length && stat.type !== "directory") {
+            throw new FsError("ENOTDIR", { syscall: "resolve", path: candidate });
+        }
+        current = candidate;
+        finalLink = stat.type === "symlink";
+    }
+    await assertCanonicalPath(fs, root, finalLink ? dirname(current) : current, options);
+    await assertCanonicalOperand(fs, root, finalLink ? dirname(path) : path, finalLink ? dirname(current) : current, options);
+    return path;
+}