@metamesh/modeling 0.10.0 → 0.11.0

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

@@ -0,0 +1,186 @@
+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.";
+/** Iterates plain fields; recipe capture may read each enumerable accessor once. */
+export function* generationDataEntries(value, captureAccessors = false) {
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
+        throw new TypeError("Generation values must be immutable plain data or Modeling recipes.");
+    for (const key of Reflect.ownKeys(value)) {
+        if (Array.isArray(value) && key === "length")
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!captureAccessors && !("value" in descriptor))
+            throw new GeometryError("INVALID_ARGUMENT", "Generation data requires own data fields, not accessors.", { operation: "computed" });
+        if (typeof key !== "string" || !descriptor.enumerable)
+            throw new TypeError("Generation data requires enumerable string-keyed fields.");
+        yield [
+            key,
+            "value" in descriptor ? descriptor.value : Reflect.get(value, key),
+        ];
+    }
+}
+/** Conservative retained-data estimate used only to evict optional session caches. */
+export function generationValueBytes(values, ceiling) {
+    const seen = new Set();
+    const buffers = new Set();
+    let bytes = 0;
+    const visit = (value, depth) => {
+        if (bytes > ceiling)
+            return;
+        if (depth > 128) {
+            bytes = Infinity;
+            return;
+        }
+        if (typeof value === "string") {
+            bytes += value.length * 2;
+            return;
+        }
+        if (typeof value !== "object" || value === null) {
+            bytes += 8;
+            return;
+        }
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        const array = isImmutableBuffer(value)
+            ? immutableBufferView(value)
+            : ArrayBuffer.isView(value)
+                ? value
+                : undefined;
+        if (array !== undefined) {
+            if (!buffers.has(array.buffer)) {
+                buffers.add(array.buffer);
+                bytes += array.buffer.byteLength;
+            }
+            return;
+        }
+        const recipe = geometryRecipe(value);
+        // Empty records and long field names still occupy retained storage.
+        bytes += 32;
+        if (recipe !== undefined) {
+            visit(recipe.call, depth + 1);
+            return;
+        }
+        for (const [key, item] of Object.entries(value)) {
+            bytes += 16 + key.length * 2;
+            visit(item, depth + 1);
+        }
+    };
+    values.forEach((value) => visit(value, 0));
+    return bytes;
+}
+/** Bounded development probe, deliberately separate from normal cache equality or production work. */
+export function compareGenerationValues(left, right) {
+    let remaining = 10_000;
+    const visited = new Map();
+    const compare = (a, b, depth = 0) => {
+        if (--remaining < 0 || depth > 128)
+            return "unsupported";
+        if (Object.is(a, b))
+            return "equal";
+        if (typeof a !== typeof b || a === null || b === null)
+            return "different";
+        if (typeof a === "function")
+            return "unsupported";
+        if (typeof a !== "object" || typeof b !== "object")
+            return "different";
+        if (visited.get(a)?.has(b))
+            return "equal";
+        const matches = visited.get(a) ?? new Set();
+        matches.add(b);
+        visited.set(a, matches);
+        const recipeA = geometryRecipe(a), recipeB = geometryRecipe(b);
+        if (recipeA !== undefined || recipeB !== undefined) {
+            if (recipeA === undefined ||
+                recipeB === undefined ||
+                recipeA.owner !== recipeB.owner ||
+                recipeA.kind !== recipeB.kind ||
+                recipeA.call.method !== recipeB.call.method ||
+                recipeA.index !== recipeB.index)
+                return "different";
+            const resolution = compare(recipeA.call.resolution, recipeB.call.resolution, depth + 1);
+            return resolution === "equal"
+                ? compare(recipeA.call.args, recipeB.call.args, depth + 1)
+                : resolution;
+        }
+        const arrayA = isImmutableBuffer(a)
+            ? immutableBufferView(a)
+            : ArrayBuffer.isView(a)
+                ? a
+                : undefined;
+        const arrayB = isImmutableBuffer(b)
+            ? immutableBufferView(b)
+            : ArrayBuffer.isView(b)
+                ? b
+                : undefined;
+        if (arrayA !== undefined || arrayB !== undefined) {
+            if (arrayA === undefined ||
+                arrayB === undefined ||
+                Object.getPrototypeOf(arrayA) !== Object.getPrototypeOf(arrayB) ||
+                arrayA.byteLength !== arrayB.byteLength)
+                return "different";
+            const bytesA = new Uint8Array(arrayA.buffer, arrayA.byteOffset, arrayA.byteLength), bytesB = new Uint8Array(arrayB.buffer, arrayB.byteOffset, arrayB.byteLength);
+            if (bytesA.length > remaining)
+                return "unsupported";
+            remaining -= bytesA.length;
+            return bytesA.every((value, index) => value === bytesB[index]) ? "equal" : "different";
+        }
+        if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b) ||
+            (Array.isArray(a) && Array.isArray(b) && a.length !== b.length))
+            return "different";
+        const keysA = Object.keys(a), keysB = Object.keys(b);
+        if (keysA.length > remaining)
+            return "unsupported";
+        if (keysA.length !== keysB.length || keysA.some((key) => !Object.hasOwn(b, key)))
+            return "different";
+        for (const key of keysA) {
+            const result = compare(Reflect.get(a, key), Reflect.get(b, key), depth + 1);
+            if (result !== "equal")
+                return result;
+        }
+        return "equal";
+    };
+    return compare(left, right);
+}
+function captureValue(value, recipeInputs, readerAllowed = () => false) {
+    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" });
+        if (typeof input !== "object" || input === null || isGeometryRecipe(input))
+            return input;
+        if (isImmutableBuffer(input))
+            return adoptImmutableBuffer(input);
+        const old = seen.get(input);
+        if (old !== undefined)
+            return old;
+        if (ArrayBuffer.isView(input)) {
+            if (!recipeInputs)
+                throw new TypeError(mutableBufferMessage);
+            const captured = immutableBuffer(input);
+            seen.set(input, captured);
+            return captured;
+        }
+        if (input instanceof ArrayBuffer)
+            throw new TypeError(mutableBufferMessage);
+        const entries = generationDataEntries(input, recipeInputs);
+        const result = Array.isArray(input)
+            ? new Array(input.length)
+            : Object.create(Object.getPrototypeOf(input) === null ? null : Object.prototype);
+        seen.set(input, result);
+        for (const [key, field] of entries)
+            Object.defineProperty(result, key, { value: copy(field), enumerable: true });
+        return Object.freeze(result);
+    };
+    return copy(value);
+}
+/** Validates while capturing immutable data; only explicitly allowed session readers may be functions. */
+export function captureGenerationValue(value, readerAllowed) {
+    return captureValue(value, false, readerAllowed);
+}
+/** Captures ordinary inputs once, including accessor values and mutable numeric arrays. */
+export function captureRecipeInputs(values) {
+    return captureValue(values, true);
+}

