Evaluator and result reference

Reference for evaluator creation, evaluation options, output classes, ownership, and exports.

Creation

createEvaluator(options?: CreateEvaluatorOptions): Promise<Evaluator>

CreateEvaluatorOptions accepts kernel, default-Manifold manifold options, and sketchSolver.

Evaluation

evaluator.evaluate(
  document: DesignDocument,
  options?: EvaluationOptions,
): Promise<CadResult<EvaluatedDesign>>

See the evaluator guide for option semantics.

EvaluatedDesign

Member	Type	Meaning
configurationId	string | null	Active named configuration, or null for the base design
outputNames	readonly string[]	Evaluated output names in deterministic order
output(name)	EvaluatedOutput	Fetch a live named output or throw for an unavailable name
dispose()	void	Release all shapes owned by the evaluation

EvaluatedSolid

Method	Returns	Notes
mesh(options?)	MeshData	Fresh detached typed arrays
measure()	ShapeMeasurements	Geometric measurements in document units
topology()	CadResult<KernelTopologySnapshot>	Requires backend topology support
export("stl")	Uint8Array	Binary STL
export("stl-ascii")	string	ASCII STL
export("obj")	string	Wavefront OBJ
export("step", options?)	Uint8Array	No-options weak native export is published; deterministic options are an unreleased 0.2 strong contract
export("brep")	Uint8Array	Requires native text BREP export
export("brep-binary")	Uint8Array	Requires native binary BREP export

EvaluatedPart

Extends EvaluatedSolid and adds part number, description, material identity, density source, billOfMaterials(), and physicalMassProperties().

EvaluatedAssembly

Provides:

• instances: flattened evaluated part occurrences with stable paths and transforms
• mesh(options?): merged placed occurrence mesh
• measure(): aggregate geometric properties
• export(format): mesh formats and compatible aggregate output
• billOfMaterials(): grouped deterministic BOM result
• physicalMassProperties(): placed density-aware aggregate

Exact native STEP/BREP assembly structure is not a public product-data model. Assembly export remains mesh-only; exact STEP/BREP must be requested from an explicitly retained single solid or part leaf.

EvaluatedImportedBody

This public result is implemented for the unreleased 0.2 line and is not in the current invariantcad@0.1.1 npm package.

evaluator.evaluateImportedBody(
  document: ImportedBodyDocument,
  options?: EvaluateImportedBodyOptions,
): Promise<CadResult<EvaluatedImportedBody>>

This separate method accepts only the opaque document returned by createImportedBodyDocument(...) or parseImportedBodyDocument(...). It does not widen the ordinary v6 DesignDocument, Evaluator.evaluate(...), or EvaluatedOutput aliases.

Member	Type	Meaning
name	string	Stable imported-body/output ID
exact	true	The admitted result uses the exact kernel path
representation	"brep"	No approximate mesh fallback is available
provenance	ImportedBodyProvenance	Frozen resource, format, units, healing: none, and expected: single-solid commitment
mesh(options?)	MeshData	Fresh tessellation of the retained exact shape
measure()	ShapeMeasurements	Backend-reported geometric measurements
topology()	CadResult<KernelTopologySnapshot>	Capability-gated imported topology; no invented feature roles
export(format, options?)	Uint8Array | string	Same capability-gated single-solid export boundary as an evaluated solid
dispose()	void	Releases this result’s imported shape; does not dispose the evaluator or kernel

Evaluation accepts a caller resolver, resourceLimits.maxResourceBytes, document limits, and an abort signal. It verifies the authored byte length and SHA-256 digest before native parsing, requires the strong document-body import capability for the exact format/unit pair, and returns structured diagnostics for missing resolution, integrity mismatch, limits, cancellation, or kernel failure. Read the verified single-body workflow for the closed format/media/unit policy and executable round trip.

Repository-only staged geometry, products, and datums

