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.

RetiredSession

A replaced session and the solids only it owned, to drop where it costs nothing (another thread). Dropping it is all there is to do with it.

SessionTransfer

An owned, self-contained copy of a thread’s assembly session: the session and a clone of every solid its scene names, keyed by the handle it had THERE. It shares nothing with the thread it came from, so that thread may free or reuse every handle afterwards (assembly_session_import).

Constants

CONSTRAINT_TYPES

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

FIXED_IS_NOT_A_CONSTRAINT

The refusal for a fixed constraint (kernel ABI, app command, batch): Fixed is the component instance’s own setting, never a constraint.

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_component_entities_json

Every NAMED face and edge of one component, resolved like assembly_resolve_refs_json (component-local frames). Entities without an analytic frame are skipped: a mate could never have referenced them. An unknown component is an empty list.

assembly_dof_json

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

assembly_drag_solve_impl

assembly_drag_solve_json

The live-drag dry run against the session (lifecycle::drag_solve). Request {poses: {componentId: {translate, rotateEulerDeg}}, unfix?: [id], reference?: {componentId: pose}, explain?: bool} — the dragged components at their dragged poses, and the last good live poses to re-base mechanical mates at. Reply {ok: true, poses: {componentId: {translate, rotateEulerDeg}}, blocking: [constraintId]} for every movable body (blocking: with explain, the constraints that would not let the dragged components reach the drag pose; empty otherwise); Err when the mates cannot hold at this drag. Nothing in the session (the state, the scene, the pending write-backs, the report) changes.

assembly_flip_plan_json

What Flip would do to constraint id, read from the live session: {ok: true, patch, seed, elements: [{component, fixed, anchor, direction, geom}], value, angleAxis} (world frame, pick order), or {ok: false, reason} for a type with no other solution. Read-only: the caller writes the patch and the seeded pose as one edit (constraints::flip_rule).

assembly_frame_solve_impl

assembly_frame_solve_json

One frame of a motion study against the session (lifecycle::frame_solve). Request {overrides: {constraintId: {value?: number, enabled?: bool}}, reference?: {componentId: {translate, rotateEulerDeg}}}: value drives a distance or angle constraint to it (model units or degrees; an angle may run past 360), enabled switches a constraint off or on for the frame, and reference is the previous frame’s poses (the warm start). Reply {ok: true, poses: {componentId: {translate, rotateEulerDeg}}} for every movable body; Err when the mates cannot hold the frame or an override names a constraint the session lacks or drives one that is not a distance or angle. Nothing in the session changes.

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_rebase_mechanical_impl

Refresh the mechanical mates’ stored references at the released poses of a live drag (lifecycle::rebase_mechanical). Request {poses: {componentId: {translate, rotateEulerDeg}}}. Reply: the updated assembly block JSON when a mechanical mate was refreshed, else null. The caller writes the block in the SAME undo step as the poses, so the next run maps a multi-turn drag from where it ended.

assembly_remove_constraint_impl

assembly_remove_constraint_json

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

assembly_resolve_refs_json

Resolve selection refs against the live session WITHOUT touching any constraint: refs_json is ["ACOMP2:Part_PZ", …]; the reply is one row per ref, {ref, ok: true, component, geom, point, direction, radius} in the owning component’s local frame, or {ref, ok: false, status, error}. Read-only — the replace-component lane snapshots a mate’s references before the swap with it.

assembly_run_solve_impl

assembly_run_solve_json

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

assembly_session_export

Copy this thread’s session for another thread (None without one).

assembly_session_import

Install a SessionTransfer as this thread’s session: every solid is registered HERE under a fresh handle and the scene is re-pointed at it. Returns what it replaced (the previous session and the solids a previous import owned) for the caller to drop.

assembly_session_serial

Which session this thread holds (see SESSION_SERIAL); 0 = none yet.

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_hidden_params

The constraint-form params to HIDE for the current values (the feature dialogs’ feature_hidden_params hook): a Distance or Angle shows its minimum/maximum only with limit on, and its single target only with limit off (the target is ignored while the range rules).

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).