package/dist/engine/index.js

@@ -1,18 +1,29 @@
 import { GeometryError } from "../geometry/errors.js";
 import { defaultModelingLimits, resolveModelingLimits } from "../geometry/model-limits.js";
-import { bindModelContext } from "../model/execution-binding.js";
 import { createExecutionContext } from "./execution.js";
-import { captureExportParts, finalizeModel } from "./finalization.js";
+import { captureExportParts } from "./finalization.js";
 import createManifoldModule from "./kernel/manifold.js";
 import { withManifoldScope } from "./native/context.js";
-import { assertSynchronousScopeResult } from "./native/ownership.js";
+import { createSession } from "./session.js";
 export { defaultModelingLimits };
 /** URL of the package's pinned WASM asset; browser bundlers may replace it with their emitted URL. */
 export const modelingWasmUrl = new URL("./kernel/manifold.wasm", import.meta.url).href;
-/** Creates an engine over one already initialized host kernel.
- * Kept internal to host integration tests; ordinary consumers use createModelEngine.
- * @internal
+/**
+ * Runs declaration and immediate assertions without initializing a kernel or finalizing parts.
+ * Geometry observations require an initialized session's `validate` method instead.
  */
+export function validateModel(program, params, ...settings) {
+    const session = createSession(program, settings[0] ?? {}, defaultModelingLimits, (_options, callback) => callback(() => {
+        throw new GeometryError("INVALID_ARGUMENT", "Geometry observations require an initialized model session.", { operation: "validateModel", details: { requiresKernel: true } });
+    }));
+    try {
+        return session.validate(params);
+    }
+    finally {
+        session.dispose();
+    }
+}
+/** Serializes operations over one initialized kernel; sessions own their caches. */
 function engineFromModule(module, engineLimits) {
     let building = false;
     return Object.freeze({
@@ -31,33 +42,33 @@ function engineFromModule(module, engineLimits) {
                 building = false;
             }
         },
-        build(build, options = {}) {
-            if (building)
-                throw new GeometryError("INVALID_ARGUMENT", "An engine cannot run nested builds.", {
-                    operation: "build",
-                });
-            const limits = resolveModelingLimits(options.limits, engineLimits);
-            building = true;
-            const startedAt = performance.now();
-            try {
-                return withManifoldScope(module, (scope) => {
-                    const execution = createExecutionContext(module, scope, limits, options.resolution);
-                    try {
-                        const output = bindModelContext(execution.context, () => build(execution.context));
-                        assertSynchronousScopeResult(output, () => new GeometryError("INVALID_ARGUMENT", "Build callbacks must be synchronous.", {
-                            operation: "build",
-                        }));
-                        const builtAt = performance.now();
-                        return finalizeModel(execution, output, limits, options, startedAt, builtAt);
-                    }
-                    finally {
-                        execution.dispose();
-                    }
-                });
-            }
-            finally {
-                building = false;
-            }
+        createSession(program, ...settings) {
+            return createSession(program, settings[0] ?? {}, engineLimits, (options, callback) => {
+                if (building)
+                    throw new GeometryError("INVALID_ARGUMENT", "An engine cannot run nested operations.", {
+                        operation: "generate",
+                    });
+                const limits = resolveModelingLimits(options.limits, engineLimits);
+                building = true;
+                try {
+                    // The trusted finalizer captures only copied manufacturing buffers. Its snapshot has
+                    // owned-copy accessors, so publish it after the native scope's structural escape check.
+                    let captured;
+                    withManifoldScope(module, (scope) => {
+                        let execution;
+                        try {
+                            captured = callback(() => (execution ??= createExecutionContext(module, scope, limits, options.resolution)));
+                        }
+                        finally {
+                            execution?.dispose();
+                        }
+                    });
+                    return captured;
+                }
+                finally {
+                    building = false;
+                }
+            });
         },
     });
 }