The repository-only stagedBodySetDesignV7(...) facade can now author the bounded primitive/import/Boolean/transform solid DAG admitted by the staged import, body-set, part, and product-assembly evaluators, plus the nodes admitted by the datum resolver, without hand-writing v7 IR. It admits typed length, angle, mass-density, and scalar parameters; named parameter, part-material, and assembly-instance-suppression configurations; document-owned materials; boxes, cylinders, spheres; ordered union/subtract/intersect nodes; ordered solid transforms and typed translate/rotate/scale/mirror conveniences; content commitments; imported bodies; body sets; parts over one staged solid DAG root or body set; acyclic fixed-placement products containing local parts, completed local assemblies, direct external parts, or one fixed external-subassembly boundary; and datum points, axes, planes, and coordinate systems. Outputs may directly reference an imported body, body set, part, or staged product assembly; generic primitive, Boolean, or transformed-solid outputs remain unsupported through this authoring facade. The lower-level mixed product evaluator described below can select a strictly admitted direct solid output; that does not add a corresponding builder method or public output kind. Datums are selected separately by node ID and are never design outputs. The built DesignDocumentV7 is detached, deeply frozen, and accepted by strict v7 parsing and semantic validation; build({ limits }) can apply partial DesignDocumentLimits overrides and raises a CadError rather than returning an invalid document. This is repository-only work staged for 0.2. The facade is not a root or package-subpath export and does not change the public 0.1.1 v6 builder or evaluator types.

Mixed product-document outputs

The internal evaluateProductDocument(kernel, document, options) boundary evaluates one ordered selection that may mix supported direct solid, body-set, part, and fixed-assembly outputs from an admitted Document v7. It returns an owned EvaluatedProductDocumentV7, whose outputs array and outputNames preserve the requested order and aliases. output(name) supports an optional kind check, while solid(name), bodySet(name), part(name), and assembly(name) provide kind-specific access. Aliases receive correctly named facades while retaining the same native definition geometry.

This is one coordinated product operation, not a loop over unrelated evaluators. It captures the root document and options once, classifies selected roots and active root-local assembly structure before the first resolver request, and admits any required external document bytes before child geometry planning. It then:

1. prepares one native-geometry batch for each document and effective configuration used by the selected roots or active assembly leaves;
2. captures the aggregate kernel capability boundary once before resolving any geometry resource;
3. resolves root and external geometry resources through one document-scoped session; and
4. executes every batch under one cross-batch shape-ownership transaction and one top-level owner.

This ordering keeps suppressed occurrences, unselected outputs, unrelated materials, and their geometry resources inert. Repeated aliases and occurrence leaves can share retained geometry without synthetic nodes, duplicate native construction, or ambiguous cleanup. A failure or cancellation releases every completed batch best-effort, and disposing a successful result invalidates its direct and assembly-borrowed leaf views together. Kernel capability and resource diagnostics remain structured: aggregate kernel failures retain the responsible document scope, selection path, and batch provenance, while resolver failures retain document scope and unambiguous external-component provenance.

Exactness belongs to each retained leaf, not to the mixed container. An exact solid or body continues to expose backend-reported measurements plus capability-gated topology and native STEP/BREP export. The exact flag describes the retained geometry representation; it does not independently certify every numeric or topological report. EvaluatedProductDocumentV7.mesh() validates and copies every selected leaf mesh before combining it. Top-level export("stl" | "stl-ascii" | "obj") is therefore a tessellated, approximate/lossy aggregate even when all leaves are exact. The mixed result does not synthesize a B-Rep compound and does not expose aggregate STEP/BREP, measurement, topology, mass properties, or BOM. A selected assembly still retains its existing assembly-scoped BOM and physical-mass operations.

The admitted solid leaf set remains the staged primitive, imported-body, Boolean, and transform graph. This boundary does not add sketches or other feature families, body-set/part/assembly inputs to Boolean or transform operations, mates, joints, solving, motion, contact, interference, collision, recursive external-product graphs, or active second-level external-document boundaries. It also does not enable a cross-run evaluator cache.

evaluateProductDocument, EvaluatedProductDocumentV7, and their supporting types are repository-staged implementation for 0.2. They are not exported by the public invariantcad@0.1.1 package root or a package subpath, are not available through the CLI, and do not promote Document v7, change the public v6 DesignDocument/EvaluatedOutput aliases, or add a migration target.

Datum-node resolution

