circuitjson-toolkit 1.3.0 → 1.4.0

package/README.md

@@ -69,6 +69,14 @@ 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).
 
+Version 1.4.0 adds cooperative structured-clone preparation and a documented
+owned-document construction path for source toolkits. Hosts can yield
+throughout large extension traversal, binary protection, and property locking,
+and format parsers can retain the identity of graphs they just created instead
+of defensively copying them again. The resulting model, extensions,
+parameters, and `DocumentResult` shape are unchanged. See the
+[1.4.0 release notes](docs/release-notes-v1.4.0.md).
+
 Before 1.1.0:
 
 ```js
@@ -115,6 +123,8 @@ const model = document.model
   cancellation, and controlled buffer transfer
 - One-pass ownership for selected source extensions, with a separate 128 MiB /
   4,000,000-item bound and exact direct/worker result parity
+- Cooperative structured-clone preparation with in-place ordinary records and
+  clean alias/cycle-preserving dense-array normalization
 - Machine-readable capability inventory and packed downstream conformance
   harness
 - Explicit `/extensions` surface retaining every previous specialized API
@@ -157,6 +167,43 @@ const components = QueryService.create(context).query({
 console.log(document.model, svg, hits, components.items)
 ```
 
+Browser hosts that receive the exact result of a platform structured clone can
+prepare it cooperatively:
+
+```js
+const context = await CircuitJsonDocumentContext.prepareStructuredCloneAsync(
+    message.data,
+    {
+        indexes: ['elements', 'relations'],
+        ownership: 'exclusive',
+        yield: () => scheduler.yield()
+    }
+)
+```
+
+`ownership: 'exclusive'` is required and transfers the graph destructively.
+The caller must relinquish every alias, including shared-memory writers, until
+the promise settles. A mutation to a node that has not been acquired yet cannot
+be reconstructed or detected later, and rejection may leave part of the graph
+locked. Use `prepareStructuredClone()` for uninterrupted same-thread adoption,
+or `prepare()` for arbitrary caller-owned values.
+
+An already prepared `CircuitJsonDocumentContext` is reused immediately and
+does not require an ownership declaration because no graph is transferred.
+Ordinary extension records are adopted in place. Dense arrays are normalized
+into clean arrays while preserving aliases and cycles, preventing unsupported
+hidden properties from carrying mutable state into the context.
+
+The model is validated and frozen before extension adoption begins. Dense
+arrays, Map/Set normalization, immutable text accounting, binary copying,
+binary installation, and property locking are divided into bounded slices.
+Individual plain extension records are limited to 16,384 properties on this
+cooperative path. The method returns the same
+`CircuitJsonDocumentContext` shape as the synchronous preparation methods.
+Omit `yield` to use `scheduler.yield()` when available and a zero-delay host
+task otherwise. This entry point accepts only exact platform structured-clone
+results with ordinary enumerable string properties.
+
 `Parser.parse()` returns the exact clone-safe `ecad-toolkit.document.v1`
 envelope:
 
@@ -338,6 +385,7 @@ copy while keeping sync, direct async, and worker results mutation-isolated.
 - [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)
+- [1.4.0 release notes](docs/release-notes-v1.4.0.md)
 - [Library scope](spec/library-scope.md)
 
 ## Package scope

package/docs/api.md

@@ -131,6 +131,44 @@ 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.
 
+To split model validation and extension sealing across host tasks, use the
+cooperative equivalent:
+
+```js
+const context = await CircuitJsonDocumentContext.prepareStructuredCloneAsync(
+    message.data,
+    {
+        indexes: ['elements', 'relations'],
+        ownership: 'exclusive',
+        yield: () => scheduler.yield()
+    }
+)
+```
+
+`ownership: 'exclusive'` is mandatory. It transfers the exact platform
+structured-clone graph destructively; the caller must relinquish all aliases
+and shared-memory writers until the promise settles. The optional `yield`
+callback is awaited after model validation and repeatedly between bounded
+slices of dense-array traversal, Map/Set normalization, immutable text
+accounting, binary copying and installation, and property locking. Individual
+plain extension records are limited to 16,384 properties on this path.
+
+Existing `CircuitJsonDocumentContext` inputs are already immutable and are
+reused immediately without an ownership declaration. During a new transfer,
+ordinary extension records retain their identity. Dense arrays are normalized
+into clean arrays while retaining graph aliases and cycles, so non-clone hidden
+properties cannot leave mutable state in the prepared context.
+
+Acquired containers are shape-locked and their descriptors are checked during
+sealing. This is not a transactional snapshot of retained aliases: a caller
+that violates exclusive ownership can change a node before it is acquired, and
+a rejected transfer may leave part of the graph locked. Without an injected
+callback the method uses `scheduler.yield()` when available, then falls back to
+a zero-delay host task. The promise resolves to the same prepared context
+returned by the synchronous methods, including the same requested indexes and
+cache behavior. Use `prepareStructuredClone()` for uninterrupted same-thread
+adoption or `prepare()` for arbitrary caller-owned graphs.
+
 ## Root entrypoint
 
 `circuitjson-toolkit` has an exact 17-class root. The 14 canonical classes are:
