circuitjson-toolkit 1.4.1 → 1.4.2

package/README.md

@@ -83,6 +83,12 @@ 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).
 
+Version 1.4.2 accelerates immutable document rebuilding and cooperative
+structured-clone adoption. Toolkit-owned frozen extension roots retain their
+identity, and cooperative finalization freezes each validated container
+atomically instead of redefining every property. See the
+[1.4.2 release notes](docs/release-notes-v1.4.2.md).
+
 Before 1.1.0:
 
 ```js
@@ -393,6 +399,7 @@ copy while keeping sync, direct async, and worker results mutation-isolated.
 - [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)
+- [1.4.2 release notes](docs/release-notes-v1.4.2.md)
 - [Library scope](spec/library-scope.md)
 
 ## Package scope

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

@@ -0,0 +1,32 @@
+# circuitjson-toolkit 1.4.2
+
+This patch release removes repeated immutable-graph work from toolkit-owned
+document rebuilds and from cooperative structured-clone adoption. Public
+document shapes, validation rules, cancellation behavior, and extension
+selection semantics remain unchanged.
+
+## Owned extension root reuse
+
+- `DocumentResult.createValidated()` retains an extension namespace that was
+  already captured, bounded, sealed, and branded by the same toolkit runtime.
+- Rebuilding a canonical document no longer traverses or copies a large frozen
+  native extension graph when only other document fields changed.
+- Arbitrary caller objects still use the defensive validation and ownership
+  path; frozen state alone never grants trusted ownership.
+
+## Atomic cooperative finalization
+
+- Cooperative structured-clone adoption validates a container's descriptors
+  before freezing the container in one atomic operation.
+- A yield can no longer expose a container with only some properties locked.
+- Large graphs avoid one `defineProperty()` call per ordinary property while
+  retaining the same deeply immutable result and cancellation checkpoints.
+
+## Verification
+
+- Ownership tests cover identity reuse for toolkit-built frozen namespaces and
+  defensive behavior for untrusted objects.
+- Cooperative snapshot tests prove that no partial property locking is visible
+  across yields.
+- The complete package suite, formatting check, packed-entrypoint checks, and
+  npm dry-run gate the release.

package/package.json

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

package/src/core/context/StructuredCloneAdoption.mjs

@@ -506,10 +506,9 @@ class StructuredCloneAdoptionTraversal {
     }
 
     /**
-     * Locks one target property-by-property so large dense containers never
-     * require one monolithic Object.freeze operation.
+     * Validates and atomically freezes one acquired target.
      * @param {object} seal Target sealing snapshot.
-     * @returns {Generator<void, void, void>} Bounded-work locking pass.
+     * @returns {Generator<void, void, void>} Cooperative locking pass.
      */
     *#sealTargetCooperatively(seal) {
         StructuredCloneAdoptionTraversal.#requireTargetShape(seal)
@@ -530,31 +529,16 @@ class StructuredCloneAdoptionTraversal {
                     'Canonical asset source changed during adoption.'
                 )
             }
-            if (!property.binary) {
-                try {
-                    Object.defineProperty(seal.target, property.key, {
-                        ...descriptor,
-                        configurable: false,
-                        writable: false
-                    })
-                } catch {
-                    throw new TypeError(
-                        'Canonical document values could not be frozen safely.'
-                    )
-                }
-            }
-            yield* this.#checkpoint()
         }
         StructuredCloneAdoptionTraversal.#requireTargetShape(seal)
-        if (!seal.shapeLocked) {
-            try {
-                Object.preventExtensions(seal.target)
-            } catch {
-                throw new TypeError(
-                    'Canonical document values could not be frozen safely.'
-                )
-            }
+        try {
+            Object.freeze(seal.target)
+        } catch {
+            throw new TypeError(
+                'Canonical document values could not be frozen safely.'
+            )
         }
+        yield* this.#checkpoint(seal.properties.length || 1)
     }
 
     /**

package/src/core/contracts/DocumentResult.mjs

@@ -1,4 +1,5 @@
 import { CircuitJsonValidationProof } from '../context/CircuitJsonValidationProof.mjs'
+import { CircuitJsonExtensionBoundary } from '../context/CircuitJsonExtensionBoundary.mjs'
 import { CircuitJsonReadOnlyDocument } from '../context/CircuitJsonReadOnlyDocument.mjs'
 import { CircuitJsonSerializedInputAudit } from '../CircuitJsonSerializedInputAudit.mjs'
 import { ToolkitAsset } from './ToolkitAsset.mjs'
@@ -147,6 +148,14 @@ export class DocumentResult {
         const hasCandidate = candidate && typeof candidate === 'object'
         if (!hasCandidate) return {}
         if (options.readonly === true && hasCandidate) {
+            // This private brand proves the frozen namespace was already
+            // captured, bounded, and sealed by this runtime.
+            if (
+                CircuitJsonExtensionBoundary.owns(extensions) &&
+                Object.isFrozen(extensions)
+            ) {
+                return extensions
+            }
             if (options.standardBuiltins === true) {
                 return CircuitJsonReadOnlyDocument.copyReadonlyExtensionValue(
                     DocumentResult.#normalizedExtension(format, candidate),