circuitjson-toolkit 1.3.0 → 1.4.0

package/src/core/context/CircuitJsonExtensionBoundary.mjs

@@ -0,0 +1,312 @@
+import { BinaryDataSnapshot } from './BinaryDataSnapshot.mjs'
+import { ProtectedExtensionBinaryBoundary } from './ProtectedExtensionBinaryBoundary.mjs'
+import { StructuredDataSnapshot } from './StructuredDataSnapshot.mjs'
+
+const OWNED_EXTENSION_ROOTS = new WeakSet()
+const EXTENSION_METADATA_LIMITS = Object.freeze({
+    label: 'Canonical extension data',
+    maxBytes: 128 * 1024 * 1024,
+    maxItems: 4_000_000,
+    preserveBinary: true
+})
+
+/**
+ * Owns and seals canonical extension graphs independently of document fields.
+ */
+export class CircuitJsonExtensionBoundary {
+    /**
+     * Returns whether an object is an already owned extension root.
+     * @param {unknown} value Extension candidate.
+     * @returns {boolean} Whether this boundary owns the root.
+     */
+    static owns(value) {
+        return Boolean(
+            value &&
+            typeof value === 'object' &&
+            OWNED_EXTENSION_ROOTS.has(value)
+        )
+    }
+
+    /**
+     * Creates one deeply frozen source-extension snapshot.
+     * @param {unknown} value Extension candidate.
+     * @param {((snapshot: unknown) => unknown) | null} [normalize] Optional normalizer.
+     * @param {{ standardBuiltins?: boolean }} [options] Proven graph provenance.
+     * @returns {unknown} Deeply immutable owned extension metadata.
+     */
+    static copyReadonly(value, normalize = null, options = {}) {
+        if (
+            CircuitJsonExtensionBoundary.owns(value) &&
+            Object.isFrozen(value) &&
+            normalize === null
+        ) {
+            return value
+        }
+        if (normalize !== null && typeof normalize !== 'function') {
+            throw new TypeError('Extension normalizer must be a function.')
+        }
+        const standardBuiltins = options?.standardBuiltins === true
+        const state = StructuredDataSnapshot.createState({
+            ...EXTENSION_METADATA_LIMITS,
+            standardBuiltins
+        })
+        const snapshot = standardBuiltins
+            ? StructuredDataSnapshot.adoptStructuredClone(value, state)
+            : StructuredDataSnapshot.capture(value, state)
+        CircuitJsonExtensionBoundary.#rejectBinaryRoot(snapshot)
+        const adoption = standardBuiltins
+            ? StructuredDataSnapshot.consumeStructuredCloneAdoption(snapshot)
+            : null
+        if (adoption && normalize === null) {
+            StructuredDataSnapshot.sealStructuredCloneAdoption(adoption)
+        } else {
+            ProtectedExtensionBinaryBoundary.protect(snapshot)
+        }
+        const normalized = normalize ? normalize(snapshot) : snapshot
+        if (normalized !== snapshot) {
+            ProtectedExtensionBinaryBoundary.protect(normalized)
+        }
+        if (!adoption || normalize !== null) {
+            CircuitJsonExtensionBoundary.#freezeValue(normalized)
+        }
+        CircuitJsonExtensionBoundary.#markOwned(normalized)
+        return normalized
+    }
+
+    /**
+     * Cooperatively adopts one structured-clone extension graph.
+     * @param {unknown} value Extension candidate.
+     * @param {{ standardBuiltins?: boolean, yield: () => Promise<void> | void }} options Proven provenance and host scheduler.
+     * @returns {Promise<unknown>} Deeply immutable owned extension metadata.
+     */
+    static async copyReadonlyAsync(value, options) {
+        if (
+            CircuitJsonExtensionBoundary.owns(value) &&
+            Object.isFrozen(value)
+        ) {
+            return value
+        }
+        if (
+            options?.standardBuiltins !== true ||
+            typeof options?.yield !== 'function'
+        ) {
+            return CircuitJsonExtensionBoundary.copyReadonly(
+                value,
+                null,
+                options
+            )
+        }
+        const state = StructuredDataSnapshot.createState({
+            ...EXTENSION_METADATA_LIMITS,
+            standardBuiltins: true
+        })
+        const snapshot = await StructuredDataSnapshot.adoptStructuredCloneAsync(
+            value,
+            state,
+            options.yield
+        )
+        CircuitJsonExtensionBoundary.#rejectBinaryRoot(snapshot)
+        CircuitJsonExtensionBoundary.#markOwned(snapshot)
+        return snapshot
+    }
+
+    /**
+     * Captures one document extension field synchronously.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {boolean} standardBuiltins Whether built-ins have local prototypes.
+     * @returns {unknown} Owned extension root or undefined.
+     */
+    static captureDocument(document, standardBuiltins) {
+        const descriptor =
+            CircuitJsonExtensionBoundary.#documentDescriptor(document)
+        if (!descriptor) return undefined
+        const captured = CircuitJsonExtensionBoundary.copyReadonly(
+            descriptor.value,
+            null,
+            { standardBuiltins }
+        )
+        if (captured === descriptor.value) return captured
+        Object.defineProperty(document, 'extensions', {
+            ...descriptor,
+            value: captured
+        })
+        return captured
+    }
+
+    /**
+     * Cooperatively captures a document extension field and rejects replacement
+     * races across scheduling boundaries.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {boolean} standardBuiltins Whether built-ins have local prototypes.
+     * @param {() => Promise<void> | void} yieldControl Host scheduler.
+     * @returns {Promise<unknown>} Owned extension root or undefined.
+     */
+    static async captureDocumentAsync(
+        document,
+        standardBuiltins,
+        yieldControl
+    ) {
+        const descriptor =
+            CircuitJsonExtensionBoundary.#documentDescriptor(document)
+        if (!descriptor) return undefined
+        const captured = await CircuitJsonExtensionBoundary.copyReadonlyAsync(
+            descriptor.value,
+            {
+                standardBuiltins,
+                yield: yieldControl
+            }
+        )
+        const current =
+            CircuitJsonExtensionBoundary.#documentDescriptor(document)
+        if (
+            !current ||
+            !CircuitJsonExtensionBoundary.#sameDataDescriptor(
+                current,
+                descriptor
+            )
+        ) {
+            throw new TypeError(
+                'Canonical document extensions changed during adoption.'
+            )
+        }
+        if (captured === descriptor.value) return captured
+        Object.defineProperty(document, 'extensions', {
+            ...descriptor,
+            value: captured
+        })
+        return captured
+    }
+
+    /**
+     * Reads and validates the optional document extension descriptor.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @returns {PropertyDescriptor | undefined} Extension descriptor.
+     */
+    static #documentDescriptor(document) {
+        let descriptor
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(document, 'extensions')
+        } catch {
+            throw new TypeError(
+                'Canonical document extensions could not be inspected safely.'
+            )
+        }
+        if (descriptor && !Object.hasOwn(descriptor, 'value')) {
+            throw new TypeError(
+                'Canonical document extensions must be an own data property.'
+            )
+        }
+        return descriptor
+    }
+
+    /**
+     * Rejects unsupported binary extension roots.
+     * @param {unknown} value Extension root.
+     * @returns {void}
+     */
+    static #rejectBinaryRoot(value) {
+        if (BinaryDataSnapshot.describeStandard(value)) {
+            throw new TypeError(
+                'Canonical extension root must be a plain data container.'
+            )
+        }
+    }
+
+    /**
+     * Marks one object root as owned by this boundary.
+     * @param {unknown} value Extension root.
+     * @returns {void}
+     */
+    static #markOwned(value) {
+        if (value && typeof value === 'object') {
+            OWNED_EXTENSION_ROOTS.add(value)
+        }
+    }
+
+    /**
+     * Deeply freezes one captured plain-data graph.
+     * @param {unknown} value Captured graph.
+     * @returns {void}
+     */
+    static #freezeValue(value) {
+        const seen = new Set()
+        const stack = [{ exit: false, value }]
+        while (stack.length) {
+            const frame = stack.pop()
+            const current = frame.value
+            if (frame.exit) {
+                try {
+                    Object.freeze(current)
+                } catch {
+                    throw new TypeError(
+                        'Canonical document values could not be frozen safely.'
+                    )
+                }
+                continue
+            }
+            if (!CircuitJsonExtensionBoundary.#container(current)) continue
+            if (seen.has(current)) continue
+            seen.add(current)
+            let descriptors
+            try {
+                descriptors = Object.getOwnPropertyDescriptors(current)
+            } catch {
+                throw new TypeError(
+                    'Canonical document values could not be inspected safely.'
+                )
+            }
+            const children = []
+            for (const descriptor of Object.values(descriptors)) {
+                if (!Object.hasOwn(descriptor, 'value')) {
+                    if (
+                        ProtectedExtensionBinaryBoundary.isProtected(descriptor)
+                    ) {
+                        continue
+                    }
+                    throw new TypeError(
+                        'Canonical document may contain only data properties.'
+                    )
+                }
+                children.push(descriptor.value)
+            }
+            stack.push({ exit: true, value: current })
+            for (let index = children.length - 1; index >= 0; index -= 1) {
+                stack.push({ exit: false, value: children[index] })
+            }
+        }
+    }
+
+    /**
+     * Returns true for plain extension containers.
+     * @param {unknown} value Candidate value.
+     * @returns {boolean} Whether the value is a plain container.
+     */
+    static #container(value) {
+        if (!value || typeof value !== 'object') return false
+        if (Array.isArray(value)) {
+            return Object.getPrototypeOf(value) === Array.prototype
+        }
+        const prototype = Object.getPrototypeOf(value)
+        return prototype === Object.prototype || prototype === null
+    }
+
+    /**
+     * Compares exact ordinary data descriptor semantics.
+     * @param {PropertyDescriptor} current Current descriptor.
+     * @param {PropertyDescriptor} expected Captured descriptor.
+     * @returns {boolean} Whether both descriptors match.
+     */
+    static #sameDataDescriptor(current, expected) {
+        return Boolean(
+            Object.hasOwn(current, 'value') &&
+            Object.hasOwn(expected, 'value') &&
+            Object.is(current.value, expected.value) &&
+            current.configurable === expected.configurable &&
+            current.enumerable === expected.enumerable &&
+            current.writable === expected.writable
+        )
+    }
+}
+
+Object.freeze(CircuitJsonExtensionBoundary.prototype)
+Object.freeze(CircuitJsonExtensionBoundary)

