@metamesh/modeling 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @metamesh/modeling
 
+## 0.12.0
+
+### Minor Changes
+
+- 45d2617: Replace named computed bindings with an optional dependency array as the third argument:
+  `computed(id, callback, dependencies?)`. Automatic parameter and computation tracking remains
+  enabled; the array supplements it for values captured outside the callback, including destructured
+  parameters. Update existing named-binding calls to close over those values and list their dependencies.
+
+  Compare dependency entries by identity, preserve computed reader chaining and cache verification,
+  and reject mutable object or array dependencies without adding deep comparisons to generation.
+
 ## 0.11.0
 
 ### Minor Changes

package/README.md

@@ -51,12 +51,26 @@ const model = generate<{ height: number; gap: number }>(({ params, computed, par
 });
 ```
 
-Changing `gap` reuses the body's validated geometry. Changing `height` recomputes it. Computations
-are pure and synchronous: bind changing locals explicitly with `computed(id, { value }, inputs => ...)`.
+Changing `gap` reuses the body's validated geometry. Changing `height` recomputes it. Read parameters
+and computed readers inside the callback; locals calculated there keep those reads tracked.
+For changing values prepared outside, add a dependency array:
+
+```ts
+const { height } = params;
+const body = computed("body", () => box({ size: [10, 10, height] }), [height]);
+```
+
+Both forms track synchronous parameter and reader calls inside the callback. An earlier parameter
+value or computed result carries no dependency into a later callback unless listed explicitly.
+The array supplements automatic tracking; even `[]` still tracks reads inside the callback.
+Entries compare with `Object.is`, without deep comparisons. Objects and arrays must be deeply
+immutable; parameter snapshots and computed results already satisfy this contract. Fresh objects
+still cause cache misses, so prefer scalar inputs and create temporary options inside the callback.
+Computations are pure and synchronous; ordinary generation without caching remains supported.
 
 Capture cached numeric arrays with `immutableBuffer(values)`: read `length` or `at(index)`, and
 call `copy()` for an owned mutable typed array. Capture cached meshes with `immutableMesh(mesh)`
-and pass their readers directly to `part`. Computed results and bindings reject raw typed arrays;
+and pass their readers directly to `part`. Computed results and dependencies reject raw typed arrays;
 ordinary transient mesh inputs, snapshots, and Worker output still use normal typed arrays.
 
 The optional session setting `verifyCache: true` reruns callbacks on cache hits and compares bounded

package/dist/api/index.d.ts

@@ -464,11 +464,12 @@ export declare interface GenerateContext<P, S = Record<never, never>> {
     readonly params: Readonly<P>;
     /** Host-prepared readonly synchronous capabilities, fixed for the session. */
     readonly services: Readonly<S>;
-    /** Registers a lazy pure calculation; capture changing locals through explicit bindings. */
-    readonly computed: {
-        <T>(id: string, callback: () => T): Computed<T>;
-        <B extends Readonly<Record<string, unknown>>, T>(id: string, bindings: B, callback: (bindings: B) => T): Computed<T>;
-    };
+    /**
+     * Registers a lazy pure calculation and automatically tracks parameter and computed-reader reads.
+     * Optional dependencies add changing outer captures; entries compare with Object.is. Objects and
+     * arrays must be deeply immutable. An empty list still tracks reads inside the callback.
+     */
+    readonly computed: <T>(id: string, callback: () => T, dependencies?: readonly unknown[]) => Computed<T>;
     /** Declares a semantic part with identity placement, or explicit placement and appearance. */
     readonly part: {
         (id: string, geometry: ComputedValue<PartGeometry>): GeneratedPart;

package/dist/engine/immutable-generation-data.js

@@ -1,7 +1,7 @@
 import { GeometryError } from "../geometry/errors.js";
 import { adoptImmutableBuffer, immutableBuffer, immutableBufferView, isImmutableBuffer, } from "../model/immutable-buffer.js";
 import { geometryRecipe, isGeometryRecipe } from "./geometry-recipes.js";
-const mutableBufferMessage = "Generation data cannot contain mutable typed arrays or raw ArrayBuffers. Use immutableBuffer(array) or immutableMesh(mesh) before caching or binding them.";
+const mutableBufferMessage = "Generation data cannot contain mutable typed arrays or raw ArrayBuffers. Use immutableBuffer(array) or immutableMesh(mesh) before caching them or declaring dependencies.";
 /** Iterates plain fields; recipe capture may read each enumerable accessor once. */
 export function* generationDataEntries(value, captureAccessors = false) {
     const prototype = Object.getPrototypeOf(value);
@@ -144,15 +144,18 @@ export function compareGenerationValues(left, right) {
     };
     return compare(left, right);
 }
-function captureValue(value, recipeInputs, readerAllowed = () => false) {
+function captureValue(value, mode, readerAllowed = () => false, validated) {
+    const recipeInputs = mode === "recipe";
     const seen = new Map();
     const copy = (input) => {
         if (typeof input === "function" && !recipeInputs && !readerAllowed(input))
-            throw new GeometryError("INVALID_ARGUMENT", "Computed values and bindings cannot contain arbitrary function closures.", { operation: "computed" });
+            throw new GeometryError("INVALID_ARGUMENT", "Computed values and dependencies cannot contain arbitrary function closures.", { operation: "computed" });
         if (typeof input !== "object" || input === null || isGeometryRecipe(input))
             return input;
         if (isImmutableBuffer(input))
             return adoptImmutableBuffer(input);
+        if (mode === "dependency" && validated?.has(input))
+            return input;
         const old = seen.get(input);
         if (old !== undefined)
             return old;
@@ -166,6 +169,14 @@ function captureValue(value, recipeInputs, readerAllowed = () => false) {
         if (input instanceof ArrayBuffer)
             throw new TypeError(mutableBufferMessage);
         const entries = generationDataEntries(input, recipeInputs);
+        if (mode === "dependency") {
+            if (!Object.isFrozen(input))
+                throw new GeometryError("INVALID_ARGUMENT", "Computed dependencies require deeply immutable objects and arrays. Read params inside the callback, use a computed value, or depend on individual scalar values.", { operation: "computed" });
+            seen.set(input, input);
+            for (const [, field] of entries)
+                copy(field);
+            return input;
+        }
         const result = Array.isArray(input)
             ? new Array(input.length)
             : Object.create(Object.getPrototypeOf(input) === null ? null : Object.prototype);
@@ -174,13 +185,32 @@ function captureValue(value, recipeInputs, readerAllowed = () => false) {
             Object.defineProperty(result, key, { value: copy(field), enumerable: true });
         return Object.freeze(result);
     };
-    return copy(value);
+    const result = copy(value);
+    // Cache validation only after the complete immutable graph succeeds, including cycles.
+    if (mode === "dependency")
+        for (const input of seen.keys())
+            validated?.add(input);
+    return result;
 }
 /** Validates while capturing immutable data; only explicitly allowed session readers may be functions. */
 export function captureGenerationValue(value, readerAllowed) {
-    return captureValue(value, false, readerAllowed);
+    return captureValue(value, "data", readerAllowed);
+}
+/** Snapshots the list, preserving immutable entry identities and validating each object only once. */
+export function captureGenerationDependencies(values, readerAllowed, validated) {
+    const inputs = [];
+    for (const [key, value] of generationDataEntries(values)) {
+        if (key !== String(inputs.length))
+            throw new TypeError("Computed dependencies must be a dense array without extra fields.");
+        inputs.push(value);
+    }
+    if (inputs.length !== values.length)
+        throw new TypeError("Computed dependencies must be a dense array without extra fields.");
+    const result = Object.freeze(inputs);
+    captureValue(result, "dependency", readerAllowed, validated);
+    return result;
 }
 /** Captures ordinary inputs once, including accessor values and mutable numeric arrays. */
 export function captureRecipeInputs(values) {
-    return captureValue(values, true);
+    return captureValue(values, "recipe");
 }

package/dist/engine/session-graph.js

@@ -1,6 +1,6 @@
 import { GeometryError } from "../geometry/errors.js";
 import { GenerationError, } from "../model/generation.js";
-import { captureGenerationValue, compareGenerationValues, generationDataEntries, } from "./immutable-generation-data.js";
+import { captureGenerationDependencies, captureGenerationValue, compareGenerationValues, generationDataEntries, } from "./immutable-generation-data.js";
 import { createModelDependencies } from "./model-dependencies.js";
 import { assertSynchronousScopeResult } from "./native/ownership.js";
 function reusableEntry(node) {
@@ -11,17 +11,13 @@ function reusableEntry(node) {
     return undefined;
 }
 const parameterKeys = Symbol("parameter-keys");
-const emptyBindings = Object.freeze({});
+const emptyInputs = Object.freeze([]);
 const isArray = (value) => Array.isArray(value);
 const canonicalId = (id) => typeof id === "string" && id.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id);
 function invalid(message) {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "generate" });
 }
-const sameBindings = (left, right) => {
-    const keys = Object.keys(left);
-    return (keys.length === Object.keys(right).length &&
-        keys.every((key) => Object.hasOwn(right, key) && Object.is(left[key], right[key])));
-};
+const sameInputs = (left, right) => left.length === right.length && left.every((value, index) => Object.is(value, right[index]));
 function evaluateComputed(callback) {
     const result = callback();
     assertSynchronousScopeResult(result, () => new GeometryError("INVALID_ARGUMENT", "Computed callbacks must be synchronous.", {
@@ -46,16 +42,18 @@ class ComputationRevision {
     parameterSnapshot;
     committed;
     readerIds;
+    validatedInputs;
     assertActive;
     assertNoFailedAssertion;
     nodes = new Map();
     keySignature;
     stack = [];
-    constructor(options, parameterSnapshot, committed, readerIds, assertActive, assertNoFailedAssertion) {
+    constructor(options, parameterSnapshot, committed, readerIds, validatedInputs, assertActive, assertNoFailedAssertion) {
         this.options = options;
         this.parameterSnapshot = parameterSnapshot;
         this.committed = committed;
         this.readerIds = readerIds;
+        this.validatedInputs = validatedInputs;
         this.assertActive = assertActive;
         this.assertNoFailedAssertion = assertNoFailedAssertion;
         // Structural reads share one unambiguous signature, even when parameter names contain NUL.
@@ -77,27 +75,22 @@ class ComputationRevision {
         this.nodes.clear();
         this.committed = new Map();
     }
-    register(id, bindingsOrCallback, callback) {
+    register(id, callback, dependencies = emptyInputs) {
         if (!canonicalId(id) || this.nodes.has(id))
             invalid("Computed IDs must be unique canonical lowercase identifiers of at most 64 characters.");
         if (this.nodes.size >= 100_000)
             throw new GeometryError("COMPLEXITY_LIMIT", "Too many declared computations.", {
                 operation: "computed",
             });
-        const bindings = typeof bindingsOrCallback === "function"
-            ? emptyBindings
-            : Object.freeze(Object.fromEntries(generationDataEntries(bindingsOrCallback)));
+        if (typeof callback !== "function" || !Array.isArray(dependencies))
+            invalid("Use computed(id, callback, dependencies?) with an optional dependency array.");
+        const inputs = dependencies === emptyInputs
+            ? emptyInputs
+            : captureGenerationDependencies(dependencies, (value) => this.readerIds.has(value), this.validatedInputs);
         const previous = this.committed.get(id);
-        let boundInputs;
-        if (previous !== undefined && sameBindings(previous.bindings, bindings))
-            boundInputs = previous.boundInputs;
-        else
-            boundInputs = captureGenerationValue(bindings, (value) => this.readerIds.has(value));
-        const invoke = typeof bindingsOrCallback === "function" ? bindingsOrCallback : () => callback(boundInputs);
         this.nodes.set(id, {
-            callback: invoke,
-            bindings,
-            boundInputs,
+            callback,
+            inputs,
             previous,
             state: { kind: "pending" },
         });
@@ -162,7 +155,7 @@ class ComputationRevision {
         }
     }
     canReuse(node, previous) {
-        if (this.options.cache === false || node.boundInputs !== previous.boundInputs)
+        if (this.options.cache === false || !sameInputs(node.inputs, previous.inputs))
             return false;
         for (const [key, value] of previous.parameters) {
             const current = key === parameterKeys ? this.keySignature : Reflect.get(this.parameterSnapshot, key);
@@ -191,6 +184,18 @@ class ComputationRevision {
         evaluation.parameters.clear();
         evaluation.dependencies.clear();
         evaluation.cacheable = true;
+        // Declared readers depend on their output, not just their stable callable identity.
+        for (const input of node.inputs) {
+            const dependency = typeof input === "function" ? this.readerIds.get(input) : undefined;
+            if (dependency !== undefined) {
+                try {
+                    this.read(dependency);
+                }
+                catch {
+                    // Failed reads already prevent reuse; the callback owns propagation or fallback.
+                }
+            }
+        }
         const result = evaluateComputed(node.callback);
         this.assertNoFailedAssertion();
         const previous = node.previous;
@@ -198,14 +203,13 @@ class ComputationRevision {
         if (reusable && previous !== undefined) {
             const comparison = compareGenerationValues(previous.value, result);
             if (comparison === "different")
-                invalid(`Cache verification for '${id}' found a changed result without a tracked dependency. Bind changing local values explicitly.`);
+                invalid(`Cache verification for '${id}' found a changed result without a tracked dependency. Add changing outer values to the dependency array.`);
             if (comparison === "unsupported")
                 invalid(`Cache verification for '${id}' cannot compare this result within its bounded data/recipe probe. Use cache: false for a full output equivalence check.`);
             value = previous.value;
         }
         return Object.freeze({
-            bindings: node.bindings,
-            boundInputs: node.boundInputs,
+            inputs: node.inputs,
             parameters: evaluation.parameters,
             dependencies: evaluation.dependencies,
             value,
@@ -221,11 +225,12 @@ export function createGenerationGraph(options, maxParts) {
     let committed = new Map();
     const readers = new Map();
     const readerIds = new WeakMap();
+    const validatedInputs = new WeakSet();
     let activeRead;
     let previousInput = {};
     let previousParameterSnapshot = {};
     // Build stable readers outside registration's lexical scope so they cannot retain a revision's
-    // callback, captured locals, or copied bindings after that revision closes.
+    // callback, captured locals, or dependency inputs after that revision closes.
     const createReader = (id) => (() => {
         if (activeRead === undefined)
             return invalid("Computed readers can only be used during their active model session revision.");
@@ -251,7 +256,7 @@ export function createGenerationGraph(options, maxParts) {
                 if (assertionFailure !== undefined)
                     throw assertionFailure;
             };
-            const computations = new ComputationRevision(options, parameterSnapshot, committed, readerIds, assertActive, assertNoFailedAssertion);
+            const computations = new ComputationRevision(options, parameterSnapshot, committed, readerIds, validatedInputs, assertActive, assertNoFailedAssertion);
             const params = new Proxy(parameterSnapshot, {
                 get: (target, key) => {
                     assertActive();
@@ -300,11 +305,11 @@ export function createGenerationGraph(options, maxParts) {
                 },
             });
             activeRead = computations.read;
-            const computed = ((id, bindingsOrCallback, callback) => {
+            const computed = ((id, callback, dependencies) => {
                 assertActive();
                 if (!declaring || computations.evaluating)
                     invalid("Declare computations only in the outer generation callback.");
-                computations.register(id, bindingsOrCallback, callback);
+                computations.register(id, callback, dependencies);
                 let reader = readers.get(id);
                 if (reader === undefined) {
                     reader = createReader(id);
@@ -403,7 +408,7 @@ export function createGenerationGraph(options, maxParts) {
                     for (const node of computations.nodes.values()) {
                         const entry = reusableEntry(node);
                         if (entry !== undefined)
-                            retained.push(entry.value, entry.bindings, entry.boundInputs, ...entry.parameters.values());
+                            retained.push(entry.value, entry.inputs, ...entry.parameters.values());
                     }
                     return [...retained, parameterSnapshot, inputValues];
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamesh/modeling",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Scoped solid modeling and pure geometry foundations for Node and browsers.",
   "license": "Apache-2.0",
   "repository": {