circuitjson-toolkit 1.2.0 → 1.3.0

package/src/core/context/CircuitJsonReadOnlyDocument.mjs

@@ -13,7 +13,7 @@ const METADATA_BUDGETS = new WeakMap()
 const EXTENSION_METADATA_LIMITS = Object.freeze({
     label: 'Canonical extension data',
     maxBytes: 128 * 1024 * 1024,
-    maxItems: 2_000_000,
+    maxItems: 4_000_000,
     preserveBinary: true
 })
 const ASSET_SCALAR_FIELDS = new Set([
@@ -41,9 +41,10 @@ export class CircuitJsonReadOnlyDocument {
      * Seals an envelope whose exact model was already deeply frozen by validation.
      * @param {Record<string, any>} document Canonical document envelope.
      * @param {object[]} model Exact deeply frozen model owned by the proof.
+     * @param {{ standardBuiltins?: boolean }} [options] Proven metadata provenance.
      * @returns {Record<string, any>} The same read-only envelope.
      */
-    static freezeValidated(document, model) {
+    static freezeValidated(document, model, options = {}) {
         if (!CircuitJsonValidationAuthority.permitsSeal(model)) {
             throw new TypeError(
                 'Validated document sealing requires an unforgeable validation proof.'
@@ -76,7 +77,8 @@ export class CircuitJsonReadOnlyDocument {
         }
         return CircuitJsonReadOnlyDocument.#freezeDocument(
             document,
-            frozenRoots
+            frozenRoots,
+            options?.standardBuiltins === true
         )
     }
 
@@ -84,14 +86,18 @@ export class CircuitJsonReadOnlyDocument {
      * Captures owned boundaries and freezes an envelope with known frozen roots.
      * @param {Record<string, any>} document Canonical document envelope.
      * @param {Set<object>} frozenRoots Deeply frozen roots that need no revisit.
+     * @param {boolean} [standardBuiltins] Whether extension built-ins have proven standard prototypes.
      * @returns {Record<string, any>} The same read-only envelope.
      */
-    static #freezeDocument(document, frozenRoots) {
+    static #freezeDocument(document, frozenRoots, standardBuiltins = false) {
         const assets = CircuitJsonReadOnlyDocument.#documentAssets(document)
         const metadataState = StructuredDataSnapshot.createState()
         CircuitJsonReadOnlyDocument.#captureAssetData(assets, metadataState)
         const extensions =
-            CircuitJsonReadOnlyDocument.#captureDocumentExtensions(document)
+            CircuitJsonReadOnlyDocument.#captureDocumentExtensions(
+                document,
+                standardBuiltins
+            )
         if (extensions && typeof extensions === 'object') {
             frozenRoots.add(extensions)
         }
@@ -199,9 +205,10 @@ export class CircuitJsonReadOnlyDocument {
      * transfer-sized item and byte ceilings.
      * @param {unknown} value Extension candidate.
      * @param {((snapshot: unknown) => unknown) | null} [normalize] Optional normalization over the owned mutable snapshot.
+     * @param {{ standardBuiltins?: boolean }} [options] Proven source-graph provenance.
      * @returns {unknown} Deeply immutable owned extension metadata.
      */
-    static copyReadonlyExtensionValue(value, normalize = null) {
+    static copyReadonlyExtensionValue(value, normalize = null, options = {}) {
         if (
             value &&
             typeof value === 'object' &&
@@ -216,7 +223,10 @@ export class CircuitJsonReadOnlyDocument {
         }
         const snapshot = StructuredDataSnapshot.capture(
             value,
-            StructuredDataSnapshot.createState(EXTENSION_METADATA_LIMITS)
+            StructuredDataSnapshot.createState({
+                ...EXTENSION_METADATA_LIMITS,
+                standardBuiltins: options?.standardBuiltins === true
+            })
         )
         ProtectedExtensionBinaryBoundary.protect(snapshot)
         const normalized = normalize ? normalize(snapshot) : snapshot
@@ -327,9 +337,10 @@ export class CircuitJsonReadOnlyDocument {
      * Captures an unowned worker or caller extension root with extension-sized
      * bounds before the generic source metadata pass begins.
      * @param {Record<string, any>} document Canonical document envelope.
+     * @param {boolean} standardBuiltins Whether extension built-ins have proven standard prototypes.
      * @returns {unknown} Owned extension root or undefined.
      */
-    static #captureDocumentExtensions(document) {
+    static #captureDocumentExtensions(document, standardBuiltins) {
         let descriptor
         try {
             descriptor = Object.getOwnPropertyDescriptor(document, 'extensions')
@@ -345,7 +356,9 @@ export class CircuitJsonReadOnlyDocument {
             )
         }
         const captured = CircuitJsonReadOnlyDocument.copyReadonlyExtensionValue(
-            descriptor.value
+            descriptor.value,
+            null,
+            { standardBuiltins }
         )
         if (captured === descriptor.value) return captured
         Object.defineProperty(document, 'extensions', {

package/src/core/context/CircuitJsonValidationProof.mjs

@@ -53,9 +53,10 @@ export class CircuitJsonValidationProof {
     /**
      * Validates, freezes, and proves one canonical document envelope.
      * @param {Record<string, any>} document Canonical document envelope.
+     * @param {{ standardBuiltins?: boolean }} [options] Proven metadata provenance.
      * @returns {Record<string, any>} The same read-only document envelope.
      */
-    static validateAndAttach(document) {
+    static validateAndAttach(document, options = {}) {
         const model = CircuitJsonValidationProof.#requireModelData(document)
         if (!CircuitJsonValidationProof.#matches(document, model)) {
             const errors =
@@ -80,7 +81,8 @@ export class CircuitJsonValidationProof {
         }
         const readonlyDocument = CircuitJsonReadOnlyDocument.freezeValidated(
             document,
-            model
+            model,
+            options
         )
         if (
             CircuitJsonValidationProof.#requireModelData(readonlyDocument) !==

package/src/core/context/ProtectedExtensionBinaryBoundary.mjs

@@ -12,7 +12,7 @@ export class ProtectedExtensionBinaryBoundary {
      * @returns {void}
      */
     static protect(root) {
-        if (BinaryDataSnapshot.describe(root)) {
+        if (BinaryDataSnapshot.describeStandard(root)) {
             throw new TypeError(
                 'Canonical extension root must be a plain data container.'
             )
@@ -51,7 +51,7 @@ export class ProtectedExtensionBinaryBoundary {
                     stack.push(child)
                     continue
                 }
-                const binary = BinaryDataSnapshot.describe(child)
+                const binary = BinaryDataSnapshot.describeStandard(child)
                 if (!binary) continue
                 const ownedBinary = child
                 /** @returns {ArrayBuffer | Uint8Array | DataView} A defensive binary copy. */

package/src/core/context/StructuredDataSnapshot.mjs

@@ -26,8 +26,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 +52,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,7 +72,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.')
         }
@@ -93,7 +95,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 +227,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)
         }