package/src/core/context/CircuitJsonReadOnlyDocument.mjs

@@ -1,4 +1,5 @@
 import { BinaryDataSnapshot } from './BinaryDataSnapshot.mjs'
+import { CircuitJsonExtensionBoundary } from './CircuitJsonExtensionBoundary.mjs'
 import { CircuitJsonMetadataBoundary } from './CircuitJsonMetadataBoundary.mjs'
 import { CircuitJsonValidationAuthority } from './CircuitJsonValidationAuthority.mjs'
 import { ProtectedExtensionBinaryBoundary } from './ProtectedExtensionBinaryBoundary.mjs'
@@ -10,12 +11,6 @@ const SEALED_ASSETS = new WeakSet()
 const ASSET_PAYLOAD_LENGTHS = new WeakMap()
 const OWNED_METADATA_ROOTS = new WeakSet()
 const METADATA_BUDGETS = new WeakMap()
-const EXTENSION_METADATA_LIMITS = Object.freeze({
-    label: 'Canonical extension data',
-    maxBytes: 128 * 1024 * 1024,
-    maxItems: 4_000_000,
-    preserveBinary: true
-})
 const ASSET_SCALAR_FIELDS = new Set([
     'id',
     'kind',
@@ -82,6 +77,53 @@ export class CircuitJsonReadOnlyDocument {
         )
     }
 
+    /**
+     * Cooperatively seals an envelope whose exact model is already validated.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {object[]} model Exact deeply frozen model owned by the proof.
+     * @param {{ standardBuiltins?: boolean, yield: () => Promise<void> | void }} options Proven provenance and host scheduler.
+     * @returns {Promise<Record<string, any>>} The same read-only envelope.
+     */
+    static async freezeValidatedAsync(document, model, options) {
+        if (!CircuitJsonValidationAuthority.permitsSeal(model)) {
+            throw new TypeError(
+                'Validated document sealing requires an unforgeable validation proof.'
+            )
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(document, 'model')
+        if (
+            !descriptor ||
+            !Object.hasOwn(descriptor, 'value') ||
+            descriptor.value !== model ||
+            !Array.isArray(model) ||
+            !Object.isFrozen(model) ||
+            typeof options?.yield !== 'function'
+        ) {
+            throw new TypeError(
+                'Validated document sealing requires its exact frozen model.'
+            )
+        }
+        const frozenRoots = new Set([model])
+        const sourceReference = Object.getOwnPropertyDescriptor(
+            document,
+            'sourceReference'
+        )
+        if (
+            sourceReference &&
+            Object.hasOwn(sourceReference, 'value') &&
+            sourceReference.value &&
+            typeof sourceReference.value === 'object'
+        ) {
+            frozenRoots.add(sourceReference.value)
+        }
+        return CircuitJsonReadOnlyDocument.#freezeDocumentAsync(
+            document,
+            frozenRoots,
+            options?.standardBuiltins === true,
+            options.yield
+        )
+    }
+
     /**
      * Captures owned boundaries and freezes an envelope with known frozen roots.
      * @param {Record<string, any>} document Canonical document envelope.
@@ -111,6 +153,43 @@ export class CircuitJsonReadOnlyDocument {
         return document
     }
 
+    /**
+     * Captures ordinary document boundaries while adopting extensions in
+     * bounded work slices.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {Set<object>} frozenRoots Deeply frozen roots.
+     * @param {boolean} standardBuiltins Whether built-ins have local prototypes.
+     * @param {() => Promise<void> | void} yieldControl Host scheduler.
+     * @returns {Promise<Record<string, any>>} The same read-only envelope.
+     */
+    static async #freezeDocumentAsync(
+        document,
+        frozenRoots,
+        standardBuiltins,
+        yieldControl
+    ) {
+        const assets = CircuitJsonReadOnlyDocument.#documentAssets(document)
+        const metadataState = StructuredDataSnapshot.createState()
+        CircuitJsonReadOnlyDocument.#captureAssetData(assets, metadataState)
+        const extensions =
+            await CircuitJsonReadOnlyDocument.#captureDocumentExtensionsAsync(
+                document,
+                standardBuiltins,
+                yieldControl
+            )
+        if (extensions && typeof extensions === 'object') {
+            frozenRoots.add(extensions)
+        }
+        CircuitJsonMetadataBoundary.normalize(document, assets, (value) =>
+            CircuitJsonReadOnlyDocument.#captureMetadataRoot(
+                value,
+                metadataState
+            )
+        )
+        CircuitJsonReadOnlyDocument.#freezeValue(document, frozenRoots)
+        return document
+    }
+
     /**
      * Reads only an internally-created defensive asset data getter.
      * @param {PropertyDescriptor | undefined} descriptor Data descriptor.
@@ -184,7 +263,8 @@ export class CircuitJsonReadOnlyDocument {
         if (
             value &&
             typeof value === 'object' &&
-            OWNED_METADATA_ROOTS.has(value) &&
+            (OWNED_METADATA_ROOTS.has(value) ||
+                CircuitJsonExtensionBoundary.owns(value)) &&
             Object.isFrozen(value)
         ) {
             return value
@@ -209,35 +289,11 @@ export class CircuitJsonReadOnlyDocument {
      * @returns {unknown} Deeply immutable owned extension metadata.
      */
     static copyReadonlyExtensionValue(value, normalize = null, options = {}) {
-        if (
-            value &&
-            typeof value === 'object' &&
-            OWNED_METADATA_ROOTS.has(value) &&
-            Object.isFrozen(value) &&
-            normalize === null
-        ) {
-            return value
-        }
-        if (normalize !== null && typeof normalize !== 'function') {
-            throw new TypeError('Extension normalizer must be a function.')
-        }
-        const snapshot = StructuredDataSnapshot.capture(
+        return CircuitJsonExtensionBoundary.copyReadonly(
             value,
-            StructuredDataSnapshot.createState({
-                ...EXTENSION_METADATA_LIMITS,
-                standardBuiltins: options?.standardBuiltins === true
-            })
+            normalize,
+            options
         )
-        ProtectedExtensionBinaryBoundary.protect(snapshot)
-        const normalized = normalize ? normalize(snapshot) : snapshot
-        if (normalized !== snapshot) {
-            ProtectedExtensionBinaryBoundary.protect(normalized)
-        }
-        CircuitJsonReadOnlyDocument.#freezeValue(normalized, new Set())
-        if (normalized && typeof normalized === 'object') {
-            OWNED_METADATA_ROOTS.add(normalized)
-        }
-        return normalized
     }
 
     /**
@@ -341,31 +397,30 @@ export class CircuitJsonReadOnlyDocument {
      * @returns {unknown} Owned extension root or undefined.
      */
     static #captureDocumentExtensions(document, standardBuiltins) {
-        let descriptor
-        try {
-            descriptor = Object.getOwnPropertyDescriptor(document, 'extensions')
-        } catch {
-            throw new TypeError(
-                'Canonical document extensions could not be inspected safely.'
-            )
-        }
-        if (!descriptor) return undefined
-        if (!Object.hasOwn(descriptor, 'value')) {
-            throw new TypeError(
-                'Canonical document extensions must be an own data property.'
-            )
-        }
-        const captured = CircuitJsonReadOnlyDocument.copyReadonlyExtensionValue(
-            descriptor.value,
-            null,
-            { standardBuiltins }
+        return CircuitJsonExtensionBoundary.captureDocument(
+            document,
+            standardBuiltins
+        )
+    }
+
+    /**
+     * Cooperatively captures a worker extension root and rejects document-level
+     * replacement races across scheduling boundaries.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {boolean} standardBuiltins Whether built-ins have local prototypes.
+     * @param {() => Promise<void> | void} yieldControl Host scheduler.
+     * @returns {Promise<unknown>} Owned extension root or undefined.
+     */
+    static async #captureDocumentExtensionsAsync(
+        document,
+        standardBuiltins,
+        yieldControl
+    ) {
+        return CircuitJsonExtensionBoundary.captureDocumentAsync(
+            document,
+            standardBuiltins,
+            yieldControl
         )
-        if (captured === descriptor.value) return captured
-        Object.defineProperty(document, 'extensions', {
-            ...descriptor,
-            value: captured
-        })
-        return captured
     }
 
     /**
@@ -684,7 +739,8 @@ export class CircuitJsonReadOnlyDocument {
         if (
             value &&
             typeof value === 'object' &&
-            OWNED_METADATA_ROOTS.has(value)
+            (OWNED_METADATA_ROOTS.has(value) ||
+                CircuitJsonExtensionBoundary.owns(value))
         ) {
             return value
         }

package/src/core/context/CircuitJsonValidationProof.mjs

@@ -57,18 +57,62 @@ export class CircuitJsonValidationProof {
      * @returns {Record<string, any>} The same read-only document envelope.
      */
     static validateAndAttach(document, options = {}) {
+        const model = CircuitJsonValidationProof.#validateModel(document)
+        return CircuitJsonValidationProof.#attachAndSeal(
+            document,
+            model,
+            options
+        )
+    }
+
+    /**
+     * Validates a clone-owned model, yields to the host, and then seals its
+     * extension envelope without weakening the matching runtime proof.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {{ standardBuiltins?: boolean, yield?: () => Promise<void> | void }} [options] Proven metadata provenance and host scheduler.
+     * @returns {Promise<Record<string, any>>} The same read-only document envelope.
+     */
+    static async validateAndAttachAsync(document, options = {}) {
+        const model = CircuitJsonValidationProof.#validateModel(document)
+        await CircuitJsonValidationProof.#yieldToHost(options?.yield)
+        return CircuitJsonValidationProof.#attachAndSealAsync(document, model, {
+            ...options,
+            yield: () => CircuitJsonValidationProof.#yieldToHost(options?.yield)
+        })
+    }
+
+    /**
+     * Validates and freezes one exact model before any cooperative yield.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @returns {object[]} Stable validated model.
+     */
+    static #validateModel(document) {
         const model = CircuitJsonValidationProof.#requireModelData(document)
