circuitjson-toolkit 1.2.1 → 1.3.0

package/README.md

@@ -61,6 +61,14 @@ million structured items, while exact project envelopes receive independent
 per-document, project-metadata, aggregate-byte, and repeated-work limits. See
 the [1.2.1 release notes](docs/release-notes-v1.2.1.md).
 
+Version 1.3.0 adds an explicit fast preparation path for documents received
+through platform structured clone. Large native extension graphs can be owned
+without exception-driven binary probing of every ordinary record, while the
+general preparation path remains prototype-independent for arbitrary caller
+input. Cross-realm and altered-prototype buffers, typed views, byte limits,
+defensive copies, and all existing return shapes remain supported.
+See the [1.3.0 release notes](docs/release-notes-v1.3.0.md).
+
 Before 1.1.0:
 
 ```js
@@ -329,6 +337,7 @@ copy while keeping sync, direct async, and worker results mutation-isolated.
 - [1.1.2 release notes](docs/release-notes-v1.1.2.md)
 - [1.2.0 release notes](docs/release-notes-v1.2.0.md)
 - [1.2.1 release notes](docs/release-notes-v1.2.1.md)
+- [1.3.0 release notes](docs/release-notes-v1.3.0.md)
 - [Library scope](spec/library-scope.md)
 
 ## Package scope

package/docs/api.md

@@ -109,6 +109,28 @@ Validation, indexes, render primitives, and other derived values are cached by
 the context. Public outputs remain detached or immutable; a caller cannot
 mutate later results through a returned object.
 
+Hosts that receive a document from the platform structured-clone algorithm may
+use the explicit provenance-aware entry point:
+
+```js
+const context = CircuitJsonDocumentContext.prepareStructuredClone(
+    message.data,
+    {
+        indexes: ['elements', 'relations']
+    }
+)
+```
+
+`prepareStructuredClone()` has the same options, return type, validation,
+ownership, limits, and derived-cache behavior as `prepare()`. It avoids
+exception-driven raw-buffer brand checks for ordinary objects by relying on the
+standard local prototypes guaranteed by a completed platform structured clone.
+Use it only for the exact structured-cloned result (or a graph created entirely
+by the toolkit after that boundary). Use `prepare()` for arbitrary caller-owned,
+cross-realm, proxy-backed, or prototype-modified input. The general path keeps
+intrinsic binary slots authoritative and preserves altered-prototype
+`ArrayBuffer`, `SharedArrayBuffer`, typed-array, and `DataView` values.
+
 ## Root entrypoint
 
 `circuitjson-toolkit` has an exact 17-class root. The 14 canonical classes are:

package/docs/release-notes-v1.3.0.md

@@ -0,0 +1,45 @@
+# circuitjson-toolkit 1.3.0
+
+## Faster canonical extension ownership
+
+This minor release adds an explicit fast ownership path for large native
+extension graphs received through the platform structured-clone algorithm.
+Ordinary records, arrays, and standard local data containers are classified
+without deliberately invoking incompatible intrinsic getters, while genuine
+buffers and views still use captured platform slots as the final authority.
+
+The new `CircuitJsonDocumentContext.prepareStructuredClone(document, options?)`
+method has the same options and return shape as `prepare()`. It is intended for
+the exact result of a completed platform structured clone, or for a graph
+created entirely by the toolkit after that boundary. Hosts must continue to use
+`prepare()` for arbitrary caller-owned, cross-realm, proxy-backed, or
+prototype-modified input. The optimization is source-format-neutral and
+requires no example-specific handling.
+
+Measured on the deterministic standard-built-in metadata workload used during
+development, capturing 50,000 populated records fell from about 3.7 seconds to
+about 0.16 seconds. Browser timing for the combined library and ECAD Forge
+release is documented by the application release because network transfer,
+application interaction preparation, and SVG mounting are outside this
+library's ownership boundary.
+
+## Compatibility and API changes
+
+- No public class, package subpath, parameter, or return field is removed or
+  renamed.
+- `CircuitJsonDocumentContext.prepareStructuredClone(document, options?)` is a
+  new opt-in method for the explicit structured-clone provenance contract.
+- Parser, project, renderer, worker, and extension result shapes are unchanged.
+- The existing `prepare()` path remains exact and prototype-independent.
+  Cross-realm and altered-prototype `ArrayBuffer`, `SharedArrayBuffer`, typed
+  array, and `DataView` values, resizable buffers, byte ceilings, and
+  defensive-copy behavior are retained.
+- Proven standard plain-data graphs no longer generate caught exceptions merely
+  to prove that each ordinary node is not binary data.
+
+The new regression coverage pauses on every thrown exception in an isolated
+runtime, proving that a representative proven-standard metadata graph completes
+with zero binary-probe exceptions. Exact-path regressions cover altered and
+cross-realm binary objects plus proxy prototype traps. Existing adversarial and
+full-suite contracts continue to cover hostile accessors, worker parity,
+mutation isolation, and bounded extension ownership.

package/docs/testing.md

@@ -21,6 +21,13 @@ checked-in artifacts. Check mode is read-only. It also preserves upstream
 transform rejection boundaries, including malformed SI-unit strings that the
 upstream schema rejects by throwing instead of returning a failed parse.
 
+`npm test` first runs the benchmark contract in an uncontended process, then
+runs the functional test modules with normal Node test concurrency, and finally
+runs the remaining elapsed-time modules in isolated phases. This preserves
+complete test coverage while preventing unrelated CPU-heavy suites from
+contaminating timing comparisons. `npm test -- <node-test-arguments>` still
+forwards focused arguments directly to the Node test runner.
+
 The schema differential suite samples every upstream union leaf, compares
 required-field failures, exercises transform-owned resistor, capacitor,
 inductor, current-source, and crystal fields, and verifies that a fresh compile
@@ -92,6 +99,13 @@ round-trip behavior, and visible rejection beyond the separate 128 MiB
 extension payload ceiling. A 3 MiB binary regression additionally requires
 byte-backed `Uint8Array` shape, defensive-copy mutation isolation, direct and
 worker parity, bounded elapsed time, and bounded JavaScript heap growth.
+An isolated inspector regression pauses on all thrown exceptions and requires
+ordinary populated records and arrays in an explicitly proven standard-built-in
+graph to complete ownership without exception-driven binary probing. Separate
+exact-path regressions require cross-realm buffers, altered-prototype
+`ArrayBuffer` and `SharedArrayBuffer` values, altered view prototypes, and
+proxy-backed non-binary candidates to retain the prior prototype-independent
+behavior.
 
 Variant-geometry tests also lock rotation-local polygon-plated pad extents and
 pill drill dimensions, independent outer/drill rotations, and every legal

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "circuitjson-toolkit",
-    "version": "1.2.1",
+    "version": "1.3.0",
     "description": "Canonical CircuitJSON parsing, project, rendering, query, manufacturing, simulation, and scene contracts",
     "keywords": [
         "circuitjson",
@@ -55,6 +55,7 @@
         "docs/release-notes-v1.1.2.md",
         "docs/release-notes-v1.2.0.md",
         "docs/release-notes-v1.2.1.md",
+        "docs/release-notes-v1.3.0.md",
         "docs/testing.md",
         "spec",
         "LICENSE",
@@ -67,7 +68,7 @@
         "REUSE.toml"
     ],
     "scripts": {
-        "test": "node --test",
+        "test": "node scripts/run-tests.mjs",
         "format": "prettier --write .",
         "check:format": "prettier --check .",
         "sync:schema": "node scripts/sync-circuit-json-schema.mjs",

package/src/core/context/BinaryDataSnapshot.mjs

@@ -22,6 +22,10 @@ const TYPED_ARRAY_LENGTH = Object.getOwnPropertyDescriptor(
     TYPED_ARRAY_PROTOTYPE,
     'byteLength'
 )?.get
+const TYPED_ARRAY_TAG = Object.getOwnPropertyDescriptor(
+    TYPED_ARRAY_PROTOTYPE,
+    Symbol.toStringTag
+)?.get
 const DATA_VIEW_BUFFER = Object.getOwnPropertyDescriptor(
     DataView.prototype,
     'buffer'
@@ -34,7 +38,40 @@ const DATA_VIEW_LENGTH = Object.getOwnPropertyDescriptor(
     DataView.prototype,
     'byteLength'
 )?.get
+const ARRAY_BUFFER_IS_VIEW = ArrayBuffer.isView
+const ARRAY_IS_ARRAY = Array.isArray
+const OBJECT_GET_PROTOTYPE_OF = Object.getPrototypeOf
+const REFLECT_APPLY = Reflect.apply
+const ARRAY_BUFFER_PROTOTYPE = ArrayBuffer.prototype
+const SHARED_ARRAY_BUFFER_PROTOTYPE =
+    typeof SharedArrayBuffer === 'function' ? SharedArrayBuffer.prototype : null
+const ARRAY_PROTOTYPE = Array.prototype
+const OBJECT_PROTOTYPE = Object.prototype
+const DATE_PROTOTYPE = Date.prototype
+const REGEXP_PROTOTYPE = RegExp.prototype
+const MAP_PROTOTYPE = Map.prototype
+const SET_PROTOTYPE = Set.prototype
 const UINT8_ARRAY_SET = Uint8Array.prototype.set
+const TYPED_ARRAY_CONSTRUCTORS = new Map([
+    ['Int8Array', Int8Array],
+    ['Uint8Array', Uint8Array],
+    ['Uint8ClampedArray', Uint8ClampedArray],
+    ['Int16Array', Int16Array],
+    ['Uint16Array', Uint16Array],
+    ['Int32Array', Int32Array],
+    ['Uint32Array', Uint32Array],
+    ...(typeof globalThis.Float16Array === 'function'
+        ? [['Float16Array', globalThis.Float16Array]]
+        : []),
+    ['Float32Array', Float32Array],
+    ['Float64Array', Float64Array],
+    ...(typeof BigInt64Array === 'function'
+        ? [
+              ['BigInt64Array', BigInt64Array],
+              ['BigUint64Array', BigUint64Array]
+          ]
+        : [])
+])
 
 /**
  * Reads and copies binary platform objects through captured intrinsic slots.
@@ -46,6 +83,104 @@ export class BinaryDataSnapshot {
      * @returns {{ buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, byteLength: number, kind: 'buffer' | 'typed-array' | 'data-view' } | null} Intrinsic binary range.
      */
     static describe(value) {
+        return BinaryDataSnapshot.#describe(value, false)
+    }
+
+    /**
+     * Describes binary data in a graph whose platform built-ins are proven to
+     * have their standard local prototypes.
+     * @param {unknown} value Binary candidate from a normalized graph.
+     * @returns {{ buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, byteLength: number, kind: 'buffer' | 'typed-array' | 'data-view' } | null} Intrinsic binary range.
+     */
+    static describeStandard(value) {
+        return BinaryDataSnapshot.#describe(value, true)
+    }
+
+    /**
+     * Classifies one binary candidate with either exact or proven-standard
+     * raw-buffer handling.
+     * @param {unknown} value Binary candidate.
+     * @param {boolean} standardBuiltins Whether local prototype identity is proven.
+     * @returns {{ buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, byteLength: number, kind: 'buffer' | 'typed-array' | 'data-view' } | null} Intrinsic binary range.
+     */
+    static #describe(value, standardBuiltins) {
+        if (value === null || typeof value !== 'object') return null
+
+        if (BinaryDataSnapshot.#isView(value)) {
+            const typed = BinaryDataSnapshot.#view(
+                value,
+                TYPED_ARRAY_BUFFER,
+                TYPED_ARRAY_OFFSET,
+                TYPED_ARRAY_LENGTH,
+                'typed-array'
+            )
+            if (typed) return typed
+            return BinaryDataSnapshot.#view(
+                value,
+                DATA_VIEW_BUFFER,
+                DATA_VIEW_OFFSET,
+                DATA_VIEW_LENGTH,
+                'data-view'
+            )
+        }
+
+        if (!standardBuiltins) {
+            return BinaryDataSnapshot.#rawBuffer(value)
+        }
+
+        let prototype
+        try {
+            prototype = OBJECT_GET_PROTOTYPE_OF(value)
+        } catch {
+            return null
+        }
+
+        if (prototype === ARRAY_BUFFER_PROTOTYPE) {
+            const byteLength = BinaryDataSnapshot.#callLength(
+                ARRAY_BUFFER_LENGTH,
+                value
+            )
+            return byteLength === null
+                ? null
+                : {
+                      buffer: value,
+                      byteOffset: 0,
+                      byteLength,
+                      kind: 'buffer'
+                  }
+        }
+        if (
+            SHARED_ARRAY_BUFFER_PROTOTYPE &&
+            prototype === SHARED_ARRAY_BUFFER_PROTOTYPE
+        ) {
+            const byteLength = BinaryDataSnapshot.#callLength(
+                SHARED_ARRAY_BUFFER_LENGTH,
+                value
+            )
+            return byteLength === null
+                ? null
+                : {
+                      buffer: value,
+                      byteOffset: 0,
+                      byteLength,
+                      kind: 'buffer'
+                  }
+        }
+        if (BinaryDataSnapshot.#isKnownNonBinary(value, prototype)) {
+            return null
+        }
+
+        // Unknown prototypes can represent genuine buffers from another realm.
+        // Keep intrinsic brand checks as the authority for that uncommon path.
+        return BinaryDataSnapshot.#rawBuffer(value)
+    }
+
+    /**
+     * Applies exact raw ArrayBuffer and SharedArrayBuffer brand getters.
+     * @param {object} value Raw-buffer candidate.
+     * @returns {{ buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: 0, byteLength: number, kind: 'buffer' } | null} Raw buffer range.
+     */
+    static #rawBuffer(value) {
         const arrayBufferLength = BinaryDataSnapshot.#callLength(
             ARRAY_BUFFER_LENGTH,
             value
@@ -71,21 +206,7 @@ export class BinaryDataSnapshot {
             }
         }
 
-        const typed = BinaryDataSnapshot.#view(
-            value,
-            TYPED_ARRAY_BUFFER,
-            TYPED_ARRAY_OFFSET,
-            TYPED_ARRAY_LENGTH,
-            'typed-array'
-        )
-        if (typed) return typed
-        return BinaryDataSnapshot.#view(
-            value,
-            DATA_VIEW_BUFFER,
-            DATA_VIEW_OFFSET,
-            DATA_VIEW_LENGTH,
-            'data-view'
-        )
+        return null
     }
 
     /**
@@ -133,8 +254,7 @@ export class BinaryDataSnapshot {
         if (range.kind === 'buffer') return bytes.buffer
         if (range.kind === 'data-view') return new DataView(bytes.buffer)
 
-        const prototype = Object.getPrototypeOf(value)
-        const Constructor = BinaryDataSnapshot.#typedArrayConstructor(prototype)
+        const Constructor = BinaryDataSnapshot.#typedArrayConstructor(value)
         if (!Constructor || Constructor === Uint8Array) return bytes
         const bytesPerElement = Constructor.BYTES_PER_ELEMENT
         if (bytes.byteLength % bytesPerElement !== 0) return bytes
@@ -150,12 +270,44 @@ export class BinaryDataSnapshot {
     static #callLength(getter, value) {
         if (typeof getter !== 'function') return null
         try {
-            return getter.call(value)
+            return REFLECT_APPLY(getter, value, [])
         } catch {
             return null
         }
     }
 
+    /**
+     * Uses the platform's side-effect-free view brand classifier.
+     * @param {unknown} value Candidate value.
+     * @returns {boolean} Whether the value has ArrayBuffer view slots.
+     */
+    static #isView(value) {
+        try {
+            return REFLECT_APPLY(ARRAY_BUFFER_IS_VIEW, ArrayBuffer, [value])
+        } catch {
+            return false
+        }
+    }
+
+    /**
+     * Returns true for common local containers that cannot be binary objects.
+     * @param {object} value Candidate object.
+     * @param {object | null} prototype Captured prototype.
+     * @returns {boolean} Whether intrinsic buffer probing can be skipped.
+     */
+    static #isKnownNonBinary(value, prototype) {
+        return (
+            ARRAY_IS_ARRAY(value) ||
+            prototype === ARRAY_PROTOTYPE ||
+            prototype === OBJECT_PROTOTYPE ||
+            prototype === null ||
+            prototype === DATE_PROTOTYPE ||
+            prototype === REGEXP_PROTOTYPE ||
+            prototype === MAP_PROTOTYPE ||
+            prototype === SET_PROTOTYPE
+        )
+    }
+
     /**
      * Reads captured intrinsic view slots without ordinary property access.
      * @param {unknown} value View candidate.
@@ -175,9 +327,9 @@ export class BinaryDataSnapshot {
         }
         try {
             return {
-                buffer: bufferGetter.call(value),
-                byteOffset: offsetGetter.call(value),
-                byteLength: lengthGetter.call(value),
+                buffer: REFLECT_APPLY(bufferGetter, value, []),
+                byteOffset: REFLECT_APPLY(offsetGetter, value, []),
+                byteLength: REFLECT_APPLY(lengthGetter, value, []),
                 kind
             }
         } catch {
@@ -186,30 +338,18 @@ export class BinaryDataSnapshot {
     }
 
     /**
-     * Maps a genuine typed-array prototype to its platform constructor.
-     * @param {object | null} prototype Candidate prototype.
+     * Maps a genuine typed array's intrinsic tag to a local constructor.
+     * @param {unknown} value Genuine typed-array value.
      * @returns {Function | null} Matching typed-array constructor.
      */
-    static #typedArrayConstructor(prototype) {
-        const constructors = [
-            Int8Array,
-            Uint8Array,
-            Uint8ClampedArray,
-            Int16Array,
-            Uint16Array,
-            Int32Array,
-            Uint32Array,
-            Float32Array,
-            Float64Array,
-            ...(typeof BigInt64Array === 'function'
-                ? [BigInt64Array, BigUint64Array]
-                : [])
-        ]
-        return (
-            constructors.find(
-                (Constructor) => Constructor.prototype === prototype
-            ) || null
-        )
+    static #typedArrayConstructor(value) {
+        if (typeof TYPED_ARRAY_TAG !== 'function') return null
+        try {
+            const tag = REFLECT_APPLY(TYPED_ARRAY_TAG, value, [])
+            return TYPED_ARRAY_CONSTRUCTORS.get(tag) || null
+        } catch {
+            return null
+        }
     }
 }
 

package/src/core/context/CircuitJsonDocumentContext.mjs

@@ -74,9 +74,31 @@ export class CircuitJsonDocumentContext {
      * @returns {CircuitJsonDocumentContext} Prepared request-scoped context.
      */
     static prepare(input, options = {}) {
+        return CircuitJsonDocumentContext.#prepare(input, options, false)
+    }
+
+    /**
+     * Prepares a document whose platform built-ins were normalized by the
+     * structured-clone algorithm.
+     * @param {unknown} input Structured-cloned document result or existing context.
+     * @param {{ indexes?: unknown }} [options] Requested context options.
+     * @returns {CircuitJsonDocumentContext} Prepared request-scoped context.
+     */
+    static prepareStructuredClone(input, options = {}) {
+        return CircuitJsonDocumentContext.#prepare(input, options, true)
+    }
+
+    /**
+     * Prepares one context with explicit metadata provenance.
+     * @param {unknown} input Document result, CircuitJSON model, or context.
+     * @param {{ indexes?: unknown }} options Requested context options.
+     * @param {boolean} standardBuiltins Whether metadata built-ins have standard local prototypes.
+     * @returns {CircuitJsonDocumentContext} Prepared request-scoped context.
+     */
+    static #prepare(input, options, standardBuiltins) {
         const context = CircuitJsonDocumentContext.#isContext(input)
             ? input
-            : CircuitJsonDocumentContext.#fromInput(input)
+            : CircuitJsonDocumentContext.#fromInput(input, standardBuiltins)
         context.#indexes.ensure(options?.indexes || [])
         return context
     }
@@ -181,15 +203,20 @@ export class CircuitJsonDocumentContext {
     /**
      * Creates one context and establishes a matching immutable model proof.
      * @param {unknown} input Document result or CircuitJSON model.
+     * @param {boolean} standardBuiltins Whether metadata built-ins have standard local prototypes.
      * @returns {CircuitJsonDocumentContext} New context.
      */
-    static #fromInput(input) {
+    static #fromInput(input, standardBuiltins) {
         const document = CircuitJsonDocumentContext.#normalizeDocument(input)
         const validationPasses = CircuitJsonValidationProof.has(document)
             ? 0
             : 1
-        const readonlyDocument =
-            CircuitJsonValidationProof.validateAndAttach(document)
+        const readonlyDocument = CircuitJsonValidationProof.validateAndAttach(
+            document,
+            {
+                standardBuiltins
+            }
+        )
         const model = CircuitJsonDocumentContext.#ownData(
             readonlyDocument,
             'model'

package/src/core/context/CircuitJsonReadOnlyDocument.mjs

@@ -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)
         }