The source-only evaluateDatumNodesV7(...) operation resolves selected Document v7 datum node IDs without creating or borrowing a geometry kernel. Its source-only contract types are EvaluateDatumNodesV7Options, DatumEvaluationLimitsV7, and EvaluatedDatumNodesV7. Node-ID selection is intentionally separate from document.outputs: attempting to make a datum an output remains invalid, and the public evaluated-output union is unchanged. The nodes option preserves the first occurrence of each requested ID; when it is omitted, every datum node is selected in lexical ID order. The result contains the selected configurationId, resolved parameters, ordered nodeIds, a keyed datums record, and structured diagnostics.

Resolution applies parameter defaults, the selected named configuration, and then bounded caller parameter overrides. A resolved point contains its length-valued position. A resolved axis contains its origin and normalized direction. Resolved planes and coordinate systems contain deterministic, orthonormal, right-handed frames. Direction components must resolve to finite numbers and each direction must have nonzero length. After normalization, a plane’s positive-X direction and normal, or a coordinate system’s positive-X and positive-Y directions, must have an absolute dot product no greater than the fixed 1e-12 threshold. Accepted pairs are deterministically re-orthonormalized rather than returning floating-point drift as authored frame semantics.

Selected-node work and caller parameter overrides are bounded independently by maxSelectedNodes and maxParameterOverrides. The operation also applies caller-selected document limits, checks cancellation, guards runtime integrity, and contains hostile descriptors and opaque thrown values behind structured diagnostics. Successful resolved values are detached and deeply frozen. Because the operation performs only expression and frame evaluation, it has no kernel capability, approximation, native-handle, or kernel-cleanup boundary.

This slice does not connect a datum plane to a sketch, admit datums into shape algebra, evaluate assemblies or external occurrences, add datum design outputs, or promote Document v7. Those remain unsupported rather than being inferred from the existence of resolved frames.

The public Evaluator.evaluateImportedBody(...) facade described above reuses the strong internal direct-output evaluator without exposing its DesignDocumentV7 input or source-only names. Repository code may also select an output authored from a StagedImportedBodyRefV7 through the broader source-only evaluateImportedBodyOutputsV7(...) operation. That lower-level operation returns an ordinary EvaluatedDesign/EvaluatedSolid shape for direct imported-body outputs, but it remains inaccessible from the package.

The source tree contains a staged evaluateBodySetOutputsV7(kernel, document, options) operation for selected Document v7 outputs that directly reference bodySet nodes. It is not exported from the package root or a package subpath, does not widen the public EvaluatedOutput union, and does not change the public v6 document or evaluator aliases. Its source-only options and result types are EvaluateBodySetOutputsV7Options, BodySetEvaluationLimitsV7, EvaluatedBodySetDesignV7, EvaluatedBodySetV7, and EvaluatedBodyV7. Options can select a configuration, supply bounded parameters and outputs, provide a resource resolver, set evaluationLimits, resourceLimits, and documentLimits, and carry a cancellation signal. The evaluation limits independently bound selected outputs, aggregate selected memberships, distinct primitive/import leaves, all solid-graph nodes, solid-reference edges, authored transform operations, and caller parameter overrides through maxSelectedOutputs, maxBodySetMembers, maxDistinctSolids, maxSolidGraphNodes, maxSolidDependencyLinks, maxTransformOperations, and maxParameterOverrides.

Each evaluated body-set output retains the authored member sequence and each member’s stable ID, optional name, and detached metadata. Every listed member is active; this slice does not select or infer a primary body. A member may reference an owned box, cylinder, sphere, imported-body leaf, or any bounded Boolean/transform DAG rooted in those leaves. The planner walks the selected closure iteratively in dependency-first order. A Boolean evaluates its target first and tools in authored order; every target/tool edge counts toward maxSolidDependencyLinks, including repeated references. Shared leaves, Booleans, and transform nodes are evaluated once per effective configuration without deduplicating the memberships that refer to them. Native primitive and transform expressions resolve against the base or selected named configuration and the admitted caller parameter values.

