circuitjson-toolkit 1.2.1 → 1.4.0

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
     }
 
     /**
@@ -120,6 +241,44 @@ export class BinaryDataSnapshot {
         }
     }
 
+    /**
+     * Copies one bounded byte range into an existing isolated byte array.
+     * @param {{ buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, byteLength: number }} range Captured intrinsic range.
+     * @param {Uint8Array} target Isolated destination bytes.
+     * @param {number} offset Visible-range byte offset.
+     * @param {number} count Number of bytes to copy.
+     * @returns {void}
+     * @internal
+     */
+    static copyBytesInto(range, target, offset, count) {
+        if (
+            !(target instanceof Uint8Array) ||
+            !Number.isSafeInteger(offset) ||
+            !Number.isSafeInteger(count) ||
+            offset < 0 ||
+            count < 0 ||
+            offset + count > range?.byteLength ||
+            target.byteLength !== range?.byteLength
+        ) {
+            throw new TypeError('Invalid binary copy range.')
+        }
+        try {
+            const source = new Uint8Array(
+                range.buffer,
+                range.byteOffset + offset,
+                count
+            )
+            const destination = new Uint8Array(
+                target.buffer,
+                target.byteOffset + offset,
+                count
+            )
+            UINT8_ARRAY_SET.call(destination, source)
+        } catch {
+            throw new TypeError('Binary data changed during capture.')
+        }
+    }
+
     /**
      * Copies one binary metadata value while retaining its common view type.
      * @param {unknown} value Binary metadata.
@@ -133,8 +292,28 @@ 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
+        return new Constructor(bytes.buffer)
+    }
+
+    /**
+     * Restores one common binary view type from completely isolated bytes.
+     * @param {unknown} value Original binary value used only for view type.
+     * @param {{ kind: 'buffer' | 'typed-array' | 'data-view' }} range Captured intrinsic kind.
+     * @param {Uint8Array} bytes Completely copied isolated bytes.
+     * @returns {ArrayBuffer | Uint8Array | DataView} Isolated binary clone.
+     * @internal
+     */
+    static cloneFromBytes(value, range, bytes) {
+        if (!(bytes instanceof Uint8Array)) {
+            throw new TypeError('Expected isolated binary bytes.')
+        }
+        if (range.kind === 'buffer') return bytes.buffer
+        if (range.kind === 'data-view') return new DataView(bytes.buffer)
+        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 +329,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 +386,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 +397,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,56 @@ 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)
+    }
+
+    /**
+     * Destructively adopts an exclusively transferred structured-clone graph
+     * while allowing hosts to service input and paint between bounded slices.
+     * @param {unknown} input Structured-cloned document result or existing context.
+     * @param {{ indexes?: unknown, ownership: 'exclusive', yield?: () => Promise<void> | void }} [options] Requested indexes, required exclusive ownership authority, and host scheduler.
+     * @returns {Promise<CircuitJsonDocumentContext>} Prepared request-scoped context.
+     */
+    static async prepareStructuredCloneAsync(input, options = {}) {
+        if (CircuitJsonDocumentContext.#isContext(input)) {
+            return CircuitJsonDocumentContext.#prepare(input, options, true)
+        }
+        if (options?.ownership !== 'exclusive') {
+            throw new TypeError(
+                'Cooperative structured-clone preparation requires exclusive ownership.'
+            )
+        }
+        const context = await CircuitJsonDocumentContext.#fromInputAsync(
+            input,
+            true,
+            options?.yield
+        )
+        context.#indexes.ensure(options?.indexes || [])
+        return context
+    }
+
+    /**
+     * 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 +228,50 @@ 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,
+            {
+                standardBuiltins
+            }
+        )
+        const model = CircuitJsonDocumentContext.#ownData(
+            readonlyDocument,
+            'model'
+        )
+        return new CircuitJsonDocumentContext(
+            readonlyDocument,
+            model,
+            validationPasses,
+            CONTEXT_CONSTRUCTION_AUTHORITY
+        )
+    }
+
+    /**
+     * Creates one context while yielding between model validation and envelope
+     * sealing for a proven structured-clone graph.
+     * @param {unknown} input Document result or CircuitJSON model.
+     * @param {boolean} standardBuiltins Whether metadata built-ins have standard local prototypes.
+     * @param {(() => Promise<void> | void) | undefined} yieldControl Host scheduler.
+     * @returns {Promise<CircuitJsonDocumentContext>} New context.
+     */
+    static async #fromInputAsync(input, standardBuiltins, yieldControl) {
         const document = CircuitJsonDocumentContext.#normalizeDocument(input)
         const validationPasses = CircuitJsonValidationProof.has(document)
             ? 0
             : 1
         const readonlyDocument =
-            CircuitJsonValidationProof.validateAndAttach(document)
+            await CircuitJsonValidationProof.validateAndAttachAsync(document, {
+                standardBuiltins,
+                yield: yieldControl
+            })
         const model = CircuitJsonDocumentContext.#ownData(
             readonlyDocument,
             'model'