circuitjson-toolkit 1.3.0 → 1.4.1

package/README.md

@@ -8,8 +8,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 CircuitJSON Toolkit is the dependency-free common runtime for the ECAD toolkit
 family. It provides the same parser, project, rendering, interaction, query,
-manufacturing, simulation, 3D scene, capability, error, and worker contracts
-used by `gerber-toolkit`, `altium-toolkit`, and `kicad-toolkit`.
+manufacturing, simulation, 3D scene, self-adjusting computation, capability,
+error, and worker contracts used by `gerber-toolkit`, `altium-toolkit`, and
+`kicad-toolkit`.
 
 CircuitJSON is the shared immutable model. Source-format packages keep their
 native decoders and fidelity data in explicit extension namespaces while
@@ -69,6 +70,19 @@ 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).
+
+Version 1.4.1 adds the canonical `SelfAdjustingComputation` runtime with
+dynamic data/control dependencies, changed-root reader lists, stale-trace
+replacement, explicit reclamation, and from-scratch consistency coverage. See
+the [1.4.1 release notes](docs/release-notes-v1.4.1.md).
+
 Before 1.1.0:
 
 ```js
@@ -115,6 +129,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 +173,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 +391,8 @@ 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)
+- [1.4.1 release notes](docs/release-notes-v1.4.1.md)
 - [Library scope](spec/library-scope.md)
 
 ## Package scope

package/docs/api.md

@@ -16,6 +16,38 @@ this document for new code. Thirty-seven previous CircuitJSON-specific classes
 remain under `circuitjson-toolkit/extensions`; the three documented viewer
 compatibility classes remain on the root. See [migration.md](migration.md).
 
+### `SelfAdjustingComputation`
+
+The root API exports the shared synchronous change-propagation runtime used by
+ECAD Forge and reusable toolkit consumers. It records dynamic property reads
+for stable named computations, maintains reverse reader lists, validates only
+the traces reached from explicit changed roots, and replaces stale control-flow
+dependencies after re-execution.
+
+```js
+import { SelfAdjustingComputation } from 'circuitjson-toolkit'
+
+const runtime = new SelfAdjustingComputation()
+const results = runtime.propagate(
+    { locale: 'en', status: 'ready' },
+    [['status']],
+    [
+        {
+            name: 'status-label',
+            computation: (state) => state.locale + ':' + state.status
+        }
+    ]
+)
+```
+
+Computations must be synchronous and treat their tracked input as read-only.
+`forget(name)` reclaims one trace, `clear()` reclaims the graph, and
+`getStatistics()` exposes bounded trace counts. Plain objects and arrays are
+traversed; non-plain objects are atomic identity dependencies unless the
+constructor's `isAtomic(value, path)` option selects an earlier boundary.
+Callers must supply conservative changed paths and test propagated results
+against a fresh execution for the same input.
+
 ## Common conventions
 
 ### Document input
@@ -131,9 +163,47 @@ 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:
+`circuitjson-toolkit` has an exact 18-class root. The 15 canonical classes are:
 
 - `Parser`
 - `ProjectLoader`
@@ -147,6 +217,7 @@ intrinsic binary slots authoritative and preserves altered-prototype
 - `SimulationService`
 - `PcbScene3dBuilder`
 - `PcbScene3dPreparator`
+- `SelfAdjustingComputation`
 - `ToolkitCapabilities`
 - `ToolkitError`
 
@@ -203,6 +274,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 +421,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/docs/release-notes-v1.4.1.md

@@ -0,0 +1,27 @@
+# circuitjson-toolkit 1.4.1
+
+This patch release adds a shared self-adjusting-computation runtime for
+persistent toolkit and application state. It implements dynamic dependency
+tracing and ordered change propagation without coupling the common package to
+DOM, Three.js, or source-format parser state.
+
+## Self-adjusting computation
+
+- `SelfAdjustingComputation` is available from the package root and is shared
+  by identity through the Gerber, Altium, KiCad, and PCB Scene3D packages.
+- Named synchronous computations record the data and control-flow paths they
+  observe. Explicit changed roots start propagation from reverse reader lists.
+- Potentially affected computations compare their previous observations and
+  reuse successful results when values, presence, key structure, and selected
+  atomic identities remain unchanged.
+- Re-execution replaces the previous trace and its abandoned reader edges.
+  `forget()` and `clear()` reclaim trace storage explicitly.
+- Tracked snapshots reject mutation and asynchronous trace escape. Callers can
+  choose an atomic boundary for immutable documents and native objects.
+
+## Verification
+
+The unit suite covers nested and structural reads, control-flow replacement,
+stale reader removal, atomic document identity, failed and asynchronous
+computations, write rejection, explicit trace reclamation, and equality with a
+fresh runtime after each propagated change.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "circuitjson-toolkit",
-    "version": "1.3.0",
+    "version": "1.4.1",
     "description": "Canonical CircuitJSON parsing, project, rendering, query, manufacturing, simulation, and scene contracts",
     "keywords": [
         "circuitjson",
@@ -56,6 +56,8 @@
         "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/release-notes-v1.4.1.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',