circuitjson-toolkit 1.4.1 → 1.4.3

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/api.md

@@ -85,11 +85,12 @@ make the common shape smaller.
 
 Validated source documents own selected extension values as one deeply
 immutable, descriptor-safe snapshot. This uses a distinct 128 MiB payload and
-4,000,000-item ceiling so large native renderer graphs do not inherit the
+8,000,000-item ceiling so large native renderer graphs do not inherit the
 compact metadata limit. The shared worker protocol applies the same ownership
 boundary after structured cloning. Canonical standalone documents retain a
-250 MB byte ceiling; exact multi-document projects use a 256 MiB aggregate
-ceiling with independent 250 MB document and project-metadata limits. Binary
+10,000,000-value and 250 MB byte ceiling; exact multi-document projects use a
+16,000,000-value and 256 MiB aggregate ceiling with independent 250 MB document
+and project-metadata limits. Binary
 values preserve their `ArrayBuffer`/typed-view shape behind defensive copy
 access, so payload bytes do not inflate into one JavaScript number per byte.
 
@@ -318,6 +319,15 @@ The parser subpath additionally exports `ParserWorkerClient`,
 `ToolkitWorkerProtocol`, and the `TOOLKIT_WORKER_PROTOCOL` version constant for
 hosts that own a custom worker lifecycle.
 
+`ParserWorkerClient.fromWorkerUrl(url)` creates a lazy module-worker client
+that privately owns its native worker and received result graphs. Native
+message provenance avoids repeated binary brand probing on ordinary records;
+all result shape, model, depth, count, and byte limits still apply. Shared and
+resizable buffers remain isolated. `new ParserWorkerClient({ createWorker })`
+continues to fully inspect custom-worker results, including genuine events
+whose payloads an earlier listener may have changed. Replacing the host Worker
+constructor also retains that defensive path.
+
 ### `ToolkitAsset.measure(asset)`
 
 Returns the exact resident payload byte length without copying. Binary lengths
