@metamesh/modeling 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @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
+
+- b5da778: Replace prepare/build with typed generation programs, optional computed values and authoritative
+  part placement. Add isolated session caches and deferred geometry with explicit snapshot ownership.
+  Expose immutable fluent Solid and Section methods for transforms, subtraction, finishing, and
+  Section-to-Solid construction, replacing the corresponding standalone operations and public
+  context facade. Generator packages require format 4 and runtime 4; previous executable contracts are unsupported.
+- bfb7a63: Keep computed dependencies correct after conditional removal and re-registration, and prevent
+  caught evaluation failures from returning earlier cached values. Reduce immutable data copying,
+  centralize geometry finalization, and validate newly delivered resources once while preserving
+  per-revision part and aggregate resource checks.
+
+  Replace transparent cached typed arrays with explicit immutableBuffer and immutableMesh capture
+  helpers. Cached numeric data exposes length, at(), and copy(); uncaptured typed arrays in computed
+  results or bindings now reject. Snapshot and Worker output buffers remain ordinary typed arrays.
+
+### Patch Changes
+
+- 88f5336: Correct immutable cache comparisons, recapture mutable mesh inputs on every run, and preserve
+  session ownership during concurrent Testkit operations. Reject unsupported hidden data fields
+  instead of silently dropping them, and reuse native operation contexts during recipe evaluation.
+- 6c90e9d: Capture computed data in one validated traversal, reuse unchanged bindings and repeated dependency
+  analysis, and share recorded operation calls across result handles. Derive internal fluent dispatch
+  from the public shape contracts and skip cache retention work when caching is disabled.
+
+  Keep failed assertions attached to their revision even when author code catches them, preventing
+  invalid snapshots and cache commits.
+
+- 60c458f: Validate placed manufacturing geometry under the requested solid policy after Float32 rounding.
+  Share world buffers between identical placed instances while still counting each instance toward
+  output limits, and include retained object storage and field names in optional cache estimates.
+- a1f5aba: Reuse evaluated computed geometry as native operands across session runs without changing the public
+  API. Preserve anchor and profile metadata, bound optional retention, and release native allocations
+  on failed candidate generation, eviction, cache clearing, and session disposal.
+- d4ffce7: Release obsolete computation callbacks and prior revision graphs when a revision closes, keeping
+  cached numerical recipes from retaining unrelated work. Consolidate recipe traversal and revision
+  cleanup without changing the public Modeling API.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -15,33 +15,86 @@ pnpm add @metamesh/modeling
 Initialize an engine, then build and export a plate with a hole:
 
 ```ts
-import { box, cylinder, subtract } from "@metamesh/modeling";
+import { box, cylinder, generate } from "@metamesh/modeling";
 import { createModelEngine } from "@metamesh/modeling/engine";
 
 const engine = await createModelEngine();
-const snapshot = engine.build(
-  () => {
-    const body = box({ size: [30, 20, 6] });
-    const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
-    return [{ id: "plate", solid: subtract(body, [bore]), color: "#67e8f9" }];
-  },
-  { resolution: { maxChordError: 0.025 } }
-);
+const model = generate<Record<never, never>>(({ part }) => {
+  const body = box({ size: [30, 20, 6] });
+  const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
+  return [part("plate", { geometry: body.subtract([bore]), color: "#67e8f9" })];
+});
+const session = engine.createSession(model, { resolution: { maxChordError: 0.025 } });
+const snapshot = session.run({});
 const bytes = await engine.export3mf(snapshot.parts, { name: "Plate" });
+snapshot.dispose();
+session.dispose();
 ```
 
-Modeling calls run inside a synchronous build; handles belong to that build. Keep the finalized
-snapshot for rendering or export. For browser WASM setup and host lifecycle, follow
+Constructors and fluent shape methods declare immutable recipes inside synchronous generation.
+Use shape methods for transforms, subtraction, and finishing; collection operations such as
+`union`, patterns, and observations remain functions. Calls apply in written order about the origin.
+A method preserves its input; no-op operations may reuse a handle. A session owns optional
+computed caches; captured snapshots stay usable after the session is disposed. Keep the finalized
+snapshot for rendering or export, then dispose it. For browser WASM setup and host lifecycle, follow
 [Run Modeling in your application](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/engine/hosting.mdx).
 