The result records the kernel representation as "mesh", "brep", or "sdf", while exact mirrors the captured kernel capability. Stock OCCT evaluates native primitive/Boolean/transform graphs as exact B-Rep; its Boolean history is partial. An owned facade can supply complete Boolean evolution only through the existing valid feature-scoped exact indexed-evolution contract. That operation-local promise does not upgrade partial history already carried by an imported or otherwise partial operand, and the result’s exact flag describes geometry rather than complete persistent history. Manifold evaluates the same native graph as approximate mesh geometry and has no topology snapshot contract. The evaluator uses the selected kernel only: it neither retries an OCCT failure on Manifold nor silently converts an exact graph to mesh. Any imported member, including one below Booleans or transforms, requires verified caller-resolved bytes and the strong exact B-Rep single-solid document-body import capability; weak native import and mesh fallback are not used.

Transform components must resolve to finite values. Scale components must be nonzero, and mirror normals must be finite and nonzero. The kernel must advertise the selected boolean or transform feature and implement its corresponding method before resource resolution or shape acquisition. A present malformed exact-evolution capability envelope is authoritative protocol failure, not a partial-history downgrade. Each graph node must return a fresh valid owned shape. A subtraction or intersection null shape or exactly zero volume becomes structured EMPTY_RESULT; an impossible empty union and negative, non-finite, or malformed volume remain kernel protocol failures. Staged evaluation has no allowEmpty option. Capability mismatch, malformed output, shape aliasing, cancellation, emptiness, or any later failure releases every acquired shape exactly once.

EvaluatedBodySetDesignV7 exposes the selected configurationId, resolved parameters, structured diagnostics, deterministic outputNames, output(name), and dispose(). EvaluatedBodySetV7 exposes its output name, ordered bodies and bodyIds, body(id), representation, exact, aggregate mesh(), and mesh-format export(...). An EvaluatedBodyV7 is a frozen descriptor containing id, source node, optional name, optional detached metadata, and an owned EvaluatedSolid in solid.

Scope	Available operation	Boundary
Per body through body(id).solid	mesh()	Returns fresh detached mesh data
Per body through body(id).solid	measure()	Returns that body’s geometric measurements
Per body through body(id).solid	topology()	Requires backend topology support
Per body through body(id).solid	export(...)	STL/OBJ is mesh-derived; STEP/text BREP/binary BREP requires the corresponding native kernel capability
Whole body set	mesh()	Combines member tessellations in authored order and is approximate
Whole body set	export("stl" | "stl-ascii" | "obj")	Mesh-derived and explicitly approximate/lossy

Whole-set STEP/BREP export, bare-body-set mass properties, and a cross-body topology namespace are unsupported. The staged operation does not fuse bodies or create a kernel compound.

Direct part outputs

The source-only evaluatePartOutputsV7(kernel, document, options) operation selects only outputs that directly reference a Document v7 part node. The part’s geometry must reference either a supported primitive/import/Boolean/transform solid DAG root or a body set admitted by the staged body-set evaluator. The source-only stagedBodySetDesignV7(...) facade constructs exactly those part documents through material(...), part(...), typed configuration .partMaterial(...), and direct part output(...); it does not admit another part, or a body set/part/assembly as a Boolean or transform input. Its source-only evaluation contract types are EvaluatePartOutputsV7Options, PartEvaluationLimitsV7, EvaluatedPartDesignV7, EvaluatedPartGeometryV7, and EvaluatedPartV7.

EvaluatedPartDesignV7 has the same evaluation-scoped container shape as the body-set result: selected configurationId, resolved parameters, structured diagnostics, deterministic outputNames, output(name), and dispose(). Each EvaluatedPartV7 retains the source part node, part number, description, detached metadata, legacy material label, effective material identity and definition, density, and density source. Its geometry is an explicit discriminated union:

• "solid" retains the source primitive, imported-body, Boolean, or transform root and one owned EvaluatedSolid.
• "bodySet" retains the source body-set node and one EvaluatedBodySetV7, including its ordered authored memberships.

The evaluator never promotes one member to a primary body and never constructs a compound or Boolean union. Part-level mesh() and export("stl" | "stl-ascii" | "obj") merge tessellations in authored order; they are approximate/lossy even when the retained bodies come from an exact kernel. Native single-body or per-body export and topology remain available only through the retained geometry’s solid facades and their kernel capabilities. A multibody part has no aggregate measure() or cross-body topology namespace.