@@ -203,6 +241,24 @@ Packed release checks reject any missing or additional root export.
 
 Import from the root or `circuitjson-toolkit/parser`.
 
+### `DocumentResult.createValidatedOwned(fields, runtime?)`
+
+Creates the same validated `ecad-toolkit.document.v1` envelope as
+`DocumentResult.createValidated(fields, runtime?)`, but adopts ordinary model
+and extension graph nodes that the calling toolkit just constructed. The
+model and retained extension nodes keep their identities and are validated and
+deeply frozen in place. The envelope schema, parameters, source-reference
+runtime option, and public return fields are unchanged. Binary payloads still
+pass through the defensive binary-property boundary.
+
+This is a destructive ownership transfer for source-toolkit convergence
+builders. Call it only when the complete ordinary graph is newly created,
+mutable, has standard local built-ins, and is no longer shared with code that
+expects to mutate it. Raw parser input, arbitrary caller objects, cross-realm
+values, proxies, and prototype-modified graphs must use
+`DocumentResult.createValidated()` instead. The method is exported from
+`circuitjson-toolkit/parser`, not from the exact root surface.
+
 ### `Parser.parse(input, options?)`
 
 Synchronously detects, decodes, validates, and returns one canonical document.
@@ -332,6 +388,34 @@ The class constructor is not a public construction path. It throws before
 observing caller input; use `prepare()` so every context carries a
 validation-bound authority that downstream viewers and applications can trust.
 
+### `CircuitJsonDocumentContext.prepareStructuredCloneAsync(input, options?)`
+
+Cooperatively validates and adopts an exact platform structured-clone result.
+`options.ownership` must be the literal string `exclusive`; it declares a
+destructive transfer and requires the caller to relinquish every alias and
+shared-memory writer until settlement. `options.indexes` accepts the same names
+as `prepare()`. `options.yield` may be an async or synchronous function; it is
+awaited after model validation and between bounded slices of extension
+adoption and sealing. If omitted, the runtime uses `scheduler.yield()` when
+present or a zero-delay host task. The method returns a promise for the same
+immutable context shape. The cooperative path enforces the normal extension
+limits plus a 16,384-property limit on each individual plain record.
+
+When `input` is already a `CircuitJsonDocumentContext`, the method performs no
+transfer and reuses it immediately, so `options.ownership` is not required.
+Transferred ordinary records are adopted in place; dense arrays are normalized
+to clean arrays with aliases and cycles preserved.
+
+Use this only at a provenance boundary that guarantees standard local
+built-ins and ordinary enumerable string properties. Large strings, binary
+payloads, dense arrays, and Map/Set values are processed across cooperative
+pauses, then acquired containers are progressively locked before the proof and
+envelope are sealed. Mutation before a node is acquired is outside the
+exclusive-transfer contract and cannot be detected reliably; rejection can
+leave a partially locked graph. Use `prepareStructuredClone()` for
+uninterrupted same-thread adoption and `prepare()` for untrusted or otherwise
+arbitrary caller graphs.
+
 ### `context.getIndex(name)` and `context.hasIndex(name)`
 
 Access a prepared index or check its presence.

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