+## Reuse unchanged work
+
+Caching is optional. A named computation tracks parameter and other computation reads; part
+placement and color stay separate from its geometry:
+
+```ts
+const model = generate<{ height: number; gap: number }>(({ params, computed, part }) => {
+  const body = computed("body", () => box({ size: [10, 10, params.height] }));
+  return [part("left", body), part("right", { geometry: body, position: [10 + params.gap, 0, 0] })];
+});
+```
+
+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 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
+data and recipes to diagnose observable missing dependencies. It can reject unsupported or large
+comparisons and cannot prove arbitrary JavaScript; production caching leaves this probe disabled.
+
+For expensive geometry followed by adjustable cuts or Booleans, put the base and finishing stage
+in separate computations. Sessions can retain the evaluated base privately, preserving native
+precision when it becomes an operand in a later run. Retention is bounded and optional; eviction
+rebuilds the original recipe. Clear or dispose the session to release retained native geometry.
+
+Use `assert(condition, message)` for a constraint that stops the revision and `warn(message)` for
+nonblocking guidance. Hosts bind prepared deterministic capabilities through session `services`.
+`validateModel` checks declarations and reached assertions without initializing a kernel; checks
+that observe geometry use an initialized session's `validate` method.
+
 ## API discovery and ownership
 
-| Import                                                                                                                                      | Use it for                                            |
-| ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| [`@metamesh/modeling`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/model/index.mdx)             | Solids, sections, transforms, and modeling operations |
-| [`@metamesh/modeling/geometry`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/geometry/index.mdx) | Pure paths, profiles, meshes, and calculations        |
-| [`@metamesh/modeling/engine`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/engine/index.mdx)     | Initialization, builds, limits, and 3MF export        |
-| [`@metamesh/modeling/text`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/text/index.mdx)         | Optional font preparation and vector layouts          |
+| Import                                                                                                                                      | Use it for                                                          |
+| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| [`@metamesh/modeling`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/model/index.mdx)             | Fluent solids and sections, constructors, and collection operations |
+| [`@metamesh/modeling/geometry`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/geometry/index.mdx) | Pure paths, profiles, meshes, and calculations                      |
+| [`@metamesh/modeling/engine`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/engine/index.mdx)     | Sessions, snapshots, limits, and 3MF export                         |
+| [`@metamesh/modeling/text`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/text/index.mdx)         | Optional font preparation and vector layouts                        |
 
 ## Documentation
 

package/dist/api/engine.d.ts

@@ -1,16 +1,16 @@
 import type { TriangleMesh } from "@metamesh/modeling/geometry";
-import type { BuildOutput, FinalizedModel, GeometryResolution, ModelingContext, ModelingLimits, FinalizedPart, GeometrySamplingLimits } from "@metamesh/modeling";
+import type { FinalizedModel, FinalizedPart, GenerationDiagnostic, GeometryResolution, ModelingLimits, ModelProgram, Vec3 } from "@metamesh/modeling";
 /** Default host resource ceilings for parts, vertices, triangles, and transferable bytes. */
 declare const defaultModelingLimits: Readonly<ModelingLimits>;
 
 
 /** Execution settings supplied by the host, independently of generator metadata. */
