toolcraft 0.0.761 → 0.0.763

package/composition.json

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

package/dist/composition.json

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

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

@@ -4,6 +4,13 @@ An asynchronous filesystem interface for memory, rooted host directories, S3, an
 
 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.
 
+The `storage` subpath exposes `PagedStorage` and `IntegerTable` for temporary
+working data. Supply `{fs, cwd, env, signal}` and an optional page-cache count
+(default 64 pages of 16 KiB). Scratch data uses retained positioned handles in
+`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.
+
 ## 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.
@@ -79,6 +86,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 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 |

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

@@ -352,6 +352,11 @@ export interface FileSystem {
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
     compareEntry?(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    /** Optional bounded, lazy directory enumeration in backend-defined order.
+     * No complete listing/sort fallback. Consumers must retire the iterator on
+     * early exit. Namespace changes may reject or follow the backend's live view;
+     * this is not a tree snapshot or a retained path-authority grant. */
+    iterateDirectory?(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
     /** Atomic final-entry removal; every directory is refused, including raced replacements. */

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

@@ -18,3 +18,4 @@ export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
 export { readFileStream } from "./fs/read-file-stream.js";
+export { PagedStorage, IntegerTable, type PagedStorageContext } from "./storage.js";

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

@@ -16,3 +16,4 @@ export * from "./fs/s3/http/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
 export { readFileStream } from "./fs/read-file-stream.js";
+export { PagedStorage, IntegerTable } from "./storage.js";

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

@@ -25,6 +25,7 @@ export declare class DeviceFileSystem implements FileSystem {
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;

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

@@ -490,6 +490,40 @@ export class DeviceFileSystem {
             throw new FsError("ENOTSUP", { path });
         await this.#filesystem.writeStream(path, source, options);
     }
+    async *iterateDirectory(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath)
+            throw new FsError("ENOTDIR", { syscall: "iterateDirectory", path });
+        const virtual = resolved === "/" ? "dev" : resolved === deviceDirectory ? "null" : undefined;
+        if (!this.#filesystem.iterateDirectory)
+            throw new FsError("ENOTSUP", { syscall: "iterateDirectory", path });
+        let seen = false;
+        try {
+            for await (const entry of this.#filesystem.iterateDirectory(virtual ? resolved : path, options)) {
+                options.signal?.throwIfAborted();
+                if (entry.name === "." || entry.name === "..")
+                    continue;
+                if (!entry.name || entry.name.includes("/") || entry.name.includes("\0"))
+                    throw new FsError("EIO", { path, message: "invalid directory entry" });
+                if (entry.name === virtual) {
+                    if (seen)
+                        continue;
+                    seen = true;
+                    yield { name: virtual, type: virtual === "dev" ? "directory" : "character" };
+                }
+                else
+                    yield { name: entry.name, type: entry.type };
+            }
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            if (!virtual || !isFsError(error, "ENOENT") && !isFsError(error, "ENOTDIR"))
+                throw error;
+        }
+        options.signal?.throwIfAborted();
+        if (virtual && !seen)
+            yield { name: virtual, type: virtual === "dev" ? "directory" : "character" };
+    }
     readdir(path, options = {}) {
         const fast = this.#tryResolveSync(path, options);
         if (fast !== undefined && fast !== "/") {

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

@@ -134,6 +134,7 @@ export declare class MemoryFileSystem implements FileSystem {
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     tryMkdirFastSync(path: string, recursive: boolean, mode: number | undefined): boolean;
     tryRmFastSync(path: string, recursive: boolean, force: boolean): boolean;

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

@@ -2508,6 +2508,26 @@ export class MemoryFileSystem {
         ownedStats.set(stat, { filesystem: this, path, root: this.root });
         return stat;
     }
+    async *iterateDirectory(path, options = {}) {
+        options.signal?.throwIfAborted();
+        const root = this.root, node = this.resolveNode(path, "iterateDirectory", true);
+        if (node.type !== "directory")
+            this.fail("ENOTDIR", "iterateDirectory", path);
+        this.permission(node, 4, "iterateDirectory", path);
+        const revision = node.revision, ino = node.ino;
+        const check = () => {
+            options.signal?.throwIfAborted();
+            if (this.root !== root || node.ino !== ino || node.revision !== revision || this.resolveNode(path, "iterateDirectory", true) !== node)
+                this.fail("EBUSY", "iterateDirectory", path);
+            this.permission(node, 4, "iterateDirectory", path);
+        };
+        node.atimeMs = Date.now();
+        for (const [name, entry] of node.entries) {
+            check();
+            yield { name, type: entry.type };
+        }
+        check();
+    }
     async readdir(path, options = {}) {
         const limit = directoryEntryLimit(options, path);
         const node = this.resolveNode(path, "readdir", true);

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

@@ -13,6 +13,7 @@ export declare class ReadOnlyFileSystem implements FileSystem {
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
     compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").EntryComparison>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     realpath(path: string, options?: FsOptions): Promise<string>;
     access(path: string, mode?: number, options?: FsOptions): Promise<void>;

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

@@ -122,6 +122,16 @@ export class ReadOnlyFileSystem {
     compareEntry(path, peer, peerPath, options = {}) {
         return compareEntries(this, path, peer, peerPath, options);
     }
+    async *iterateDirectory(path, options = {}) {
+        options.signal?.throwIfAborted();
+        if (!this.#filesystem.iterateDirectory)
+            throw new FsError("ENOTSUP", { syscall: "iterateDirectory", path });
+        for await (const entry of this.#filesystem.iterateDirectory(path, options)) {
+            options.signal?.throwIfAborted();
+            yield { name: entry.name, type: entry.type };
+        }
+        options.signal?.throwIfAborted();
+    }
     async readdir(path, options) {
         const limit = options?.maxEntries === undefined ? undefined : directoryEntryLimit(options, path);
         const entries = await this.#filesystem.readdir(path, options);

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

@@ -81,6 +81,7 @@ export declare class RealFileSystem implements FileSystem {
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rmdir(path: string, options?: FsOptions): Promise<void>;

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

@@ -638,6 +638,33 @@ export class RealFileSystem {
             return fileStat(await native.lstat(target, { bigint: true }));
         });
     }
+    async *iterateDirectory(path, options = {}) {
+        let handle, failed = false;
+        try {
+            // Preserve the acquired handle even if cancellation arrives during open:
+            // the following read admission will observe it and finally will close it.
+            handle = await this.operation("iterateDirectory", path, options, async () => {
+                const target = await this.path(path, options);
+                options.signal?.throwIfAborted();
+                return native.opendir(target, { bufferSize: 1 });
+            }, undefined, true);
+            while (true) {
+                const entry = await this.operation("iterateDirectory", path, options, () => handle.read());
+                if (entry === null)
+                    break;
+                yield { name: entry.name, type: fileType(entry) };
+            }
+        }
+        catch (error) {
+            failed = true;
+            options.signal?.throwIfAborted();
+            throw error;
+        }
+        finally {
+            if (handle)
+                await finishCleanup(() => handle.close(), failed);
+        }
+    }
     async readdir(path, options = {}) {
         const limit = directoryEntryLimit(options, path);
         return this.operation("readdir", path, options, async () => {

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

@@ -21,7 +21,7 @@ const operations = new Set([
     "prepareDirectoryAncestry", "prepareStagingResolution", "publishStagedFileSet",
     "publishFileConditional", "removeEntryConditional", "removeTreeConditional", "writeFileConditional", "removeFileConditional", "createStagedFile", "publishStagedFile", "removeStagedFile", "prepareDirectory",
     "confineExtraction", "access", "appendFile", "canonicalizeMissingTarget", "capabilitiesFor", "chmod", "compareEntry",
-    "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir",
+    "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir", "iterateDirectory",
     "readlink", "realpath", "rename", "resizeFile", "rm", "rmdir", "unlink", "stat", "symlink", "truncate", "utimes",
     "writeFile", "writeStream",
 ]);
@@ -188,7 +188,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
             close: (options = {}) => closing ??= Promise.resolve().then(() => descriptor.close(options)),
         };
     };
-    const wrapStream = (source, options) => {
+    const wrapStream = (source, options, chargeNext = false) => {
         const budgetFrames = getScopedTransportBudget();
         return {
             [Symbol.asyncIterator]() {
@@ -203,6 +203,8 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             await closing;
                             return { done: true, value: undefined };
                         }
+                        if (chargeNext)
+                            admit(options);
                         const result = await withScopedTransportBudget(budgetFrames, operation);
                         assertOpen(options);
                         if (closing) {
@@ -430,7 +432,11 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             });
                         return Reflect.apply(method, original, args);
                     })();
+                if (property === "iterateDirectory")
+                    args[1] = { ...args[1], signal: combineSignal(args[1]?.signal) };
                 const result = Reflect.apply(method, original, args);
+                if (property === "iterateDirectory")
+                    return wrapStream(result, args[1], true);
                 return property === "readStream" ? wrapStream(result, args[1]) : result;
             };
             const dispatch = (...args) => {
@@ -528,7 +534,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                                     ? async (...args) => ownedMutationCapabilities(original, retainedResizeCapabilities(original, await dispatch(...args)))
                                     : property === "openReadFile"
                                         ? async (...args) => wrapHandle(await dispatch(...args))
-                                        : operations.has(property) && property !== "canonicalizeMissingTarget" && property !== "readStream"
+                                        : operations.has(property) && property !== "canonicalizeMissingTarget" && property !== "readStream" && property !== "iterateDirectory"
                                             ? (...args) => {
                                                 try {
                                                     const res = dispatch(...args);

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

@@ -0,0 +1,49 @@
+import type { FileSystem } from "./contracts/filesystem.js";
+export interface PagedStorageContext {
+    readonly fs: FileSystem;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly signal: AbortSignal;
+}
+/** A bounded page cache backed only by the caller filesystem. The default is
+ * one MiB; callers own close() on every outcome. Memory filesystems still retain
+ * spilled data in RAM, so large workloads require an external backing provider. */
+export declare class PagedStorage {
+    private readonly context;
+    private readonly maxPages;
+    private readonly pages;
+    private readonly controller;
+    private readonly signal;
+    private descriptor;
+    private parent;
+    private initial;
+    private path;
+    private diskLength;
+    private unlinked;
+    private end;
+    private active;
+    private closing;
+    constructor(context: PagedStorageContext, maxPages?: number);
+    allocate(length: number): number;
+    private operation;
+    private spill;
+    private flush;
+    private page;
+    write(position: number, bytes: Uint8Array): Promise<void>;
+    append(bytes: Uint8Array): Promise<number>;
+    read(position: number, length: number): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+/** Fixed-depth radix index: both dense and sparse 64-bit keys use bounded RAM. */
+export declare class IntegerTable {
+    private readonly storage;
+    private readonly maxEntries;
+    private root;
+    private readonly cache;
+    constructor(storage: PagedStorage, maxEntries?: number);
+    private retain;
+    get(key: bigint): Promise<bigint | undefined>;
+    set(key: bigint, value: bigint): Promise<void>;
+    private lookup;
+    private persist;
+}

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

@@ -0,0 +1,265 @@
+import { FsError, isFsError } from "./contracts/errors.js";
+const pageBytes = 16 * 1024;
+let serial = 0;
+/** A bounded page cache backed only by the caller filesystem. The default is
+ * one MiB; callers own close() on every outcome. Memory filesystems still retain
+ * spilled data in RAM, so large workloads require an external backing provider. */
+export class PagedStorage {
+    context;
+    maxPages;
+    pages = new Map();
+    controller = new AbortController();
+    signal;
+    descriptor;
+    parent;
+    initial;
+    path;
+    diskLength = 0;
+    unlinked = false;
+    end = 8; // Zero is the absent-pointer sentinel.
+    active = Promise.resolve();
+    closing;
+    constructor(context, maxPages = 64) {
+        this.context = context;
+        this.maxPages = maxPages;
+        if (!Number.isSafeInteger(maxPages) || maxPages < 1)
+            throw new RangeError("Invalid storage page cache size");
+        this.signal = AbortSignal.any([context.signal, this.controller.signal]);
+    }
+    allocate(length) {
+        this.signal.throwIfAborted();
+        if (!Number.isSafeInteger(length) || length < 0 || length > Number.MAX_SAFE_INTEGER - this.end)
+            throw new FsError("EFBIG");
+        const offset = this.end;
+        this.end += length;
+        return offset;
+    }
+    operation(action) {
+        this.signal.throwIfAborted();
+        const work = this.active.then(() => {
+            this.signal.throwIfAborted();
+            return action();
+        });
+        this.active = work.then(() => undefined, () => undefined);
+        return work;
+    }
+    async spill() {
+        const { fs, cwd, env } = this.context;
+        if (!fs.open || !fs.removeFileConditional)
+            throw new FsError("ENOTSUP", { message: "spill storage requires retained read/write handles and conditional removal" });
+        const selected = env.TMPDIR || cwd;
+        const directory = selected.startsWith("/") ? selected : `${cwd}/${selected}`;
+        this.parent = await fs.stat(directory, { signal: this.signal });
+        this.signal.throwIfAborted();
+        if (this.parent.type !== "directory")
+            throw new FsError("ENOTDIR", { path: directory });
+        for (let attempt = 0; attempt < 128; attempt++) {
+            const path = `${directory.endsWith("/") ? directory : directory + "/"}.storage-${++serial}`;
+            try {
+                this.descriptor = await fs.open(path, { access: "readwrite", creation: "exclusive", mode: 0o600, signal: this.signal });
+                this.path = path;
+                break;
+            }
+            catch (error) {
+                this.signal.throwIfAborted();
+                if (!isFsError(error) || error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        if (!this.descriptor)
+            throw new FsError("EEXIST", { path: directory });
+        // Retain the acquisition receipt even if cancellation wins immediately after open.
+        this.initial = await this.descriptor.stat();
+        this.signal.throwIfAborted();
+        if (!this.descriptor.capabilities.positionedRead || !this.descriptor.capabilities.positionedWrite)
+            throw new FsError("ENOTSUP");
+        // Detach the name before storing input. A later output or random-source path
+        // cannot alias our scratch file; the retained descriptor owns its lifetime.
+        await fs.removeFileConditional(this.path, { parent: this.parent, expected: this.initial, signal: this.signal });
+        this.unlinked = true;
+        for (const [number, page] of this.pages)
+            await this.flush(number, page);
+    }
+    async flush(number, page) {
+        if (!page.dirty)
+            return;
+        let offset = 0;
+        while (offset < pageBytes) {
+            this.signal.throwIfAborted();
+            const count = await this.descriptor.write(page.bytes.subarray(offset), number * pageBytes + offset, { signal: this.signal });
+            this.signal.throwIfAborted();
+            if (!Number.isSafeInteger(count) || count <= 0 || count > pageBytes - offset)
+                throw new FsError("EIO");
+            offset += count;
+        }
+        this.diskLength = Math.max(this.diskLength, (number + 1) * pageBytes);
+        page.dirty = false;
+    }
+    async page(number) {
+        this.signal.throwIfAborted();
+        const cached = this.pages.get(number);
+        if (cached) {
+            this.pages.delete(number);
+            this.pages.set(number, cached);
+            return cached;
+        }
+        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);
+        }
+        const page = { bytes: new Uint8Array(pageBytes), dirty: false };
+        if (number * pageBytes < this.diskLength) {
+            let offset = 0;
+            while (offset < pageBytes) {
+                const count = await this.descriptor.read(page.bytes.subarray(offset), number * pageBytes + offset, { signal: this.signal });
+                this.signal.throwIfAborted();
+                if (!Number.isSafeInteger(count) || count <= 0 || count > pageBytes - offset)
+                    throw new FsError("EIO");
+                offset += count;
+            }
+        }
+        this.pages.set(number, page);
+        return page;
+    }
+    write(position, bytes) {
+        if (!Number.isSafeInteger(position) || position < 8 || position + bytes.length > this.end)
+            throw new RangeError("Invalid paged storage range");
+        return this.operation(async () => {
+            for (let offset = 0; offset < bytes.length;) {
+                const target = position + offset;
+                const page = await this.page(Math.floor(target / pageBytes));
+                const count = Math.min(bytes.length - offset, pageBytes - target % pageBytes);
+                page.bytes.set(bytes.subarray(offset, offset + count), target % pageBytes);
+                page.dirty = true;
+                offset += count;
+            }
+        });
+    }
+    async append(bytes) {
+        const position = this.allocate(bytes.length);
+        await this.write(position, bytes);
+        return position;
+    }
+    read(position, length) {
+        if (!Number.isSafeInteger(position) || position < 8 || !Number.isSafeInteger(length) || length < 0 || length > pageBytes || position + length > this.end)
+            throw new RangeError("Invalid paged storage range");
+        return this.operation(async () => {
+            const bytes = new Uint8Array(length);
+            for (let offset = 0; offset < length;) {
+                const source = position + offset;
+                const page = await this.page(Math.floor(source / pageBytes));
+                const count = Math.min(length - offset, pageBytes - source % pageBytes);
+                bytes.set(page.bytes.subarray(source % pageBytes, source % pageBytes + count), offset);
+                offset += count;
+            }
+            return bytes;
+        });
+    }
+    close() {
+        this.controller.abort(new FsError("ECANCELED"));
+        return this.closing ??= (async () => {
+            await this.active.catch(() => { });
+            this.pages.clear();
+            const descriptor = this.descriptor;
+            if (!descriptor)
+                return;
+            const cancellation = new FsError("ECANCELED");
+            try {
+                if (!this.unlinked) {
+                    const expected = this.initial ?? await descriptor.stat();
+                    await this.context.fs.removeFileConditional(this.path, { parent: this.parent, expected }).catch(error => {
+                        if (!isFsError(error) || error.code !== "ENOENT")
+                            throw error;
+                    });
+                }
+            }
+            finally {
+                // Conditional descriptors must discard their private staged writes, not
+                // publish the scratch data when the command retires its handle.
+                await descriptor.close({ signal: AbortSignal.abort(cancellation) }).catch(error => {
+                    if (error !== cancellation)
+                        throw error;
+                });
+            }
+        })();
+    }
+}
+/** Fixed-depth radix index: both dense and sparse 64-bit keys use bounded RAM. */
+export class IntegerTable {
+    storage;
+    maxEntries;
+    root = 0;
+    cache = new Map();
+    constructor(storage, maxEntries = 4096) {
+        this.storage = storage;
+        this.maxEntries = maxEntries;
+        if (!Number.isSafeInteger(maxEntries) || maxEntries < 1)
+            throw new RangeError("Invalid integer table cache size");
+    }
+    async retain(key, value, dirty) {
+        if (this.cache.size === this.maxEntries && !this.cache.has(key)) {
+            const [oldKey, old] = this.cache.entries().next().value;
+            if (old.dirty)
+                await this.persist(oldKey, old.value);
+            this.cache.delete(oldKey);
+        }
+        this.cache.delete(key);
+        this.cache.set(key, { value, dirty });
+    }
+    async get(key) {
+        const cached = this.cache.get(key);
+        if (cached) {
+            this.cache.delete(key);
+            this.cache.set(key, cached);
+            return cached.value;
+        }
+        const value = await this.lookup(key);
+        if (value !== undefined)
+            await this.retain(key, value, false);
+        return value;
+    }
+    async set(key, value) {
+        if (key < 0n || key > 0xffffffffffffffffn || value < 0n || value >= 0xffffffffffffffffn)
+            throw new RangeError("Invalid storage integer table value");
+        await this.retain(key, value, true);
+    }
+    async lookup(key) {
+        let node = this.root;
+        for (let shift = 60n; shift >= 0n; shift -= 4n) {
+            if (!node)
+                return undefined;
+            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);
+        }
+        return undefined;
+    }
+    async persist(key, value) {
+        if (!this.root)
+            this.root = this.storage.allocate(128);
+        let node = this.root;
+        for (let shift = 60n; shift >= 0n; shift -= 4n) {
+            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);
+            if (shift === 0n) {
+                view.setBigUint64(0, value + 1n, true);
+                await this.storage.write(slot, bytes);
+                return;
+            }
+            let child = Number(view.getBigUint64(0, true));
+            if (!child) {
+                child = this.storage.allocate(128);
+                view.setBigUint64(0, BigInt(child), true);
+                await this.storage.write(slot, bytes);
+            }
+            node = child;
+        }
+    }
+}

package/node_modules/@poe-code/safe-fs/package.json

@@ -161,6 +161,13 @@
     "./bridge": {
       "types": "./dist/bridge/index.d.ts",
       "import": "./dist/bridge/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "workerd": "./dist/storage.js",
+      "browser": "./dist/storage.js",
+      "worker": "./dist/storage.js",
+      "import": "./dist/storage.js"
     }
   },
   "files": [

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

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

package/node_modules/toolcraft-schema/package.json

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

package/package.json

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