toolcraft 0.0.771 → 0.0.773

package/composition.json

@@ -106,6 +106,11 @@
       "version": "0.1.0",
       "license": "MIT"
     },
+    {
+      "name": "saxes",
+      "version": "6.0.0",
+      "license": "ISC"
+    },
     {
       "name": "sisteransi",
       "version": "1.0.5",
@@ -118,7 +123,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.124",
+      "version": "0.1.129",
       "license": "MIT"
     },
     {
@@ -133,7 +138,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.771",
+      "version": "0.0.773",
       "license": "MIT"
     },
     {
@@ -143,7 +148,12 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.771",
+      "version": "0.0.773",
+      "license": "MIT"
+    },
+    {
+      "name": "xmlchars",
+      "version": "2.2.0",
       "license": "MIT"
     },
     {

package/dist/composition.json

@@ -106,6 +106,11 @@
       "version": "0.1.0",
       "license": "MIT"
     },
+    {
+      "name": "saxes",
+      "version": "6.0.0",
+      "license": "ISC"
+    },
     {
       "name": "sisteransi",
       "version": "1.0.5",
@@ -118,7 +123,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.124",
+      "version": "0.1.129",
       "license": "MIT"
     },
     {
@@ -133,7 +138,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.771",
+      "version": "0.0.773",
       "license": "MIT"
     },
     {
@@ -143,7 +148,12 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.771",
+      "version": "0.0.773",
+      "license": "MIT"
+    },
+    {
+      "name": "xmlchars",
+      "version": "2.2.0",
       "license": "MIT"
     },
     {

package/node_modules/@poe-code/safe-fs/dist/contracts/filesystem.d.ts

@@ -87,6 +87,8 @@ export interface FileSystemCapabilities {
     readonly synchronousDirectoryValidation?: boolean;
     /** Captures a followed destination path with a synchronous commit validator. */
     readonly synchronousStagingResolution?: boolean;
+    /** Also binds the final symlink and its target in the synchronous validator. */
+    readonly synchronousFollowedStagingResolution?: boolean;
     /** Invokes commitGuard in the same synchronous section as staged replacement. */
     readonly guardedStagingPublication?: boolean;
     readonly atomicFilePublication?: boolean;
@@ -129,6 +131,7 @@ export interface CapabilityQueryOptions extends OpenReadFileOptions {
      * Omission retains the ordinary per-target query and its acquisition intent. */
     readonly stagingAncestry?: boolean;
     readonly stagingResolution?: boolean;
+    readonly followFinalSymlink?: boolean;
     readonly create?: boolean;
     readonly creation?: OpenFileOptions["creation"];
 }
@@ -233,6 +236,10 @@ export interface FileStagingEntry {
 export interface FileResolutionStep extends FileStagingEntry {
     readonly linkTarget?: string;
 }
+export interface PrepareStagingResolutionOptions extends FsOptions {
+    /** Requires synchronousFollowedStagingResolution; omission preserves final-entry resolution. */
+    readonly followFinalSymlink?: boolean;
+}
 export interface FileStagingResolution {
     readonly path: string;
     readonly parent: FileStat;
@@ -344,7 +351,7 @@ export interface FileSystem {
      * The returned guard checks current identities/search access synchronously;
      * preparation is not validation, and the guard's result is not an async lease. */
     prepareDirectoryAncestry?(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
-    prepareStagingResolution?(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    prepareStagingResolution?(path: string, options?: PrepareStagingResolutionOptions): Promise<FileStagingResolution>;
     removeStagedFile?(staging: FileStaging, options?: FsOptions): Promise<void>;
     openReadFile?(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
     openResizeFile?(path: string, options?: OpenResizeFileOptions): Promise<FileResizeHandle>;

package/node_modules/@poe-code/safe-fs/dist/core.d.ts

@@ -8,7 +8,7 @@ export * from "./fs/object-publication/index.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
-export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
+export { parseXml, parseXmlSteps, parseXmlStream, XmlLimitError } from "./xml.js";
 export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";

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

@@ -8,7 +8,7 @@ export * from "./fs/object-publication/index.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
-export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
+export { parseXml, parseXmlSteps, parseXmlStream, XmlLimitError } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
 export * from "./fs/s3/index.js";

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

@@ -132,7 +132,7 @@ export function readOnlyCapabilities(capabilities) {
     ].filter(name => capabilities[name] !== undefined).map(name => [name, capabilities[name]]));
     return Object.freeze({
         ...inspection, retainedStagingCleanup: false, retainedStagingWrite: false, readOnly: true, write: false, append: false, exclusiveCreate: false,
-        synchronousStagingResolution: false,
+        synchronousStagingResolution: false, synchronousFollowedStagingResolution: false,
         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, conditionalChmod: false, timestamps: false,
@@ -144,7 +144,7 @@ export function quotaCapabilities(capabilities) {
     const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, capabilities.streamingAppend, !capabilities.readOnly);
     const streamingAppend = requireCapabilities(capabilities.append, capabilities.streamingAppend, !capabilities.readOnly);
     const { streamingWrite: ignoredWrite, streamingAppend: ignoredAppend, ...rest } = capabilities;
-    return Object.freeze({ ...rest, synchronousStagingResolution: false, retainedStagingCleanup: false, retainedStagingWrite: false, atomicStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicStagedFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+    return Object.freeze({ ...rest, synchronousStagingResolution: false, synchronousFollowedStagingResolution: false, retainedStagingCleanup: false, retainedStagingWrite: false, atomicStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicStagedFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
@@ -179,6 +179,8 @@ export function ownedMutationCapabilities(filesystem, capabilities = filesystem.
         (unavailable ??= {}).synchronousDirectoryValidation = false;
     if (capabilities.synchronousStagingResolution === true && (capabilities.readOnly === true || typeof filesystem.prepareStagingResolution !== "function"))
         (unavailable ??= {}).synchronousStagingResolution = false;
+    if (capabilities.synchronousFollowedStagingResolution === true && (capabilities.synchronousStagingResolution !== true || unavailable?.synchronousStagingResolution === false))
+        (unavailable ??= {}).synchronousFollowedStagingResolution = false;
     if (capabilities.guardedStagingPublication === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
         (unavailable ??= {}).guardedStagingPublication = false;
     if (capabilities.atomicDirectoryMetadata === true && (capabilities.readOnly === true || typeof filesystem.prepareDirectory !== "function"))

package/node_modules/@poe-code/safe-fs/dist/fs/devices/index.d.ts

@@ -1,5 +1,5 @@
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
-import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PrepareStagingResolutionOptions, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 import { type EntryLocation } from "../mount/comparison.js";
 import { pathNamespace } from "../path-namespace.js";
@@ -43,7 +43,7 @@ export declare class DeviceFileSystem implements FileSystem {
     publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
     publishStagedFileSet(receipt: FileStaging, destination: string, supplied: PublishStagedFileSetOptions): Promise<FileStat>;
     prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
-    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    prepareStagingResolution(path: string, options?: PrepareStagingResolutionOptions): Promise<FileStagingResolution>;
     removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
     prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     rename(source: string, destination: string, options?: RenameOptions): Promise<void>;

package/node_modules/@poe-code/safe-fs/dist/fs/devices/index.js

@@ -13,7 +13,7 @@ import { openFileDescriptor } from "../descriptor.js";
 import { normalizePath } from "../../contracts/virtual-path.js";
 const views = new WeakMap();
 const deviceCapabilities = Object.freeze({
-    synchronousStagingResolution: false,
+    synchronousStagingResolution: false, synchronousFollowedStagingResolution: false,
     readOnly: false, read: true, stat: true, realpath: true, access: true, readdir: false,
     write: true, append: true, exclusiveCreate: true, streamingRead: true, retainedRead: true,
     streamingWrite: true, streamingAppend: true, independentWriteStreams: true, copy: true, exclusiveCopy: true,
@@ -179,7 +179,7 @@ export class DeviceFileSystem {
         let selected;
         const traversal = options.stagingResolution === true ? { virtual: false } : undefined;
         try {
-            resolved = await this.#resolve(path, options, options.stagingResolution !== true && (options.create !== undefined || options.creation !== "exclusive"), options.create, traversal);
+            resolved = await this.#resolve(path, options, options.stagingResolution === true ? options.followFinalSymlink === true : options.create !== undefined || options.creation !== "exclusive", options.create, traversal);
         }
         catch (error) {
             options.signal?.throwIfAborted();
@@ -210,7 +210,7 @@ export class DeviceFileSystem {
         // This intent cannot bind virtual traversal. Do not infer other path
         // capabilities by resolving the shadowed entry in the backing filesystem.
         if (traversal?.virtual)
-            return Object.freeze({ synchronousStagingResolution: false });
+            return Object.freeze({ synchronousStagingResolution: false, synchronousFollowedStagingResolution: false });
         if (selected === undefined) {
             const query = this.#filesystem.capabilitiesFor;
             options.signal?.throwIfAborted();
@@ -229,6 +229,7 @@ export class DeviceFileSystem {
                     throw new FsError("EAGAIN", { path });
                 if ([resolution.path, ...resolution.traversed.map(entry => entry.path)].some(entry => entry === deviceDirectory || entry.startsWith(`${deviceDirectory}/`))) {
                     (unavailable ??= {}).synchronousStagingResolution = false;
+                    unavailable.synchronousFollowedStagingResolution = false;
                 }
                 runStagingGuard(resolution.validate);
             }
@@ -237,6 +238,7 @@ export class DeviceFileSystem {
                 if (!isFsError(error, "ENOTSUP"))
                     throw error;
                 (unavailable ??= {}).synchronousStagingResolution = false;
+                unavailable.synchronousFollowedStagingResolution = false;
             }
         }
         if (resolved.startsWith(`${deviceDirectory}/`)) {
@@ -244,6 +246,7 @@ export class DeviceFileSystem {
             u.atomicStagingAncestry = false;
             u.synchronousDirectoryValidation = false;
             u.synchronousStagingResolution = false;
+            u.synchronousFollowedStagingResolution = false;
         }
         if (typeof this.#filesystem.open !== "function" && capabilities.open !== false)
             (unavailable ??= {}).open = false;
@@ -753,19 +756,19 @@ export class DeviceFileSystem {
         }
     }
     async prepareStagingResolution(path, options = {}) {
-        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        const controls = { ...(options.signal === undefined ? {} : { signal: options.signal }), ...(options.followFinalSymlink === true ? { followFinalSymlink: true } : {}) };
         controls.signal?.throwIfAborted();
         if (normalizePath(path) !== path || !path.startsWith("/"))
             throw new FsError("EINVAL", { path });
         try {
             const traversal = { virtual: false };
-            const resolved = await this.#resolve(path, controls, false, undefined, traversal);
+            const resolved = await this.#resolve(path, controls, controls.followFinalSymlink === true, undefined, traversal);
             controls.signal?.throwIfAborted();
             if (traversal.virtual)
                 throw new FsError("ENOTSUP", { path });
             const declared = ownedMutationCapabilities(this.#filesystem, await this.#filesystem.capabilitiesFor?.(path, { ...controls, stagingResolution: true }) ?? this.#filesystem.capabilities);
             controls.signal?.throwIfAborted();
-            if (declared.synchronousStagingResolution !== true || !this.#filesystem.prepareStagingResolution)
+            if (declared.synchronousStagingResolution !== true || controls.followFinalSymlink === true && declared.synchronousFollowedStagingResolution !== true || !this.#filesystem.prepareStagingResolution)
                 throw new FsError("ENOTSUP", { path });
             const receipt = snapshotStagingResolution(await this.#filesystem.prepareStagingResolution(path, controls));
             controls.signal?.throwIfAborted();

package/node_modules/@poe-code/safe-fs/dist/fs/memory/index.d.ts

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, FileDescriptor, OpenFileOptions, OpenReadFileOptions, OpenResizeFileOptions, WriteFileOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, FileDescriptor, OpenFileOptions, OpenReadFileOptions, OpenResizeFileOptions, WriteFileOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PrepareStagingResolutionOptions, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 import { type MemoryAtomicView } from "./atomic-view.js";
 import { MemoryAllocation, MemoryLedger } from "./ledger.js";
@@ -116,7 +116,7 @@ export declare class MemoryFileSystem implements FileSystem {
     createStagedFile(directoryPath: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     private retainStagingCleanup;
     prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
-    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    prepareStagingResolution(path: string, options?: PrepareStagingResolutionOptions): Promise<FileStagingResolution>;
     private verifyDirectoryAncestry;
     publishStagedFile(receipt: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
     publishStagedFileSet(receipt: FileStaging, destination: string, options: PublishStagedFileSetOptions): Promise<FileStat>;

package/node_modules/@poe-code/safe-fs/dist/fs/memory/index.js

@@ -585,7 +585,7 @@ const SHARED_STOCK_MEMORY_CAPABILITIES = Object.freeze({
     timestamps: true,
     atomicRename: true,
     atomicStagedFileMutation: true, atomicFileStaging: true, retainedStagingCleanup: true, retainedStagingWrite: true, atomicStagingAncestry: true, atomicFileMutation: true, atomicEntryRemoval: true, atomicEntryRemovalReceipt: true, atomicTreeRemoval: true,
-    synchronousDirectoryValidation: true, synchronousStagingResolution: true, guardedStagingPublication: true,
+    synchronousDirectoryValidation: true, synchronousStagingResolution: true, synchronousFollowedStagingResolution: true, guardedStagingPublication: true,
     atomicDirectoryMetadata: true,
     streamingRead: true,
     retainedRead: true,
@@ -2186,13 +2186,14 @@ export class MemoryFileSystem {
         return () => this.verifyDirectoryAncestry(entries, controls);
     }
     async prepareStagingResolution(path, options = {}) {
+        const followFinal = options.followFinalSymlink === true;
         const controls = options.signal === undefined ? {} : { signal: options.signal };
         controls.signal?.throwIfAborted();
         this.validatePath(path, "prepareStagingResolution");
         if (!path.startsWith("/") || normalizePath(path) !== path)
             this.fail("EINVAL", "prepareStagingResolution", path);
         const traversed = [];
-        const location = this.resolve(path, "prepareStagingResolution", { followFinal: false, allowMissing: true, resolutionSteps: traversed });
+        const location = this.resolve(path, "prepareStagingResolution", { followFinal, allowMissing: true, resolutionSteps: traversed });
         if (location.node && location.node.type !== "file")
             this.fail("ENOTSUP", "prepareStagingResolution", path);
         const parentPath = location.path.slice(0, location.path.lastIndexOf("/")) || "/";
@@ -2207,7 +2208,7 @@ export class MemoryFileSystem {
             const currentSteps = [];
             let current;
             try {
-                current = this.resolve(path, "verifyStagingResolution", { followFinal: false, allowMissing: true, resolutionSteps: currentSteps });
+                current = this.resolve(path, "verifyStagingResolution", { followFinal, allowMissing: true, resolutionSteps: currentSteps });
             }
             catch (error) {
                 if (error instanceof FsError && ["ENOENT", "ENOTDIR", "ELOOP"].includes(error.code))

package/node_modules/@poe-code/safe-fs/dist/fs/mount/index.d.ts

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PrepareStagingResolutionOptions, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
 export interface MountFileSystemOptions {
@@ -18,7 +18,7 @@ export declare class MountFileSystem implements FileSystem {
     private supportsStagingAncestry;
     private supportsDirectoryValidation;
     prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
-    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    prepareStagingResolution(path: string, options?: PrepareStagingResolutionOptions): Promise<FileStagingResolution>;
     private prepareAncestry;
     private protected;
     openReadFile(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;

package/node_modules/@poe-code/safe-fs/dist/fs/mount/index.js

@@ -191,7 +191,8 @@ export class MountFileSystem {
                 fail("EINVAL");
             const location = await this.resolve(path, options, {
                 allowMissing: options.create ?? true,
-                followFinal: options.stagingResolution !== true && (options.create !== undefined || options.creation !== "exclusive"),
+                retainedResolution: options.stagingResolution === true && options.followFinalSymlink === true,
+                followFinal: options.stagingResolution === true ? options.followFinalSymlink === true : options.create !== undefined || options.creation !== "exclusive",
                 ...(options.create === undefined ? {} : { resizeCreate: options.create }),
             });
             const observed = ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(location.local, options)
@@ -212,15 +213,15 @@ export class MountFileSystem {
                     const input = location.mount.path === "/" ? path : path.slice(location.mount.path.length) || "/";
                     const declared = input === location.local ? resize : ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(input, options) ?? location.mount.backend.capabilities);
                     options.signal?.throwIfAborted();
-                    resolution = declared.synchronousStagingResolution === true && await this.supportsStagingAncestry(location, resize, options);
+                    resolution = declared.synchronousStagingResolution === true && (options.followFinalSymlink !== true || declared.synchronousFollowedStagingResolution === true) && await this.supportsStagingAncestry(location, resize, options);
                 }
             }
             const conditionalChmod = options.conditionalChmod === true
                 ? resize.conditionalChmod === true && typeof location.mount.backend.chmod === "function"
                     && await this.supportsDirectoryValidation(location.path.slice(0, location.path.lastIndexOf("/")) || "/", options, true)
                 : this.capabilities.conditionalChmod;
-            const { synchronousDirectoryValidation: ignoredValidation, synchronousStagingResolution: ignoredResolution, ...ordinary } = resize;
-            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
+            const { synchronousDirectoryValidation: ignoredValidation, synchronousStagingResolution: ignoredResolution, synchronousFollowedStagingResolution: ignoredFollowedResolution, ...ordinary } = resize;
+            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution, ...(options.followFinalSymlink === true ? { synchronousFollowedStagingResolution: resolution } : {}) }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
             const capabilities = location.synthetic ? { ...withOpen, open: false, retainedRead: false }
                 : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, withOpen));
             if (location.synthetic)
@@ -264,19 +265,19 @@ export class MountFileSystem {
         return this.operation("prepareDirectoryAncestry", ancestors.at(-1)?.path ?? "/", options, () => this.prepareAncestry(ancestors, options));
     }
     prepareStagingResolution(path, options = {}) {
-        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        const controls = { ...(options.signal === undefined ? {} : { signal: options.signal }), ...(options.followFinalSymlink === true ? { followFinalSymlink: true } : {}) };
         return this.operation("prepareStagingResolution", path, controls, async () => {
             if (normalizePath(globalPath(path)) !== path)
                 fail("EINVAL");
             const observed = [];
-            const location = await this.resolve(path, controls, { followFinal: false, allowMissing: true, resolutionSteps: observed });
+            const location = await this.resolve(path, controls, { followFinal: controls.followFinalSymlink === true, retainedResolution: controls.followFinalSymlink === true, allowMissing: true, resolutionSteps: observed });
             if (location.synthetic || !within(location.mount.path, path))
                 fail("ENOTSUP");
             const backend = location.mount.backend;
             const input = location.mount.path === "/" ? path : path.slice(location.mount.path.length) || "/";
             const declared = ownedMutationCapabilities(backend, await backend.capabilitiesFor?.(input, { ...controls, stagingResolution: true }) ?? backend.capabilities);
             controls.signal?.throwIfAborted();
-            if (declared.synchronousStagingResolution !== true || !backend.prepareStagingResolution)
+            if (declared.synchronousStagingResolution !== true || controls.followFinalSymlink === true && declared.synchronousFollowedStagingResolution !== true || !backend.prepareStagingResolution)
                 fail("ENOTSUP");
             const prefix = directoryAncestryPaths(location.mount.path).map(ancestor => {
                 const entry = observed.find(step => step.path === ancestor);
@@ -546,6 +547,10 @@ export class MountFileSystem {
         let followedFinalLink = false;
         const verified = async (location) => {
             let inspection = !location.stat && settings.resizeCreate === true ? creationVerification : verification;
+            // A guarded resolution binds the original link chain and missing target
+            // through the authoritative backend receipt; realpath cannot name absence.
+            if (settings.retainedResolution && !location.stat && followedFinalLink)
+                inspection = undefined;
             // A missing entry has no realpath. Verify its existing parent while
             // leaving dangling final symlinks on the ordinary following path.
             if (inspection && !location.stat && settings.allowMissing && !followedFinalLink && inspection.finalName === undefined) {

package/node_modules/@poe-code/safe-fs/dist/fs/overlay/index.d.ts

@@ -43,6 +43,7 @@ export declare class OverlayFileSystem implements FileSystem {
     private bytes;
     private cleanGarbage;
     cleanup(options?: FsOptions): Promise<void>;
+    private stagingOptions;
     private staged;
     private preserve;
     private clone;

package/node_modules/@poe-code/safe-fs/dist/fs/overlay/index.js

@@ -554,7 +554,12 @@ export class OverlayFileSystem {
     async cleanup(options = {}) {
         return this.run(options, () => this.cleanGarbage(true));
     }
+    // Receipts describe overlay paths and identities, never backing-layer staging paths.
+    stagingOptions({ signal }) {
+        return signal === undefined ? {} : { signal };
+    }
     async staged(options, operation) {
+        options = this.stagingOptions(options);
         const root = `/.virtual-bash-overlay-${platform.randomUUID()}`;
         if (await this.maybeStat(this.#upper, root, options) || await this.maybeStat(this.#lower, root, options))
             fail("EEXIST", root);
@@ -570,6 +575,7 @@ export class OverlayFileSystem {
         }
     }
     async preserve(path, stat, options) {
+        options = this.stagingOptions(options);
         if (this.#upper.chmod)
             await this.#upper.chmod(path, stat.mode & 0o7777, options);
         else if (((await this.#upper.lstat(path, options)).mode & 0o7777) !== (stat.mode & 0o7777))
@@ -579,6 +585,7 @@ export class OverlayFileSystem {
         await this.#upper.utimes(path, stat.atimeMs, stat.mtimeMs, options);
     }
     async clone(entry, destination, options) {
+        options = this.stagingOptions(options);
         if (entry.stat.type !== "directory" && ((entry.stat.nlink ?? 1) > 1
             || (entry.backend.capabilities.hardlinks === true && entry.stat.nlink === undefined))) {
             fail("ENOTSUP", entry.path, "copy-up cannot preserve hardlink identity");
@@ -608,6 +615,7 @@ export class OverlayFileSystem {
         }
     }
     async ensureDirectory(path, options) {
+        options = this.stagingOptions(options);
         const entry = await this.lookup(path, options);
         if (!entry)
             fail("ENOENT", path);
@@ -618,6 +626,7 @@ export class OverlayFileSystem {
         await this.copyUp(entry, options);
     }
     async copyUp(entry, options) {
+        options = this.stagingOptions(options);
         if (entry.backend === this.#upper)
             return;
         if (entry.path === "/")
@@ -640,6 +649,7 @@ export class OverlayFileSystem {
         });
     }
     async parent(path, options) {
+        options = this.stagingOptions(options);
         const parent = await this.lookup(dirname(path), options);
         if (!parent)
             fail("ENOENT", dirname(path));

package/node_modules/@poe-code/safe-fs/dist/fs/overlay/memory-publication.js

@@ -376,6 +376,24 @@ export class OverlayMemoryPublication {
         const owned = await this.upper.createStagedFile(directory, name, content, { ...options, parent });
         const staging = Object.freeze({
             parent: owned.parent, directory: owned.directory, file: owned.file,
+            ...(owned.writer ? { writer: Object.freeze({
+                    write: async (bytes, controls = {}) => {
+                        controls.signal?.throwIfAborted();
+                        this.stores();
+                        guard?.();
+                        this.check(ancestors);
+                        await owned.writer.write(bytes, controls);
+                    },
+                    finish: async (controls = {}) => {
+                        controls.signal?.throwIfAborted();
+                        this.stores();
+                        guard?.();
+                        this.check(ancestors);
+                        const stat = await owned.writer.finish(controls);
+                        this.stages.set(staging.directory, { ...owned, file: { ...owned.file, stat } });
+                        return stat;
+                    },
+                }) } : {}),
             ...(owned.cleanup ? { cleanup: createStagingCleanup(directory, controls => this.cleanup(staging, controls, true), () => owned.cleanup.close()) } : {}),
         });
         this.stages.set(staging.directory, owned);

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

@@ -459,7 +459,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                     try {
                         const declared = ownedMutationCapabilities(original, await original.capabilitiesFor?.(path, { ...controls, stagingResolution: true }) ?? original.capabilities);
                         controls.signal?.throwIfAborted();
-                        if (declared.synchronousStagingResolution !== true)
+                        if (declared.synchronousStagingResolution !== true || controls.followFinalSymlink === true && declared.synchronousFollowedStagingResolution !== true)
                             throw new FsError("ENOTSUP", { path });
                         const resolution = snapshotStagingResolution(await Reflect.apply(method, original, [path, controls]));
                         controls.signal?.throwIfAborted();

package/node_modules/@poe-code/safe-fs/dist/storage.d.ts

@@ -49,7 +49,7 @@ export declare class IntegerTable {
     /** Ordered replay with a fixed 16-level radix stack (at most 2 KiB of
      * owned node bytes) and 128 output records. Batches avoid alternating sparse
      * index reads with consumer writes on every record. Mutation is not permitted. */
-    entries(): AsyncGenerator<readonly [bigint, bigint]>;
+    entries(start?: bigint, end?: bigint): AsyncGenerator<readonly [bigint, bigint]>;
     /** Hot radix paths must not evict dirty leaf pages in a one-page backend. */
     private branch;
     private lookup;

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

@@ -103,14 +103,20 @@ export class PagedStorage {
             this.pages.set(number, cached);
             return cached;
         }
+        let reusable;
         if (this.pages.size === this.maxPages) {
             if (!this.descriptor)
                 await this.spill();
             const [oldNumber, oldPage] = this.pages.entries().next().value;
             await this.flush(oldNumber, oldPage);
             this.pages.delete(oldNumber);
+            reusable = oldPage;
         }
-        const page = { bytes: new Uint8Array(pageBytes), dirty: false };
+        // Flush owns the bytes until its awaited write completes. Reuse only then;
+        // zero new/unwritten ranges so the previous page cannot leak into them.
+        const page = reusable ?? { bytes: new Uint8Array(pageBytes), dirty: false };
+        if (reusable)
+            page.bytes.fill(0);
         if (number * pageBytes < this.diskLength) {
             let offset = 0;
             while (offset < pageBytes) {
@@ -204,8 +210,14 @@ export class IntegerTable {
     async retain(key, value, dirty) {
         if (this.cache.size === this.maxEntries && !this.cache.has(key)) {
             const [oldKey, old] = this.cache.entries().next().value;
+            // Flush the bounded dirty window together, before the caller touches other
+            // stored data. One dirty leaf per insertion otherwise thrashes a page cache.
             if (old.dirty)
-                await this.persist(oldKey, old.value);
+                for (const [key, entry] of this.cache)
+                    if (entry.dirty) {
+                        await this.persist(key, entry.value);
+                        entry.dirty = false;
+                    }
             this.cache.delete(oldKey);
         }
         this.cache.delete(key);
@@ -232,7 +244,11 @@ export class IntegerTable {
     /** Ordered replay with a fixed 16-level radix stack (at most 2 KiB of
      * owned node bytes) and 128 output records. Batches avoid alternating sparse
      * index reads with consumer writes on every record. Mutation is not permitted. */
-    async *entries() {
+    async *entries(start = 0n, end = 0x10000000000000000n) {
+        if (start < 0n || start > end || end > 0x10000000000000000n)
+            throw new RangeError("Invalid integer table range");
+        if (start === end)
+            return;
         const revision = this.revision;
         const check = () => { if (revision !== this.revision)
             throw new Error("Integer table changed during iteration"); };
@@ -259,6 +275,8 @@ export class IntegerTable {
                 if (!value)
                     continue;
                 const key = prefix | BigInt(slot) << shift;
+                if (key >= end || key + (1n << shift) <= start)
+                    continue;
                 if (shift === 0n)
                     yield [key, value - 1n];
                 else

package/node_modules/@poe-code/xml-ast/README.md

@@ -16,9 +16,10 @@ console.log(document.children[0].text); // A & B
 | API | Use |
 | --- | --- |
 | `parseXml(source, limits?)` | Parse a string into an `XmlElement`. |
+| `parseXmlStream(chunks, limits?, checkpoint?)` | Consume synchronous or asynchronous string chunks into an `XmlElement`. |
 | `parseXmlSteps(source, limits?)` | Advance a parser through work checkpoints; the generator returns the completed element. |
 | `XmlLimitError` | Inspect which configured resource limit was exceeded through its `limit` property. |
-| `XmlElement`, `XmlContent`, `XmlAttribute`, `XmlName`, `XmlLimits` | Describe and consume the XML tree without Node.js types. |
+| `XmlElement`, `XmlContent`, `XmlAttribute`, `XmlName`, `XmlLimits`, `XmlStreamLimits` | Describe and consume the XML tree without Node.js types. |
 
 Pass positive integer limits for depth, element and content counts, attributes, namespaces, and text. Omitted limits are unlimited. `retainContent` preserves ordered mixed content; `onElement` observes element names, parents, and depths during parsing. `expectedEncoding` checks an XML declaration against the caller's decoded input.
 
@@ -26,3 +27,11 @@ Pass positive integer limits for depth, element and content counts, attributes,
 Pass `recover: message => report(message)` to repair truncated elements,
 mismatched closing tags, and undeclared entities. Each repair calls the callback.
 Resource limits and the prohibition on DTDs remain in force.
+
+`parseXmlStream` consumes each chunk before requesting the next and calls the optional asynchronous checkpoint with at most 512 UTF-16 units. It preserves the buffered parser’s tree shape, namespaces and retained content. The source is closed on parsing or checkpoint failure. Decode byte sources incrementally before passing their strings. This avoids a full source string; the resulting tree and individual XML tokens still reside in memory. Recovery remains available through the buffered parser.
+
+For validation or root-name detection, pass `retainTree: false` to `parseXmlStream`. It validates the complete document and enforces the same limits, but returns a root element with empty data fields. Only open element frames, namespace scopes and current parser tokens remain resident; completed descendants, text, attributes and document content are not retained. `onElement` still observes each element.
+
+Use `streamElements: { matches, consume }` to process selected complete subtrees asynchronously. Matching non-root elements are detached from their parent; nested matches remain inside the selected ancestor. `consume(element, parent, before?)` runs in source order and is awaited before the next 512-unit parse window. The producer closes on consumer failure. This mode requires normal tree/content retention and retains each selected subtree until consumption; individual large subtrees and XML tokens still need their own storage strategy.
+
+Set `streamElements.captureBefore: true` to detach preceding sibling content when each subtree is selected and receive it as `before`. This preserves text, CDATA, comments and sibling order even when multiple subtrees share one parse window. The remaining trailing content stays in the parent. Store both `before` and the subtree when you need to reconstruct the original mixed content.

package/node_modules/@poe-code/xml-ast/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class XmlLimitError extends SyntaxError {
+    readonly limit: string;
+    constructor(limit: string, message: string);
+}

package/node_modules/@poe-code/xml-ast/dist/errors.js

@@ -0,0 +1,7 @@
+export class XmlLimitError extends SyntaxError {
+    limit;
+    constructor(limit, message) {
+        super(message);
+        this.limit = limit;
+    }
+}

package/node_modules/@poe-code/xml-ast/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { XmlLimitError } from "./errors.js";
 export interface XmlName {
     readonly name: string;
     readonly namespace: string;
@@ -39,9 +40,6 @@ export interface XmlLimits {
     readonly maxTextLength?: number;
     readonly onElement?: (element: XmlName, parent: XmlName | undefined, depth: number) => void;
 }
-export declare class XmlLimitError extends SyntaxError {
-    readonly limit: string;
-    constructor(limit: string, message: string);
-}
 export declare function parseXmlSteps(input: string, limits?: XmlLimits): Generator<number, XmlElement, void>;
 export declare function parseXml(input: string, limits?: XmlLimits): XmlElement;
+export { parseXmlStream, type XmlStreamLimits } from "./stream.js";