Named configuration selection first determines the effective material ID. An explicit part massDensity then takes precedence over that material’s density, while the legacy material string remains only an authored descriptive label. Missing density is never inferred from a name: physicalMassProperties() returns a structured missing-density failure, and billOfMaterials() returns its deterministic one-row report with incomplete mass and a warning.

The authoring facade enforces typed, same-builder material and part references. Material, part, configuration, parameter, resource, import, and membership options are captured as exact plain own-data records; unknown fields and accessors are rejected without invoking getters. Caller metadata and collections are detached before the resulting v7 document is deeply frozen.

For a multibody part, physical mass applies the one effective part density to each authored membership and combines the independent-body mass, center of mass, and inertia contributions. Shared aliases are counted once per authored membership, and spatial overlaps are also counted independently; the operation does not detect interference or subtract a union volume. The calculation uses the selected backend’s measurements. The result’s backend representation and exact capability describe that boundary, but do not make the returned floating-point mass an independent mathematical-exactness guarantee. A bare EvaluatedBodySetV7 still has no aggregate mass contract.

Part evaluation accepts the same configuration, parameter, output, resolver, resource-limit, document-limit, and cancellation boundaries as body-set evaluation. Its evaluation limits bound selected outputs, parameter overrides, authored part-body memberships, distinct acquired solid leaves, all solid-graph nodes, all Boolean and transform dependency links, authored transform operations, and resolved material definitions through maxSelectedOutputs, maxParameterOverrides, maxPartBodies, maxDistinctSolids, maxSolidGraphNodes, maxSolidDependencyLinks, maxTransformOperations, and maxResolvedMaterials. These limits bound document admission and shape acquisition, not mesh buffers produced by later facade calls. Tessellation and mesh export remain backend work controlled by MeshOptions; hostile or very large geometry still belongs in a disposable worker or process with an application-owned output ceiling.

Fixed-placement product outputs

The source-only evaluateProductAssemblyOutputsV7(kernel, document, options) operation selects outputs that directly reference an assembly. It is the product-oriented alias of the historical evaluateLocalAssemblyOutputsV7(...) source name. The corresponding product result aliases are EvaluatedProductAssemblyDesignV7, EvaluatedProductAssemblyV7, and EvaluatedProductOccurrenceV7; the staged local result names remain available during this repository-only transition. The authoring facade constructs this boundary through assembly(...), externalPart(...), externalAssembly(...), configuration .instanceSuppressed(...), and direct assembly output(...).

The evaluator first expands the active root-local graph. A direct external-part handle contributes one selected child part. A fixed external subassembly admits its committed child document, requires the selected output to directly reference an assembly, and expands its child-local parts and nested local assemblies. Each active occurrence path may cross at most one external-document boundary.

Every emitted occurrence keeps its final authored instance ID, full root-to-leaf path, part node, effective configuration, material and density provenance, and composed root-relative affine placement. An external occurrence also retains its committed component-document identity, and its full path spans the document boundary. A child part must still use the geometry admitted by the direct staged part evaluator: one supported primitive/import/Boolean/transform solid DAG root or one supported body set.

The root option establishes the selected output assembly’s initial context. Within every containing assembly, that active context resolves its definition-scoped suppression overrides and placement expressions. A local edge’s inherit, base, or named selector uses the applicable root-document context. For an external edge, inherit maps root base to child base or a root named ID to the same child ID; base and named select directly inside the child. Descendant selectors, suppression, and placement expressions are then interpreted in that child document. Caller parameter overrides specialize root contexts only and never cross the external boundary.

Placement operations execute in authored order on each edge and compose parent first. Occurrence IDs, full paths, configurations, component provenance, and root-relative transforms are detached, frozen snapshots. Embedded EvaluatedPartV7 values remain owner-bound and their operations fail after the containing evaluated design is disposed.

An explicit false suppression override can activate an instance authored as suppressed. Suppression is resolved before descendant admission, so a suppressed edge prunes its entire subtree without charging descendant traversal or resource work. A suppressed nested external component is inert. An active external descendant inside an admitted child would cross a second document boundary and returns a structured unsupported diagnostic before nested resolution or child geometry/kernel work. Facade-authored local nesting remains acyclic, strict admission rejects hand-authored dependency cycles, and traversal fails closed if a recursive local path reaches it.