@@ -66,11 +77,22 @@ function engineFromModule(module, engineLimits) {
  *
  * @example Build a box in a host application
  * ```ts
- * import { box } from "@metamesh/modeling";
+ * import { box, generate } from "@metamesh/modeling";
  * import { createModelEngine } from "@metamesh/modeling/engine";
  *
  * const engine = await createModelEngine();
- * const snapshot = engine.build(() => box({ size: [30, 20, 8] }));
+ * const model = generate<Record<never, never>>(({ part }) => [part("body", box({ size: [30, 20, 8] }))]);
+ * const session = engine.createSession(model);
+ * try {
+ *   const snapshot = session.run({});
+ *   try {
+ *     await engine.export3mf(snapshot.parts);
+ *   } finally {
+ *     snapshot.dispose();
+ *   }
+ * } finally {
+ *   session.dispose();
+ * }
  * ```
  */
 export async function createModelEngine(options = {}) {

package/dist/engine/model-dependencies.js

@@ -0,0 +1,46 @@
+/** 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];
+        while (pending.length > 0) {
+            const id = pending.pop();
+            if (visited.has(id))
+                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);
+        }
+        const result = [...parameters];
+        rootParameters.set(root, result);
+        return result;
+    };
+    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.position, part.rotation].flatMap((value) => {
+                const id = typeof value === "function" ? readerIds.get(value) : undefined;
+                return id === undefined ? [] : [id];
+            });
+            return Object.freeze({
+                id: part.id,
+                computations: Object.freeze(roots),
+                parameters: Object.freeze([...new Set(roots.flatMap(parametersFor))].sort()),
+            });
+        })),
+    });
+}

package/dist/engine/model-summary.js

@@ -0,0 +1,43 @@
+import { GeometryError } from "../geometry/errors.js";
+/** Counts manufacturing instances while charging shared backing storage only once. */
+export function createModelSummary(limits) {
+    let vertices = 0, triangles = 0, bytes = 0, volumeMm3 = 0;
+    const storage = new Set();
+    const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+    return {
+        add(geometry) {
+            const measurements = geometry.measurements;
+            vertices += measurements.vertexCount;
+            triangles += measurements.triangleCount;
+            volumeMm3 += measurements.signedVolume;
+            for (const buffer of [geometry.positions.buffer, geometry.indices.buffer])
+                if (!storage.has(buffer)) {
+                    storage.add(buffer);
+                    bytes += buffer.byteLength;
+                }
+            if (vertices > limits.maxVertices ||
+                triangles > limits.maxTriangles ||
+                bytes > limits.maxBytes)
+                throw new GeometryError("COMPLEXITY_LIMIT", "Aggregate output exceeds the execution limits.", { operation: "generate" });
+            for (let axis = 0; axis < 3; axis++) {
+                min[axis] = Math.min(min[axis], measurements.bounds.min[axis]);
+                max[axis] = Math.max(max[axis], measurements.bounds.max[axis]);
+            }
+        },
+        finish(startedAt, builtAt) {
+            const endedAt = performance.now();
+            return {
+                bounds: Object.freeze({ min: Object.freeze(min), max: Object.freeze(max) }),
+                stats: Object.freeze({
+                    vertices,
+                    triangles,
+                    bytes,
+                    volumeMm3,
+                    buildMs: builtAt - startedAt,
+                    finalizationMs: endedAt - builtAt,
+                    generationMs: endedAt - startedAt,
+                }),
+            };
+        },
+    };
+}

package/dist/engine/native/ownership.js

@@ -4,7 +4,7 @@ const disposedScopes = new WeakSet();
  * reverse construction order and disposal is idempotent.
  */
 export class WasmObjectScope {
-    #owned = [];
+    #owned = new Set();
     #disposed = false;
     /**
      * Transfers cleanup responsibility for a live WASM value to this scope.
@@ -15,9 +15,15 @@ export class WasmObjectScope {
             value.delete();
             throw new Error("Cannot add an object to a disposed WASM scope.");
         }
-        this.#owned.push(value);
+        this.#owned.add(value);
         return value;
     }
+    /** @internal Transfers one live value to a private owner without deleting it. */
+    release(value) {
+        if (this.#disposed || !this.#owned.delete(value)) {
+            throw new Error("Cannot release a value outside its active WASM scope.");
+        }
+    }
     /**
      * Deletes owned values in reverse construction order.
      *
@@ -32,15 +38,15 @@ export class WasmObjectScope {
         this.#disposed = true;
         disposedScopes.add(this);
         const errors = [];
-        for (let index = this.#owned.length - 1; index >= 0; index -= 1) {
+        for (const value of [...this.#owned].reverse()) {
             try {
-                this.#owned[index].delete();
+                value.delete();
             }
             catch (error) {
                 errors.push(error);
             }
         }
-        this.#owned.length = 0;
+        this.#owned.clear();
         if (errors.length > 0) {
             throw new AggregateError(errors, `Failed to delete ${errors.length} WASM object(s).`);
         }

package/dist/engine/placement.js

@@ -0,0 +1,24 @@
+import { validateAnalyzedSolidMesh } from "../geometry/mesh-solid.js";
+import { measureTriangleMesh } from "../geometry/mesh.js";
+import { composeTransform3, eulerTransform3, translationTransform3, } from "../geometry/transform3.js";
+/** Places already validated immutable geometry once, retaining its indexed topology. */
+export function placeFinalizedGeometry(source, position, rotation, meshValidation) {
+    if ([...position, ...rotation].every((value) => value === 0))
+        return source;
+    const matrix = composeTransform3(translationTransform3(position), eulerTransform3(rotation));
+    const positions = new Float32Array(source.positions.length);
+    for (let offset = 0; offset < positions.length; offset += 3) {
+        const x = source.positions[offset], y = source.positions[offset + 1], z = source.positions[offset + 2];
+        positions[offset] = matrix[0] * x + matrix[1] * y + matrix[2] * z + matrix[3];
+        positions[offset + 1] = matrix[4] * x + matrix[5] * y + matrix[6] * z + matrix[7];
+        positions[offset + 2] = matrix[8] * x + matrix[9] * y + matrix[10] * z + matrix[11];
+    }
+    const mesh = { positions, indices: source.indices };
+    // Rigid placement preserves indexed connectivity. Measure actual Float32 world output to keep
+    // exact bounds/volume/area without another topology or kernel pass under the default policy.
+    const measurements = Object.freeze({ ...source.measurements, ...measureTriangleMesh(mesh) });
+    // Float32 placement can close gaps between shells even when the local mesh passed validation.
+    if (meshValidation === "solid")
+        validateAnalyzedSolidMesh(mesh, measurements);
+    return Object.freeze({ ...source, ...mesh, measurements });
+}

package/dist/engine/recipe-realization.js

@@ -0,0 +1,119 @@
+import { GeometryError } from "../geometry/errors.js";
+import { immutableBufferView, isImmutableBuffer } from "../model/immutable-buffer.js";
+import { geometryRecipe, isGeometryRecipe, } from "./geometry-recipes.js";
+/**
+ * Resolves session recipes within one revision. These maps memoize borrowed native handles;
+ * the execution scope still owns allocation and cleanup, including handles restored from cache.
+ */
+export class RecipeRealization {
+    owner;
+    native;
+    duringNative;
+    restoreNative;
+    realized = new Map();
+    operands = new Set();
+    resolvedCalls = new Map();
+    nativeContexts = new Map();
+    constructor(owner, native, duringNative, restoreNative) {
+        this.owner = owner;
+        this.native = native;
+        this.duringNative = duringNative;
+        this.restoreNative = restoreNative;
+    }
+    /** Rejects foreign recipes before declaration, without realizing any geometry. */
+    assertOwned(values) {
+        for (const shape of recipeShapes(values))
+            this.assertRecipeOwner(geometryRecipe(shape));
+    }
+    /** Runs an observation or operation with captured inputs and its declaring resolution. */
+    invoke(call) {
+        let context = this.nativeContexts.get(call.resolution);
+        if (context === undefined) {
+            context = this.native().withResolution(call.resolution);
+            this.nativeContexts.set(call.resolution, context);
+        }
+        const operation = context[call.method];
+        const args = this.resolveValue(call.args, true);
+        return this.duringNative(() => Reflect.apply(operation, undefined, args));
+    }
+    /** Split/component handles share one operation result, even when selected separately. */
+    evaluate(call) {
+        if (!this.resolvedCalls.has(call))
+            this.resolvedCalls.set(call, this.invoke(call));
+        return this.resolvedCalls.get(call);
+    }
+    resolve(shape) {
+        return this.resolveValue(shape);
+    }
+    realizedShape(shape) {
+        return this.realized.get(shape);
+    }
+    /** Prefers intermediate operands when not every computed 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)));
+    }
+    assertRecipeOwner(recipe) {
+        if (recipe.owner !== this.owner)
+            throw new GeometryError("INVALID_ARGUMENT", "Geometry belongs to another model session.", {
+                operation: "generate",
+            });
+    }
+    realizeShape(shape) {
+        const recipe = geometryRecipe(shape);
+        this.assertRecipeOwner(recipe);
+        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;
+        }
+        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()) {
+        if (isImmutableBuffer(value))
+            return immutableBufferView(value);
+        if (isGeometryRecipe(value)) {
+            if (operand)
+                this.operands.add(value);
+            return this.realizeShape(value);
+        }
+        if (typeof value !== "object" ||
+            value === null ||
+            ArrayBuffer.isView(value) ||
+            value instanceof ArrayBuffer)
+            return value;
+        if (seen.has(value))
+            return seen.get(value);
+        const resolved = Array.isArray(value)
+            ? new Array(value.length)
+            : Object.create(Object.getPrototypeOf(value));
+        seen.set(value, resolved);
+        for (const [key, item] of Object.entries(value))
+            Object.defineProperty(resolved, key, {
+                value: this.resolveValue(item, operand, seen),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        return resolved;
+    }
+}
+/** Walks captured data once, including shared and cyclic containers, without inspecting buffers. */
+function* recipeShapes(values, seen = new Set()) {
+    for (const value of values) {
+        if (typeof value !== "object" || value === null || seen.has(value))
+            continue;
+        seen.add(value);
+        if (isGeometryRecipe(value))
+            yield value;
+        else if (!isImmutableBuffer(value) && !ArrayBuffer.isView(value))
+            yield* recipeShapes(Object.values(value), seen);
+    }
+}