Complete executable workflow
This canonical module builds a two-instance assembly, selects a named configuration that changes its width, suppresses one occurrence, substitutes its material, and verifies the resulting BOM.examples/docs/assembly-configuration-bom.ts. A configuration must contain at
least one override; duplicate overrides inside one configuration are rejected
during authoring.
After serialization, applications select the same variant by its stable ID:
EvaluatedDesign.configurationId records the active configuration or is
null for the default document context.
Override categories
Configuration overrides are definition-scoped. If the same subassembly is
instanced twice, suppressing an instance inside that subassembly definition
affects both placements. Per-occurrence effectivity is roadmap work.
Deterministic BOM
The BOM:- excludes suppressed occurrences
- groups shared part definitions deterministically
- rolls nested quantities through the occurrence tree
- includes part number, description, material identity, density source, occurrence IDs, and mass information when available
- composes affine placement for physical-property aggregation
Repository-only Document v7 part authoring and evaluation
The source tree contains a staged authoring and evaluation path for Document v7 outputs that directly reference a part.stagedBodySetDesignV7(...) now exposes
source-only length, angle, mass-density, and scalar parameters;
union(...), subtract(...), and intersect(...) solid authoring;
transform(...), translate(...), rotate(...), scale(...), and
mirror(...) solid authoring; material(...); part(...); configuration
.partMaterial(...); and direct part output(...). This is executable
protocol evidence, not a public package workflow: the package-root builder,
document alias, evaluator aliases, CLI, and migration target remain v6.
A staged part’s geometry must be one owned solid DAG rooted in a box, cylinder,
sphere, or imported-body leaf, or one owned body set composed from those solid
DAG roots. Internal solid nodes are target-first, authored-tool-order Booleans
or ordered transforms. Primitive, imported, transformed, or prior Boolean
solids can feed a Boolean; Boolean and transform results can feed one another.
Transforms can be chained and parameterized by length, angle, or scalar
expressions. Parts cannot wrap another part, and the facade does not admit a
body set, part, or assembly as a Boolean or transform input. Materials and
parts are builder-owned typed handles; foreign or forged handles are rejected.
New option records must be exact plain own-data records, and accessor-backed or
unknown fields are rejected without invoking them. Part, material,
configuration, and membership metadata is detached before the document is
deeply frozen.
The staged result preserves part number, description, detached metadata,
legacy material label, effective material definition, density, and density
source. Its geometry is explicitly either one retained solid or one retained
body set; the evaluator never chooses a primary body. Named configuration
material overrides select the effective material identity. Authored or
configured density parameters resolve in the selected configuration and may be
further specialized by bounded caller overrides. An explicit part density
takes precedence over the effective material’s density, while a legacy
material label and material name remain descriptive and never supply inferred
density.
billOfMaterials() returns one deterministic part row with quantity one.
Missing density leaves its mass incomplete and produces a warning rather than
inventing zero. physicalMassProperties() requires one finite positive
density and, for a body set, applies it uniformly to every authored membership
before combining independent-body mass, center of mass, and inertia. Shared
solid aliases and spatially overlapping bodies each count once per
membership—the operation performs neither deduplication nor a Boolean union.
The numeric properties inherit the selected geometry backend’s measurement
quality.
The part facade can merge tessellations and export STL or OBJ, all explicitly
approximate/lossy. Exact export and topology remain per-solid or per-body
capabilities. Aggregate geometric measurement, cross-body topology, exact
aggregate STEP/BREP, assemblies, occurrence rollups, interference handling,
per-body materials, Boolean/transform inputs that are body sets, parts, or
assemblies, and general part graphs beyond primitive/import/Boolean/transform
DAGs are outside this staged slice. A primitive, Boolean, or transformed solid
cannot be a direct staged output; it must be retained by a part or body set.
Stock OCCT evaluates native and imported Boolean/transform DAGs as exact B-Rep
when every imported leaf satisfies the strong exact single-solid
document-import contract. Stock Boolean history is partial; a matched owned
facade supplies complete bounded evolution for the current Boolean only when
it proves the feature-scoped protocol, without upgrading partial operand
history. Manifold evaluates native primitive/Boolean/transform DAGs as
approximate mesh geometry with no topology snapshot and cannot stand in for
the import boundary. Evaluation never falls back between the two backends.
Body-set and part evaluation separately bound distinct leaves, all solid-graph
nodes, every Boolean target/tool and transform input edge, and authored
transform operations with maxDistinctSolids, maxSolidGraphNodes,
maxSolidDependencyLinks, and maxTransformOperations. A present malformed
exact-evolution capability envelope fails before resolver or kernel work; it is
not silently treated as partial history.
Repository-only staged product assemblies
The staged facade can wrap admitted local parts and already-completed local assemblies in an acyclic fixed-placement graph throughassembly(...).
externalPart(resource, output) binds one named part output from a committed
InvariantCAD document, while externalAssembly(resource, output) binds one
named assembly output for fixed-subassembly placement. The source-only
evaluateProductAssemblyOutputsV7(...) operation evaluates the resulting
product.
A staged configuration can call
instanceSuppressed(assembly, instanceId, suppressed?); the configuration
active for each containing assembly overrides that definition’s authored
suppression, and false reactivates an instance authored as suppressed. This
entire section describes repository-only work staged for 0.2. It is not
available from the public 0.1.1 package root, a package subpath, the public
builder/evaluator, or the CLI, and the public document alias and migration
target remain v6.
Each staged instance carries one child configuration selector. Local and
external components interpret the same selector at different document
boundaries:
For a direct external part, the chosen child context controls that part’s
geometry, material, density, and product intent. For a fixed external
subassembly, it establishes the selected child assembly context; configuration
selectors on child-local descendants are then interpreted inside the child
document. Child configuration suppression and placement expressions apply to
their own assembly definitions.
Root caller parameter overrides specialize selected contexts in the root
document only. They never cross the external document boundary, so a same-named
child parameter keeps the value defined by the child’s base or named
configuration. A selected child configuration that does not exist returns
CONFIGURATION_MISSING with parent occurrence and child configuration-path
provenance after document admission and before geometry work; evaluation does
not fall back to base.
Active part leaves retain full root-to-leaf occurrence paths, including all
segments inside a selected external subassembly. Placement operations execute
in authored order on each edge and compose parent first into a root-relative
transform. Local parts reuse one evaluated result for equal
(part, effective configuration) states. Direct external parts reuse one result
for equal (resource, output, effective child configuration) states. Leaves
reached through an external subassembly reuse geometry by
(resource, child part node, effective child configuration). Neither rule
collapses occurrences or quantities, and neither is a cross-run cache or
geometric-equivalence claim. Different child output names retain distinct
component, diagnostic, and BOM identity even when both select the same part or
assembly and share evaluated geometry.
The contextual BOM keeps unlike component/configuration states in separate,
deterministically ordered rows. A local component records its part node. An
external component additionally records the committed document resource,
digest, byte length, requested output and output kind, admitted source version,
and child part node. One external assembly may therefore contribute several BOM
rows, one for each distinct child part/configuration state. Repeated occurrences
of the same external output and child context aggregate quantity normally;
distinct output aliases retain separate BOM rows. Every row records stable
occurrence paths, effective material and density provenance, definition mass,
placed total mass, and quantity. Missing density leaves the affected row and
overall total incomplete, with diagnostics instead of an invented zero.
Physical mass applies each context’s density to every single- or multibody part
membership, then uses the root-relative affine placement before combining mass,
center of mass, and inertia. The numeric result inherits backend measurement
quality rather than gaining an independent exactness guarantee. Aliases and
overlaps still count per authored membership and occurrence; this is not
interference subtraction or a Boolean union.
Suppression is decided before descendant admission, so a suppressed edge prunes
its entire subtree without resolving its external document. Traversal is bounded
by maxAssemblyDepth, maxOccurrencePathSegments, scanned-instance,
active-occurrence, placement, contextual-part, maxExternalDocuments, and
downstream document/part/resource ceilings. Solid nodes, Boolean target/tool and
transform input edges, and authored transform operations remain bounded across
the active product. Repeated occurrences in one effective context share that
work, different contexts are charged independently, and suppressed subtrees
contribute nothing.
A direct external output must be a part admitted by the staged part evaluator.
An external-assembly handle must select a direct assembly output; that child may
contain bounded acyclic local parts and nested local assemblies whose leaves are
admitted by the same part evaluator. For example, a migrated v6 part backed by
an extrusion still fails with EVALUATION_UNSUPPORTED before child geometry or
scoped resource work rather than silently widening the supported feature set.
Each active occurrence path may cross at most one external-document boundary. A
suppressed nested external component is inert, while an active one is rejected
before nested resolution or child geometry/kernel work. Recursive external
products, cross-document parameter overrides, per-body materials, mates, joints,
DOF, motion, contact, interference/collision, product topology, aggregate
geometric measurement, and exact aggregate STEP/BREP export remain unsupported.
Product mesh, binary/ASCII STL, and OBJ are approximate/lossy aggregate
tessellation views.
Runtime parameter overrides
ExplicitEvaluationOptions.parameters can further specialize the selected
configuration. This is useful for one-off builds without adding a permanent
named variant. Keep named release/manufacturing variants in the document when
they need reviewable identity and repeatability.