Module replace_component 

Replace component (swap an occurrence’s part, keep its mates by name when the parts share lineage; mark the rest unresolved) — replace_components, the report, repair, and the Save As lineage stamp. REPLACE COMPONENT: swap the part an ACOMP occurrence (or every occurrence of a part) shows, keeping the occurrence — its id, pose, fixed flag and attributes — and every mate that still has something to hold on to.

Why the mates can survive at all

A mate references ACOMP<n>:<part entity name> (see the kernel’s assembly::mapping module doc). The replace keeps the ACOMP id and swaps only inputParams.partName, so every reference re-resolves by NAME against the new part on the next run. The names come from the part’s own feature ids (Part_PZ, Hole1_S, split pieces _1, _2), so a family member (the family’s document with other expression values) and a part saved as a variation and then edited carry the same names for the same faces.

Lineage: when a name match is trusted

Two unrelated parts can both have an Extrude1_top, so a name match alone proves nothing. The match is trusted automatically only when the two parts share LINEAGE (lineage_keys): the same source, members of one family (familySource.family), or one saved from the other (DERIVED_FROM_KEY, the chain Save As writes). Even then, an entity whose geometry class changed (a plane that became a cylinder) is not kept.

Without shared lineage, every healthy mate on the replaced occurrences is written DISABLED before the run, with a replace marker. Nothing resolves against the new part and nothing moves until the user confirms. The summary offers the same-name entity (pre-ticked when its geometry agrees with the old frame) or the nearest entity of the same class. A suggestion is never applied silently.

The marker and the report

An unresolved mate is KEPT, disabled, with persistentData.replace = {from, to, wasEnabled, refs: [{ref, reason, suggestion}]} (it rides save/reopen). EngineState::replace_repair points a reference at a picked entity and, once nothing is left unresolved, re-enables the mate (if it was enabled before) and drops the marker. Deleting goes through the ordinary constraint delete.

Part edits

A PART EDIT (Update components, a Work part push) is the same check with the part replaced by its own next version: EngineState::commit_part_edit adopts the edited document and classifies the mates of every occurrence of the edited parts once its run lands, with lineage trusted. One rule differs: a reference whose name is gone (or now names another class of geometry) is RE-ATTACHED automatically when exactly one entity of the edited part lies on the same carrier (geometry_agrees); the report lists each one, old ref → new ref. Anything else is held with the same marker (origin: "edit"), so the Repair pick and Accept work unchanged. A replace never auto-attaches.

The replace itself is ONE undo step: one document edit (library block + partName + disabled mates), adopted with one checkpoint. The classification runs once that edit’s run has landed (EngineState::finish_component_replace, from pump), and its marker write is silent (no second undo entry).

Structs

ReplaceCapture

What EngineState::capture_replace read before the swap.

Suggestion

Enums

RefOutcome

What the replace concluded about one reference.

Constants

BROKEN_STATUSES

BROKEN, for callers outside this module.

DERIVED_FROM_KEY

The top-level document key Save As appends the source’s identity to.

REPLACE_MARKER

The persistentData key an unresolved mate carries.

Functions

classify_ref

Classify one reference of a replaced component. pre is the reference’s resolution BEFORE the replace (the kernel row, ok: true); candidates the new part’s entities; old_names the old part’s local entity names (for the split note); trusted = shared lineage.

classify_vertex_ref

Classify a VERTEX reference ({solid}@x,y,z, a position in the component’s frame): kept only when, with shared lineage, the new part has a vertex at exactly the old point (the resolver snaps within a tolerance, so the point is compared, never trusted). Otherwise unresolved; the same ref is offered when it resolves, pre-ticked when it is the same point.

entries_lineage

The lineage word of two parts-library entries ({sourceKey, document}), or None when they share nothing.

family_key

family:<file> for a family member (its familySource.family).

follow_pattern_seeds

The report’s notes for the Pattern Components seeded by a replaced component in document: one per pattern, how many of its instances follow. Nothing about them is edited: the instances re-emit from the seed’s new part in the same run, and a seed given as a face of the component (ACOMP2:Pin_S, a pick) resolves by its component prefix, so it survives a part without that face. instances is every Pattern Component instance the last run placed.

geometry_agrees

Whether new is the same analytic carrier as old: the same class, and the same plane / axis / circle / line / point / sphere within tolerance (a plane must keep its sense: a flipped face is a different face). This is what a mate actually resolves against, so a split face’s piece agrees.

lineage_keys

The lineage keys of a part: its own source identity, every identity it was saved from (derivedFrom) and its family (family:<file>), each passed through canonicalize (stores spell one file several ways). Two parts share lineage when their key sets intersect.

marker_json

The marker an unresolved mate carries (persistentData.replace). origin is replace or edit; a marker saved before origins existed has none and reads as replace.

shared_lineage

How two parts are related, or None when they share nothing.

stamp_derived_from

Append source_identity (and, for a family member, its family) to the document’s DERIVED_FROM_KEY chain — what Save As writes so a copy edited later is still recognised as a variation of its original. Keeps the existing chain, no duplicates.