Repeated instances do not collapse occurrence identity or quantity. Local parts reuse equal (part node, effective configuration) states, and direct external parts reuse equal (resource, output, child configuration) states. Leaves reached through a fixed subassembly share geometry by (resource, child part node, child configuration). Distinct external output aliases retain separate component, diagnostic, and BOM identity even when they share evaluated geometry. These are evaluation-call reuse rules, not a cross-run cache or persistent geometric-equivalence claim.

The evaluated product exposes ordered active occurrences, aggregate mesh, STL/OBJ export, contextual bill of materials, and placed physical mass properties. Exact child solids retain capability-gated per-solid or per-body topology and native export. Product mesh, binary/ASCII STL, and OBJ are tessellation views and therefore approximate/lossy even when every retained body came from an exact kernel. The operation does not invent a B-Rep compound, fuse overlaps, subtract interference, or provide exact aggregate STEP/BREP.

The BOM keeps unlike component/configuration states in separate rows and reports stable occurrence paths, quantity, effective material, density source, definition mass, placed total mass, external output kind, and committed child identity where applicable. One external assembly can contribute several child part rows. Missing density remains incomplete mass with diagnostics rather than an invented zero. Physical mass applies each part context’s density to every authored body membership, transforms each occurrence by its placement, and combines mass, center of mass, and inertia. Its numeric quality follows backend measurements; aliases and spatial overlaps count per membership and occurrence, with no Boolean or interference semantics.

Product evaluation independently bounds selected outputs, root caller overrides, external documents, assembly depth, scanned instances, active occurrences, aggregate leaf-path segments, placement operations, contextual parts, part-body memberships, acquired leaves, solid-graph nodes, dependency links, transform operations, resolved materials, documents, and resources. maxAssemblyDepth defaults to 64, with the selected root at depth one, and maxOccurrencePathSegments defaults to 1,000,000. maxScannedInstances charges every expanded definition slot, while maxActiveOccurrences charges every unsuppressed component edge, including intermediate assembly edges. Repeated occurrences in one effective context share applicable graph work, different contexts are charged separately, and suppressed subtrees are pruned before descendant counters advance.

The operation checks cancellation throughout option capture, document admission, child expansion, planning, resource resolution, kernel acquisition, and the final success boundary. These ceilings do not bound mesh buffers created by later result methods; hostile or very large tessellation still belongs in a disposable worker or process with an application-owned output ceiling.

Evaluation is transactional: failure releases every distinct acquired shape exactly once, including shapes acquired by earlier child contexts. A successful evaluated design owns each distinct shape until dispose(). After disposal, design output lookup, part/body/product operations, mesh/export, and per-body solid operations fail deterministically. Detached mesh, export, measurement, BOM, metadata, and occurrence snapshots already returned remain detached. The caller-supplied kernel is borrowed and is never disposed by the staged design.

Active second-level external document references, recursive external product graphs, unsupported child feature families, datum-backed sketches, healing, location I/O, Boolean or transform inputs that are body sets/parts/assemblies, other body-consuming operations, and generic solid outputs remain unsupported. The slice adds no mates, joints, degrees-of-freedom solving, motion, contact, interference, collision, assembly-wide topology, aggregate geometric measure(), exact aggregate STEP/BREP, or cross-run cache. This work is staged for 0.2 and does not widen the public 0.1.1 package-root EvaluatedOutput union, document alias, builder, evaluator, CLI, or migration target; those remain on the frozen v6 surface.

Lifetime

Every method that touches an output asserts its owning evaluation is live. Detached strings, byte arrays, typed arrays, plain measurement objects, diagnostics, and BOM reports remain ordinary JavaScript values after disposal. Output wrapper methods do not.

const bytes = output.export("stl");
evaluated.dispose();

// bytes is still owned by the caller.

Errors

Most evaluation failures return diagnostics. Direct output(name) misuse, post-disposal access, and unsupported direct export() formats throw. An unsupported export uses CadError, which carries its structured diagnostics. Invalid high-level STEP option structure or metadata likewise throws CadError with the unreleased 0.2 EXPORT_OPTIONS_INVALID code; its JSON-Pointer path is relative to StepExportOptions, not the design document. Valid cancellation signals continue to use AbortError, and direct low-level kernel exports keep their backend validation exceptions.