toolcraft 0.0.787 → 0.0.789

package/composition.json

@@ -138,7 +138,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.787",
+      "version": "0.0.789",
       "license": "MIT"
     },
     {
@@ -148,7 +148,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.787",
+      "version": "0.0.789",
       "license": "MIT"
     },
     {

package/dist/composition.json

@@ -138,7 +138,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.787",
+      "version": "0.0.789",
       "license": "MIT"
     },
     {
@@ -148,7 +148,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.787",
+      "version": "0.0.789",
       "license": "MIT"
     },
     {

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

@@ -10,6 +10,11 @@ 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.
+To bound aggregate pages across multiple live stores, pass the same
+`new PagedStorageCache(16)` as the third argument to each `PagedStorage` constructor.
+This shares a 256 KiB resident-page budget; `cache.residentBytes` reports current
+page retention. Eviction uses each store's filesystem, and each store still owns
+its `close()` cleanup. The budget excludes caller buffers and backend storage.
 `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

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, parseXmlStream, XmlLimitError } from "./xml.js";
+export { parseXml, parseXmlSteps, parseXmlSourceSteps, normalizeXmlChunks, 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";
@@ -18,4 +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";
+export { PagedStorage, PagedStorageCache, IntegerTable, type PagedStorageContext } from "./storage.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, parseXmlStream, XmlLimitError } from "./xml.js";
+export { parseXml, parseXmlSteps, parseXmlSourceSteps, normalizeXmlChunks, parseXmlStream, XmlLimitError } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
 export * from "./fs/s3/index.js";
@@ -16,4 +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";
+export { PagedStorage, PagedStorageCache, IntegerTable } from "./storage.js";

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

@@ -5,12 +5,31 @@ export interface PagedStorageContext {
     readonly env: Readonly<Record<string, string | undefined>>;
     readonly signal: AbortSignal;
 }
+type Page = {
+    bytes: Uint8Array;
+    dirty: boolean;
+};
+/** Shares one resident-page limit across stores, retaining each store's caller
+ * filesystem and cleanup ownership. Serializes cache users through eviction IO. */
+export declare class PagedStorageCache {
+    private readonly maxPages;
+    private readonly pages;
+    private active;
+    constructor(maxPages: number);
+    get residentBytes(): number;
+    run<T>(action: () => Promise<T>): Promise<T>;
+    acquire(): Promise<Page>;
+    retain(page: Page, release: () => Promise<void>): void;
+    touch(page: Page): void;
+    forget(page: Page): void;
+}
 /** 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 cache?;
     private readonly pages;
     private readonly controller;
     private readonly signal;
@@ -23,7 +42,7 @@ export declare class PagedStorage {
     private end;
     private active;
     private closing;
-    constructor(context: PagedStorageContext, maxPages?: number);
+    constructor(context: PagedStorageContext, maxPages?: number, cache?: PagedStorageCache | undefined);
     allocate(length: number): number;
     private operation;
     private spill;
@@ -55,3 +74,4 @@ export declare class IntegerTable {
     private lookup;
     private persist;
 }
+export {};

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

@@ -1,12 +1,50 @@
 import { FsError, isFsError } from "./contracts/errors.js";
 const pageBytes = 16 * 1024;
 let serial = 0;
+/** Shares one resident-page limit across stores, retaining each store's caller
+ * filesystem and cleanup ownership. Serializes cache users through eviction IO. */
+export class PagedStorageCache {
+    maxPages;
+    pages = new Map();
+    active = Promise.resolve();
+    constructor(maxPages) {
+        this.maxPages = maxPages;
+        if (!Number.isSafeInteger(maxPages) || maxPages < 1)
+            throw new RangeError("Invalid storage page cache size");
+    }
+    get residentBytes() { return this.pages.size * pageBytes; }
+    run(action) {
+        const work = this.active.then(action);
+        this.active = work.then(() => undefined, () => undefined);
+        return work;
+    }
+    async acquire() {
+        if (this.pages.size < this.maxPages)
+            return { bytes: new Uint8Array(pageBytes), dirty: false };
+        const [page, release] = this.pages.entries().next().value;
+        await release();
+        this.pages.delete(page);
+        page.bytes.fill(0);
+        return page;
+    }
+    retain(page, release) {
+        this.pages.delete(page);
+        this.pages.set(page, release);
+    }
+    touch(page) {
+        const release = this.pages.get(page);
+        this.pages.delete(page);
+        this.pages.set(page, release);
+    }
+    forget(page) { this.pages.delete(page); }
+}
 /** 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;
+    cache;
     pages = new Map();
     controller = new AbortController();
     signal;
@@ -19,9 +57,10 @@ export class PagedStorage {
     end = 8; // Zero is the absent-pointer sentinel.
     active = Promise.resolve();
     closing;
-    constructor(context, maxPages = 64) {
+    constructor(context, maxPages = 64, cache) {
         this.context = context;
         this.maxPages = maxPages;
+        this.cache = cache;
         if (!Number.isSafeInteger(maxPages) || maxPages < 1)
             throw new RangeError("Invalid storage page cache size");
         this.signal = AbortSignal.any([context.signal, this.controller.signal]);
@@ -36,10 +75,11 @@ export class PagedStorage {
     }
     operation(action) {
         this.signal.throwIfAborted();
-        const work = this.active.then(() => {
+        const execute = () => {
             this.signal.throwIfAborted();
             return action();
-        });
+        };
+        const work = this.active.then(() => this.cache ? this.cache.run(execute) : execute());
         this.active = work.then(() => undefined, () => undefined);
         return work;
     }
@@ -101,6 +141,7 @@ export class PagedStorage {
         if (cached) {
             this.pages.delete(number);
             this.pages.set(number, cached);
+            this.cache?.touch(cached);
             return cached;
         }
         let reusable;
@@ -110,11 +151,14 @@ export class PagedStorage {
             const [oldNumber, oldPage] = this.pages.entries().next().value;
             await this.flush(oldNumber, oldPage);
             this.pages.delete(oldNumber);
+            this.cache?.forget(oldPage);
             reusable = oldPage;
         }
         // 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 };
+        const page = reusable ?? (this.cache ? await this.cache.acquire() : { bytes: new Uint8Array(pageBytes), dirty: false });
+        // Shared eviction may await IO owned by a different, still-live signal.
+        this.signal.throwIfAborted();
         if (reusable)
             page.bytes.fill(0);
         if (number * pageBytes < this.diskLength) {
@@ -128,6 +172,12 @@ export class PagedStorage {
             }
         }
         this.pages.set(number, page);
+        this.cache?.retain(page, async () => {
+            if (!this.descriptor)
+                await this.spill();
+            await this.flush(number, page);
+            this.pages.delete(number);
+        });
         return page;
     }
     write(position, bytes) {
@@ -168,28 +218,33 @@ export class PagedStorage {
         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")
+            const retire = async () => {
+                for (const page of this.pages.values())
+                    this.cache?.forget(page);
+                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;
                     });
                 }
-            }
-            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;
-                });
-            }
+            };
+            await (this.cache ? this.cache.run(retire) : retire());
         })();
     }
 }

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

@@ -26,9 +26,12 @@ Pass positive integer limits for depth, element and content counts, attributes,
 `parseXmlSteps` yields work counts so a host can account for parsing and yield between checkpoints. Syntax errors and resource limits remain errors by default; parsing never fetches external entities.
 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.
+Resource limits and the prohibition on DTDs remain in force. With `retainTree: false`,
+`parseXmlSteps` discards completed nodes and can emit synchronous `events`, including
+repaired closing events. Drain events between generator checkpoints to await
+external storage; the source string and open parser frames remain resident.
 
-`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.
+`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 is available through `parseXmlSteps` or the externally backed source API.
 
 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.
 
@@ -42,3 +45,12 @@ window awaits the consumer before advancing. Event elements contain names,
 attributes and namespace metadata; individual XML tokens and open ancestry still
 remain resident. This mode lets a caller own document storage independently of
 the codec. Consumer failures propagate unchanged and close the input iterator.
+
+`normalizeXmlChunks(chunks)` validates XML characters and normalizes BOM/line endings
+in windows of at most 513 UTF-16 units, preserving surrogate pairs across chunks.
+Store those windows in caller-owned backing and drive `parseXmlSourceSteps(length,
+limits)`: numbers are work checkpoints; read requests specify UTF-16 `offset` and
+`length` (at most 4096 units). Fill each request's `value` before advancing the
+iterator. The source must already be validated and normalized. This supports the
+same repairs and events without a complete source string; tokens and open ancestry
+still remain resident. Close the iterator and backing on errors or cancellation.

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

@@ -0,0 +1,3 @@
+export declare function validCharacter(point: number): boolean;
+/** Validate scalar values and normalize XML line endings in fixed windows. */
+export declare function normalizeXmlChunks(source: AsyncIterable<string> | Iterable<string>): AsyncGenerator<string>;

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

@@ -0,0 +1,49 @@
+export function validCharacter(point) {
+    return point === 9 || point === 10 || point === 13
+        || (point >= 0x20 && point <= 0xd7ff)
+        || (point >= 0xe000 && point <= 0xfffd)
+        || (point >= 0x10000 && point <= 0x10ffff);
+}
+/** Validate scalar values and normalize XML line endings in fixed windows. */
+export async function* normalizeXmlChunks(source) {
+    let first = true, afterCR = false, high = 0, output = '';
+    for await (const chunk of source) {
+        for (let index = 0; index < chunk.length; index++) {
+            const code = chunk.charCodeAt(index);
+            if (first) {
+                first = false;
+                if (code === 0xfeff)
+                    continue;
+            }
+            if (high) {
+                if (code < 0xdc00 || code > 0xdfff)
+                    throw new SyntaxError('Invalid XML: invalid character');
+                output += String.fromCharCode(high, code);
+                high = 0;
+            }
+            else {
+                if (afterCR) {
+                    afterCR = false;
+                    if (code === 10)
+                        continue;
+                }
+                if (code >= 0xd800 && code <= 0xdbff) {
+                    high = code;
+                    continue;
+                }
+                if (!validCharacter(code))
+                    throw new SyntaxError('Invalid XML: invalid character');
+                afterCR = code === 13;
+                output += code === 13 ? '\n' : chunk[index];
+            }
+            if (output.length >= 512) {
+                yield output;
+                output = '';
+            }
+        }
+    }
+    if (high)
+        throw new SyntaxError('Invalid XML: invalid character');
+    if (output)
+        yield output;
+}

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

@@ -1,3 +1,7 @@
+export { normalizeXmlChunks } from "./characters.js";
+import { type XmlSourceStep } from "./source.js";
+export type { XmlSourceRead, XmlSourceStep } from "./source.js";
+import type { XmlStreamEvent } from "./stream.js";
 export { XmlLimitError } from "./errors.js";
 export interface XmlName {
     readonly name: string;
@@ -40,6 +44,15 @@ export interface XmlLimits {
     readonly maxTextLength?: number;
     readonly onElement?: (element: XmlName, parent: XmlName | undefined, depth: number) => void;
 }
-export declare function parseXmlSteps(input: string, limits?: XmlLimits): Generator<number, XmlElement, void>;
+export interface XmlStepLimits extends XmlLimits {
+    /** Return root metadata without retaining descendants or text. */
+    readonly retainTree?: boolean;
+    /** Synchronous ordered events, including repaired closes. Requires retainTree:
+     * false. Drive the step iterator to await external consumers between windows. */
+    readonly events?: (event: XmlStreamEvent) => void;
+}
+/** Parse a validated, BOM-free, line-normalized UTF-16 source via bounded read requests. */
+export declare function parseXmlSourceSteps(length: number, limits?: XmlStepLimits): Generator<XmlSourceStep, XmlElement, void>;
+export declare function parseXmlSteps(input: string, limits?: XmlStepLimits): Generator<number, XmlElement, void>;
 export declare function parseXml(input: string, limits?: XmlLimits): XmlElement;
 export { parseXmlStream, type XmlStreamLimits, type XmlStreamEvent } from "./stream.js";

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

@@ -1,7 +1,10 @@
+import { validCharacter } from "./characters.js";
+export { normalizeXmlChunks } from "./characters.js";
+import { XmlSource } from "./source.js";
 import { XmlLimitError } from "./errors.js";
 export { XmlLimitError } from "./errors.js";
 function* find(source, needle, start) {
-    const found = source.indexOf(needle, start);
+    const found = typeof source === "string" ? source.indexOf(needle, start) : yield* source.indexOf(needle, start);
     const end = found < 0 ? source.length : found;
     let remaining = end - start;
     while (remaining >= 512) {
@@ -17,12 +20,6 @@ const xmlnsNamespace = "http://www.w3.org/2000/xmlns/";
 function invalid(message) {
     throw new SyntaxError(`Invalid XML: ${message}`);
 }
-function validCharacter(point) {
-    return point === 9 || point === 10 || point === 13
-        || (point >= 0x20 && point <= 0xd7ff)
-        || (point >= 0xe000 && point <= 0xfffd)
-        || (point >= 0x10000 && point <= 0x10ffff);
-}
 function nameStart(point) {
     return point === 95 || (point >= 65 && point <= 90) || (point >= 97 && point <= 122)
         || (point >= 0xc0 && point <= 0xd6) || (point >= 0xd8 && point <= 0xf6)
@@ -182,67 +179,39 @@ function* validDeclaration(content, expectedEncoding) {
     }
     return offset === content.length;
 }
-export function* parseXmlSteps(input, limits = {}) {
+function validateLimits(limits) {
+    for (const limit of [limits.maxDepth, limits.maxNodes, limits.maxAttributes, limits.maxContentNodes, limits.maxAttributesPerElement, limits.maxNamespaces]) {
+        if (limit !== undefined && ((limit !== Infinity && !Number.isSafeInteger(limit)) || limit < 1))
+            throw new RangeError("XML limits must be positive integers");
+    }
+    if (limits.maxTextLength !== undefined && ((limits.maxTextLength !== Infinity && !Number.isSafeInteger(limits.maxTextLength)) || limits.maxTextLength < 1))
+        throw new RangeError("XML limits must be positive integers");
+    if (limits.events && limits.retainTree !== false)
+        throw new TypeError("XML events require retainTree: false");
+}
+/** Parse a validated, BOM-free, line-normalized UTF-16 source via bounded read requests. */
+export function* parseXmlSourceSteps(length, limits = {}) {
+    validateLimits(limits);
+    const source = new XmlSource(length);
     const maxDepth = limits.maxDepth ?? Infinity;
     const maxNodes = limits.maxNodes ?? Infinity;
     const maxAttributes = limits.maxAttributes ?? Infinity;
     const retainContent = limits.retainContent !== false;
+    const retainTree = limits.retainTree !== false;
+    const retain = retainTree && retainContent;
     const maxContentNodes = limits.maxContentNodes ?? Infinity;
     const emptyContent = Object.freeze([]);
     const emptyAttributes = Object.freeze([]);
     const emptyNamespaces = new Map();
     const maxAttributesPerElement = limits.maxAttributesPerElement ?? Infinity;
     const maxNamespaces = limits.maxNamespaces ?? Infinity;
-    for (const limit of [limits.maxDepth, limits.maxNodes, limits.maxAttributes, limits.maxContentNodes, limits.maxAttributesPerElement, limits.maxNamespaces]) {
-        if (limit !== undefined && ((limit !== Infinity && !Number.isSafeInteger(limit)) || limit < 1))
-            throw new RangeError("XML limits must be positive integers");
-    }
     const maxTextLength = limits.maxTextLength ?? Infinity;
-    if (limits.maxTextLength !== undefined && ((maxTextLength !== Infinity && !Number.isSafeInteger(maxTextLength)) || maxTextLength < 1))
-        throw new RangeError("XML limits must be positive integers");
     let textLength = 0;
     const admitText = (text) => {
         if (text.length > maxTextLength - textLength)
             throw new XmlLimitError("maxTextLength", "XML text limit exceeded");
         textLength += text.length;
     };
-    const chunks = [];
-    const start = input.charCodeAt(0) === 0xfeff ? 1 : 0;
-    let chunkStart = start;
-    let chunkLength = 0;
-    let normalizedChunk = "";
-    // Keep validated spans intact; only changed line endings need new strings.
-    for (let index = start; index < input.length; index++) {
-        const point = input.codePointAt(index);
-        if (!validCharacter(point))
-            invalid("invalid character");
-        if (point === 13) {
-            normalizedChunk += input.slice(chunkStart, index) + "\n";
-            if (input.charCodeAt(index + 1) === 10)
-                index++;
-            chunkStart = index + 1;
-            chunkLength++;
-        }
-        else {
-            chunkLength += point > 0xffff ? 2 : 1;
-            if (point > 0xffff)
-                index++;
-        }
-        if (chunkLength >= 512) {
-            if (normalizedChunk) {
-                chunks.push(normalizedChunk + input.slice(chunkStart, index + 1));
-                normalizedChunk = "";
-                chunkStart = index + 1;
-            }
-            chunkLength = 0;
-            yield 512;
-        }
-    }
-    if (chunkLength)
-        yield chunkLength;
-    if (chunks.length || normalizedChunk)
-        chunks.push(normalizedChunk + input.slice(chunkStart));
-    const source = chunks.length ? chunks.join("") : input.slice(start);
     const stack = [];
     let root;
     const prolog = [];
@@ -262,7 +231,7 @@ export function* parseXmlSteps(input, limits = {}) {
     const skipWhitespace = function* () {
         const start = offset;
         while (offset < source.length) {
-            const c = source.charCodeAt(offset);
+            const c = (yield* source.charCodeAt(offset));
             if (c !== 32 && c !== 9 && c !== 10 && c !== 13)
                 break;
             offset++;
@@ -277,7 +246,7 @@ export function* parseXmlSteps(input, limits = {}) {
     const scanName = function* () {
         const start = offset;
         while (offset < source.length) {
-            const c = source.charCodeAt(offset);
+            const c = (yield* source.charCodeAt(offset));
             if (c === 32 || c === 9 || c === 13 || c === 10 || c === 47 || c === 61 || c === 62 || c === 63)
                 break;
             offset++;
@@ -287,7 +256,7 @@ export function* parseXmlSteps(input, limits = {}) {
                 pendingWork -= 512;
             }
         }
-        const name = source.slice(start, offset);
+        const name = (yield* source.slice(start, offset));
         pendingWork += offset - start;
         while (pendingWork >= 512) {
             yield 512;
@@ -304,10 +273,10 @@ export function* parseXmlSteps(input, limits = {}) {
                 pendingWork -= 512;
             }
         }
-        if (source.charCodeAt(offset) !== 60) {
-            const next = source.indexOf("<", offset);
+        if ((yield* source.charCodeAt(offset)) !== 60) {
+            const next = (yield* source.indexOf("<", offset));
             const endPos = next < 0 ? source.length : next;
-            const text = source.slice(offset, endPos);
+            const text = (yield* source.slice(offset, endPos));
             pendingWork += (endPos - offset) + text.length;
             while (pendingWork >= 512) {
                 yield 512;
@@ -323,11 +292,13 @@ export function* parseXmlSteps(input, limits = {}) {
             admitText(resolved);
             const parent = stack.at(-1);
             if (parent) {
-                parent.element.text += resolved;
+                if (retainTree)
+                    parent.element.text += resolved;
                 if (resolved.length) {
                     admitContent();
-                    if (retainContent)
+                    if (retain)
                         parent.content.push({ kind: "text", text: resolved });
+                    limits.events?.({ type: "content", content: { kind: "text", text: resolved }, parent: parent.element });
                 }
             }
             else {
@@ -347,42 +318,46 @@ export function* parseXmlSteps(input, limits = {}) {
                 }
                 if (resolved.length) {
                     admitContent();
-                    if (retainContent)
+                    if (retain)
                         (root ? epilog : prolog).push({ kind: "text", text: resolved });
+                    limits.events?.({ type: "content", content: { kind: "text", text: resolved }, parent: undefined });
                 }
             }
             offset = endPos;
         }
-        else if (source.startsWith("<!--", offset)) {
+        else if ((yield* source.startsWith("<!--", offset))) {
             const end = yield* find(source, "-->", offset + 4);
-            if (end < 0 || (yield* find(source.slice(offset + 4, end), "--", 0)) >= 0 || source.slice(offset + 4, end).endsWith("-")) {
+            const text = end < 0 ? "" : yield* source.slice(offset + 4, end);
+            if (end < 0 || (yield* find(text, "--", 0)) >= 0 || text.endsWith("-")) {
                 invalid("malformed comment");
             }
             const parent = stack.at(-1);
-            const text = source.slice(offset + 4, end);
             admitText(text);
             admitContent();
-            if (retainContent) {
+            if (retain) {
                 (parent?.content ?? (root ? epilog : prolog)).push({ kind: "comment", text });
             }
+            limits.events?.({ type: "content", content: { kind: "comment", text }, parent: parent?.element });
             offset = end + 3;
         }
-        else if (source.startsWith("<![CDATA[", offset)) {
+        else if ((yield* source.startsWith("<![CDATA[", offset))) {
             if (!stack.length)
                 invalid("CDATA outside root");
             const end = yield* find(source, "]]>", offset + 9);
             if (end < 0)
                 invalid("unterminated CDATA");
-            const cdataText = source.slice(offset + 9, end);
+            const cdataText = (yield* source.slice(offset + 9, end));
             admitText(cdataText);
             const parent = stack.at(-1);
-            parent.element.text += cdataText;
+            if (retainTree)
+                parent.element.text += cdataText;
             admitContent();
-            if (retainContent)
+            if (retain)
                 parent.content.push({ kind: "cdata", text: cdataText });
+            limits.events?.({ type: "content", content: { kind: "cdata", text: cdataText }, parent: parent.element });
             offset = end + 3;
         }
-        else if (source.startsWith("<?", offset)) {
+        else if ((yield* source.startsWith("<?", offset))) {
             const start = offset;
             offset += 2;
             const [target] = yield* scanName();
@@ -393,14 +368,14 @@ export function* parseXmlSteps(input, limits = {}) {
             const end = yield* find(source, "?>", offset);
             if (end < 0)
                 invalid("unterminated processing instruction");
-            const content = source.slice(offset, end);
+            const content = (yield* source.slice(offset, end));
             if (target.length === 3 && target.toLowerCase() === "xml") {
                 if (start !== 0 || target !== "xml"
                     || !(yield* validDeclaration(content, limits.expectedEncoding))) {
                     invalid("unsupported XML declaration");
                 }
                 if (retainContent)
-                    declaration = source.slice(start, end + 2);
+                    declaration = (yield* source.slice(start, end + 2));
             }
             else if (content && !" \t\n\r".includes(content[0]))
                 invalid("invalid processing instruction");
@@ -417,16 +392,17 @@ export function* parseXmlSteps(input, limits = {}) {
                 const text = content.slice(wsStart);
                 admitText(text);
                 admitContent();
-                if (retainContent) {
+                if (retain) {
                     (parent?.content ?? (root ? epilog : prolog)).push({ kind: "processing-instruction", target, text });
                 }
+                limits.events?.({ type: "content", content: { kind: "processing-instruction", target, text }, parent: parent?.element });
             }
             offset = end + 2;
         }
-        else if (source.startsWith("<!", offset)) {
+        else if ((yield* source.startsWith("<!", offset))) {
             invalid("DTD and entity declarations are forbidden");
         }
-        else if (source.charCodeAt(offset + 1) === 47) {
+        else if ((yield* source.charCodeAt(offset + 1)) === 47) {
             offset += 2;
             const [name] = yield* scanName();
             yield* skipWhitespace();
@@ -434,15 +410,18 @@ export function* parseXmlSteps(input, limits = {}) {
                 yield 512;
                 pendingWork -= 512;
             }
-            if (source[offset++] !== ">" || stack.pop()?.name !== name) {
+            const closed = (yield* source.slice(offset++, offset)) === ">" ? stack.pop() : undefined;
+            if (closed?.name !== name) {
                 if (!limits.recover)
                     invalid("mismatched closing tag");
                 limits.recover("mismatched closing tag");
             }
+            if (closed)
+                limits.events?.({ type: "close", element: closed.element, parent: stack.at(-1)?.element });
         }
         else {
             offset++;
-            const repeated = previousEmpty && source.startsWith(previousEmpty.suffix, offset) ? previousEmpty : undefined;
+            const repeated = previousEmpty && (yield* source.startsWith(previousEmpty.suffix, offset)) ? previousEmpty : undefined;
             const [name, prefix, localName] = repeated
                 ? [repeated.name, repeated.prefix, repeated.localName]
                 : (yield* scanName());
@@ -465,7 +444,7 @@ export function* parseXmlSteps(input, limits = {}) {
                     yield 512;
                     pendingWork -= 512;
                 }
-                const ch = source.charCodeAt(offset);
+                const ch = (yield* source.charCodeAt(offset));
                 if (ch === 47 || ch === 62 || limits.recover && offset === source.length)
                     break;
                 if (ws === 0)
@@ -482,13 +461,13 @@ export function* parseXmlSteps(input, limits = {}) {
                 if ((attributes?.size ?? 0) >= maxAttributesPerElement)
                     throw new XmlLimitError("maxAttributesPerElement", "XML attribute limit exceeded");
                 yield* skipWhitespace();
-                if (source[offset++] !== "=")
+                if ((yield* source.slice(offset++, offset)) !== "=")
                     invalid("missing attribute equals");
                 yield* skipWhitespace();
-                const quote = source[offset++];
+                const quote = (yield* source.slice(offset++, offset));
                 if (quote !== '"' && quote !== "'")
                     invalid("unquoted attribute");
-                const end = source.indexOf(quote, offset);
+                const end = (yield* source.indexOf(quote, offset));
                 const scanLen = (end < 0 ? source.length : end) - offset;
                 pendingWork += scanLen;
                 while (pendingWork >= 512) {
@@ -497,7 +476,7 @@ export function* parseXmlSteps(input, limits = {}) {
                 }
                 if (end < 0)
                     invalid("unterminated attribute");
-                const raw = source.slice(offset, end);
+                const raw = (yield* source.slice(offset, end));
                 pendingWork += raw.length * 2;
                 while (pendingWork >= 512) {
                     yield 512;
@@ -581,31 +560,36 @@ export function* parseXmlSteps(input, limits = {}) {
                 yield 512;
                 pendingWork -= 512;
             }
-            const content = retainContent ? [] : undefined;
+            const content = retain ? [] : undefined;
             const element = { kind: "element", name, namespace, localName, children: [], text: "", content: content ?? emptyContent, attributes: retainContent ? retainedAttributes : emptyAttributes, namespaces: retainContent ? namespaces : emptyNamespaces, ...(root === undefined && retainContent ? { prolog, epilog, ...(declaration === undefined ? {} : { declaration }) } : {}) };
             const parent = stack.at(-1);
             if (parent) {
-                parent.element.children.push(element);
-                parent.content?.push(element);
+                if (retainTree) {
+                    parent.element.children.push(element);
+                    parent.content?.push(element);
+                }
             }
             else if (root)
                 invalid("multiple root elements");
             else
                 root = element;
-            const empty = source[offset] === "/";
+            const empty = (yield* source.slice(offset, offset + 1)) === "/";
             if (empty)
                 offset++;
-            if (source[offset++] !== ">") {
+            if ((yield* source.slice(offset++, offset)) !== ">") {
                 if (!limits.recover)
                     invalid("unterminated start tag");
                 limits.recover("unterminated start tag");
             }
             // Only cache compact, attribute-free spellings. Namespace resolution and
             // every admission counter still run for each distinct physical element.
-            if (empty && !attributes && name.length <= 512 && source.slice(offset - name.length - 3, offset) === `<${name}/>`)
+            if (empty && !attributes && name.length <= 512 && (yield* source.slice(offset - name.length - 3, offset)) === `<${name}/>`)
                 previousEmpty = { suffix: name + "/>", name, prefix, localName };
+            limits.events?.({ type: "open", element, parent: parent?.element });
             if (!empty)
                 stack.push({ element, content, name, namespaces });
+            else
+                limits.events?.({ type: "close", element, parent: parent?.element });
         }
     }
     if (pendingWork > 0) {
@@ -618,9 +602,73 @@ export function* parseXmlSteps(input, limits = {}) {
         if (!limits.recover)
             invalid("incomplete document");
         limits.recover("incomplete document");
+        while (stack.length) {
+            const closed = stack.pop();
+            limits.events?.({ type: "close", element: closed.element, parent: stack.at(-1)?.element });
+            yield 1;
+        }
     }
     return root;
 }
+function* normalizeXmlSteps(input) {
+    const chunks = [];
+    const start = input.charCodeAt(0) === 0xfeff ? 1 : 0;
+    let chunkStart = start;
+    let chunkLength = 0;
+    let normalizedChunk = "";
+    // Keep validated spans intact; only changed line endings need new strings.
+    for (let index = start; index < input.length; index++) {
+        const point = input.codePointAt(index);
+        if (!validCharacter(point))
+            invalid("invalid character");
+        if (point === 13) {
+            normalizedChunk += input.slice(chunkStart, index) + "\n";
+            if (input.charCodeAt(index + 1) === 10)
+                index++;
+            chunkStart = index + 1;
+            chunkLength++;
+        }
+        else {
+            chunkLength += point > 0xffff ? 2 : 1;
+            if (point > 0xffff)
+                index++;
+        }
+        if (chunkLength >= 512) {
+            if (normalizedChunk) {
+                chunks.push(normalizedChunk + input.slice(chunkStart, index + 1));
+                normalizedChunk = "";
+                chunkStart = index + 1;
+            }
+            chunkLength = 0;
+            yield 512;
+        }
+    }
+    if (chunkLength)
+        yield chunkLength;
+    if (chunks.length || normalizedChunk)
+        chunks.push(normalizedChunk + input.slice(chunkStart));
+    return chunks.length ? chunks.join("") : input.slice(start);
+}
+export function* parseXmlSteps(input, limits = {}) {
+    validateLimits(limits);
+    const source = yield* normalizeXmlSteps(input);
+    const parser = parseXmlSourceSteps(source.length, limits);
+    let step = parser.next();
+    try {
+        while (!step.done) {
+            if (typeof step.value === "number")
+                yield step.value;
+            else
+                step.value.value = source.slice(step.value.offset, step.value.offset + step.value.length);
+            step = parser.next();
+        }
+        return step.value;
+    }
+    finally {
+        if (!step.done)
+            parser.return(undefined);
+    }
+}
 export function parseXml(input, limits = {}) {
     const parser = parseXmlSteps(input, limits);
     let result = parser.next();

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

@@ -0,0 +1,18 @@
+/** Fill value with exactly the requested UTF-16 span before advancing the parser. */
+export interface XmlSourceRead {
+    readonly offset: number;
+    readonly length: number;
+    value?: string;
+}
+export type XmlSourceStep = number | XmlSourceRead;
+/** One fixed window; individual returned tokens still have their own size cost. */
+export declare class XmlSource {
+    readonly length: number;
+    private window;
+    private start;
+    constructor(length: number);
+    slice(start: number, end?: number): Generator<XmlSourceStep, string, void>;
+    charCodeAt(offset: number): Generator<XmlSourceStep, number, void>;
+    startsWith(value: string, offset: number): Generator<XmlSourceStep, boolean, void>;
+    indexOf(value: string, offset: number): Generator<XmlSourceStep, number, void>;
+}

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

@@ -0,0 +1,47 @@
+/** One fixed window; individual returned tokens still have their own size cost. */
+export class XmlSource {
+    length;
+    window = '';
+    start = -1;
+    constructor(length) {
+        this.length = length;
+        if (!Number.isSafeInteger(length) || length < 0)
+            throw new RangeError("Invalid XML source length");
+    }
+    *slice(start, end = this.length) {
+        start = start < 0 ? Math.max(0, this.length + start) : Math.min(start, this.length);
+        end = end < 0 ? Math.max(0, this.length + end) : Math.min(end, this.length);
+        let result = '';
+        while (start < end) {
+            if (start < this.start || start >= this.start + this.window.length) {
+                const offset = Math.floor(start / 4096) * 4096;
+                const read = { offset, length: Math.min(4096, this.length - offset) };
+                yield read;
+                if (typeof read.value !== 'string' || read.value.length !== read.length)
+                    throw new TypeError('Incomplete XML source read');
+                this.window = read.value;
+                this.start = offset;
+            }
+            const stop = Math.min(end, this.start + this.window.length);
+            result += this.window.slice(start - this.start, stop - this.start);
+            start = stop;
+        }
+        return result;
+    }
+    *charCodeAt(offset) {
+        return (yield* this.slice(offset, offset + 1)).charCodeAt(0);
+    }
+    *startsWith(value, offset) {
+        return (yield* this.slice(offset, offset + value.length)) === value;
+    }
+    *indexOf(value, offset) {
+        while (offset < this.length) {
+            const end = Math.min(this.length, offset + 4096 + value.length - 1);
+            const found = (yield* this.slice(offset, end)).indexOf(value);
+            if (found >= 0)
+                return offset + found;
+            offset += 4096;
+        }
+        return -1;
+    }
+}

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

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

package/node_modules/toolcraft-schema/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.787",
+  "version": "0.0.789",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -177,7 +177,7 @@
     "saxes"
   ],
   "optionalDependencies": {
-    "toolcraft-schema": "0.0.787",
+    "toolcraft-schema": "0.0.789",
     "toolcraft-design": "*",
     "@poe-code/frontmatter": "*",
     "@poe-code/agent-mcp-config": "*",