toolcraft 0.0.767 → 0.0.769

package/composition.json

@@ -133,7 +133,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.767",
+      "version": "0.0.769",
       "license": "MIT"
     },
     {
@@ -143,7 +143,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.767",
+      "version": "0.0.769",
       "license": "MIT"
     },
     {

package/dist/composition.json

@@ -133,7 +133,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.767",
+      "version": "0.0.769",
       "license": "MIT"
     },
     {
@@ -143,7 +143,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.767",
+      "version": "0.0.769",
       "license": "MIT"
     },
     {

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

@@ -10,6 +10,10 @@ working data. Supply `{fs, cwd, env, signal}` and an optional page-cache count
 `env.TMPDIR` or `cwd`, with conditional unlink and cleanup through `close()`.
 Providers must support those capabilities; there is no host fallback. Use an
 external backend for large data because memory filesystems retain spilled bytes.
+`IntegerTable.entries()` replays records in unsigned key order with a fixed
+16-level node stack and batches of at most 128 records. It accepts zero-filled
+caller storage with `allocate`, `read` and `write`; mutation during traversal
+is rejected. Branch pointers use a separate fixed 128-entry cache.
 
 ## Quickstart
 
@@ -86,7 +90,7 @@ cause. Preserve cancellation/control exceptions separately. Cross-family
 | 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` |
-| Enumerate directories lazily | Optional `iterateDirectory`; memory and native backends, with mount/overlay/readonly/quota/device/scoped delegation; backend order, no sorted-array fallback |
+| Enumerate directories lazily | Optional `iterateDirectory`; memory, native and paged S3 backends, with mount/overlay/readonly/quota/device/scoped delegation; backend order, no sorted-array fallback |
 | 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 |
@@ -133,7 +137,11 @@ 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.
+retain only the owned staging entries; replacement entries remain protected. When
+`atomicStagedFileMutation` is available, `publishStagedFile(..., { preserveIdentity: true,
+parent, destination })` updates an existing file without breaking hardlink aliases.
+Memory and its supported wrappers adopt staged bytes and timestamps while keeping
+the destination identity and mode; unsupported adapters reject this option.
 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

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

@@ -76,6 +76,8 @@ export interface FileSystemCapabilities {
     /** Owned staging serialized within a trusted host; requires external tree isolation. */
     readonly trustedOwnedStaging?: boolean;
     readonly atomicFileStaging?: boolean;
+    /** Staged payload publication can atomically preserve an existing inode. */
+    readonly atomicStagedFileMutation?: boolean;
     /** Creates a cleanup handle bound to owned staging entries, independent of ancestor paths. */
     readonly retainedStagingCleanup?: boolean;
     readonly retainedStagingWrite?: boolean;
@@ -277,6 +279,11 @@ export interface CreateStagedFileOptions extends FsOptions {
     readonly mtimeMs?: number;
 }
 export interface PublishStagedFileOptions extends FsOptions {
+    /** Requires atomicStagedFileMutation and an existing regular destination.
+     * Atomically adopts staged bytes and timestamps while preserving destination
+     * identity, links and mode. Consumes the staged pathname as ordinary publication.
+     * Unsupported hosts must reject before effects, never silently rename. */
+    readonly preserveIdentity?: boolean;
     readonly ancestors?: readonly FileStagingEntry[];
     /** Trusted, mutation-free validation. Must return literal true synchronously;
      * a promise is not acceptance. Requires guardedStagingPublication. */

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

@@ -7,4 +7,4 @@ export declare function openRetainedResizeFile(filesystem: FileSystem, path: str
 export declare function readOnlyCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function quotaCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function ownedMutationCapabilities(filesystem: FileSystem, capabilities?: FileSystemCapabilities): FileSystemCapabilities;
-export declare function requireOwnedMutation(filesystem: FileSystem, path: string, capability: "retainedStagingCleanup" | "atomicFilePublication" | "atomicEntryRemoval" | "atomicEntryRemovalReceipt" | "atomicTreeRemoval" | "atomicFileMutation" | "atomicFileStaging" | "guardedStagingPublication" | "atomicStagingAncestry" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;
+export declare function requireOwnedMutation(filesystem: FileSystem, path: string, capability: "retainedStagingCleanup" | "atomicFilePublication" | "atomicEntryRemoval" | "atomicEntryRemovalReceipt" | "atomicTreeRemoval" | "atomicFileMutation" | "atomicFileStaging" | "atomicStagedFileMutation" | "guardedStagingPublication" | "atomicStagingAncestry" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;

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

@@ -136,7 +136,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, conditionalChmod: false, timestamps: false,
-        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicStagedFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         atomicFilePublication: false, atomicRename: false, atomicRenameNoReplace: false, streamingWrite: 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, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+    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,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
@@ -167,6 +167,8 @@ export function ownedMutationCapabilities(filesystem, capabilities = filesystem.
     if (capabilities.atomicFileStaging === true && (capabilities.readOnly === true
         || typeof filesystem.createStagedFile !== "function" || typeof filesystem.publishStagedFile !== "function" || typeof filesystem.removeStagedFile !== "function"))
         (unavailable ??= {}).atomicFileStaging = false;
+    if (capabilities.atomicStagedFileMutation === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
+        (unavailable ??= {}).atomicStagedFileMutation = false;
     if (capabilities.retainedStagingCleanup === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
         (unavailable ??= {}).retainedStagingCleanup = false;
     if (capabilities.retainedStagingWrite === true && (capabilities.retainedStagingCleanup !== true || unavailable?.retainedStagingCleanup === false))

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

@@ -20,7 +20,7 @@ const deviceCapabilities = Object.freeze({
     remove: false, removeDirectory: false, recursiveRemove: false, rename: false,
     mkdir: false, recursiveMkdir: false, symlinks: false, hardlinks: false, readlink: false,
     permissions: false, timestamps: false, truncate: false, randomAccessWrite: false,
-    open: true, retainedStagingCleanup: false, atomicFilePublication: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+    open: true, retainedStagingCleanup: false, atomicFilePublication: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicStagedFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
     atomicRename: false, atomicRenameNoReplace: false, descriptorWriteStream: true, retainedResize: true, atomicResize: false,
 });
 function globalCapabilities(filesystem) {
@@ -31,6 +31,7 @@ function globalCapabilities(filesystem) {
         synchronousDirectoryValidation: ["prepareDirectoryAncestry"], guardedStagingPublication: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
         synchronousStagingResolution: ["prepareStagingResolution"],
         trustedOwnedStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory"],
+        atomicStagedFileMutation: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
         atomicFilePublication: ["publishFileConditional"], atomicEntryRemoval: ["removeEntryConditional"], atomicEntryRemovalReceipt: ["removeEntryConditional"], atomicTreeRemoval: ["removeTreeConditional"], atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
         streamingRead: ["readStream"], streamingWrite: ["writeStream"], retainedRead: ["openReadFile"],
         streamingAppend: ["writeStream"], descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
@@ -667,6 +668,8 @@ export class DeviceFileSystem {
             await this.#mutable(path, options, false);
         await requireOwnedMutation(this.#filesystem, staging.directory.path, "atomicFileStaging", options);
         await requireOwnedMutation(this.#filesystem, destination, "atomicFileStaging", options, options.destination === null);
+        if (options.preserveIdentity)
+            await requireOwnedMutation(this.#filesystem, destination, "atomicStagedFileMutation", options);
         if (!this.#filesystem.publishStagedFile)
             throw new FsError("ENOTSUP", { path: destination });
         if (options.commitGuard !== undefined)

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

@@ -584,7 +584,7 @@ const SHARED_STOCK_MEMORY_CAPABILITIES = Object.freeze({
     permissions: true,
     timestamps: true,
     atomicRename: true,
-    atomicFileStaging: true, retainedStagingCleanup: true, retainedStagingWrite: true, atomicStagingAncestry: true, atomicFileMutation: true, atomicEntryRemoval: true, atomicEntryRemovalReceipt: true, atomicTreeRemoval: 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,
     atomicDirectoryMetadata: true,
     streamingRead: true,
@@ -2245,6 +2245,7 @@ export class MemoryFileSystem {
     }
     async publishStagedFile(receipt, destination, options) {
         const signal = options.signal;
+        const preserveIdentity = options.preserveIdentity === true;
         const guard = options.commitGuard;
         const ancestors = options.ancestors === undefined ? undefined : snapshotDirectoryAncestry(options.ancestors);
         const snapshot = (entry) => ({ path: entry.path, stat: { ...entry.stat } });
@@ -2272,9 +2273,48 @@ export class MemoryFileSystem {
             this.fail("EINVAL", "publishStagedFile", destination);
         if (target.node && target.node.type !== "file")
             this.fail("EAGAIN", "publishStagedFile", destination);
+        if (preserveIdentity) {
+            if (this.capabilities.atomicStagedFileMutation !== true)
+                this.fail("ENOTSUP", "publishStagedFile", destination);
+            if (file.node?.type !== "file" || target.node?.type !== "file" || expected === null)
+                this.fail("EINVAL", "publishStagedFile", destination);
+            this.permission(file.parent, 3, "publishStagedFile", staging.file.path);
+            this.permission(target.parent, 3, "publishStagedFile", destination);
+            this.permission(target.node, 2, "publishStagedFile", destination);
+            // Provider-owned storage is copied directly, without assembling an archive
+            // in caller memory. Preserve retained staging readers and independent writes.
+            this.admitSize(target.node, file.node.byteLength, "publishStagedFile", destination);
+            const allocation = this.allocate(file.node.byteLength, "publishStagedFile", destination);
+            try {
+                for (let offset = 0; offset < file.node.byteLength; offset += 65536) {
+                    allocation.data.set(file.node.data.subarray(offset, offset + 65536), offset);
+                }
+            }
+            catch (error) {
+                allocation.release();
+                throw error;
+            }
+            // No awaits or overridable operations occur between admission and commit.
+            const now = Date.now();
+            this.replaceData(target.node, allocation);
+            this.changed(target.node, now);
+            target.node.atimeMs = file.node.atimeMs;
+            target.node.mtimeMs = file.node.mtimeMs;
+            file.parent.entries.delete(file.name);
+            this.ledger.release(file.name.length * 2, 1);
+            file.node.nlink--;
+            file.node.ctimeMs = now;
+            file.node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, file.node.revision + 1);
+            this.releaseNode(file.node);
+            this.changed(file.parent, now);
+            memoryCaches.get(this.ledger).clearWrites();
+            return;
+        }
         return MemoryFileSystem.prototype.rename.call(this, staging.file.path, destination, { ...controls, noReplace: expected === null });
     }
     async publishStagedFileSet(receipt, destination, options) {
+        if (options.preserveIdentity)
+            this.fail("ENOTSUP", "publishStagedFileSet", destination);
         const signal = options.signal;
         const guard = options.commitGuard;
         const ancestors = options.ancestors === undefined ? undefined : snapshotDirectoryAncestry(options.ancestors);

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

@@ -109,6 +109,7 @@ export class MountFileSystem {
                 retainedStagingCleanup: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
                 synchronousDirectoryValidation: ["prepareDirectoryAncestry"], guardedStagingPublication: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
                 trustedOwnedStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory"],
+                atomicStagedFileMutation: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
                 atomicFilePublication: ["publishFileConditional"], atomicEntryRemoval: ["removeEntryConditional"], atomicEntryRemovalReceipt: ["removeEntryConditional"], atomicTreeRemoval: ["removeTreeConditional"], atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
                 symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"], timestamps: ["utimes"], readlink: ["readlink"],
                 descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
@@ -128,7 +129,7 @@ export class MountFileSystem {
             return values.every(value => value === true) ? true : values.every(value => value === false) ? false : undefined;
         };
         const semantics = Object.fromEntries([
-            "guardedStagingPublication", "retainedStagingCleanup", "atomicEntryRemovalReceipt",
+            "guardedStagingPublication", "retainedStagingCleanup", "atomicEntryRemovalReceipt", "atomicStagedFileMutation",
             "trustedOwnedStaging", "atomicFilePublication", "atomicEntryRemoval", "atomicTreeRemoval", "atomicFileMutation", "atomicFileStaging", "atomicDirectoryMetadata", "read", "stat", "readdir", "realpath", "access", "open", "versionedDescriptors",
             "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
             "remove", "removeDirectory", "recursiveRemove", "rename", "atomicRenameNoReplace", "copy", "exclusiveCopy", "readlink", "truncate",
@@ -1096,6 +1097,8 @@ export class MountFileSystem {
             await requireOwnedMutation(local.mount.backend, target.local, "atomicFileStaging", options, options.destination === null);
             if (!local.mount.backend.publishStagedFile)
                 fail("ENOTSUP");
+            if (options.preserveIdentity)
+                await requireOwnedMutation(local.mount.backend, target.local, "atomicStagedFileMutation", options);
             if (ancestors || callerGuard !== undefined)
                 await requireOwnedMutation(local.mount.backend, target.local, "guardedStagingPublication", options, options.destination === null);
             if (!ancestors) {

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

@@ -384,6 +384,8 @@ export class OverlayMemoryPublication {
         return staging;
     }
     async publish(staging, path, options) {
+        if (options.preserveIdentity)
+            throw new FsError("ENOTSUP", { path });
         options.signal?.throwIfAborted();
         this.path(path);
         const owned = this.stages.get(staging.directory);

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

@@ -413,6 +413,8 @@ export class RealFileSystem {
             throw new FsError("EAGAIN");
     }
     async publishStagedFile(staging, destination, options) {
+        if (options.preserveIdentity)
+            throw new FsError("ENOTSUP", { path: destination });
         return this.operation("publishStagedFile", staging.file.path, options, async () => {
             options.signal?.throwIfAborted();
             if (options.ancestors !== undefined || options.commitGuard !== undefined)

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

@@ -109,6 +109,7 @@ export declare class S3FileSystem implements FileSystem {
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     mkdir(input: string, options?: MkdirOptions): Promise<void>;
     readdir(input: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    iterateDirectory(input: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     private tree;
     rmdir(input: string, options?: FsOptions): Promise<void>;
     rm(input: string, options?: RemoveOptions): Promise<void>;

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

@@ -341,25 +341,33 @@ export class S3FileSystem {
         if (key.endsWith("/") && object.Size !== 0)
             fail("ENOTSUP", "listObjectsV2", path, "nonempty slash-suffixed objects cannot be treated as directories");
     }
-    async *pages(prefix, path, options, delimiter, maxKeys = this.pageSize) {
-        const tokens = new Set();
-        let token;
-        let entries = 0;
+    async *pages(prefix, path, options, delimiter, maxKeys = this.pageSize, rememberTokens = true) {
+        // Buffered callers preserve exact repeated-token rejection. Lazy traversal
+        // detects continuation cycles without retaining the whole token history.
+        const tokens = rememberTokens ? new Set() : undefined;
+        let token, checkpoint;
+        let entries = 0, pageCount = 0, span = 0, power = 1;
         do {
             const page = await this.page(prefix, path, options, delimiter, token, maxKeys);
             entries += (page.Contents?.length ?? 0) + (page.CommonPrefixes?.length ?? 0);
-            if (entries > this.maxListEntries || tokens.size >= this.maxListEntries)
+            if (entries > this.maxListEntries || ++pageCount > this.maxListEntries)
                 fail("EFBIG", "listObjectsV2", path, "listing exceeds maxListEntries");
+            const truncated = page.IsTruncated, next = page.NextContinuationToken;
             yield page;
-            if (!page.IsTruncated)
+            if (!truncated)
                 return;
-            token = page.NextContinuationToken;
-            if (typeof token !== "string" || !token || tokens.has(token))
+            if (typeof next !== "string" || !next || next === token || next === checkpoint || tokens?.has(next))
                 fail("EIO", "listObjectsV2", path, "missing or repeated continuation token");
-            tokens.add(token);
+            if (++span === power) {
+                checkpoint = next;
+                span = 0;
+                power = Math.min(Number.MAX_SAFE_INTEGER, power * 2);
+            }
+            tokens?.add(next);
+            token = next;
         } while (true);
     }
-    async inspect(path, options) {
+    async inspect(path, options, rememberTokens = true) {
         if (path === "/") {
             const listing = await this.page(this.prefix, path, options, undefined, undefined, 1);
             const marker = this.prefix && listing.Contents?.some(object => object.Key === this.prefix)
@@ -375,7 +383,7 @@ export class S3FileSystem {
         const directoryKey = this.directoryKey(path);
         let directory = false;
         let hasMarker = false;
-        for await (const children of this.pages(directoryKey, path, options, undefined, 1)) {
+        for await (const children of this.pages(directoryKey, path, options, undefined, 1, rememberTokens)) {
             if ((children.Contents?.length ?? 0) > 0) {
                 directory = true;
                 hasMarker = children.Contents.some(object => object.Key === directoryKey);
@@ -393,7 +401,7 @@ export class S3FileSystem {
             return { stat: this.makeStat("directory", marker), ...(marker ? { metadata: marker } : {}) };
         return undefined;
     }
-    async lookup(path, options) {
+    async lookup(path, options, rememberTokens = true) {
         const ancestors = [];
         for (let parent = posix.dirname(path); path !== "/"; parent = posix.dirname(parent)) {
             ancestors.unshift(parent);
@@ -403,13 +411,13 @@ export class S3FileSystem {
         for (const parent of ancestors) {
             if (parent === "/" && this.prefix === "")
                 continue;
-            const ancestor = await this.inspect(parent, options);
+            const ancestor = await this.inspect(parent, options, rememberTokens);
             if (!ancestor)
                 fail("ENOENT", "stat", parent);
             if (ancestor.stat.type !== "directory")
                 fail("ENOTDIR", "stat", parent);
         }
-        return this.inspect(path, options);
+        return this.inspect(path, options, rememberTokens);
     }
     requireDirectorySuffix(input, info) {
         if (input.endsWith("/") && info?.stat.type === "file")
@@ -596,6 +604,37 @@ export class S3FileSystem {
         }
         return [...entries.values()].sort((left, right) => compareKeys(left.name, right.name));
     }
+    async *iterateDirectory(input, options = {}) {
+        const path = this.path(input);
+        const directory = await this.lookup(path, options, false);
+        if (!directory)
+            fail("ENOENT", "iterateDirectory", path);
+        if (directory.stat.type !== "directory")
+            fail("ENOTDIR", "iterateDirectory", path);
+        const prefix = this.directoryKey(path);
+        for await (const page of this.pages(prefix, path, options, "/", this.pageSize, false)) {
+            // Snapshot one bounded service page before yielding to caller code.
+            if ((page.Contents?.length ?? 0) + (page.CommonPrefixes?.length ?? 0) > this.pageSize)
+                fail("EIO", "iterateDirectory", path, "transport exceeded requested page size");
+            const entries = [];
+            for (const item of page.Contents ?? [])
+                if (item.Key !== prefix)
+                    entries.push({ name: item.Key.slice(prefix.length), type: "file" });
+            for (const item of page.CommonPrefixes ?? [])
+                entries.push({ name: item.Prefix.slice(prefix.length, -1), type: "directory" });
+            for (const entry of entries) {
+                this.checkAbort(options, "iterateDirectory", path);
+                if (!entry.name || entry.name.includes("/"))
+                    fail("EIO", "iterateDirectory", path, "invalid direct child in delimited listing");
+                // Revalidation preserves file/prefix collision detection across pages
+                // and follows the backend's live namespace without retaining all names.
+                const child = await this.lookup(path === "/" ? `/${entry.name}` : `${path}/${entry.name}`, options, false);
+                this.checkAbort(options, "iterateDirectory", path);
+                if (child)
+                    yield { name: entry.name, type: child.stat.type };
+            }
+        }
+    }
     async tree(path, options) {
         const objects = new Map();
         for await (const page of this.pages(this.directoryKey(path), path, options)) {

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

@@ -343,6 +343,8 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             if (property === "publishStagedFile") {
                                 const publishOptions = (options ?? {});
                                 await requireOwnedMutation(original, args[1], "atomicFileStaging", publishOptions, publishOptions.destination === null);
+                                if (publishOptions.preserveIdentity)
+                                    await requireOwnedMutation(original, args[1], "atomicStagedFileMutation", publishOptions);
                                 const query = options.destination === null ? { ...options, create: true } : options;
                                 const declared = ownedMutationCapabilities(original, await original.capabilitiesFor?.(args[1], query) ?? original.capabilities);
                                 assertReady();
@@ -444,7 +446,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                     return executeDispatch(args);
                 if (operations.has(property)) {
                     const optionIndex = ["compareEntry", "createStagedFile", "utimes"].includes(String(property)) ? 3
-                        : ["writeFile", "appendFile", "writeStream", "rename", "copyFile", "link", "symlink", "access", "chmod", "truncate", "resizeFile", "publishFileConditional", "writeFileConditional", "publishStagedFile"].includes(String(property)) ? 2 : 1;
+                        : ["writeFile", "appendFile", "writeStream", "rename", "copyFile", "link", "symlink", "access", "chmod", "truncate", "resizeFile", "publishFileConditional", "writeFileConditional", "publishStagedFile", "publishStagedFileSet"].includes(String(property)) ? 2 : 1;
                     args[optionIndex] = scopeTransportOptions((args[optionIndex] ?? {}), admit, credit);
                 }
                 return runScopedTransportBudget(admit, () => executeDispatch(args), credit);

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

@@ -39,11 +39,19 @@ export declare class IntegerTable {
     private readonly storage;
     private readonly maxEntries;
     private root;
+    private revision;
+    private readonly branches;
     private readonly cache;
-    constructor(storage: PagedStorage, maxEntries?: number);
+    constructor(storage: Pick<PagedStorage, "allocate" | "read" | "write">, maxEntries?: number);
     private retain;
     get(key: bigint): Promise<bigint | undefined>;
     set(key: bigint, value: bigint): Promise<void>;
+    /** 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]>;
+    /** Hot radix paths must not evict dirty leaf pages in a one-page backend. */
+    private branch;
     private lookup;
     private persist;
 }

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

@@ -192,6 +192,8 @@ export class IntegerTable {
     storage;
     maxEntries;
     root = 0;
+    revision = 0;
+    branches = new Map();
     cache = new Map();
     constructor(storage, maxEntries = 4096) {
         this.storage = storage;
@@ -224,19 +226,92 @@ export class IntegerTable {
     async set(key, value) {
         if (key < 0n || key > 0xffffffffffffffffn || value < 0n || value >= 0xffffffffffffffffn)
             throw new RangeError("Invalid storage integer table value");
+        this.revision++;
         await this.retain(key, value, true);
     }
+    /** 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() {
+        const revision = this.revision;
+        const check = () => { if (revision !== this.revision)
+            throw new Error("Integer table changed during iteration"); };
+        for (const [key, entry] of this.cache)
+            if (entry.dirty) {
+                check();
+                await this.persist(key, entry.value);
+                check();
+                entry.dirty = false;
+            }
+        const storage = this.storage;
+        async function* visit(position, shift, prefix) {
+            check();
+            if (!position)
+                return;
+            const bytes = new Uint8Array(await storage.read(position, 128));
+            check();
+            if (bytes.length !== 128)
+                throw new RangeError("Truncated integer table node");
+            const node = new DataView(bytes.buffer);
+            for (let slot = 0; slot < 16; slot++) {
+                check();
+                const value = node.getBigUint64(slot * 8, true);
+                if (!value)
+                    continue;
+                const key = prefix | BigInt(slot) << shift;
+                if (shift === 0n)
+                    yield [key, value - 1n];
+                else
+                    yield* visit(Number(value), shift - 4n, key);
+            }
+        }
+        const batch = [];
+        for await (const entry of visit(this.root, 60n, 0n)) {
+            batch.push(entry);
+            if (batch.length === 128) {
+                for (const entry of batch) {
+                    check();
+                    yield entry;
+                }
+                batch.length = 0;
+            }
+        }
+        for (const entry of batch) {
+            check();
+            yield entry;
+        }
+        check();
+    }
+    /** Hot radix paths must not evict dirty leaf pages in a one-page backend. */
+    branch(key, shift, position) {
+        const prefix = key >> shift | 1n << (64n - shift);
+        const value = position ?? this.branches.get(prefix);
+        if (value !== undefined) {
+            this.branches.delete(prefix);
+            this.branches.set(prefix, value);
+            if (this.branches.size > 128)
+                this.branches.delete(this.branches.keys().next().value);
+        }
+        return value;
+    }
     async lookup(key) {
         let node = this.root;
         for (let shift = 60n; shift >= 0n; shift -= 4n) {
             if (!node)
                 return undefined;
+            const cached = shift === 0n ? undefined : this.branch(key, shift);
+            if (cached !== undefined) {
+                node = cached;
+                continue;
+            }
             const slot = node + Number((key >> shift) & 15n) * 8;
             const bytes = await this.storage.read(slot, 8);
             const value = new DataView(bytes.buffer, bytes.byteOffset, 8).getBigUint64(0, true);
             if (shift === 0n)
                 return value === 0n ? undefined : value - 1n;
             node = Number(value);
+            if (node)
+                this.branch(key, shift, node);
         }
         return undefined;
     }
@@ -245,6 +320,11 @@ export class IntegerTable {
             this.root = this.storage.allocate(128);
         let node = this.root;
         for (let shift = 60n; shift >= 0n; shift -= 4n) {
+            const cached = shift === 0n ? undefined : this.branch(key, shift);
+            if (cached !== undefined) {
+                node = cached;
+                continue;
+            }
             const slot = node + Number((key >> shift) & 15n) * 8;
             const bytes = await this.storage.read(slot, 8);
             const view = new DataView(bytes.buffer, bytes.byteOffset, 8);
@@ -260,6 +340,7 @@ export class IntegerTable {
                 await this.storage.write(slot, bytes);
             }
             node = child;
+            this.branch(key, shift, child);
         }
     }
 }

package/node_modules/tiny-stdio-mcp-server/dist/composition.json

@@ -8,7 +8,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.767",
+      "version": "0.0.769",
       "license": "MIT"
     }
   ]

package/node_modules/toolcraft-schema/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-schema",
-  "version": "0.0.767",
+  "version": "0.0.769",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.767",
+  "version": "0.0.769",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -175,7 +175,7 @@
     "@poe-code/terminal-text"
   ],
   "optionalDependencies": {
-    "toolcraft-schema": "0.0.767",
+    "toolcraft-schema": "0.0.769",
     "toolcraft-design": "*",
     "@poe-code/frontmatter": "*",
     "@poe-code/agent-mcp-config": "*",