circuitjson-toolkit 1.2.1 → 1.4.0

package/README.md

@@ -61,6 +61,22 @@ 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).
+
+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
@@ -107,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
@@ -149,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:
 
@@ -329,6 +384,8 @@ 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)
+- [1.4.0 release notes](docs/release-notes-v1.4.0.md)
 - [Library scope](spec/library-scope.md)
 
 ## Package scope

package/docs/api.md

@@ -109,6 +109,66 @@ 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.
+
+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:
@@ -181,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.
@@ -310,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.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/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/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.4.0",
     "description": "Canonical CircuitJSON parsing, project, rendering, query, manufacturing, simulation, and scene contracts",
     "keywords": [
         "circuitjson",
@@ -55,6 +55,8 @@
         "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/release-notes-v1.4.0.md",
         "docs/testing.md",
         "spec",
         "LICENSE",
@@ -67,7 +69,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/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',