@poe-platform/safe-fs 0.1.816 → 0.1.818

package/README.md

@@ -15,6 +15,9 @@ To bound aggregate pages across multiple live stores, pass the same
 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.
+Call `await storage.prepare()` before opening a directory iterator when its
+snapshot includes the scratch directory. It acquires and unlinks the backing
+handle up front, so later spills do not mutate that directory's namespace.
 `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/dist/safe-fs/core.d.ts

@@ -9,7 +9,7 @@ export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
 export { parseXml, parseXmlSteps, parseXmlSourceSteps, normalizeXmlChunks, parseXmlStream, XmlLimitError } from "./xml.js";
-export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits, XmlParserFrame, XmlFrameRequest } from "./xml.js";
+export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits, XmlParserFrame, XmlFrameRequest, XmlNamespaceScope, XmlNamespaceRequest, XmlAttributeRequest, XmlAttributeRecord } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
 export * from "./fs/s3/index.js";

package/dist/safe-fs/storage.d.ts

@@ -44,6 +44,8 @@ export declare class PagedStorage {
     private closing;
     constructor(context: PagedStorageContext, maxPages?: number, cache?: PagedStorageCache | undefined);
     allocate(length: number): number;
+    /** Acquire and unlink backing storage before observing a directory snapshot. */
+    prepare(): Promise<void>;
     private operation;
     private spill;
     private flush;

package/dist/safe-fs/storage.js

@@ -73,6 +73,11 @@ export class PagedStorage {
         this.end += length;
         return offset;
     }
+    /** Acquire and unlink backing storage before observing a directory snapshot. */
+    async prepare() {
+        await this.operation(async () => { if (!this.descriptor)
+            await this.spill(); });
+    }
     operation(action) {
         this.signal.throwIfAborted();
         const execute = () => {

package/dist/xml-ast/attributes.d.ts

@@ -0,0 +1,47 @@
+export interface XmlAttributeRecord {
+    name: string;
+    prefix: string;
+    localName: string;
+    value: string;
+    next: number;
+}
+export interface XmlAttributeState {
+    reference: number;
+    first: number;
+    length: number;
+    size: number;
+}
+export type XmlAttributeRequest = {
+    attributeOperation: 'has' | 'expanded';
+    state: XmlAttributeState;
+    name: string;
+    found?: boolean;
+} | {
+    attributeOperation: 'append';
+    state: XmlAttributeState;
+    attribute: Omit<XmlAttributeRecord, 'next'>;
+    result?: XmlAttributeState;
+} | {
+    attributeOperation: 'read';
+    state: XmlAttributeState;
+    reference: number;
+    values: boolean;
+    result?: XmlAttributeRecord;
+};
+/** Buffered APIs use local collections; external parsing retains only a store
+ * handle and one current attribute. Hosts preserve order and last-value recovery. */
+export declare class XmlAttributes {
+    private readonly external;
+    private state;
+    private readonly names;
+    private readonly records;
+    private readonly expandedNames;
+    constructor(external: boolean);
+    get length(): number;
+    get size(): number;
+    get first(): number;
+    has(name: string): Generator<XmlAttributeRequest, boolean, void>;
+    append(name: string, prefix: string, localName: string, value: string): Generator<XmlAttributeRequest, void, void>;
+    read(reference: number, values: boolean): Generator<XmlAttributeRequest, XmlAttributeRecord, void>;
+    expanded(name: string): Generator<XmlAttributeRequest, boolean, void>;
+}

package/dist/xml-ast/attributes.js

@@ -0,0 +1,62 @@
+/** Buffered APIs use local collections; external parsing retains only a store
+ * handle and one current attribute. Hosts preserve order and last-value recovery. */
+export class XmlAttributes {
+    external;
+    state = { reference: 0, first: 0, length: 0, size: 0 };
+    names = new Map();
+    records = [];
+    expandedNames = new Set();
+    constructor(external) {
+        this.external = external;
+    }
+    get length() { return this.state.length; }
+    get size() { return this.state.size; }
+    get first() { return this.state.first; }
+    *has(name) {
+        if (!this.length)
+            return false;
+        if (!this.external)
+            return this.names.has(name);
+        const request = { attributeOperation: 'has', state: this.state, name };
+        yield request;
+        if (request.found === undefined)
+            throw new TypeError('Incomplete XML attribute lookup');
+        return request.found;
+    }
+    *append(name, prefix, localName, value) {
+        if (!this.external) {
+            this.names.set(name, value);
+            this.records.push({ name, prefix, localName });
+            this.state = { reference: 0, first: 1, length: this.records.length, size: this.names.size };
+            return;
+        }
+        const request = { attributeOperation: 'append', state: this.state, attribute: { name, prefix, localName, value } };
+        yield request;
+        if (!request.result)
+            throw new TypeError('Incomplete XML attribute append');
+        this.state = request.result;
+    }
+    *read(reference, values) {
+        if (!this.external) {
+            const attribute = this.records[reference - 1];
+            return { ...attribute, value: values ? this.names.get(attribute.name) : '', next: reference < this.length ? reference + 1 : 0 };
+        }
+        const request = { attributeOperation: 'read', state: this.state, reference, values };
+        yield request;
+        if (!request.result)
+            throw new TypeError('Incomplete XML attribute read');
+        return request.result;
+    }
+    *expanded(name) {
+        if (!this.external) {
+            const found = this.expandedNames.has(name);
+            this.expandedNames.add(name);
+            return found;
+        }
+        const request = { attributeOperation: 'expanded', state: this.state, name };
+        yield request;
+        if (request.found === undefined)
+            throw new TypeError('Incomplete XML expanded attribute lookup');
+        return request.found;
+    }
+}

package/dist/xml-ast/frames.d.ts

@@ -4,6 +4,7 @@ export interface XmlParserFrame {
     content: XmlContent[] | undefined;
     name: string;
     namespaces: Map<string, string>;
+    namespaceScope?: XmlNamespaceScope;
 }
 export type XmlFrameRequest = {
     readonly frameOperation: 'push';
@@ -26,3 +27,23 @@ export declare class XmlFrames {
     push(frame: XmlParserFrame): Generator<XmlFrameRequest, void, void>;
     pop(): Generator<XmlFrameRequest, XmlParserFrame | undefined, void>;
 }
+/** A host-owned immutable namespace scope; count includes the built-in xml prefix. */
+export interface XmlNamespaceScope {
+    readonly reference: number;
+    readonly size: number;
+}
+export type XmlNamespaceRequest = {
+    readonly namespaceOperation: 'get';
+    readonly scope: XmlNamespaceScope;
+    readonly prefix: string;
+    value?: string;
+    complete?: true;
+} | {
+    readonly namespaceOperation: 'set';
+    readonly scope: XmlNamespaceScope;
+    readonly prefix: string;
+    readonly value: string;
+    result?: XmlNamespaceScope;
+};
+export declare function namespaceValue(scope: Map<string, string> | XmlNamespaceScope, prefix: string): Generator<XmlNamespaceRequest, string | undefined, void>;
+export declare function bindNamespace(scope: Map<string, string> | XmlNamespaceScope, prefix: string, value: string): Generator<XmlNamespaceRequest, Map<string, string> | XmlNamespaceScope, void>;

package/dist/xml-ast/frames.js

@@ -43,3 +43,23 @@ export class XmlFrames {
         return frame;
     }
 }
+export function* namespaceValue(scope, prefix) {
+    if (scope instanceof Map)
+        return scope.get(prefix);
+    const request = { namespaceOperation: 'get', scope, prefix };
+    yield request;
+    if (!request.complete)
+        throw new TypeError('Incomplete XML namespace read');
+    return request.value;
+}
+export function* bindNamespace(scope, prefix, value) {
+    if (scope instanceof Map) {
+        scope.set(prefix, value);
+        return scope;
+    }
+    const request = { namespaceOperation: 'set', scope, prefix, value };
+    yield request;
+    if (!request.result)
+        throw new TypeError('Incomplete XML namespace update');
+    return request.result;
+}

package/dist/xml-ast/index.d.ts

@@ -1,5 +1,7 @@
-import { type XmlFrameRequest } from "./frames.js";
-export type { XmlParserFrame, XmlFrameRequest } from "./frames.js";
+import { type XmlAttributeRequest } from "./attributes.js";
+export type { XmlAttributeRequest, XmlAttributeRecord, XmlAttributeState } from "./attributes.js";
+import { type XmlNamespaceRequest, type XmlFrameRequest } from "./frames.js";
+export type { XmlParserFrame, XmlFrameRequest, XmlNamespaceScope, XmlNamespaceRequest } from "./frames.js";
 export { normalizeXmlChunks } from "./characters.js";
 import { type XmlSourceStep } from "./source.js";
 export type { XmlSourceRead, XmlSourceStep } from "./source.js";
@@ -61,11 +63,18 @@ export interface XmlSourceLimits extends XmlStepLimits {
     readonly fragmentContent?: boolean;
     /** Store active parser frames through host-serviced requests. Requires retainTree: false. */
     readonly storeFrames?: boolean;
+    /** Resolve namespace scopes through host-serviced requests. Requires retainTree: false. */
+    readonly storeNamespaces?: boolean;
+    /** Store attribute collections through host requests and emit resolved attributes individually. */
+    readonly storeAttributes?: boolean;
+    readonly onAttribute?: (attribute: XmlAttribute, element: XmlElement) => void;
 }
-export type XmlParseStep = XmlSourceStep | XmlFrameRequest;
+export type XmlParseStep = XmlSourceStep | XmlFrameRequest | XmlNamespaceRequest | XmlAttributeRequest;
 /** Parse a validated, BOM-free, line-normalized UTF-16 source via bounded read requests. */
 export declare function parseXmlSourceSteps(length: number | undefined, limits?: XmlStepLimits & {
     readonly storeFrames?: false;
+    readonly storeNamespaces?: false;
+    readonly storeAttributes?: false;
 }): Generator<XmlSourceStep, XmlElement, void>;
 export declare function parseXmlSourceSteps(length: number | undefined, limits: XmlSourceLimits): Generator<XmlParseStep, XmlElement, void>;
 export declare function parseXmlSteps(input: string, limits?: XmlStepLimits): Generator<number, XmlElement, void>;

package/dist/xml-ast/index.js

@@ -1,4 +1,5 @@
-import { XmlFrames } from "./frames.js";
+import { XmlAttributes } from "./attributes.js";
+import { XmlFrames, bindNamespace, namespaceValue } from "./frames.js";
 import { validCharacter } from "./characters.js";
 export { normalizeXmlChunks } from "./characters.js";
 import { XmlSource } from "./source.js";
@@ -255,6 +256,10 @@ export function* parseXmlSourceSteps(length, limits = {}) {
     validateLimits(limits);
     if (limits.storeFrames && limits.retainTree !== false)
         throw new TypeError("Stored XML frames require retainTree: false");
+    if (limits.storeAttributes && limits.retainTree !== false)
+        throw new TypeError("Stored XML attributes require retainTree: false");
+    if (limits.storeNamespaces && limits.retainTree !== false)
+        throw new TypeError("Stored XML namespaces require retainTree: false");
     if (limits.fragmentContent && limits.retainTree !== false)
         throw new TypeError("XML content fragments require retainTree: false");
     const source = new XmlSource(length);
@@ -277,6 +282,7 @@ export function* parseXmlSourceSteps(length, limits = {}) {
             throw new XmlLimitError("maxTextLength", "XML text limit exceeded");
         textLength += text.length;
     };
+    const initialNamespaces = limits.storeNamespaces ? yield* bindNamespace({ reference: 0, size: 0 }, "xml", xmlNamespace) : new Map([["xml", xmlNamespace]]);
     const stack = new XmlFrames(limits.storeFrames === true);
     let root;
     const prolog = [];
@@ -552,9 +558,9 @@ export function* parseXmlSourceSteps(length, limits = {}) {
                 yield 512;
                 pendingWork -= 512;
             }
-            let attributes;
-            const attrMeta = [];
-            let namespaces = (yield* stack.peek())?.namespaces ?? new Map([["xml", xmlNamespace]]);
+            const attributes = new XmlAttributes(limits.storeAttributes === true);
+            const namespaceParent = yield* stack.peek();
+            let namespaces = namespaceParent?.namespaceScope ?? namespaceParent?.namespaces ?? (initialNamespaces instanceof Map ? new Map(initialNamespaces) : initialNamespaces);
             let ownsNamespaces = stack.length === 0;
             while (!repeated) {
                 const ws = (yield* skipWhitespace());
@@ -572,11 +578,11 @@ export function* parseXmlSourceSteps(length, limits = {}) {
                     yield 512;
                     pendingWork -= 512;
                 }
-                if (attributes?.has(attribute))
+                if ((yield* attributes.has(attribute)))
                     invalid("duplicate attribute");
                 if (++attributeCount > maxAttributes)
                     throw new XmlLimitError("maxAttributes", "XML attribute limit exceeded");
-                if ((attributes?.size ?? 0) >= maxAttributesPerElement)
+                if (attributes.size >= maxAttributesPerElement)
                     throw new XmlLimitError("maxAttributesPerElement", "XML attribute limit exceeded");
                 yield* skipWhitespace();
                 if ((yield* source.slice(offset++, offset)) !== "=")
@@ -609,8 +615,7 @@ export function* parseXmlSourceSteps(length, limits = {}) {
                     pendingWork -= 512;
                 }
                 admitText(value);
-                (attributes ??= new Map()).set(attribute, value);
-                attrMeta.push([attribute, attrPrefix, attrLocal]);
+                yield* attributes.append(attribute, attrPrefix, attrLocal, value);
                 offset = end + 1;
                 if (attribute === "xmlns" || attribute.startsWith("xmlns:")) {
                     const nsPrefix = attribute === "xmlns" ? "" : attribute.slice(6);
@@ -618,7 +623,7 @@ export function* parseXmlSourceSteps(length, limits = {}) {
                         || (nsPrefix === "xml") !== (value === xmlNamespace)
                         || (nsPrefix !== "" && value === ""))
                         invalid("invalid namespace binding");
-                    if (!ownsNamespaces) {
+                    if (!ownsNamespaces && namespaces instanceof Map) {
                         const copy = new Map();
                         for (const [key, uri] of namespaces) {
                             copy.set(key, uri);
@@ -627,25 +632,25 @@ export function* parseXmlSourceSteps(length, limits = {}) {
                         namespaces = copy;
                         ownsNamespaces = true;
                     }
-                    namespaces.set(nsPrefix, value);
+                    namespaces = yield* bindNamespace(namespaces, nsPrefix, value);
                     if (namespaces.size > maxNamespaces)
                         throw new XmlLimitError("maxNamespaces", "XML namespace scope limit exceeded");
                 }
             }
-            if (attrMeta.length > 0) {
-                const expanded = attrMeta.length > 1 ? new Set() : undefined;
-                for (let i = 0; i < attrMeta.length; i++) {
-                    const [attribute, attrPrefix, attrLocal] = attrMeta[i];
+            if (attributes.length > 0) {
+                for (let cursor = attributes.first; cursor;) {
+                    const record = yield* attributes.read(cursor, false);
+                    cursor = record.next;
+                    const { name: attribute, prefix: attrPrefix, localName: attrLocal } = record;
                     if (attribute === "xmlns" || attribute.startsWith("xmlns:"))
                         continue;
                     pendingWork += attribute.length;
-                    if (attrPrefix && !namespaces.has(attrPrefix))
+                    if (attrPrefix && (yield* namespaceValue(namespaces, attrPrefix)) === undefined)
                         invalid("unbound attribute prefix");
-                    if (expanded) {
-                        const key = `${attrPrefix ? namespaces.get(attrPrefix) : ""}\0${attrLocal}`;
-                        if (expanded.has(key))
+                    if (attributes.length > 1) {
+                        const key = `${attrPrefix ? (yield* namespaceValue(namespaces, attrPrefix)) : ""}\0${attrLocal}`;
+                        if (yield* attributes.expanded(key))
                             invalid("duplicate expanded attribute");
-                        expanded.add(key);
                     }
                 }
             }
@@ -654,23 +659,25 @@ export function* parseXmlSourceSteps(length, limits = {}) {
                 yield 512;
                 pendingWork -= 512;
             }
-            if (prefix === "xmlns" || (prefix && !namespaces.has(prefix)))
+            if (prefix === "xmlns" || (prefix && (yield* namespaceValue(namespaces, prefix)) === undefined))
                 invalid("unbound element prefix");
             if (++nodes > maxNodes)
                 throw new XmlLimitError("maxNodes", "XML resource limit exceeded");
             if (stack.length + 1 > maxDepth)
                 throw new XmlLimitError("maxDepth", "XML resource limit exceeded");
-            const namespace = namespaces.get(prefix) ?? "";
+            const namespace = (yield* namespaceValue(namespaces, prefix)) ?? "";
             limits.onElement?.({ name, namespace, localName }, (yield* stack.peek())?.element, stack.length + 1);
             admitContent();
             const retainedAttributes = [];
-            if (retainContent && attributes) {
-                for (let i = 0; i < attrMeta.length; i++) {
-                    const [attribute, attrPrefix, attrLocal] = attrMeta[i];
-                    const value = attributes.get(attribute);
+            if (retainContent) {
+                for (let cursor = attributes.first; cursor;) {
+                    const record = yield* attributes.read(cursor, !limits.storeAttributes);
+                    cursor = record.next;
+                    const { name: attribute, prefix: attrPrefix, localName: attrLocal, value } = record;
                     admitContent();
-                    retainedAttributes.push({ name: attribute, localName: attrLocal,
-                        namespace: attribute === "xmlns" || attrPrefix === "xmlns" ? xmlnsNamespace : attrPrefix ? namespaces.get(attrPrefix) : "", value });
+                    if (!limits.storeAttributes)
+                        retainedAttributes.push({ name: attribute, localName: attrLocal,
+                            namespace: attribute === "xmlns" || attrPrefix === "xmlns" ? xmlnsNamespace : attrPrefix ? (yield* namespaceValue(namespaces, attrPrefix)) : "", value });
                     pendingWork += attribute.length + 1;
                 }
             }
@@ -679,7 +686,7 @@ export function* parseXmlSourceSteps(length, limits = {}) {
                 pendingWork -= 512;
             }
             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 element = { kind: "element", name, namespace, localName, children: [], text: "", content: content ?? emptyContent, attributes: retainContent ? retainedAttributes : emptyAttributes, namespaces: retainContent && namespaces instanceof Map ? namespaces : emptyNamespaces, ...(root === undefined && retainContent ? { prolog, epilog, ...(declaration === undefined ? {} : { declaration }) } : {}) };
             const parent = (yield* stack.peek());
             if (parent) {
                 if (retainTree) {
@@ -701,11 +708,22 @@ export function* parseXmlSourceSteps(length, limits = {}) {
             }
             // 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 && (yield* source.slice(offset - name.length - 3, offset)) === `<${name}/>`)
+            if (empty && !attributes.length && 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 (limits.storeAttributes && limits.onAttribute && retainContent) {
+                yield 1;
+                for (let cursor = attributes.first; cursor;) {
+                    const attribute = yield* attributes.read(cursor, true);
+                    cursor = attribute.next;
+                    const namespace = attribute.name === "xmlns" || attribute.prefix === "xmlns" ? xmlnsNamespace
+                        : attribute.prefix ? (yield* namespaceValue(namespaces, attribute.prefix)) : "";
+                    limits.onAttribute({ name: attribute.name, localName: attribute.localName, namespace, value: attribute.value }, element);
+                    yield 1;
+                }
+            }
             if (!empty)
-                yield* stack.push({ element, content, name, namespaces });
+                yield* stack.push({ element, content, name, namespaces: namespaces instanceof Map ? namespaces : new Map(), ...(namespaces instanceof Map ? {} : { namespaceScope: namespaces }) });
             else
                 limits.events?.({ type: "close", element, parent: parent?.element });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.816",
+  "version": "0.1.818",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",