circuitjson-toolkit 1.2.1 → 1.4.0

package/src/core/context/StructuredCloneCollectionNormalizer.mjs

@@ -0,0 +1,86 @@
+const NO_STANDARD_COLLECTION = Symbol('NoStandardCollection')
+const MAP_ENTRIES = Map.prototype.entries
+const MAP_ITERATOR_NEXT = Object.getPrototypeOf(new Map().entries()).next
+const MAP_SIZE = Object.getOwnPropertyDescriptor(Map.prototype, 'size')?.get
+const SET_ITERATOR_NEXT = Object.getPrototypeOf(new Set().values()).next
+const SET_SIZE = Object.getOwnPropertyDescriptor(Set.prototype, 'size')?.get
+const SET_VALUES = Set.prototype.values
+
+/**
+ * Normalizes standard structured-clone collections in bounded entry slices.
+ */
+export class StructuredCloneCollectionNormalizer {
+    /**
+     * Returns the private sentinel for a non-collection candidate.
+     * @returns {symbol} Non-collection sentinel.
+     */
+    static get notHandled() {
+        return NO_STANDARD_COLLECTION
+    }
+
+    /**
+     * Normalizes one Map or Set through captured platform iteration.
+     * @param {object} value Collection candidate.
+     * @param {object | null} prototype Captured prototype.
+     * @param {PropertyKey[]} keys Captured own keys.
+     * @param {number} depth Current collection depth.
+     * @param {{ adopt: (value: unknown, depth: number) => Generator<void, unknown, void>, checkpoint: () => Generator<void, void, void>, collect: (value: unknown) => Generator<void, void, void>, remember: (source: object, result: unknown[]) => void, reserve: (count: number) => void }} operations Traversal operations.
+     * @returns {Generator<void, unknown, void>} Normalized collection or sentinel.
+     */
+    static *normalize(value, prototype, keys, depth, operations) {
+        const map = prototype === Map.prototype
+        const set = prototype === Set.prototype
+        if (!map && !set) return NO_STANDARD_COLLECTION
+        if (keys.length) {
+            throw new TypeError(
+                `Canonical asset source ${map ? 'maps' : 'sets'} may not have custom properties.`
+            )
+        }
+        const sizeGetter = map ? MAP_SIZE : SET_SIZE
+        if (typeof sizeGetter !== 'function') {
+            throw new TypeError(
+                `Canonical asset source contains an invalid ${map ? 'map' : 'set'}.`
+            )
+        }
+        let size
+        let iterator
+        try {
+            size = Reflect.apply(sizeGetter, value, [])
+            iterator = Reflect.apply(map ? MAP_ENTRIES : SET_VALUES, value, [])
+        } catch {
+            throw new TypeError(
+                `Canonical asset source contains an invalid ${map ? 'map' : 'set'}.`
+            )
+        }
+        operations.reserve(1)
+        operations.reserve(map ? size * 2 : size)
+        const result = []
+        operations.remember(value, result)
+        const iteratorNext = map ? MAP_ITERATOR_NEXT : SET_ITERATOR_NEXT
+        for (let index = 0; index < size; index += 1) {
+            const row = Reflect.apply(iteratorNext, iterator, [])
+            if (row.done || (map && !Array.isArray(row.value))) {
+                throw new TypeError(
+                    `Canonical asset source ${map ? 'map' : 'set'} changed during inspection.`
+                )
+            }
+            result[index] = map
+                ? [
+                      yield* operations.adopt(row.value[0], depth + 1),
+                      yield* operations.adopt(row.value[1], depth + 1)
+                  ]
+                : yield* operations.adopt(row.value, depth + 1)
+            yield* operations.checkpoint()
+        }
+        if (!Reflect.apply(iteratorNext, iterator, []).done) {
+            throw new TypeError(
+                `Canonical asset source ${map ? 'map' : 'set'} changed during inspection.`
+            )
+        }
+        yield* operations.collect(result)
+        return result
+    }
+}
+
+Object.freeze(StructuredCloneCollectionNormalizer.prototype)
+Object.freeze(StructuredCloneCollectionNormalizer)

