Module assembly 

Assembly constraint state, lifecycle, and solver mapping.

The assembly block

Constraints are kernel history state: a top-level assembly block on the history request — { constraints: [ { type, inputParams, persistentData, enabled, open } ], idCounter } — that round-trips through the saved document. The pre-purge envelope keys (assemblyConstraints / assemblyConstraintIdCounter) are NOT read (no-backwards-compat).

Lifecycle, run at the tail of every history execution

1. VALIDATE ([lifecycle]): disabled → status:'disabled'; unknown type → an error entry without aborting the rest; duplicate detection across the overlapping family {touch_align, distance, angle, concentric, perpendicular, tangent} via order-independent selection-pair signatures.
2. MAP ([mapping]): each element ref resolves through solvers/assembly_resolve to an analytic frame in the owning component’s LOCAL space. Unresolvable/unsupported selections fail that constraint only (status from crate::ResolveError::status); the solve continues.
3. SOLVE: ONE crate::solve_assembly call over every mapped constraint; per-mate residuals/statuses + solver diagnostics merge into each constraint’s persistentData; distance/angle first-solve initialization commits into inputParams only on success.
4. WRITE BACK: solved poses re-pose the scene components in place ([crate::feature_pipeline::component]) and are exported as generic inputParams.transform JSON updates for the owning ACOMP features (the pose-authority contract; applied by assembly_apply_document_json with no compile-time dependency on the ACOMP feature).

Pose self-consistency (why an unapplied write-back cannot corrupt)

Mate-local frames are computed as record.transform⁻¹ · world_frame, and each body’s solver pose IS record.transform — so even when the record’s absolute pose is stale (the app has not yet folded a pose update back into the ACOMP feature), the solve is self-consistent: reconstructed world frames equal the actual world geometry, satisfied constraints produce no motion, and a re-executed component simply re-solves to the same poses. The write-back matters for PERSISTENCE (save/load) and cache fingerprints, not for per-run geometric correctness.

Structs

AssemblyState

The document’s assembly block: the ordered constraint list plus the persistent id counter (monotonic, never reused — mirrors the feature counter’s contract).

ConstraintEntry

One persisted constraint: { type, inputParams, persistentData, enabled, open }. inputParams carries id, elements (selection ref strings) and the type-specific params; persistentData is the solver-state merge target (status/message/diagnostics/orientation cache).

ConstraintTypeDef

One constraint type’s static definition.

Constants

CONSTRAINT_TYPES

Spec §4 table order — also the panel’s + dropdown order.

Functions

assembly_add_constraint_impl

assembly_add_constraint_json

Add a constraint of constraint_type with the given inputParams JSON (elements etc.; id is minted from the type’s short name + the persistent counter when absent). Auto-solves; returns {id, report}.

assembly_apply_document_impl

assembly_apply_document_json

Fold the session’s solved state into a history DOCUMENT: replaces the top-level assembly block and writes each pending pose / grounded flag into the owning feature’s inputParams (matched by inputParams.id — generic JSON, no dependency on the ACOMP feature shape). The app calls this on its document before persisting or re-running (the pose-authority write-back).

assembly_apply_inferred_constraints_json

Scan and CREATE: every accepted candidate becomes a constraint, then ONE solve runs for the whole batch (each inferred constraint is already satisfied at the pose it was read from, so a healthy assembly does not move). Returns {ok, created: [id…], report, solve}.

assembly_dof_json

The last solve’s DOF/diagnostics summary ({ok, dof, rank, redundant, status, strategy, iterations, maxResidual, ...} or {ok:false, error}).

assembly_infer_constraints_json

SCAN the live scene for constraints its component placement implies, without creating anything. options_json is [super::infer::InferOptions] ({} for the defaults). Never Err: a missing session or a bad options object comes back as {ok: false, error} — a JsValue error aborts a native build.

assembly_inferable_types_json

The inferable constraint types, joined to the catalogue: [{type, label, icon, longName, detects, defaultOn}]. Session-free — the dialog can list what the button offers before any document is open.

assembly_move_constraint_impl

assembly_move_constraint_json

Reorder a constraint to index (clamped). Auto-solves; returns the report.

assembly_overlay_json

Overlay geometry for the viewport graphics lane: per enabled constraint, the resolved WORLD anchor points/directions/geometry classes (post-solve), the status, the evaluated value, and (multi-element types) the element role groups — [{id, type, status, message, anchors, directions, geoms, value, unit, target, groups}]. Constraints whose selections do not resolve emit status/message only (no anchors).

assembly_pose_updates_json

The pending generic feature write-backs: {"poses": {componentId: transformParam}, "isFixed": {componentId: bool}}. The transform param is {translate, rotateEulerDeg (deg, intrinsic XYZ)} — exactly the shape the ACOMP feature’s inputParams.transform reader expects.

assembly_remove_constraint_impl

assembly_remove_constraint_json

Delete a constraint. Auto-solves; returns the solve report.

assembly_run_solve_impl

assembly_run_solve_json

Manual solve (the panel’s Solve button). Returns the solve report.

assembly_set_constraint_enabled_impl

assembly_set_constraint_enabled_json

Enable/disable a constraint. Auto-solves; returns the solve report.

assembly_set_constraint_open_impl

assembly_set_constraint_open_json

Persist a constraint row’s dialog expansion state (view state — no solve).

assembly_state_json

The current assembly block (post-solve) as JSON — the panel’s list source and the state the app folds back into its document.

assembly_statuses_json

Per-constraint status rows: [{id, type, enabled, open, status, message, satisfied, error}].

assembly_update_constraint_impl

assembly_update_constraint_json

Replace a constraint’s inputParams (the dialog commit). Auto-solves; returns the solve report.

constraint_schema_catalogue

number params are expression-capable against the part’s expression scope (the dialog engine’s established convention).

constraint_type

Look up a type definition by its canonical type string.

transform_to_pose_params

The generic inputParams.transform pose write-back JSON: {translate, rotateEulerDeg} with degrees in the intrinsic XYZ order (R = Rx·Ry·Rz — features::common::compose_trs_matrix). This is the write-side half of the ACOMP feature’s reader contract (assembly_component.rs reads exactly transform.translate + transform.rotateEulerDeg; a mismatched key would silently zero the pose on the next history run).