@metamesh/modeling 0.18.0 → 0.20.0

package/dist/engine/recipe-realization.js

@@ -4,8 +4,9 @@ import { isImmutableMathValue } from "../geometry/math/immutable-value.js";
 import { geometryRecipe, isGeometryRecipe } from "../model/geometry-recipes.js";
 import { generationDataMetadata } from "../model/immutable-generation-data.js";
 /**
- * Evaluates immutable recipes within one host revision. These maps memoize borrowed native handles;
- * the execution scope still owns allocation and cleanup, including handles restored from cache.
+ * Evaluates immutable recipes within one host revision. These maps memoize borrowed native handles.
+ * The execution scope owns new allocations; the native cache retains ownership and cleanup
+ * responsibility for restored handles.
  */
 export class RecipeRealization {
     session;
@@ -25,6 +26,11 @@ export class RecipeRealization {
     }
     /** Explicit recipe settings override this host's defaults; unspecified settings remain inherited. */
     invoke(call) {
+        const context = this.contextFor(call);
+        this.realizeShapes([...recipeShapes(call.args)]);
+        return this.invokeNative(call, context);
+    }
+    contextFor(call) {
         const resolution = call.resolution;
         let context = this.nativeContexts.get(resolution);
         if (context === undefined) {
@@ -32,6 +38,9 @@ export class RecipeRealization {
             context = resolution === undefined ? host : host.withResolution(resolution);
             this.nativeContexts.set(resolution, context);
         }
+        return context;
+    }
+    invokeNative(call, context) {
         const operation = context[call.method];
         const args = this.resolveValue(call.args, true);
         return this.duringNative(() => Reflect.apply(operation, undefined, args));
@@ -43,12 +52,13 @@ export class RecipeRealization {
         return this.resolvedCalls.get(call);
     }
     resolve(shape) {
-        return this.resolveValue(shape);
+        this.realizeShapes([shape]);
+        return this.realized.get(shape);
     }
     realizedShape(shape) {
         return this.realized.get(shape);
     }
-    /** Prefers intermediate operands when not every computed output fits the retention budget. */
+    /** Prefers intermediate operands when not every memo output fits the retention budget. */
     retentionCandidates(values) {
         const shapes = new Set(recipeShapes(values));
         return [...shapes].sort((left, right) => Number(this.operands.has(right)) - Number(this.operands.has(left)));
@@ -57,30 +67,68 @@ export class RecipeRealization {
     assertAccessible(shape) {
         if (this.accessible.has(shape))
             return;
-        const recipe = geometryRecipe(shape);
-        if (recipe.observedSession !== undefined && recipe.observedSession !== this.session)
-            throw new GeometryError("INVALID_ARGUMENT", "Observed components can only be evaluated in the model session that selected them.", { operation: "components" });
-        for (const operand of recipeShapes(recipe.call.args))
-            this.assertAccessible(operand);
-        this.accessible.add(shape);
+        const pending = [shape];
+        const checked = new Set();
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (this.accessible.has(current) || checked.has(current))
+                continue;
+            const recipe = geometryRecipe(current);
+            if (recipe.observedSession !== undefined && recipe.observedSession !== this.session)
+                throw new GeometryError("INVALID_ARGUMENT", "Observed components can only be evaluated in the model session that selected them.", { operation: "components" });
+            checked.add(current);
+            for (const operand of recipeShapes(recipe.call.args))
+                pending.push(operand);
+        }
+        // Do not mark a parent accessible if validation of a descendant failed and was caught.
+        for (const current of checked)
+            this.accessible.add(current);
     }
-    realizeShape(shape) {
-        const recipe = geometryRecipe(shape);
-        this.assertAccessible(shape);
-        if (this.realized.has(shape))
-            return this.realized.get(shape);
-        // Restoring a retained value avoids replay but still borrows through this revision's scope.
-        const retained = this.restoreNative(shape);
-        if (retained !== undefined) {
-            this.realized.set(shape, retained);
-            return retained;
+    /**
+     * Evaluates recipes in operand order with an explicit work stack.
+     * A retained parent bypasses evaluation of its children, but never their ownership validation.
+     */
+    realizeShapes(shapes) {
+        for (const shape of shapes)
+            this.assertAccessible(shape);
+        const pending = shapes
+            .map((shape) => ({ kind: "shape", shape }))
+            .reverse();
+        while (pending.length > 0) {
+            const work = pending.pop();
+            if (work.kind === "invoke") {
+                if (!this.resolvedCalls.has(work.call))
+                    this.resolvedCalls.set(work.call, this.invokeNative(work.call, work.context));
+                continue;
+            }
+            const { shape } = work;
+            const recipe = geometryRecipe(shape);
+            if (work.kind === "select") {
+                const result = this.resolvedCalls.get(recipe.call);
+                this.realized.set(shape, recipe.index === undefined
+                    ? result
+                    : result[recipe.index]);
+                continue;
+            }
+            if (this.realized.has(shape))
+                continue;
+            // Restoring a parent avoids realizing its operands, after validating their ownership.
+            const retained = this.restoreNative(shape);
+            if (retained !== undefined) {
+                this.realized.set(shape, retained);
+                continue;
+            }
+            // LIFO order is operands -> native call -> selected handle. Shared split/joint calls
+            // execute once; later selections read the cached call result without replaying operands.
+            pending.push({ kind: "select", shape });
+            if (!this.resolvedCalls.has(recipe.call)) {
+                const context = this.contextFor(recipe.call);
+                pending.push({ kind: "invoke", call: recipe.call, context });
+                const operands = [...recipeShapes(recipe.call.args)];
+                for (let index = operands.length - 1; index >= 0; index--)
+                    pending.push({ kind: "shape", shape: operands[index] });
+            }
         }
-        const result = this.evaluate(recipe.call);
-        const selected = recipe.index === undefined
-            ? result
-            : result[recipe.index];
-        this.realized.set(shape, selected);
-        return selected;
     }
     /** Copies argument containers so native code cannot mutate captured recipe inputs. */
     resolveValue(value, operand = false, seen = new Map()) {
@@ -89,7 +137,7 @@ export class RecipeRealization {
         if (isGeometryRecipe(value)) {
             if (operand)
                 this.operands.add(value);
-            return this.realizeShape(value);
+            return this.realized.get(value);
         }
         if (typeof value === "object" && value !== null && isImmutableMathValue(value))
             return value;
@@ -115,14 +163,22 @@ export class RecipeRealization {
     }
 }
 /** Walks captured data once, including shared and cyclic containers, without inspecting buffers. */
-function* recipeShapes(values, seen = new Set()) {
-    for (const value of values) {
+function* recipeShapes(values) {
+    const seen = new Set();
+    const pending = [values[Symbol.iterator]()];
+    while (pending.length > 0) {
+        const next = pending.at(-1).next();
+        if (next.done) {
+            pending.pop();
+            continue;
+        }
+        const value = next.value;
         if (typeof value !== "object" || value === null || seen.has(value))
             continue;
         seen.add(value);
         const metadata = generationDataMetadata(value);
         if (metadata !== undefined) {
-            yield* recipeShapes(metadata.children, seen);
+            pending.push(metadata.children[Symbol.iterator]());
             continue;
         }
         if (isGeometryRecipe(value))
@@ -130,6 +186,6 @@ function* recipeShapes(values, seen = new Set()) {
         else if (!isImmutableBuffer(value) &&
             !ArrayBuffer.isView(value) &&
             !isImmutableMathValue(value))
-            yield* recipeShapes(Object.values(value), seen);
+            pending.push(Object.values(value)[Symbol.iterator]());
     }
 }

package/dist/engine/session/declarations.js

@@ -0,0 +1,98 @@
+import { GeometryError } from "../../geometry/errors.js";
+import { captureDiagnosticPath } from "../../model/diagnostic-path.js";
+import { GenerationError, } from "../../model/generation.js";
+import { assertSynchronousScopeResult } from "../native/ownership.js";
+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: "memo" });
+}
+/** Owns one revision's parts and diagnostics; caught assertions remain fatal to that revision. */
+export function createGenerationDeclarations(options) {
+    const { assertActive, isMemoEvaluating, hasParameter } = options;
+    const diagnostics = [];
+    const declaredParts = new WeakSet();
+    const partIds = new Set();
+    let declaring = true;
+    let assertionFailure;
+    const assertNoFailedAssertion = () => {
+        if (assertionFailure !== undefined)
+            throw assertionFailure;
+    };
+    const issue = (severity, message, metadata) => {
+        assertActive();
+        if (typeof message !== "string" || message.length === 0)
+            invalid("Diagnostics require a nonempty message.");
+        if (metadata?.parameterId !== undefined && !hasParameter(metadata.parameterId))
+            invalid("Diagnostic parameterId must name an existing parameter.");
+        diagnostics.push(Object.freeze({
+            severity,
+            message,
+            ...(metadata?.parameterId === undefined ? {} : { parameterId: metadata.parameterId }),
+            ...(metadata?.path === undefined ? {} : { path: captureDiagnosticPath(metadata.path) }),
+        }));
+        if (severity === "error") {
+            // A model's catch block must not turn a failed assertion into a successful revision.
+            assertionFailure ??= new GenerationError(diagnostics);
+            throw assertionFailure;
+        }
+    };
+    const part = (id, value) => {
+        assertActive();
+        if (!declaring || isMemoEvaluating())
+            invalid("Declare parts only in outer generation.");
+        if (!canonicalId(id) || partIds.has(id))
+            invalid("Part IDs must be unique canonical identifiers.");
+        partIds.add(id);
+        const configuration = typeof value === "object" && value !== null && "geometry" in value
+            ? value
+            : { geometry: value };
+        if ("position" in configuration || "rotation" in configuration)
+            invalid("Part placement uses transform.");
+        if ([configuration.geometry, configuration.transform].some((item) => typeof item === "function"))
+            invalid("Parts require ordinary geometry and transform values.");
+        const descriptor = Object.freeze({ ...configuration, id });
+        declaredParts.add(descriptor);
+        return descriptor;
+    };
+    function assert(condition, message, metadata) {
+        assertActive();
+        if (typeof condition !== "boolean")
+            invalid("assert requires a boolean condition.");
+        if (!condition)
+            issue("error", message, metadata);
+    }
+    const warn = (message, metadata) => {
+        if (!declaring || isMemoEvaluating())
+            invalid("Warnings must be emitted in outer generation.");
+        issue("warning", message, metadata);
+    };
+    return {
+        part,
+        assert,
+        warn,
+        diagnostics: diagnostics,
+        get declaring() {
+            return declaring;
+        },
+        assertNoFailedAssertion,
+        finish(output) {
+            assertSynchronousScopeResult(output, () => new GeometryError("INVALID_ARGUMENT", "Generation callbacks must be synchronous."));
+            assertNoFailedAssertion();
+            declaring = false;
+            const parts = Array.isArray(output)
+                ? output
+                : [output];
+            if (parts.length === 0)
+                invalid("Generation must return at least one declared part.");
+            if (parts.length > options.maxParts)
+                throw new GeometryError("COMPLEXITY_LIMIT", `Output exceeds ${options.maxParts} parts.`);
+            const ids = new Set();
+            for (const descriptor of parts) {
+                if (!declaredParts.has(descriptor) || ids.has(descriptor.id))
+                    invalid("Return each declared output part at most once.");
+                ids.add(descriptor.id);
+            }
+            return parts;
+        },
+    };
+}

package/dist/engine/session/dependencies.js

@@ -1,46 +1,146 @@
-/** Projects recorded reads into immutable host metadata without evaluating any computation. */
-export function createModelDependencies(output, modelParameters, entries, readerIds) {
-    const parameterNames = (entry) => [...(entry?.parameters.keys() ?? [])].filter((key) => typeof key === "string");
-    const rootParameters = new Map();
-    const parametersFor = (root) => {
-        const cached = rootParameters.get(root);
-        if (cached !== undefined)
-            return cached;
-        const parameters = new Set();
-        const visited = new Set();
-        const pending = [root];
+import { isImmutableBuffer } from "../../geometry/immutable-buffer.js";
+import { isImmutableMathValue } from "../../geometry/math/immutable-value.js";
+import { geometryRecipe } from "../../model/geometry-recipes.js";
+import { generationDataMetadata } from "../../model/immutable-generation-data.js";
+const objectValue = (value) => typeof value === "object" && value !== null;
+function children(value, includeRecipeOperands = false) {
+    if (isImmutableBuffer(value) ||
+        isImmutableMathValue(value) ||
+        ArrayBuffer.isView(value) ||
+        value instanceof ArrayBuffer)
+        return [];
+    const recipe = geometryRecipe(value);
+    if (recipe !== undefined)
+        return includeRecipeOperands ? recipe.call.args : [];
+    return generationDataMetadata(value)?.children ?? Object.values(value);
+}
+/**
+ * Projects diagnostic provenance without participating in cache invalidation.
+ * Immutable membership summaries and their weak reverse index survive revisions; origin IDs do not.
+ */
+export function createMemoProvenance() {
+    const summaries = new WeakMap();
+    const memberships = new WeakMap();
+    const summarize = (value) => {
+        let summary = summaries.get(value);
+        if (summary !== undefined)
+            return summary;
+        summary = new WeakSet();
+        const reference = new WeakRef(summary);
+        const pending = [value];
         while (pending.length > 0) {
-            const id = pending.pop();
-            if (visited.has(id))
+            const current = pending.pop();
+            if (summary.has(current))
                 continue;
-            visited.add(id);
-            const entry = entries.get(id);
-            for (const key of parameterNames(entry))
-                parameters.add(key);
-            for (const dependency of entry?.dependencies.keys() ?? [])
-                pending.push(dependency);
+            summary.add(current);
+            let membership = memberships.get(current);
+            if (membership === undefined) {
+                membership = { summaries: new Set(), compactAt: 16 };
+                memberships.set(current, membership);
+            }
+            // A surviving child must not retain its obsolete output containers. Weak references
+            // preserve warm summaries without keeping roots alive. Geometric compaction amortizes
+            // cleanup even when many live outputs share this child; queries also prune dead entries.
+            if (membership.summaries.size >= membership.compactAt) {
+                for (const known of membership.summaries)
+                    if (known.deref() === undefined)
+                        membership.summaries.delete(known);
+                membership.compactAt = Math.max(16, membership.summaries.size * 2);
+            }
+            membership.summaries.add(reference);
+            for (const child of children(current))
+                if (objectValue(child))
+                    pending.push(child);
         }
-        const result = [...parameters];
-        rootParameters.set(root, result);
-        return result;
+        summaries.set(value, summary);
+        return summary;
     };
-    return Object.freeze({
-        modelParameters: Object.freeze([...modelParameters].sort()),
-        computations: Object.freeze([...entries].map(([id, entry]) => Object.freeze({
-            id,
-            parameters: Object.freeze(parameterNames(entry).sort()),
-            computations: Object.freeze([...(entry?.dependencies.keys() ?? [])].sort()),
-        }))),
-        parts: Object.freeze(output.map((part) => {
-            const roots = [part.geometry, part.transform].flatMap((value) => {
-                const id = typeof value === "function" ? readerIds.get(value) : undefined;
-                return id === undefined ? [] : [id];
-            });
+    return (output, modelParameters, calls) => {
+        const origins = new Map();
+        const owners = (value) => {
+            const found = new Set();
+            const membership = memberships.get(value);
+            if (membership === undefined)
+                return found;
+            // Cached dormant outputs can outnumber this revision's calls. Probe the smaller index
+            // so a surviving shared child does not make current work proportional to cache history.
+            if (origins.size < membership.summaries.size) {
+                for (const [summary, ids] of origins)
+                    if (summary.has(value))
+                        for (const id of ids)
+                            found.add(id);
+                return found;
+            }
+            for (const reference of membership.summaries) {
+                const summary = reference.deref();
+                if (summary === undefined)
+                    membership.summaries.delete(reference);
+                else
+                    for (const id of origins.get(summary) ?? [])
+                        found.add(id);
+            }
+            return found;
+        };
+        const transitive = new Map();
+        const roots = (values) => {
+            const found = new Set(), visited = new WeakSet();
+            const pending = [...values];
+            while (pending.length > 0) {
+                const value = pending.pop();
+                if (!objectValue(value) || visited.has(value))
+                    continue;
+                visited.add(value);
+                const known = owners(value);
+                for (const id of known)
+                    found.add(id);
+                // Once an object has an origin, its owning calls supply transitive dependencies.
+                // Only unowned recipes expose operands; containing a recipe never claims its operands.
+                if (known.size === 0)
+                    for (const child of children(value, true))
+                        pending.push(child);
+            }
+            return found;
+        };
+        const allParameters = (direct, dependencies) => {
+            const parameters = new Set(direct);
+            for (const dependency of dependencies)
+                for (const parameter of transitive.get(dependency) ?? [])
+                    parameters.add(parameter);
+            return parameters;
+        };
+        const computations = calls.map((call) => {
+            // Publish this output's origin after reading its inputs: aliases can depend on earlier
+            // producers of the same value, while the current call cannot become its own dependency.
+            const dependencies = roots(call.inputs);
+            const parameters = [...call.parameters.keys()]
+                .filter((key) => typeof key === "string")
+                .sort();
+            transitive.set(call.id, allParameters(parameters, dependencies));
+            if (objectValue(call.value)) {
+                const summary = summarize(call.value);
+                const known = origins.get(summary);
+                if (known === undefined)
+                    origins.set(summary, [call.id]);
+                else
+                    known.push(call.id);
+            }
             return Object.freeze({
-                id: part.id,
-                computations: Object.freeze(roots),
-                parameters: Object.freeze([...new Set(roots.flatMap(parametersFor))].sort()),
+                id: call.id,
+                parameters: Object.freeze(parameters),
+                computations: Object.freeze([...dependencies].sort()),
             });
-        })),
-    });
+        });
+        return Object.freeze({
+            modelParameters: Object.freeze([...modelParameters].sort()),
+            computations: Object.freeze(computations),
+            parts: Object.freeze(output.map((part) => {
+                const dependencies = roots([part.geometry, part.transform]);
+                return Object.freeze({
+                    id: part.id,
+                    computations: Object.freeze([...dependencies].sort()),
+                    parameters: Object.freeze([...allParameters([], dependencies)].sort()),
+                });
+            })),
+        });
+    };
 }