@@ -0,0 +1,84 @@
+# circuitjson-toolkit 1.4.0
+
+This minor release removes redundant ownership work when a source toolkit or
+browser worker has already established an exact graph provenance boundary. It
+also lets browser hosts return control between validation and extension
+sealing without changing the canonical result contract.
+
+## Owned document construction
+
+- `DocumentResult.createValidatedOwned(fields, runtime?)` creates the same
+  validated `ecad-toolkit.document.v1` envelope as `createValidated()`.
+- A source-toolkit convergence builder may transfer a newly constructed,
+  standard-built-in graph into the envelope. Ordinary model and extension
+  nodes retain their identities and are deeply frozen in place instead of
+  being copied into a second full graph.
+- The method is intentionally destructive. It is only safe when the toolkit
+  exclusively owns the complete mutable graph and will not mutate it after the
+  call. Arbitrary caller values, raw untrusted input, cross-realm objects,
+  proxies, and altered prototypes must continue through `createValidated()`.
+- Binary properties retain their defensive boundary and validation. Ownership
+  limits, validation proofs, and immutable-envelope guarantees are unchanged.
+
+## Cooperative structured-clone preparation
+
+- `CircuitJsonDocumentContext.prepareStructuredCloneAsync(input, options?)`
+  accepts the same structured-clone input and `indexes` option as the
+  synchronous method, plus the required `ownership: 'exclusive'` declaration
+  and an optional `yield` scheduler.
+- This is a destructive transfer. Callers must relinquish every alias and
+  shared-memory writer until settlement. Mutation before a node is acquired is
+  outside the contract and cannot be detected reliably; rejection can leave a
+  partially locked graph.
+- The method validates and deeply freezes the model, then yields between
+  bounded slices of dense-array traversal, Map/Set normalization, immutable
+  text accounting, binary copying and installation, and property locking
+  before sealing the canonical envelope.
+- Acquired containers are shape-locked and their descriptors are checked while
+  sealing. Individual plain extension records are capped at 16,384 properties
+  so one record cannot create an unbounded cooperative inspection step.
+- Existing immutable contexts are reused without a transfer declaration.
+  Transferred ordinary records retain identity; dense arrays are normalized
+  into clean arrays while preserving aliases and cycles, preventing unsupported
+  hidden properties from leaking mutable state.
+- An injected `yield` function is awaited at each scheduling boundary. Without
+  one, the toolkit prefers `scheduler.yield()` and otherwise uses a zero-delay
+  host task.
+- The promise resolves to the same immutable `CircuitJsonDocumentContext`
+  shape with the same indexes, caches, limits, and validation authority.
+
+## Compatibility
+
+- No parser option, package subpath, class, parameter, or return field is
+  removed or renamed.
+- `DocumentResult` remains `ecad-toolkit.document.v1`; its `model`, `source`,
+  `extensions`, `assets`, `diagnostics`, and `statistics` fields are unchanged.
+- `createValidatedOwned()` and `prepareStructuredCloneAsync()` are additive.
+  The defensive and synchronous APIs retain their previous behavior.
+
+## Verification and performance
+
+Synthetic regression coverage verifies ordinary-record identity retention,
+alias/cycle-preserving clean arrays, deep freeze, chunked text and binary
+processing, dense-array and Map/Set scheduling,
+cooperative yield ordering, progressive shape/property locking, the exclusive
+ownership contract, and context reuse across document batches. The full
+adversarial suite continues to cover hostile accessors, altered and cross-realm
+built-ins, defensive binary ownership, worker parity, synchronous mutation
+isolation, and bounded extension graphs.
+
+On the same browser and machine, the exact large native-PCB deep link that
+previously produced 3.29-second and 2.17-second renderer-main tasks retained
+the same 25,729-element PCB SVG and view box after this release. A final fresh
+open peaked at 17.7 milliseconds on the renderer main thread. A forced reload
+peaked at 404.4 milliseconds, consisting of 196.8 milliseconds of browser
+structured-clone deserialization plus 205.3 milliseconds of browser garbage
+collection; no application JavaScript task approached the previous stalls.
+The largest scheduled parser-worker task in that reload was 5.9 milliseconds.
+A separate 150,000-record exclusive-adoption probe yielded 880 times and
+completed in 487.35 milliseconds, with a 1.22-millisecond p95 slice and a
+6.94-millisecond maximum outlier. A 32 MiB immutable-text probe completed in
+8.13 milliseconds across 513 yields; a 32 MiB binary probe completed in 3.40
+milliseconds across 514 yields. These figures describe fixed local workloads
+and are not runtime guarantees; deterministic shape, validation, and ownership
+tests remain the release gates.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "circuitjson-toolkit",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "description": "Canonical CircuitJSON parsing, project, rendering, query, manufacturing, simulation, and scene contracts",
     "keywords": [
         "circuitjson",
@@ -56,6 +56,7 @@
         "docs/release-notes-v1.2.0.md",
         "docs/release-notes-v1.2.1.md",
         "docs/release-notes-v1.3.0.md",
+        "docs/release-notes-v1.4.0.md",
         "docs/testing.md",
         "spec",
         "LICENSE",

package/src/core/Parser.mjs

@@ -211,7 +211,7 @@ export class Parser {
             normalized.options.retainSource === 'reference'
                 ? { sourceReference: normalized.sourceReference }
                 : {}
-        return DocumentResult.createValidated(
+        return DocumentResult.createValidatedOwned(
             {
                 fileName: normalized.input.fileName,
                 fileType: 'circuitjson',

package/src/core/context/BinaryDataSnapshot.mjs

@@ -241,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.
@@ -261,6 +299,27 @@ export class BinaryDataSnapshot {
         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
+        return new Constructor(bytes.buffer)
+    }
+
     /**
      * Calls a captured buffer length getter as a brand check.
      * @param {Function | null | undefined} getter Intrinsic getter.

package/src/core/context/CircuitJsonDocumentContext.mjs

@@ -88,6 +88,31 @@ export class CircuitJsonDocumentContext {
         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.
@@ -229,6 +254,36 @@ export class CircuitJsonDocumentContext {
         )
     }
 
+    /**
+     * 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 =
+            await CircuitJsonValidationProof.validateAndAttachAsync(document, {
+                standardBuiltins,
+                yield: yieldControl
+            })
+        const model = CircuitJsonDocumentContext.#ownData(
+            readonlyDocument,
+            'model'
+        )
+        return new CircuitJsonDocumentContext(
+            readonlyDocument,
+            model,
+            validationPasses,
+            CONTEXT_CONSTRUCTION_AUTHORITY
+        )
+    }
+
     /**
      * Normalizes supported context input into a canonical document envelope.
      * @param {unknown} input Document result or CircuitJSON model.