@metamesh/modeling 0.10.0 → 0.11.0

package/dist/engine/session.js

@@ -0,0 +1,184 @@
+import { GeometryError } from "../geometry/errors.js";
+import { resolveModelingLimits } from "../geometry/model-limits.js";
+import { bindModelContext } from "../model/execution-binding.js";
+import { createDeferredContext } from "./deferred-context.js";
+import { captureGenerationValue, generationValueBytes } from "./immutable-generation-data.js";
+import { createGenerationGraph } from "./session-graph.js";
+import { createNativeGeometryCache } from "./session-native.js";
+import { createSnapshotCache } from "./session-snapshot.js";
+function invalid(message) {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "generate" });
+}
+/** Coordinates native transactions and bounded atomic cache commits; snapshots own their lifetime. */
+export function createSession(program, suppliedOptions, engineLimits, transaction) {
+    const options = Object.freeze({
+        ...suppliedOptions,
+        ...(suppliedOptions.resolution === undefined
+            ? {}
+            : { resolution: captureGenerationValue(suppliedOptions.resolution) }),
+        ...(suppliedOptions.limits === undefined
+            ? {}
+            : { limits: captureGenerationValue(suppliedOptions.limits) }),
+    });
+    if (program?.kind !== "metamesh-model" || typeof program.generate !== "function")
+        invalid("Expected a generate() model program.");
+    const limits = resolveModelingLimits(options.limits, engineLimits);
+    const owner = {};
+    // Capabilities may be class instances with private state or nonenumerable methods. The host
+    // owns their fixed lifetime; copying their enumerable fields would change their semantics.
+    const services = (options.services ?? Object.freeze({}));
+    const caches = {
+        graph: createGenerationGraph(options, limits.maxParts),
+        snapshots: createSnapshotCache(options, limits),
+        geometry: createNativeGeometryCache(),
+        clear() {
+            this.graph.clear();
+            this.snapshots.clear();
+            this.geometry.clear();
+        },
+    };
+    const context = { owner, program, services, options, limits, caches };
+    let disposed = false;
+    let running = false;
+    function execute(input, mode) {
+        if (disposed)
+            invalid("This model session has been disposed.");
+        if (running)
+            invalid("Model generation cannot nest.");
+        if (typeof input !== "object" || input === null || Array.isArray(input))
+            invalid("Parameters must be a plain object.");
+        running = true;
+        const revision = new SessionRevision(context);
+        try {
+            const completed = transaction(options, (native) => revision.execute(input, native, mode));
+            if (completed.kind === "validation")
+                return completed.diagnostics;
+            // Nothing becomes reusable until geometry validation AND native cleanup have succeeded.
+            revision.commit();
+            return completed.snapshot;
+        }
+        finally {
+            try {
+                revision.dispose();
+            }
+            finally {
+                running = false;
+            }
+        }
+    }
+    return Object.freeze({
+        run: (params) => execute(params, "run"),
+        validate: (params) => execute(params, "validate"),
+        clearCache() {
+            if (running)
+                invalid("Cannot clear a running session.");
+            caches.clear();
+        },
+        dispose() {
+            if (running)
+                invalid("Cannot dispose a running session.");
+            disposed = true;
+            caches.clear();
+        },
+    });
+}
+/**
+ * Owns one attempted revision, including provisional retained native allocations. Declaration and capture
+ * happen inside the native transaction; commit is allowed only after that transaction cleans up.
+ * Disposal invalidates readers and releases any native allocations that were not committed.
+ */
+class SessionRevision {
+    session;
+    revision;
+    cacheCandidate;
+    nativeDepth = 0;
+    constructor(session) {
+        this.session = session;
+    }
+    execute(input, native, mode) {
+        const { owner, options, limits, caches } = this.session;
+        const revision = caches.graph.begin(input, () => this.assertDeclarationAllowed());
+        this.revision = revision;
+        const deferred = createDeferredContext(owner, () => native().context, limits, options.resolution ?? {}, (callback) => this.evaluateNative(callback), revision.assertActive, (shape) => {
+            const retained = caches.geometry.get(shape);
+            if (retained !== undefined)
+                return native().restoreNative(retained);
+            return undefined;
+        });
+        return bindModelContext(deferred.context, () => this.generate(revision, deferred, native, mode));
+    }
+    generate(revision, deferred, native, mode) {
+        const { program, services, caches } = this.session;
+        const startedAt = performance.now();
+        const output = program.generate({ ...revision.context, services });
+        revision.finish(output);
+        if (mode === "validate")
+            return { kind: "validation", diagnostics: Object.freeze([...revision.diagnostics]) };
+        const captured = caches.snapshots.capture({
+            output,
+            native,
+            deferred,
+            startedAt,
+            builtAt: performance.now(),
+            diagnostics: revision.diagnostics,
+            readDependencies: () => revision.dependencies(output),
+        });
+        this.prepareNativeCache(revision, captured, deferred, native);
+        return { kind: "snapshot", snapshot: captured.snapshot };
+    }
+    /** Retention is optional: an over-budget revision still produces a valid uncached snapshot. */
+    prepareNativeCache(revision, captured, deferred, native) {
+        const { options, limits, caches } = this.session;
+        if (options.cache === false)
+            return;
+        const retainedBytes = generationValueBytes([...revision.retainedValues(), ...captured.retainedValues], limits.maxBytes);
+        if (retainedBytes > limits.maxBytes)
+            return;
+        const nativeCandidate = caches.geometry.prepare(deferred.retentionCandidates(revision.computedValues()), (shape) => {
+            const realized = deferred.realizedShape(shape);
+            if (realized !== undefined)
+                return native().captureNative(realized);
+            return undefined;
+        }, (entry) => native().detachNative(entry), limits.maxBytes - retainedBytes);
+        this.cacheCandidate = { graph: revision, snapshot: captured, native: nativeCandidate };
+    }
+    /** Native replacement can fail during eviction; no other cache may survive that failure. */
+    commit() {
+        try {
+            const candidate = this.cacheCandidate;
+            if (candidate === undefined) {
+                this.session.caches.clear();
+                return;
+            }
+            candidate.native.commit();
+            candidate.graph.commit();
+            candidate.snapshot.commit();
+        }
+        catch (error) {
+            this.session.caches.clear();
+            throw error;
+        }
+    }
+    dispose() {
+        this.revision?.close();
+        this.revision = undefined;
+        // A cached recipe callback can retain the revision guard. Drop staged snapshot references
+        // even after commit, when the native candidate no longer owns provisional allocations.
+        const candidate = this.cacheCandidate;
+        this.cacheCandidate = undefined;
+        candidate?.native.dispose();
+    }
+    assertDeclarationAllowed() {
+        if (this.nativeDepth > 0)
+            invalid("Reactive reads and Modeling calls are not allowed in late numerical callbacks. Capture immutable inputs while declaring the recipe.");
+    }
+    evaluateNative(callback) {
+        this.nativeDepth++;
+        try {
+            return callback();
+        }
+        finally {
+            this.nativeDepth--;
+        }
+    }
+}