+        if (CircuitJsonValidationProof.#matches(document, model)) return model
+        const errors = CircuitJsonValidationAuthority.validateAndFreeze(model)
+        if (errors.length) throw new TypeError(errors[0])
+        if (CircuitJsonValidationProof.#requireModelData(document) !== model) {
+            throw new TypeError(
+                'CircuitJSON document model changed during validation.'
+            )
+        }
+        return model
+    }
+
+    /**
+     * Attaches the private proof and seals the matching document envelope.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {object[]} model Stable validated model.
+     * @param {{ standardBuiltins?: boolean }} options Proven metadata provenance.
+     * @returns {Record<string, any>} Read-only document envelope.
+     */
+    static #attachAndSeal(document, model, options) {
+        if (CircuitJsonValidationProof.#requireModelData(document) !== model) {
+            throw new TypeError(
+                'CircuitJSON document model changed before sealing.'
+            )
+        }
         if (!CircuitJsonValidationProof.#matches(document, model)) {
-            const errors =
-                CircuitJsonValidationAuthority.validateAndFreeze(model)
-            if (errors.length) throw new TypeError(errors[0])
-            if (
-                CircuitJsonValidationProof.#requireModelData(document) !== model
-            ) {
-                throw new TypeError(
-                    'CircuitJSON document model changed during validation.'
-                )
-            }
             Object.defineProperty(document, VALIDATION_PROOF, {
                 configurable: false,
                 enumerable: false,
@@ -96,6 +140,74 @@ export class CircuitJsonValidationProof {
         return readonlyDocument
     }
 
+    /**
+     * Attaches the proof and cooperatively seals a matching clone-owned
+     * document envelope.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {object[]} model Stable validated model.
+     * @param {{ standardBuiltins?: boolean, yield: () => Promise<void> }} options Proven provenance and normalized scheduler.
+     * @returns {Promise<Record<string, any>>} Read-only document envelope.
+     */
+    static async #attachAndSealAsync(document, model, options) {
+        if (CircuitJsonValidationProof.#requireModelData(document) !== model) {
+            throw new TypeError(
+                'CircuitJSON document model changed before sealing.'
+            )
+        }
+        if (!CircuitJsonValidationProof.#matches(document, model)) {
+            Object.defineProperty(document, VALIDATION_PROOF, {
+                configurable: false,
+                enumerable: false,
+                value: new CircuitJsonValidationToken(
+                    model,
+                    VALIDATION_TOKEN_SECRET
+                ),
+                writable: false
+            })
+        }
+        const readonlyDocument =
+            await CircuitJsonReadOnlyDocument.freezeValidatedAsync(
+                document,
+                model,
+                options
+            )
+        if (
+            CircuitJsonValidationProof.#requireModelData(readonlyDocument) !==
+                model ||
+            !CircuitJsonValidationProof.#matches(readonlyDocument, model)
+        ) {
+            throw new TypeError(
+                'CircuitJSON document model changed while sealing its validation proof.'
+            )
+        }
+        return readonlyDocument
+    }
+
+    /**
+     * Yields through an injected scheduler, the browser scheduler API, or a
+     * zero-delay host task in that order.
+     * @param {(() => Promise<void> | void) | undefined} yieldControl Optional host scheduler.
+     * @returns {Promise<void>}
+     */
+    static async #yieldToHost(yieldControl) {
+        if (yieldControl !== undefined) {
+            if (typeof yieldControl !== 'function') {
+                throw new TypeError(
+                    'Structured-clone yield control must be a function.'
+                )
+            }
+            await yieldControl()
+            return
+        }
+        const scheduler = globalThis.scheduler
+        const schedulerYield = scheduler?.yield
+        if (typeof schedulerYield === 'function') {
+            await Reflect.apply(schedulerYield, scheduler, [])
+            return
+        }
+        await new Promise((resolve) => globalThis.setTimeout(resolve, 0))
+    }
+
     /**
      * Returns true when an envelope proof matches its current model reference.
      * @param {unknown} document Document candidate.