@@ -711,3 +721,9 @@ circuitjson-toolkit/testing
 circuitjson-toolkit/workers/parser.worker.mjs
 circuitjson-toolkit/styles/renderers.css
 ```
+
+Worker payload preparation uses captured array/view brand checks before raw
+buffer probes. Short strings are counted directly in UTF-8, including surrogate
+pairs and replacement characters, without allocating encoded byte buffers.
+Cross-realm buffers, changed prototypes, and bounded binary ownership retain
+the same validation rules.

package/docs/model-format.md

@@ -102,12 +102,12 @@ must not duplicate the CircuitJSON model or keep a renamed renderer model.
 Default parsing excludes raw/base64/full-payload graphs.
 
 When a caller explicitly selects a native extension, the toolkit captures and
-freezes that graph once under a distinct ceiling of 4,000,000 structured items
+freezes that graph once under a distinct ceiling of 8,000,000 structured items
 and 128 MiB of string or binary content. The ceiling is shared across the
 selected namespace and applies equally after worker transfer. Canonical
-standalone documents allow the extension plus envelope overhead within five
-million result values and 250 MB. Exact project envelopes allow eight million
-aggregate values and 256 MiB, while each document stays within five million
+standalone documents allow the extension plus envelope overhead within ten
+million result values and 250 MB. Exact project envelopes allow sixteen million
+aggregate values and 256 MiB, while each document stays within ten million
 values and 250 MB and non-document project metadata stays within two million
 values and 250 MB. Reused graphs are charged independently to each local scope,
 and repeated accounting work is itself bounded by the aggregate project

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.3",
     "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/SelfAdjustingComputation.mjs

@@ -17,15 +17,9 @@ export class SelfAdjustingComputation {
     /** @type {Set<string> | null} */
     #affectedComputations
 
-    /** @type {(value: object, path: PropertyKey[]) => boolean} */
+    /** @type {((value: object, path: PropertyKey[]) => boolean) | null} */
     #isAtomic
 
-    /** @type {Map<symbol, number>} */
-    #symbolIds
-
-    /** @type {number} */
-    #nextSymbolId
-
     /**
      * @param {{ isAtomic?: (value: object, path: PropertyKey[]) => boolean }} [options] Dependency-tracking options.
      */
@@ -36,11 +30,7 @@ export class SelfAdjustingComputation {
         this.#propagationInput = null
         this.#affectedComputations = null
         this.#isAtomic =
-            typeof options.isAtomic === 'function'
-                ? options.isAtomic
-                : () => false
-        this.#symbolIds = new Map()
-        this.#nextSymbolId = 1
+            typeof options.isAtomic === 'function' ? options.isAtomic : null
     }
 
     /**
@@ -264,16 +254,14 @@ export class SelfAdjustingComputation {
      * @returns {{ dependencies: object[], value: any }} Successful trace.
      */
     #trace(input, computation) {
-        const dependencies = new Map()
+        const dependencies = []
         const proxyCache = new WeakMap()
         const proxyMetadata = new WeakMap()
-        const trackedInput = this.#createProxy({
-            target: input,
-            path: [],
-            dependencies,
-            proxyCache,
-            proxyMetadata
-        })
+        const trackedInput = this.#createProxy(
+            { dependencies, proxyCache, proxyMetadata },
+            input,
+            { path: [], children: null, observations: null }
+        )
         const trackedValue = computation(trackedInput)
         if (SelfAdjustingComputation.#isPromiseLike(trackedValue)) {
             throw new TypeError(
@@ -287,39 +275,44 @@ export class SelfAdjustingComputation {
                 ? proxyMetadata.get(trackedValue)
                 : null
         if (metadata) {
-            this.#record(dependencies, {
-                type: 'value',
-                path: metadata.path,
-                expected: metadata.target
-            })
+            this.#record(
+                dependencies,
+                metadata.pathNode,
+                'value',
+                metadata.target
+            )
         }
 
         return {
-            dependencies: [...dependencies.values()],
+            // Later reads of a returned container must not rewrite this trace.
+            dependencies: dependencies.map((dependency) => ({ ...dependency })),
             value: metadata?.target ?? trackedValue
         }
     }
 
     /**
      * Creates a read-tracking proxy for one traversable input container.
-     * @param {{ target: object, path: PropertyKey[], dependencies: Map<string, object>, proxyCache: WeakMap<object, Map<string, object>>, proxyMetadata: WeakMap<object, { target: object, path: PropertyKey[] }> }} context Tracking context.
+     * @param {{ dependencies: object[], proxyCache: WeakMap<object, Map<object, object>>, proxyMetadata: WeakMap<object, { target: object, pathNode: object }> }} context Shared trace context.
+     * @param {object} target Traversable raw input container.
+     * @param {object} pathNode Interned input path in this trace.
      * @returns {object} Read-tracking proxy.
      */
-    #createProxy(context) {
-        const pathKey = this.#pathKey(context.path)
-        const cachedByPath = context.proxyCache.get(context.target)
-        if (cachedByPath?.has(pathKey)) {
-            return cachedByPath.get(pathKey)
+    #createProxy(context, target, pathNode) {
+        const cachedByPath = context.proxyCache.get(target)
+        const cached = cachedByPath?.get(pathNode)
+        if (cached) {
+            return cached
         }
 
-        const proxy = new Proxy(context.target, {
+        const proxyContext = { ...context, pathNode }
+        const proxy = new Proxy(target, {
             get: (target, property) =>
-                this.#readProperty(context, target, property),
+                this.#readProperty(proxyContext, target, property),
             has: (target, property) =>
-                this.#readPresence(context, target, property),
-            ownKeys: (target) => this.#readKeys(context, target),
+                this.#readPresence(proxyContext, target, property),
+            ownKeys: (target) => this.#readKeys(proxyContext, target),
             getOwnPropertyDescriptor: (target, property) =>
-                this.#readDescriptor(context, target, property),
+                this.#readDescriptor(proxyContext, target, property),
             set: () => this.#rejectWrite(),
             defineProperty: () => this.#rejectWrite(),
             deleteProperty: () => this.#rejectWrite(),
@@ -327,13 +320,13 @@ export class SelfAdjustingComputation {
             preventExtensions: () => this.#rejectWrite()
         })
         const nextCachedByPath = cachedByPath || new Map()
-        nextCachedByPath.set(pathKey, proxy)
+        nextCachedByPath.set(pathNode, proxy)
         if (!cachedByPath) {
-            context.proxyCache.set(context.target, nextCachedByPath)
+            context.proxyCache.set(target, nextCachedByPath)
         }
         context.proxyMetadata.set(proxy, {
-            target: context.target,
-            path: [...context.path]
+            target,
+            pathNode
         })
         return proxy
     }
@@ -347,21 +340,18 @@ export class SelfAdjustingComputation {
      */
     #readProperty(context, target, property) {
         const value = Reflect.get(target, property, target)
-        const path = [...context.path, property]
-        if (this.#isTraversable(value, path)) {
-            this.#record(context.dependencies, {
-                type: 'kind',
-                path,
-                expected: SelfAdjustingComputation.#valueKind(value)
-            })
-            return this.#createProxy({ ...context, target: value, path })
+        const pathNode = this.#childPath(context.pathNode, property)
+        if (this.#isTraversable(value, pathNode.path)) {
+            this.#record(
+                context.dependencies,
+                pathNode,
+                'kind',
+                SelfAdjustingComputation.#valueKind(value)
+            )
+            return this.#createProxy(context, value, pathNode)
         }
 
-        this.#record(context.dependencies, {
-            type: 'value',
-            path,
-            expected: value
-        })
+        this.#record(context.dependencies, pathNode, 'value', value)
         return value
     }
 
@@ -373,13 +363,9 @@ export class SelfAdjustingComputation {
      * @returns {boolean} Whether the property exists.
      */
     #readPresence(context, target, property) {
-        const path = [...context.path, property]
+        const pathNode = this.#childPath(context.pathNode, property)
         const expected = Reflect.has(target, property)
-        this.#record(context.dependencies, {
-            type: 'has',
-            path,
-            expected
-        })
+        this.#record(context.dependencies, pathNode, 'has', expected)
         return expected
     }
 
@@ -391,11 +377,7 @@ export class SelfAdjustingComputation {
      */
     #readKeys(context, target) {
         const expected = Reflect.ownKeys(target)
-        this.#record(context.dependencies, {
-            type: 'keys',
-            path: [...context.path],
-            expected
-        })
+        this.#record(context.dependencies, context.pathNode, 'keys', expected)
         return expected
     }
 
@@ -408,11 +390,12 @@ export class SelfAdjustingComputation {
      */
     #readDescriptor(context, target, property) {
         const descriptor = Reflect.getOwnPropertyDescriptor(target, property)
-        this.#record(context.dependencies, {
-            type: 'descriptor',
-            path: [...context.path, property],
-            expected: SelfAdjustingComputation.#descriptorState(descriptor)
-        })
+        this.#record(
+            context.dependencies,
+            this.#childPath(context.pathNode, property),
+            'descriptor',
+            SelfAdjustingComputation.#descriptorState(descriptor)
+        )
         return descriptor
     }
 
@@ -424,23 +407,50 @@ export class SelfAdjustingComputation {
      */
     #isTraversable(value, path) {
         if (!value || typeof value !== 'object') return false
-        if (this.#isAtomic(value, [...path])) return false
+        if (this.#isAtomic?.(value, [...path])) return false
         if (Array.isArray(value)) return true
         const prototype = Reflect.getPrototypeOf(value)
         return prototype === Object.prototype || prototype === null
     }
 
     /**
-     * Stores or replaces one dependency by type and input path.
-     * @param {Map<string, object>} dependencies Dependency registry.
-     * @param {{ type: string, path: PropertyKey[], expected: any }} dependency Dependency record.
+     * Interns one child path using property identity without encoding its ancestors.
+     * Path and proxy caches belong to one trace and are never reused by a later snapshot.
+     * @param {object} parent Parent path node.
+     * @param {PropertyKey} property Observed property key.
+     * @returns {object} Canonical child path node for this trace.
+     */
+    #childPath(parent, property) {
+        const previous = parent.children?.get(property)
+        if (previous) return previous
+        const child = {
+            path: [...parent.path, property],
+            children: null,
+            observations: null
+        }
+        parent.children ??= new Map()
+        parent.children.set(property, child)
+        return child
+    }
+
+    /**
+     * Stores the last observation of each dependency type at an interned path.
+     * @param {object[]} dependencies Dependency registry in first-observed order.
+     * @param {object} pathNode Interned path node.
+     * @param {string} type Dependency comparison category.
+     * @param {any} expected Most recently observed value or structural state.
      * @returns {void}
      */
-    #record(dependencies, dependency) {
-        dependencies.set(
-            dependency.type + ':' + this.#pathKey(dependency.path),
-            dependency
-        )
+    #record(dependencies, pathNode, type, expected) {
+        const previous = pathNode.observations?.get(type)
+        if (previous) {
+            previous.expected = expected
+            return
+        }
+        const dependency = { type, path: pathNode.path, expected }
+        pathNode.observations ??= new Map()
+        pathNode.observations.set(type, dependency)
+        dependencies.push(dependency)
     }
 
     /**
@@ -530,27 +540,6 @@ export class SelfAdjustingComputation {
         return { found: true, value }
     }
 
-    /**
-     * Creates a collision-free string key for a property path.
-     * @param {PropertyKey[]} path Input path.
-     * @returns {string} Registry key.
-     */
-    #pathKey(path) {
-        return path
-            .map((property) => {
-                if (typeof property === 'symbol') {
-                    if (!this.#symbolIds.has(property)) {
-                        this.#symbolIds.set(property, this.#nextSymbolId)
-                        this.#nextSymbolId += 1
-                    }
-                    return 'y' + this.#symbolIds.get(property)
-                }
-                const text = String(property)
-                return 's' + text.length + ':' + text
-            })
-            .join('|')
-    }
-
     /**
      * Rejects mutation through a tracked snapshot.
      * @returns {never}

package/src/core/context/CircuitJsonExtensionBoundary.mjs

@@ -6,7 +6,7 @@ const OWNED_EXTENSION_ROOTS = new WeakSet()
 const EXTENSION_METADATA_LIMITS = Object.freeze({
     label: 'Canonical extension data',
     maxBytes: 128 * 1024 * 1024,
-    maxItems: 4_000_000,
+    maxItems: 8_000_000,
     preserveBinary: true
 })
 

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/context/StructuredCloneTextAccounting.mjs

@@ -1,4 +1,5 @@
 const TEXT_ACCOUNTING_CHUNK_CHARACTERS = 64 * 1_024
+const SHORT_TEXT_CHARACTERS = 256
 const STRING_CHAR_CODE_AT = String.prototype.charCodeAt
 const STRING_SLICE = String.prototype.slice
 const TEXT_ENCODER = new TextEncoder()
@@ -17,6 +18,14 @@ export class StructuredCloneTextAccounting {
      */
     static *reserve(value, state, operations) {
         if (state.maxBytes === Number.MAX_SAFE_INTEGER) return
+        if (value.length <= SHORT_TEXT_CHARACTERS) {
+            const length = StructuredCloneTextAccounting.#shortByteLength(value)
+            if (state.bytes + length > state.maxBytes) {
+                throw new TypeError(`${state.label} is too large.`)
+            }
+            operations.reserve(length)
+            return
+        }
         let length = 0
         let offset = 0
         while (offset < value.length) {
@@ -49,6 +58,35 @@ export class StructuredCloneTextAccounting {
         }
         operations.reserve(length)
     }
+
+    /**
+     * Counts bounded short text without allocating an encoded byte buffer.
+     * Lone surrogates consume the three UTF-8 bytes of a replacement character.
+     * @param {string} value Short immutable text.
+     * @returns {number} UTF-8 byte length.
+     */
+    static #shortByteLength(value) {
+        let length = 0
+        for (let index = 0; index < value.length; index += 1) {
+            const code = STRING_CHAR_CODE_AT.call(value, index)
+            if (code <= 0x7f) {
+                length += 1
+            } else if (code <= 0x7ff) {
+                length += 2
+            } else if (code >= 0xd800 && code <= 0xdbff) {
+                const next = STRING_CHAR_CODE_AT.call(value, index + 1)
+                if (next >= 0xdc00 && next <= 0xdfff) {
+                    length += 4
+                    index += 1
+                } else {
+                    length += 3
+                }
+            } else {
+                length += 3
+            }
+        }
+        return length
+    }
 }
 
 Object.freeze(StructuredCloneTextAccounting.prototype)

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),