package/dist/engine/shape-anchors.js

@@ -54,6 +54,11 @@ export function createShapeAnchorOwner(assertShape, aliasShape) {
     };
     return {
         remember,
+        /** Private immutable metadata retained with a session-owned native shape. */
+        read(shape) {
+            assertShape(shape);
+            return anchors.get(shape);
+        },
         anchor(shape, name) {
             assertShape(shape);
             anchorName(name, "anchor");

package/dist/geometry/mesh-centroid.js

@@ -10,16 +10,17 @@ import { analyzeTriangleMesh } from "./mesh.js";
  * @returns A fresh immutable XYZ volume centroid.
  */
 export function computeTriangleMeshCentroid(mesh) {
-    const facts = analyzeTriangleMesh(mesh, { requireClosed: true });
+    const source = { positions: mesh.positions, indices: mesh.indices };
+    const facts = analyzeTriangleMesh(source, { requireClosed: true });
     if (!(facts.signedVolume > 0))
         throw new GeometryError("INVALID_TOPOLOGY", "A volume centroid requires positive oriented volume.", { operation: "computeTriangleMeshCentroid" });
     const origin = facts.bounds.min;
     const totals = [0, 0, 0], corrections = [0, 0, 0];
-    for (let offset = 0; offset < mesh.indices.length; offset += 3) {
-        const a = mesh.indices[offset] * 3, b = mesh.indices[offset + 1] * 3, c = mesh.indices[offset + 2] * 3;
-        const ax = mesh.positions[a] - origin[0], ay = mesh.positions[a + 1] - origin[1], az = mesh.positions[a + 2] - origin[2];
-        const bx = mesh.positions[b] - origin[0], by = mesh.positions[b + 1] - origin[1], bz = mesh.positions[b + 2] - origin[2];
-        const cx = mesh.positions[c] - origin[0], cy = mesh.positions[c + 1] - origin[1], cz = mesh.positions[c + 2] - origin[2];
+    for (let offset = 0; offset < source.indices.length; offset += 3) {
+        const a = source.indices[offset] * 3, b = source.indices[offset + 1] * 3, c = source.indices[offset + 2] * 3;
+        const ax = source.positions[a] - origin[0], ay = source.positions[a + 1] - origin[1], az = source.positions[a + 2] - origin[2];
+        const bx = source.positions[b] - origin[0], by = source.positions[b + 1] - origin[1], bz = source.positions[b + 2] - origin[2];
+        const cx = source.positions[c] - origin[0], cy = source.positions[c + 1] - origin[1], cz = source.positions[c + 2] - origin[2];
         const volume = (ax * (by * cz - bz * cy) + ay * (bz * cx - bx * cz) + az * (bx * cy - by * cx)) / 6;
         const coordinates = [(ax + bx + cx) / 4, (ay + by + cy) / 4, (az + bz + cz) / 4];
         for (let axis = 0; axis < 3; axis++) {

package/dist/geometry/mesh-planar.js

@@ -175,8 +175,9 @@ const fallbackReasonForCandidate = (before, after, boundaryEdgeKeys) => {
  * @returns Optimized connectivity and before/after diagnostics, or an unchanged safe fallback.
  */
 export function optimizePlanarPatches(mesh, options = {}) {
+    const source = { positions: mesh.positions, indices: mesh.indices };
     const resolved = resolveOptions(options);
-    const before = buildTriangleMeshQualityAnalysis(mesh, options);
+    const before = buildTriangleMeshQualityAnalysis(source, options);
     if (!before.report.isClosedOrientedManifold) {
         return unchangedResult(mesh, before.report, 0, false, "input-not-closed-oriented-manifold");
     }
@@ -316,10 +317,10 @@ export function optimizePlanarPatches(mesh, options = {}) {
         const patchId = before.patchByFace[firstUse.face];
         const patch = before.patches[patchId];
         const normal = patch.report.normal;
-        const startPoint = pointAt(mesh.positions, firstUse.start);
-        const endPoint = pointAt(mesh.positions, firstUse.end);
-        const firstPoint = pointAt(mesh.positions, oppositeFirst);
-        const secondPoint = pointAt(mesh.positions, oppositeSecond);
+        const startPoint = pointAt(source.positions, firstUse.start);
+        const endPoint = pointAt(source.positions, firstUse.end);
+        const firstPoint = pointAt(source.positions, oppositeFirst);
+        const secondPoint = pointAt(source.positions, oppositeSecond);
         const sideOfReplacementFirst = dot(cross(subtract(secondPoint, firstPoint), subtract(startPoint, firstPoint)), normal);
         const sideOfReplacementSecond = dot(cross(subtract(secondPoint, firstPoint), subtract(endPoint, firstPoint)), normal);
         const sideOfCurrentFirst = dot(cross(subtract(endPoint, startPoint), subtract(firstPoint, startPoint)), normal);
@@ -335,12 +336,12 @@ export function optimizePlanarPatches(mesh, options = {}) {
         }
         const replacementFirst = [oppositeFirst, firstUse.start, oppositeSecond];
         const replacementSecond = [oppositeFirst, oppositeSecond, firstUse.end];
-        const replacementFirstArea = dot(cross(subtract(pointAt(mesh.positions, replacementFirst[1]), firstPoint), subtract(pointAt(mesh.positions, replacementFirst[2]), firstPoint)), normal);
-        const replacementSecondArea = dot(cross(subtract(pointAt(mesh.positions, replacementSecond[1]), firstPoint), subtract(pointAt(mesh.positions, replacementSecond[2]), firstPoint)), normal);
+        const replacementFirstArea = dot(cross(subtract(pointAt(source.positions, replacementFirst[1]), firstPoint), subtract(pointAt(source.positions, replacementFirst[2]), firstPoint)), normal);
+        const replacementSecondArea = dot(cross(subtract(pointAt(source.positions, replacementSecond[1]), firstPoint), subtract(pointAt(source.positions, replacementSecond[2]), firstPoint)), normal);
         if (replacementFirstArea <= minimumDoubleArea || replacementSecondArea <= minimumDoubleArea) {
             continue;
         }
-        const qualityComparison = comparePairQuality(pairQuality(mesh.positions, firstTriangle, secondTriangle), pairQuality(mesh.positions, replacementFirst, replacementSecond), before.tolerance.angular);
+        const qualityComparison = comparePairQuality(pairQuality(source.positions, firstTriangle, secondTriangle), pairQuality(source.positions, replacementFirst, replacementSecond), before.tolerance.angular);
         if (qualityComparison < 0)
             continue;
         if (qualityComparison === 0) {
@@ -385,11 +386,11 @@ export function optimizePlanarPatches(mesh, options = {}) {
     if (flipCount === 0) {
         return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted);
     }
-    const indices = new Uint32Array(mesh.indices.length);
+    const indices = new Uint32Array(source.indices.length);
     for (let faceIndex = 0; faceIndex < triangles.length; faceIndex += 1) {
         indices.set(triangles[faceIndex], faceIndex * 3);
     }
-    const candidate = { indices, positions: mesh.positions };
+    const candidate = { indices, positions: source.positions };
     const after = buildTriangleMeshQualityAnalysis(candidate, options);
     const fallbackReason = fallbackReasonForCandidate(before, after, boundaryEdgeKeys);
     if (fallbackReason !== undefined) {

package/dist/geometry/mesh-quality.js

@@ -235,14 +235,15 @@ const buildPatchAnalysis = (faces, edges, faceIndices, id) => {
 };
 /** @internal */
 export function buildTriangleMeshQualityAnalysis(mesh, options = {}) {
+    const source = { positions: mesh.positions, indices: mesh.indices };
     const maximumTriangleCount = positiveInteger(options.maximumTriangleCount ?? DEFAULT_MAXIMUM_TRIANGLE_COUNT, "Maximum analyzed triangle count");
-    structurallyValidateMesh(mesh, maximumTriangleCount);
-    const { bounds, extent } = meshBoundsAndExtent(mesh.positions);
+    structurallyValidateMesh(source, maximumTriangleCount);
+    const { bounds, extent } = meshBoundsAndExtent(source.positions);
     const tolerance = resolveGeometryTolerance(extent, options.tolerance);
     const planarLinearTolerance = Math.max(tolerance.linear, Math.max(extent, 1) * FLOAT32_EPSILON * 8);
     const planarAngularTolerance = Math.max(tolerance.angular, MINIMUM_PLANAR_ANGULAR_TOLERANCE);
-    const vertexCount = mesh.positions.length / 3;
-    const triangleCount = mesh.indices.length / 3;
+    const vertexCount = source.positions.length / 3;
+    const triangleCount = source.indices.length / 3;
     const neighbourSets = Array.from({ length: vertexCount }, () => new Set());
     const vertexTriangleIncidence = new Uint32Array(vertexCount);
     const mutableEdges = new Map();
@@ -253,13 +254,13 @@ export function buildTriangleMeshQualityAnalysis(mesh, options = {}) {
     let nearZeroAreaTriangleCount = 0;
     let minimumTriangleAngleRadians = Number.POSITIVE_INFINITY;
     let maximumTriangleAspectRatio = 0;
-    for (let offset = 0; offset < mesh.indices.length; offset += 3) {
+    for (let offset = 0; offset < source.indices.length; offset += 3) {
         const vertices = [
-            mesh.indices[offset],
-            mesh.indices[offset + 1],
-            mesh.indices[offset + 2],
+            source.indices[offset],
+            source.indices[offset + 1],
+            source.indices[offset + 2],
         ];
-        const face = faceAnalysis(mesh.positions, vertices, offset / 3);
+        const face = faceAnalysis(source.positions, vertices, offset / 3);
         faces.push(face);
         surfaceArea += face.area;
         minimumTriangleAngleRadians = Math.min(minimumTriangleAngleRadians, face.minimumAngleRadians);
@@ -269,9 +270,9 @@ export function buildTriangleMeshQualityAnalysis(mesh, options = {}) {
             face.normal === undefined) {
             nearZeroAreaTriangleCount += 1;
         }
-        const first = pointAt(mesh.positions, vertices[0]);
-        const second = pointAt(mesh.positions, vertices[1]);
-        const third = pointAt(mesh.positions, vertices[2]);
+        const first = pointAt(source.positions, vertices[0]);
+        const second = pointAt(source.positions, vertices[1]);
+        const third = pointAt(source.positions, vertices[2]);
         signedVolume +=
             (first[0] * (second[1] * third[2] - second[2] * third[1]) +
                 first[1] * (second[2] * third[0] - second[0] * third[2]) +
@@ -305,7 +306,7 @@ export function buildTriangleMeshQualityAnalysis(mesh, options = {}) {
             continue;
         const first = edge.uses[0].face;
         const second = edge.uses[1].face;
-        if (facesAreCoplanar(faces[first], faces[second], mesh.positions, planarAngularTolerance, planarLinearTolerance)) {
+        if (facesAreCoplanar(faces[first], faces[second], source.positions, planarAngularTolerance, planarLinearTolerance)) {
             adjacency[first].push(second);
             adjacency[second].push(first);
         }
@@ -325,7 +326,7 @@ export function buildTriangleMeshQualityAnalysis(mesh, options = {}) {
             for (const candidate of adjacency[faceIndex]) {
                 if (patchByFace[candidate] !== -1)
                     continue;
-                if (!facesAreCoplanar(faces[seed], faces[candidate], mesh.positions, planarAngularTolerance, planarLinearTolerance)) {
+                if (!facesAreCoplanar(faces[seed], faces[candidate], source.positions, planarAngularTolerance, planarLinearTolerance)) {
                     continue;
                 }
                 patchByFace[candidate] = id;

package/dist/geometry/mesh-signature.js

@@ -71,6 +71,7 @@ const hashCanonicalKeys = (header, groups) => {
  * @throws {@link GeometryError} When validation, topology, tolerance, or complexity checks fail.
  */
 export function createTriangleMeshSignature(mesh, options = {}) {
+    const source = { positions: mesh.positions, indices: mesh.indices };
     const maximumTriangleCount = options.maximumTriangleCount ?? DEFAULT_MAXIMUM_TRIANGLE_COUNT;
     if (!Number.isSafeInteger(maximumTriangleCount) || maximumTriangleCount <= 0) {
         throw new GeometryError("INVALID_ARGUMENT", "maximumTriangleCount must be a positive safe integer.", {
@@ -78,10 +79,10 @@ export function createTriangleMeshSignature(mesh, options = {}) {
             details: { maximumTriangleCount },
         });
     }
-    if (!(mesh.positions instanceof Float32Array) || !(mesh.indices instanceof Uint32Array)) {
-        validateTriangleMesh(mesh, { requireClosed: true });
+    if (!(source.positions instanceof Float32Array) || !(source.indices instanceof Uint32Array)) {
+        validateTriangleMesh(source, { requireClosed: true });
     }
-    const triangleCount = mesh.indices.length / 3;
+    const triangleCount = source.indices.length / 3;
     if (triangleCount > maximumTriangleCount) {
         throw new GeometryError("COMPLEXITY_LIMIT", `Mesh signature analysis is limited to ${maximumTriangleCount} triangles; received ${triangleCount}.`, {
             operation: "createTriangleMeshSignature",
@@ -90,7 +91,7 @@ export function createTriangleMeshSignature(mesh, options = {}) {
     }
     const positionTolerance = validatePositiveTolerance(options.positionTolerance ?? DEFAULT_POSITION_TOLERANCE, "positionTolerance");
     const volumeTolerance = validatePositiveTolerance(options.volumeTolerance ?? DEFAULT_VOLUME_TOLERANCE, "volumeTolerance");
-    const measured = analyzeTriangleMesh(mesh, { requireClosed: true, includeTopology: true });
+    const measured = analyzeTriangleMesh(source, { requireClosed: true, includeTopology: true });
     const connectedComponentCount = measured.connectedComponentCount;
     const edgeCount = measured.edgeCount;
     const eulerCharacteristic = measured.vertexCount - edgeCount + measured.triangleCount;
@@ -101,11 +102,11 @@ export function createTriangleMeshSignature(mesh, options = {}) {
             details: { connectedComponentCount, edgeCount, eulerCharacteristic },
         });
     }
-    const coordinateKeys = Array.from({ length: measured.vertexCount }, (_, vertex) => coordinateKey(mesh.positions, vertex, positionTolerance));
+    const coordinateKeys = Array.from({ length: measured.vertexCount }, (_, vertex) => coordinateKey(source.positions, vertex, positionTolerance));
     const vertexKeys = [...coordinateKeys].sort();
     const triangleKeys = [];
-    for (let offset = 0; offset < mesh.indices.length; offset += 3) {
-        triangleKeys.push(canonicalOrientedTriangleKey(coordinateKeys[mesh.indices[offset]], coordinateKeys[mesh.indices[offset + 1]], coordinateKeys[mesh.indices[offset + 2]]));
+    for (let offset = 0; offset < source.indices.length; offset += 3) {
+        triangleKeys.push(canonicalOrientedTriangleKey(coordinateKeys[source.indices[offset]], coordinateKeys[source.indices[offset + 1]], coordinateKeys[source.indices[offset + 2]]));
     }
     triangleKeys.sort();
     const quantizeBounds = ({ min, max }) => Object.freeze({

package/dist/geometry/mesh-solid.js

@@ -50,11 +50,14 @@ function validationWork(mesh, options) {
 }
 /** @internal Fresh measurements precede one adjacency traversal for closure, fans, and shells. */
 export function analyzeSolidMesh(mesh, options = {}) {
-    const work = validationWork(mesh, options);
-    const measurements = analyzeTriangleMesh(mesh, {
+    const source = typeof mesh === "object" && mesh !== null
+        ? { positions: mesh.positions, indices: mesh.indices }
+        : mesh;
+    const work = validationWork(source, options);
+    const measurements = analyzeTriangleMesh(source, {
         ...(options.tolerance === undefined ? {} : { tolerance: options.tolerance }),
     });
-    checkSolidGeometry(mesh, measurements, options, work);
+    checkSolidGeometry(source, measurements, options, work);
     return measurements;
 }
 /**
@@ -63,7 +66,10 @@ export function analyzeSolidMesh(mesh, options = {}) {
  * Never accepts public cached facts; public validation always analyzes mutable input afresh.
  */
 export function validateAnalyzedSolidMesh(mesh, measurements, options = {}) {
-    checkSolidGeometry(mesh, measurements, options, validationWork(mesh, options));
+    const source = typeof mesh === "object" && mesh !== null
+        ? { positions: mesh.positions, indices: mesh.indices }
+        : mesh;
+    checkSolidGeometry(source, measurements, options, validationWork(source, options));
 }
 function checkSolidGeometry(mesh, facts, options, { count, maximumTests }) {
     const epsilon = resolveGeometryTolerance(Math.hypot(...facts.bounds.max.map((value, axis) => value - facts.bounds.min[axis])), options.tolerance).linear;

package/dist/geometry/mesh.js

@@ -4,26 +4,28 @@ import { writeMeshVertex } from "./numeric.js";
 import { resolveGeometryTolerance } from "./tolerance.js";
 import { transformDeterminant3, validateTransform3 } from "./transform3.js";
 function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = false) {
+    // Snapshot meshes can expose owned-copy accessors. Read each buffer once before traversal.
+    const source = { positions: mesh.positions, indices: mesh.indices };
     const measurements = mode === "measure";
-    if (!(mesh.positions instanceof Float32Array) || !(mesh.indices instanceof Uint32Array)) {
+    if (!(source.positions instanceof Float32Array) || !(source.indices instanceof Uint32Array)) {
         throw new GeometryError("INVALID_MESH", "Triangle meshes require Float32Array positions and Uint32Array indices.");
     }
-    if (mesh.positions.length % 3 !== 0) {
+    if (source.positions.length % 3 !== 0) {
         throw new GeometryError("INVALID_MESH", "Mesh positions must contain complete XYZ vertices.");
     }
-    if (mesh.indices.length % 3 !== 0) {
+    if (source.indices.length % 3 !== 0) {
         throw new GeometryError("INVALID_MESH", "Mesh indices must contain complete triangles.");
     }
-    const vertexCount = mesh.positions.length / 3;
-    if ((vertexCount === 0 || mesh.indices.length === 0) &&
-        !(options.allowEmpty && vertexCount === 0 && mesh.indices.length === 0)) {
+    const vertexCount = source.positions.length / 3;
+    if ((vertexCount === 0 || source.indices.length === 0) &&
+        !(options.allowEmpty && vertexCount === 0 && source.indices.length === 0)) {
         throw new GeometryError("INVALID_MESH", "A triangle mesh must contain vertices and faces.");
     }
     const min = [Infinity, Infinity, Infinity];
     const max = [-Infinity, -Infinity, -Infinity];
-    for (let offset = 0; offset < mesh.positions.length; offset += 3) {
+    for (let offset = 0; offset < source.positions.length; offset += 3) {
         for (let axis = 0; axis < 3; axis += 1) {
-            const coordinate = mesh.positions[offset + axis];
+            const coordinate = source.positions[offset + axis];
             if (!Number.isFinite(coordinate)) {
                 throw new GeometryError("NON_FINITE_VALUE", `Mesh position ${offset + axis} must be finite.`);
             }
@@ -34,9 +36,9 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
     const extent = vertexCount === 0 ? 0 : Math.max(max[0] - min[0], max[1] - min[1], max[2] - min[2]);
     const minimumDoubleArea = resolveGeometryTolerance(extent, options.tolerance).area;
     const edges = options.requireClosed || topology
-        ? new IndexedMeshEdgeTable(mesh.indices.length, topology)
+        ? new IndexedMeshEdgeTable(source.indices.length, topology)
         : null;
-    const triangleCount = mesh.indices.length / 3;
+    const triangleCount = source.indices.length / 3;
     const parents = topology ? new Int32Array(triangleCount) : null;
     const ranks = topology ? new Uint8Array(triangleCount) : null;
     const referenced = topology ? new Uint8Array(vertexCount) : null;
@@ -73,18 +75,18 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
     };
     // Keep the two hot-loop accumulators independent and local: no mutable numeric objects escape.
     let surfaceArea = 0, areaCorrection = 0, signedVolume = 0, volumeCorrection = 0;
-    const originX = mesh.positions[0] ?? 0, originY = mesh.positions[1] ?? 0, originZ = mesh.positions[2] ?? 0;
-    for (let offset = 0; offset < mesh.indices.length; offset += 3) {
-        const a = mesh.indices[offset], b = mesh.indices[offset + 1], c = mesh.indices[offset + 2];
+    const originX = source.positions[0] ?? 0, originY = source.positions[1] ?? 0, originZ = source.positions[2] ?? 0;
+    for (let offset = 0; offset < source.indices.length; offset += 3) {
+        const a = source.indices[offset], b = source.indices[offset + 1], c = source.indices[offset + 2];
         if (a >= vertexCount || b >= vertexCount || c >= vertexCount) {
             throw new GeometryError("INVALID_MESH", `Triangle ${offset / 3} references a missing vertex.`);
         }
         if (a === b || b === c || c === a) {
             throw new GeometryError("DEGENERATE_GEOMETRY", `Triangle ${offset / 3} repeats a vertex.`);
         }
-        const ax = mesh.positions[a * 3], ay = mesh.positions[a * 3 + 1], az = mesh.positions[a * 3 + 2];
-        const abx = mesh.positions[b * 3] - ax, aby = mesh.positions[b * 3 + 1] - ay, abz = mesh.positions[b * 3 + 2] - az;
-        const acx = mesh.positions[c * 3] - ax, acy = mesh.positions[c * 3 + 1] - ay, acz = mesh.positions[c * 3 + 2] - az;
+        const ax = source.positions[a * 3], ay = source.positions[a * 3 + 1], az = source.positions[a * 3 + 2];
+        const abx = source.positions[b * 3] - ax, aby = source.positions[b * 3 + 1] - ay, abz = source.positions[b * 3 + 2] - az;
+        const acx = source.positions[c * 3] - ax, acy = source.positions[c * 3 + 1] - ay, acz = source.positions[c * 3 + 2] - az;
         const crossX = aby * acz - abz * acy, crossY = abz * acx - abx * acz, crossZ = abx * acy - aby * acx;
         const doubleArea = Math.hypot(crossX, crossY, crossZ);
         if (doubleArea <= minimumDoubleArea) {
@@ -206,12 +208,13 @@ export function measureTriangleMesh(mesh, options = {}) {
  * @throws {@link GeometryError} When no mesh is supplied or an input is invalid.
  */
 export function joinTriangleMeshes(meshes) {
-    if (meshes.length === 0) {
+    const sources = meshes.map(({ positions, indices }) => ({ positions, indices }));
+    if (sources.length === 0) {
         throw new GeometryError("INVALID_ARGUMENT", "Joining meshes requires at least one mesh.");
     }
-    meshes.forEach((mesh) => validateTriangleMesh(mesh));
-    const positionLength = meshes.reduce((sum, mesh) => sum + mesh.positions.length, 0);
-    const indexLength = meshes.reduce((sum, mesh) => sum + mesh.indices.length, 0);
+    sources.forEach((mesh) => validateTriangleMesh(mesh));
+    const positionLength = sources.reduce((sum, mesh) => sum + mesh.positions.length, 0);
+    const indexLength = sources.reduce((sum, mesh) => sum + mesh.indices.length, 0);
     if (positionLength / 3 > 0xffff_ffff) {
         throw new GeometryError("INVALID_MESH", "Joined mesh exceeds the Uint32 vertex index range.");
     }
@@ -220,7 +223,7 @@ export function joinTriangleMeshes(meshes) {
     let positionOffset = 0;
     let indexOffset = 0;
     let vertexOffset = 0;
-    for (const mesh of meshes) {
+    for (const mesh of sources) {
         positions.set(mesh.positions, positionOffset);
         for (let index = 0; index < mesh.indices.length; index += 1) {
             indices[indexOffset + index] = mesh.indices[index] + vertexOffset;
@@ -238,14 +241,15 @@ export function joinTriangleMeshes(meshes) {
  * @returns Fresh position and index buffers; the input remains unchanged.
  */
 export function reverseTriangleMesh(mesh) {
-    validateTriangleMesh(mesh);
-    const indices = new Uint32Array(mesh.indices);
+    const source = { positions: mesh.positions, indices: mesh.indices };
+    validateTriangleMesh(source);
+    const indices = new Uint32Array(source.indices);
     for (let offset = 0; offset < indices.length; offset += 3) {
         const second = indices[offset + 1];
         indices[offset + 1] = indices[offset + 2];
         indices[offset + 2] = second;
     }
-    return { indices, positions: new Float32Array(mesh.positions) };
+    return { indices, positions: new Float32Array(source.positions) };
 }
 /**
  * Applies an affine transform to a mesh and preserves outward face orientation.
@@ -258,20 +262,21 @@ export function reverseTriangleMesh(mesh) {
  * @returns A mesh with fresh transformed positions and copied or reversed indices.
  */
 export function transformTriangleMesh(mesh, transform) {
-    validateTriangleMesh(mesh);
+    const source = { positions: mesh.positions, indices: mesh.indices };
+    validateTriangleMesh(source);
     validateTransform3(transform);
-    const positions = new Float32Array(mesh.positions.length);
-    for (let offset = 0; offset < mesh.positions.length; offset += 3) {
-        const x = mesh.positions[offset];
-        const y = mesh.positions[offset + 1];
-        const z = mesh.positions[offset + 2];
+    const positions = new Float32Array(source.positions.length);
+    for (let offset = 0; offset < source.positions.length; offset += 3) {
+        const x = source.positions[offset];
+        const y = source.positions[offset + 1];
+        const z = source.positions[offset + 2];
         writeMeshVertex(positions, offset, [
             transform[0] * x + transform[1] * y + transform[2] * z + transform[3],
             transform[4] * x + transform[5] * y + transform[6] * z + transform[7],
             transform[8] * x + transform[9] * y + transform[10] * z + transform[11],
         ], "transformTriangleMesh");
     }
-    const indices = new Uint32Array(mesh.indices);
+    const indices = new Uint32Array(source.indices);
     if (transformDeterminant3(transform) < 0) {
         for (let offset = 0; offset < indices.length; offset += 3) {
             const second = indices[offset + 1];

package/dist/index.js

@@ -1 +1,3 @@
 export * from "./model/operations.js";
+export * from "./model/generation.js";
+export { immutableBuffer, immutableMesh } from "./model/immutable-buffer.js";

package/dist/model/execution-binding.js

@@ -1,7 +1,7 @@
 import { GeometryError } from "../geometry/errors.js";
 // One protocol key lets locally bundled operation wrappers resolve the host's execution
 // without depending on package instances, class identity, or initializing a native runtime.
-const executionKey = Symbol.for("@metamesh/modeling/execution/2");
+const executionKey = Symbol.for("@metamesh/modeling/execution/4");
 const bindings = globalThis;
 /** Internal host binding. Executable callbacks are synchronous and may not nest executions. */
 export function bindModelContext(context, build) {
@@ -10,7 +10,7 @@ export function bindModelContext(context, build) {
             operation: "build",
         });
     }
-    bindings[executionKey] = { version: 2, context };
+    bindings[executionKey] = { version: 4, context };
     try {
         return build();
     }
@@ -18,11 +18,11 @@ export function bindModelContext(context, build) {
         delete bindings[executionKey];
     }
 }
-/** Resolves only the current live build; imported functions carry no native state themselves. */
+/** Resolves the private realm protocol; imported functions carry no native state themselves. */
 export function currentModelContext(operation) {
     const binding = bindings[executionKey];
-    if (binding?.version !== 2) {
-        throw new GeometryError("INVALID_ARGUMENT", "Modeling functions can only run inside build().", {
+    if (binding?.version !== 4) {
+        throw new GeometryError("INVALID_ARGUMENT", "Modeling functions can only run inside generate().", {
             operation,
         });
     }

package/dist/model/generation.js

@@ -0,0 +1,27 @@
+/** A user-correctable assertion failure. Successful computation caches never retain failures. */
+export class GenerationError extends Error {
+    /** Issues reached in normal JavaScript order, ending with the first failed assertion. */
+    diagnostics;
+    /** Captures immutable diagnostics; unexpected author errors retain their original type. */
+    constructor(diagnostics) {
+        super(diagnostics.at(-1)?.message ?? "Generation failed.");
+        this.name = "GenerationError";
+        this.diagnostics = Object.freeze(diagnostics.map((issue) => Object.freeze({ ...issue })));
+    }
+}
+/**
+ * Defines a typed model without executing it. Use `computed` only for work worth reusing.
+ *
+ * @example A simple model
+ * ```ts
+ * const model = generate<{ height: number }>(({ params, part, assert }) => {
+ *   assert(params.height > 0, "Height must be positive.");
+ *   return [part("body", box({ size: [10, 10, params.height] }))];
+ * });
+ * ```
+ */
+export function generate(callback) {
+    if (typeof callback !== "function")
+        throw new TypeError("generate requires a callback.");
+    return Object.freeze({ kind: "metamesh-model", generate: callback });
+}