package/src/core/context/StructuredCloneTextAccounting.mjs

@@ -0,0 +1,55 @@
+const TEXT_ACCOUNTING_CHUNK_CHARACTERS = 64 * 1_024
+const STRING_CHAR_CODE_AT = String.prototype.charCodeAt
+const STRING_SLICE = String.prototype.slice
+const TEXT_ENCODER = new TextEncoder()
+const TEXT_ENCODER_ENCODE = TextEncoder.prototype.encode
+
+/**
+ * Accounts immutable structured-clone text without one long UTF-8 scan.
+ */
+export class StructuredCloneTextAccounting {
+    /**
+     * Measures one string across bounded encoding slices.
+     * @param {string} value Immutable text value.
+     * @param {{ bytes: number, label: string, maxBytes: number }} state Shared accounting state.
+     * @param {{ checkpoint: () => Generator<void, void, void>, reserve: (count: number) => void }} operations Traversal operations.
+     * @returns {Generator<void, void, void>} Bounded text accounting pass.
+     */
+    static *reserve(value, state, operations) {
+        if (state.maxBytes === Number.MAX_SAFE_INTEGER) return
+        let length = 0
+        let offset = 0
+        while (offset < value.length) {
+            let end = Math.min(
+                value.length,
+                offset + TEXT_ACCOUNTING_CHUNK_CHARACTERS
+            )
+            const trailing = Reflect.apply(STRING_CHAR_CODE_AT, value, [
+                end - 1
+            ])
+            const next = Reflect.apply(STRING_CHAR_CODE_AT, value, [end])
+            if (
+                end < value.length &&
+                trailing >= 0xd800 &&
+                trailing <= 0xdbff &&
+                next >= 0xdc00 &&
+                next <= 0xdfff
+            ) {
+                end -= 1
+            }
+            const chunk = Reflect.apply(STRING_SLICE, value, [offset, end])
+            length += Reflect.apply(TEXT_ENCODER_ENCODE, TEXT_ENCODER, [
+                chunk
+            ]).byteLength
+            if (state.bytes + length > state.maxBytes) {
+                throw new TypeError(`${state.label} is too large.`)
+            }
+            offset = end
+            if (offset < value.length) yield* operations.checkpoint()
+        }
+        operations.reserve(length)
+    }
+}
+
+Object.freeze(StructuredCloneTextAccounting.prototype)
+Object.freeze(StructuredCloneTextAccounting)

package/src/core/context/StructuredDataSnapshot.mjs

@@ -1,4 +1,5 @@
 import { BinaryDataSnapshot } from './BinaryDataSnapshot.mjs'
+import { StructuredCloneAdoption } from './StructuredCloneAdoption.mjs'
 
 const METADATA_MAX_DEPTH = 256
 const METADATA_MAX_ITEMS = 100_000
@@ -26,8 +27,8 @@ const SET_VALUES = Set.prototype.values
 export class StructuredDataSnapshot {
     /**
      * Creates state shared by multiple metadata roots in one request.
-     * @param {{ label?: string, maxBytes?: number, maxItems?: number, preserveBinary?: boolean }} [limits] Capture limits.
-     * @returns {{ seen: Map<object, unknown>, accounted: Set<object>, bytes: number, items: number, label: string, maxBytes: number, maxItems: number, preserveBinary: boolean }} Capture state.
+     * @param {{ label?: string, maxBytes?: number, maxItems?: number, preserveBinary?: boolean, standardBuiltins?: boolean }} [limits] Capture limits and proven graph provenance.
+     * @returns {{ seen: Map<object, unknown>, accounted: Set<object>, bytes: number, items: number, label: string, maxBytes: number, maxItems: number, preserveBinary: boolean, standardBuiltins: boolean }} Capture state.
      */
     static createState(limits = {}) {
         const maxBytes =
@@ -52,7 +53,8 @@ export class StructuredDataSnapshot {
             label: String(limits.label || 'Canonical asset source'),
             maxBytes,
             maxItems,
-            preserveBinary: limits.preserveBinary === true
+            preserveBinary: limits.preserveBinary === true,
+            standardBuiltins: limits.standardBuiltins === true
         }
     }
 
@@ -71,13 +73,66 @@ export class StructuredDataSnapshot {
             !Number.isSafeInteger(state.maxBytes) ||
             !Number.isSafeInteger(state.maxItems) ||
             typeof state.label !== 'string' ||
-            typeof state.preserveBinary !== 'boolean'
+            typeof state.preserveBinary !== 'boolean' ||
+            typeof state.standardBuiltins !== 'boolean'
         ) {
             throw new TypeError('Invalid source-metadata capture state.')
         }
         return StructuredDataSnapshot.#capture(value, state, 0)
     }
 