-export interface BuildOptions {
+export interface GenerationOptions {
     /** Optional bounded intersection and nested-shell checks; defaults to indexed topology validation. */
     readonly meshValidation?: "topology" | "solid";
     /** Per-build limits, no larger than the configured engine ceilings. */
     readonly limits?: Partial<ModelingLimits>;
-    /** Physical sampling defaults; model-derived contexts and exact counts override these. */
+    /** Physical sampling defaults; operation options and exact counts override these. */
     readonly resolution?: GeometryResolution;
     /** Optional bounded planar cleanup; unsupported candidates preserve the original part. */
     readonly meshTopologyMode?: "original" | "optimized";
@@ -21,11 +21,90 @@ export interface BuildOptions {
 export interface ModelEngine {
     /** Immutable resource ceilings selected when this engine was initialized. */
     readonly limits: ModelingLimits;
-    /** Runs once, finalizes copied parts, and disposes all native values on every exit. */
-    build(build: (model: ModelingContext) => BuildOutput, options?: BuildOptions): FinalizedModel;
+    /** Creates isolated caches; prepared service capabilities remain fixed for its lifetime. */
+    createSession<P, S>(program: ModelProgram<P, S>, ...options: keyof S extends never ? [options?: SessionOptions<S>] : [options: SessionOptions<S> & {
+        readonly services: S;
+    }]): ModelSession<P>;
     /** Serializes already finalized mesh parts; never prepares or builds a generator again. */
     export3mf(parts: readonly ExportMeshPart[], options?: Export3mfOptions): Promise<ArrayBuffer>;
 }
+/** Fixed generation policy and deterministic host capabilities for one model session. */
+export interface SessionOptions<S = Record<never, never>> extends GenerationOptions {
+    /** Host-owned synchronous capabilities, required when declared by the program. The original
+     * environment is retained; its behavior and assets must remain deterministic and fixed for
+     * this session. Equivalent function wrappers do not constitute an asset revision.
+     */
+    readonly services?: S;
+    /** Enables reuse; defaults to true. Set false for uncached output equivalence checks. */
+    readonly cache?: boolean;
+    /** Development-only cache-hit probe: reruns pure callbacks and compares bounded data/recipes.
+     * Unsupported closures or large results fail explicitly; this cannot prove arbitrary JavaScript.
+     */
+    readonly verifyCache?: boolean;
+}
+/** Validated local geometry resource; accessors return owned buffer copies. */
+export interface GeometryResource extends TriangleMesh {
+    /** Session-scoped immutable resource identity, stable while geometry is reused. */
+    readonly id: string;
+    /** Immutable resource revision; a new resource receives a new identity. */
+    readonly revision: number;
+    /** Facts for the exact local manufacturing buffers. */
+    readonly measurements: FinalizedPart["measurements"];
+}
+/** A world-space manufacturing part plus its reusable local renderer resource. */
+export interface SnapshotPart extends FinalizedPart {
+    /** Validated geometry in local coordinates, independent of placement and appearance. */
+    readonly geometry: GeometryResource;
+    /** XYZ translation in millimetres after rotation. */
+    readonly position: Vec3;
+    /** Fixed global X, then Y, then Z rotation in degrees. */
+    readonly rotation: Vec3;
+}
+/** Captured immutable revision; disposal never changes another snapshot or an in-flight export. */
+export interface ModelSnapshot extends FinalizedModel {
+    /** Ordered world-space parts, each referring to reusable local geometry. */
+    readonly parts: readonly SnapshotPart[];
+    /** Nonblocking diagnostics emitted for this revision. */
+    readonly diagnostics: readonly GenerationDiagnostic[];
+    /** Known dependency graph; outer reads remain conservative model-wide dependencies. */
+    readonly dependencies: ModelDependencies;
+    /** Releases this snapshot's references; idempotent, further access is invalid. */
+    dispose(): void;
+}
+/** Known dependencies for inspection; plain JavaScript bindings do not reveal their parameter origin. */
+export interface ModelDependencies {
+    /** Parameter keys read outside computed callbacks, affecting structure or ordinary code. */
+    readonly modelParameters: readonly string[];
+    /** Direct dependencies recorded by successfully evaluated computations. */
+    readonly computations: readonly {
+        /** Session-local computation identity. */
+        readonly id: string;
+        /** Direct top-level parameter reads. */
+        readonly parameters: readonly string[];
+        /** Direct computed-reader dependencies. */
+        readonly computations: readonly string[];
+    }[];
+    /** Part reader roots and known transitive parameter dependencies. */
+    readonly parts: readonly {
+        /** Stable semantic output part identity. */
+        readonly id: string;
+        /** Computed readers supplied as geometry or placement roots. */
+        readonly computations: readonly string[];
+        /** Known transitive parameter dependencies through these roots. */
+        readonly parameters: readonly string[];
+    }[];
+}
+/** Stateful execution owner; a failed revision cannot change previously returned snapshots. */
+export interface ModelSession<P> {
+    /** Generates an atomic manufacturing snapshot or throws; parameters are copied and frozen. */
+    run(params: Readonly<P>): ModelSnapshot;
+    /** Runs declaration and reached assertions without realizing returned parts. */
+    validate(params: Readonly<P>): readonly GenerationDiagnostic[];
+    /** Clears optional caches without invalidating captured snapshots. */
+    clearCache(): void;
+    /** Releases session ownership; idempotent, captured snapshots remain usable. */
+    dispose(): void;
+}
 /**
  * Manufacturing buffers accepted by the snapshot exporter.
  */
@@ -59,17 +138,35 @@ export { defaultModelingLimits };
 /** URL of the package's pinned WASM asset; browser bundlers may replace it with their emitted URL. */
 export declare const modelingWasmUrl: string;
 
+/**
+ * Runs declaration and immediate assertions without initializing a kernel or finalizing parts.
+ * Geometry observations require an initialized session's `validate` method instead.
+ */
+export declare function validateModel<P, S>(program: ModelProgram<P, S>, params: Readonly<P>, ...settings: keyof S extends never ? [options?: SessionOptions<S>] : [options: SessionOptions<S> & {
+    readonly services: S;
+}]): readonly GenerationDiagnostic[];
 /**
  * Initializes one host kernel and returns a lifecycle-safe engine. No generator initializes WASM.
  *
  * @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 declare function createModelEngine(options?: ModelEngineOptions): Promise<ModelEngine>;
-export type { BuildOutput, FinalizedModel, FinalizedPart, ModelingContext, ModelingLimits, GeometryResolution, GeometrySamplingLimits, };
+export type { ModelingLimits };