+    /**
+     * Adopts a proven standard structured-clone graph synchronously.
+     * @param {unknown} value Structured-cloned metadata candidate.
+     * @param {Record<string, any>} state Shared capture state.
+     * @returns {unknown} Adopted graph.
+     */
+    static adoptStructuredClone(value, state) {
+        return StructuredCloneAdoption.adopt(
+            value,
+            state,
+            (candidate, captureState, depth) =>
+                StructuredDataSnapshot.#capture(candidate, captureState, depth)
+        )
+    }
+
+    /**
+     * Adopts and seals a proven structured-clone graph in bounded work slices.
+     * @param {unknown} value Structured-cloned metadata candidate.
+     * @param {Record<string, any>} state Shared capture state.
+     * @param {() => Promise<void> | void} yieldControl Host scheduler.
+     * @returns {Promise<unknown>} Adopted and sealed graph.
+     */
+    static async adoptStructuredCloneAsync(value, state, yieldControl) {
+        return StructuredCloneAdoption.adoptAndSealAsync(
+            value,
+            state,
+            (candidate, captureState, depth) =>
+                StructuredDataSnapshot.#capture(candidate, captureState, depth),
+            yieldControl
+        )
+    }
+
+    /**
+     * Consumes the sealing plan produced by synchronous clone adoption.
+     * @param {unknown} value Adopted graph root.
+     * @returns {object | null} Trusted one-use sealing plan.
+     * @internal
+     */
+    static consumeStructuredCloneAdoption(value) {
+        return StructuredCloneAdoption.consume(value)
+    }
+
+    /**
+     * Seals one synchronously adopted graph from its trusted plan.
+     * @param {object} plan Trusted adoption plan.
+     * @returns {void}
+     * @internal
+     */
+    static sealStructuredCloneAdoption(plan) {
+        StructuredCloneAdoption.seal(plan)
+    }
+
     /**
      * Accounts an already normalized metadata snapshot without cloning it.
      * @param {unknown} value Owned metadata snapshot.
@@ -93,7 +148,8 @@ export class StructuredDataSnapshot {
             !Number.isSafeInteger(state.maxBytes) ||
             !Number.isSafeInteger(state.maxItems) ||
             typeof state.label !== 'string' ||
-            typeof state.preserveBinary !== 'boolean'
+            typeof state.preserveBinary !== 'boolean' ||
+            typeof state.standardBuiltins !== 'boolean'
         ) {
             throw new TypeError('Invalid source-metadata capture state.')
         }
@@ -224,7 +280,9 @@ export class StructuredDataSnapshot {
         if (state.seen.has(value)) return state.seen.get(value)
         StructuredDataSnapshot.#reserve(state, 1)
 
-        const binary = BinaryDataSnapshot.describe(value)
+        const binary = state.standardBuiltins
+            ? BinaryDataSnapshot.describeStandard(value)
+            : BinaryDataSnapshot.describe(value)
         if (binary) {
             return StructuredDataSnapshot.#binary(value, binary, state)
         }

package/src/core/contracts/DocumentResult.mjs

@@ -17,16 +17,17 @@ export class DocumentResult {
      * @returns {Record<string, any>} Canonical document result.
      */
     static create(fields = {}) {
-        return DocumentResult.#create(fields, false)
+        return DocumentResult.#create(fields, false, false)
     }
 
     /**
      * Creates the common envelope with the requested extension ownership mode.
      * @param {Record<string, any>} fields Document fields.
      * @param {boolean} readonlyExtensions Whether to capture immutable extensions now.
+     * @param {boolean} standardBuiltins Whether extension data is a toolkit-owned ordinary graph.
      * @returns {Record<string, any>} Canonical document result.
      */
-    static #create(fields, readonlyExtensions) {
+    static #create(fields, readonlyExtensions, standardBuiltins) {
         const source = DocumentResult.#source(fields)
         const audit = CircuitJsonSerializedInputAudit.inspect(
             fields.model,
@@ -46,7 +47,7 @@ export class DocumentResult {
             extensions: DocumentResult.extensionForSource(
                 source.format,
                 fields.extensions,
-                { readonly: readonlyExtensions }
+                { readonly: readonlyExtensions, standardBuiltins }
             ),
             assets: Array.isArray(fields.assets)
                 ? fields.assets.map((asset) =>
@@ -75,7 +76,29 @@ export class DocumentResult {
      * @returns {Record<string, any>} Proven canonical document result.
      */
     static createValidated(fields = {}, runtime = {}) {
-        const document = DocumentResult.#create(fields, true)
+        return DocumentResult.#createValidated(fields, runtime, false)
+    }
+
+    /**
+     * Creates a validated envelope by consuming toolkit-owned ordinary
+     * extension data without an intermediate defensive graph copy.
+     * @param {Record<string, any>} [fields] Toolkit-owned document fields.
+     * @param {{ sourceReference?: object }} [runtime] Runtime-only fields.
+     * @returns {Record<string, any>} Proven canonical document result.
+     */
+    static createValidatedOwned(fields = {}, runtime = {}) {
+        return DocumentResult.#createValidated(fields, runtime, true)
+    }
+
+    /**
+     * Creates one validated envelope with explicit extension provenance.
+     * @param {Record<string, any>} fields Document fields.
+     * @param {{ sourceReference?: object }} runtime Runtime-only fields.
+     * @param {boolean} standardBuiltins Whether extension data is toolkit-owned.
+     * @returns {Record<string, any>} Proven canonical document result.
+     */
+    static #createValidated(fields, runtime, standardBuiltins) {
+        const document = DocumentResult.#create(fields, true, standardBuiltins)
         if (Object.hasOwn(runtime || {}, 'sourceReference')) {
             Object.defineProperty(document, 'sourceReference', {
                 configurable: false,
@@ -84,7 +107,9 @@ export class DocumentResult {
                 writable: false
             })
         }
-        return CircuitJsonValidationProof.validateAndAttach(document)
+        return CircuitJsonValidationProof.validateAndAttach(document, {
+            standardBuiltins
+        })
     }
 
     /**
@@ -113,7 +138,7 @@ export class DocumentResult {
      * Selects and normalizes the extension namespace owned by a source.
      * @param {string} format Source format.
      * @param {unknown} extensions Extension candidates.
-     * @param {{ readonly?: boolean }} [options] Extension ownership options.
+     * @param {{ readonly?: boolean, standardBuiltins?: boolean }} [options] Extension ownership options.
      * @returns {Record<string, any>} Normalized extension map.
      */
     static extensionForSource(format, extensions, options = {}) {
@@ -122,6 +147,13 @@ export class DocumentResult {
         const hasCandidate = candidate && typeof candidate === 'object'
         if (!hasCandidate) return {}
         if (options.readonly === true && hasCandidate) {
+            if (options.standardBuiltins === true) {
+                return CircuitJsonReadOnlyDocument.copyReadonlyExtensionValue(
+                    DocumentResult.#normalizedExtension(format, candidate),
+                    null,
+                    { standardBuiltins: true }
+                )
+            }
             return CircuitJsonReadOnlyDocument.copyReadonlyExtensionValue(
                 candidate,
                 (snapshot) =>