docs: topological naming research (FreeCAD ElementMap, Onshape queries)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
NiJingzhe
2026-11-04 03:12:21 +08:00
parent 093ef71e53
commit 39ddebade7
+327
View File
@@ -0,0 +1,327 @@
# Topological naming: how FreeCAD does it, and what SimpleCADAPI should do
Status: research note, 2026-11-04. Nothing here is implemented.
Legend. **[V]** = verified by reading the cited source in this session (ego-browser; GitHub raw files fetched from
FreeCAD `main`, wiki pages). **[I]** = inference or recollection, not verified from a source here. Line numbers refer
to the `main` branch as fetched today and will drift.
## 1. The problem
A parametric feature (fillet, sketch-on-face, hole) must say "this face/edge of the upstream body". Kernels expose
sub-shapes only by traversal order or geometry. When an upstream parameter or operation changes, traversal order
reshuffles and geometry moves, so "Face13" or "the face with centroid near (0,0,10)" may now denote a different face,
or none. A stable reference needs an identity for each sub-shape that is (a) derived from the modelling history, not
from position, and (b) re-resolved after every rebuild, with an explicit outcome when the identity is gone.
## 2. How FreeCAD 1.0 does it
### 2.1 Provenance and status
- The algorithm is realthunder's, developed in his Link/LinkStage3 fork; it was integrated into FreeCAD 1.0 over about
a year (release notes: "Realthunder's algorithm has been carefully implemented... The TNP problem is not completely
solved") [V]. Sources:
- Release notes 1.0: https://wiki.freecad.org/Release_notes_1.0 (PR #13705 listed as the finalizing PR).
- Wiki page: https://wiki.freecad.org/Topological_naming_problem. It states the algorithm has three purposes, in
order: (1) detect and display broken references, (2) propose a likely fix (e.g. fillet/chamfer edge selection),
(3) auto-repair only when confident ("First, do no harm") [V]. It explicitly says the algorithm "is not intended
to fix every failure"; datum planes and body-origin-based sketches remain best practice [V].
- realthunder's design notes: https://github.com/realthunder/FreeCAD_assembly3/wiki/Topological-Naming (framework,
tags, hasher, versioning) and https://github.com/realthunder/FreeCAD_assembly3/wiki/Topological-Naming-Algorithm
(the naming algorithm with pseudo-code) [V].
### 2.2 Data structures [V]
- `Data::IndexedName` = type + index (`Face12`). `Data::MappedName` = a byte string (the stable name). Source:
https://github.com/FreeCAD/FreeCAD/blob/main/src/App/MappedName.h and
https://github.com/FreeCAD/FreeCAD/blob/main/src/App/IndexedName.h
- `Data::ElementMap` (https://github.com/FreeCAD/FreeCAD/blob/main/src/App/ElementMap.h): a bidirectional map
MappedName <-> IndexedName, owned by `Data::ComplexGeoData` (base of `Part::TopoShape`). Documented as
`indexedNames` (type -> queue of children) plus `mappedNames` (name -> IndexedName); children can carry a recursive
child map (for compounds). `find(MappedName)`, `find(IndexedName)`, `findAll(IndexedName)` exist; one element can
have several names, a name maps to exactly one element (realthunder notes, "setElementName").
- `Part::TopoShape` additionally carries an integer `Tag` identifying the owner document object (unique per document,
not a UUID). Tag 0 disables automatic mapping [V, realthunder notes "Object Identification"]. The tag is appended to
names whose source comes from a different shape so that two operands do not collide.
- `App::StringHasher` (per document): long names are replaced by `#<hex id>`, with the original strings stored in a
reference-counted table and persisted with the document; only strings actually used are saved by default [V,
realthunder notes "String Hasher"].
- Element map version string, `GeoFeature::getElementMapVersion()`: concatenates the TopoShape algorithm version, OCCT
version, ComplexGeoData version and hasher threshold. On document load, a mismatch marks the feature for recompute
and resets link shadow copies, because any change in OCCT history behaviour changes generated names [V, realthunder
notes "Element Map Versioning"; `GeoFeature.cpp` line ~264 reads the version].
### 2.3 How names are generated per operation [V]
All "make element" operations in
https://github.com/FreeCAD/FreeCAD/blob/main/src/Mod/Part/App/TopoShapeExpansion.cpp
(`makeElementBoolean` ~l.6069, `makeElementFillet` ~l.4148, `makeElementChamfer` ~l.4180, `makeElementPrism` ~l.4644,
`makeElementPrismUntil`, `makeElementShape`, loft/pipe/offset variants, `makeShapeWithElementMap` ~l.1420) build the
result with an OCCT `BRepBuilderAPI_MakeShape` derivative (or `BRepAlgoAPI_*` / `BRepTools_History`) and then hand
it to `TopoShape::makeShapeWithElementMap(shape, mapper, inputShapes, op)`. The `Mapper` abstraction (`MapperMaker`
at ~l.5745-5840) forwards to the OCCT history calls `Modified(s)`, `Generated(s)`, and for histories also
`IsDeleted`, each wrapped in try/catch because "OCCT being OCCT" not all makers honour the interface.
`BRepBuilderAPI_Sewing` and `BRepOffsetAPI_ThruSections` need special handling (algorithm page).
The core algorithm (algorithm page, `makESHAPE` in the pseudo-code), four passes:
1. Unchanged elements: copy the input names onto the identical sub-shapes of the result (`mapSubElement`).
2. Modified / Generated: for each input vertex, edge, face, ask the mapper for `Modified` and `Generated` new
sub-shapes; each new element gets a name built from the source's mapped name plus a marker, an op code, the source
tag and the source name length. If several sources map to one element, the first is the "main" source and the rest
go in a bracket group.
3. Upper-element naming: still-unnamed edges/vertices get `<upper name>;:U<n>`, possibly several names (one per
adjacent named face), "to improve stability of the next step".
4. Lower-element naming: still-unnamed faces/edges are named from the sorted set of their named lower elements,
`(edge1,edge2,...);:L`.
Name grammar (examples from the algorithm page, verbatim shapes):
`Face6;:M2;FUS;:T1:5:F`: source `Face...` (5 chars, tag 1), `;:M2` = modified, 2nd modification index, `FUS` = fuse op
code, `;:T1:5:F` = trailing tag 1, source-name length 5, element type F. `;:G` = generated, `;:MG` = both, `;:U` =
upper-derived, `;:L` = lower-derived. A name nests: the source's whole mapped name is the prefix, so a name encodes
the history chain and can be traced back (`traceElement`, `isElementGenerated`, ~l.6344). The selection prefix `;`
marks a mapped name in the GUI (`;:M...`); a missing reference is displayed with `?` (`Data::MISSING_PREFIX`,
`GeoFeature::hasMissingElement`) [V for the existence of the missing prefix; the exact characters I did not
confirm].
Primitives (`Part::Box` etc.) have no map: their elements are considered fixed (`Face1`...). Sketcher names its edges
by geometry id: `g1;SKT` -> `Edge1`, `g1v1;SKT` -> `Vertex1` [V, realthunder notes], i.e. the sketch's own geometry
ids are the roots of every name derived from it. That is why sketch -> pad faces are stable.
### 2.4 How a reference is stored and re-resolved [V]
- A feature stores references in `App::PropertyLinkSub` / `PropertyLinkSubList` / `PropertyXLink`
(https://github.com/FreeCAD/FreeCAD/blob/main/src/App/PropertyLinks.h): object + sub-name list. Each sub-name has a
`ShadowSub = ElementNamePair {newName, oldName}`: the mapped (stable) name and the plain indexed name, both kept
current. Saves still write the indexed name, so older FreeCAD can open the file (realthunder notes "Property Link").
- When the owner shape changes, `GeoFeature` signals dependents, and `PropertyLinkBase::_updateElementReference`
(https://github.com/FreeCAD/FreeCAD/blob/main/src/App/PropertyLinks.cpp ~l.449-600) looks up the mapped name in the
new `ElementMap` and rewrites the stored indexed name if it moved (`Face13 -> Face14`).
- If the mapped name is missing: first a geometry search, `GeoFeature::searchElementCache(oldElement,
CheckGeometry)`, then with plain tolerance, then `rescueDriftedElement`. Before the shape changes, GeoFeature
snapshots the geometry of every referenced element; after the change it searches the new shape for an element with
the same geometry (`SearchOption::CheckGeometry | SingleResult | AdaptiveTolerance`, which "widens the tolerance
stepwise and accepts only a unique match", `ComplexGeoData.h` l.60-65). Only if all that fails the reference is
marked missing (`?` prefix) and the feature errors. So the order is: name first, geometry as repair, error last.
- Dress-ups (`FeatureDressUp.cpp`, https://github.com/FreeCAD/FreeCAD/blob/main/src/Mod/PartDesign/App/FeatureDressUp.cpp)
read `ShadowSub` (`newName` else `oldName`, ~l.290) and can relink to matching sub-elements when the base feature is
replaced (`relinkToMatchingSubelements`, ~l.384): this is the "propose a candidate fix" behaviour.
### 2.5 What still breaks [V unless marked]
- The project itself says TNP is "not completely solved" (release notes) and the algorithm is a heuristic that
"is not intended to fix every failure" (wiki). Inserting/removing features mid-tree makes auto-repair less likely.
- Names depend on OCCT history. Any OCCT change, hasher on/off, threshold, or algorithm change alters names, hence the
version string and forced recompute (above). Names are therefore not stable across kernel upgrades; this is handled
by recomputing, not by keeping the old names.
- Splits/merges: one old face becoming two (e.g. a cut through a face) yields two elements whose names share the
source and differ by the `M<index>` number; which one the reference follows depends on OCCT's ordering of
`Modified()` [I, consequence of the grammar].
- Not every operation is naming-aware; shapes built by non-`makeElement*` code get no map (`ElementMapPolicy::Drop`
exists in `makeShapeWithElementMap`) [V for the policy; which workbenches still drop is I].
### 2.6 Cost and size [V qualitatively, no numbers measured]
Names grow with history depth (each name embeds its source name); realthunder introduced the StringHasher for
exactly this and warns names "will quickly go out of control" without it. Cost per operation: building per-type
ancestry caches (`ShapeInfo`, `_cache->getAncestry`) and iterating every input sub-shape through the mapper
(passes 1-4 above are O(sub-shapes) with hash maps). The element map is saved with each shape-bearing object. I did
not find benchmark numbers; the 1.0 integration discussion mentions performance work but I did not read it.
## 3. Other systems (all from recollection unless noted; none were fetched, one Onshape docs fetch was blocked)
| System | Mechanism [I] | Stable across upstream edit? | Failure behaviour |
|---|---|---|---|
| Onshape | Each topological entity gets a deterministic ID derived from the feature that created it and its role (e.g. "the cap of this extrude"), computed from the feature's own history. FeatureScript queries (`qCreatedBy`, `qOwnerBody`, `qAdjacent`, `qGeometry`...) are stored; persistent IDs are resolved at rebuild | Yes for most; the design intent is the query, not a single ID | Reference can become empty/ambiguous; feature errors, user re-selects. |
| SolidWorks | Feature tree + internal persistent references (per-face/edge ids that are carried through the feature history) plus geometry heuristics | Mostly; known failures ("dangling" references) | Rebuild error / "lost reference" until user re-attaches. |
| Fusion 360 | Entity tokens (opaque strings) for B-Rep entities, valid for the same design state; plus a "temp ID" per session | Tokens survive many edits within a design; not guaranteed across all | Token lookup fails -> null entity. |
| CadQuery / build123d | No persistent naming; selectors by geometry/orientation (`faces(">Z")`), tags on workplane stack only within one script | n/a: re-run whole script, selector re-evaluates on new geometry | Selector returns 0 or wrong set; user script handles it. (This is where we are today.) |
Common point [I]: all commercial kernels give the *kernel* the job of reporting per-operation history (Parasolid/ACIS
have it; OCCT has `Modified`/`Generated`/`IsDeleted`), and store a query or lineage, not a position.
## 4. What our kernel already records (read from src/cpp, [V])
Good news: the C++ kernel already captures OCCT history per operation, and tag lineage is already projected through
it. What is missing is a persistent, resolvable *name* built from that history.
- OCCT history capture: `src/cpp/include/scad/semantic/tracking.hpp` ("OCCT algorithm history -> TopoDelta").
`src/cpp/src/semantic/tracking_detail.hpp` defines `HistorySource` with `BuilderHistory` (wraps a finished
`BRepBuilderAPI_MakeShape`: `IsDeleted`/`Modified`/`Generated`) and `RetainedHistory` (wraps `BRepTools_History`).
Per-operation trackers: `tracking_blends.cpp` (`track_blend` for fillet/chamfer, uses `op.Contour`/`op.Edge` to find
the edges actually blended and marks generated faces as blend patches; shell likewise), `tracking_booleans.cpp`,
`tracking_sweeps.cpp`, `tracking_lofts.cpp`, `tracking_transforms.cpp`, `tracking_primitives.cpp`. Booleans fill
history via `kernel::booleans.cpp` (`SetToFillHistory`, `fuse_shapes_with_history` merging the unify history).
`TrackingPolicy::Graph` turns face/edge history queries off (used for standard-part factories) [V, header comment].
- Result of tracking: `TopoDelta` in `src/cpp/include/scad/topo/delta.hpp`: per output/deleted sub-shape a `TopoEntry`
{`TopoRef`, `TopoEvent` Preserved/Modified/Generated/Deleted, `origin_role`, `parent_refs`}, plus kernel-native
`TopoRoleEntry` roles ("extrude.first_cap"). It is stored on every graph node: `std::optional<TopoDelta> topo_delta`
in `src/cpp/include/scad/reactive/graph.hpp` (node and node-spec).
- Identity: `kernel_topo_id()` = hash of (TShape, Location), orientation ignored; it is valid only while the shape is
alive and "the recorder resolves kernel ids to stable per-root ids" such as `face_3` (`topo_index` in
`src/reactive/internal.hpp`, "face_3 -> 3") [V]. A `face_N` id is an *index* into the root's face list, i.e.
positional: the same weakness as FreeCAD's `Face12`. [I] it is stable within one executed graph run but not across
re-execution after a parameter change.
- Semantic layer on top: tags (`include/scad/topo/tagging.hpp`, `TagBinding` with 128-bit id, evidence, certainty,
lifecycle; `tag_factories.hpp` with `LineagePolicy`, `lineage_policy_allows(policy, LineageDerivation)`;
`shape.hpp` `add_tag_lineage`) projected through the delta. This is why kwarg tags survive booleans and source-edge
tags project to fillet patches (docs/skill/references/ql-playbook.md rows at l.58-62).
- Editor side: `src/simplecadapi/editor/features.py` `selection_recipe()` (l.~798) emits `scad.ql.tag(...)` first when
every picked item carries a tag with a known feature slug, else geometry (`selector_conditions` in
`selection.py`), with `.exactly(n)` as the count check; `extract_recipe` keeps it on edit.
What is missing:
1. No persistent identity for a *picked* sub-shape: the editor stores tags/geometry, not "this sub-shape of node N".
2. Deltas are recorded per node but there is no resolver "(node, sub-shape name) -> sub-shape of the re-executed
result", and no name that is stable across re-execution. `face_N` is an index.
3. Plain user tags on faces are blocked by a "face-source gate", and face-channel gaps exist for kwarg tags through
fillet/chamfer (playbook rows). The delta has the data (`Modified`/`Generated`) but the projection stops.
4. No fallback ranking (history, then geometry with uniqueness) and no "candidate fix" output. Geometry fallback is
in the notebook cell source and is a hard windowed match, not tolerance-widening-until-unique.
5. History is skipped under `TrackingPolicy::Graph`, and some ops (loft section correspondence, per playbook l.185)
are explicitly "kernel-matched, not stable".
## 5. Recommendation
### 5.1 What the stable reference should be
A **history path**, not a tag and not a position: the reference is
`(origin node id, origin entity role, derivation chain)` where each link is
`{node id, event ∈ {Preserved, Modified, Generated}, source ref, ordinal}`. Concretely, store a small record in the
feature (not a string-encoded blob like FreeCAD's `;:M2;FUS;:T1:5:F`; we have a typed `TopoDelta`, so use it):
```
ElementRef = {
anchor: {node_id, kind, role?, index?}, # the "root name": where this entity was born
chain: [ {node_id, event, ord} ... ], # Modified/Generated hops up to the node the feature consumes
guard: {kind, area, centroid, normal/length} # geometric fingerprint used only to verify/repair
}
```
Roots (anchors) should be the things already deterministic in our kernel: a primitive's named faces, an extrude's
`first_cap`/`last_cap`/side-per-profile-edge (sketch geometry ids, as FreeCAD uses `g1;SKT`), revolve caps, and
user-pinned semantic tags. Everything else is derived by following `Modified`/`Generated` through `topo_delta`.
This is exactly FreeCAD's model (stable roots + history hops) with typed fields instead of string grammar.
### 5.2 Where history capture belongs
The C++ kernel, per operation, via the OCCT make-shape history; it is already there (section 4). The work is not
new capture but (a) making the kernel emit, for each result sub-shape, a **name** (root + hops) rather than only a
per-run index, and (b) a deterministic ordinal when several result sub-shapes descend from one source (sort by a
stable key: tag/role first, then a geometric key such as centroid lexicographic order at fixed tolerance, never
OCCT iteration order), because `Modified()` ordering is not a promise [I]. Use the same fall-through order FreeCAD
uses for unnamed elements (upper-derived, then lower-derived names) only where history yields nothing.
Ops that skip history (`TrackingPolicy::Graph`) are fine: the user does not reference faces of standard-part
internals; but the *consumed* body of any feature a user picks from must run with history on.
### 5.3 How a GUI feature stores it
The picked item's `ElementRef` (JSON, short) goes in the feature cell as a kwarg-style literal or a structured cell
comment that the editor already round-trips (`extract_recipe`), e.g.
`_edges = scad.ref.edges([ElementRef(...), ...], source={BODY})`, resolved by the SDK, not by recipe text. Keep the
current tag and geometry lines as *secondary* evidence inside the same ref (`guard`), not as the main mechanism.
Per FreeCAD's `ShadowSub`, also keep the last resolved positional name only as a cache/hint.
### 5.4 Resolution and failure behaviour
Resolver order (mirrors FreeCAD 2.4):
1. Follow the chain through the new run's recorded deltas to a set of result sub-shapes.
2. If exactly one: done. If several (split): pick by ordinal; if the picked count differs from what the feature
needs, fail with the candidate list.
3. If none (deleted or chain broken): geometry search with `guard`, widening tolerance stepwise and accepting only a
**unique** match (FreeCAD's `AdaptiveTolerance`); mark the result `repaired_by_geometry` in the output.
4. Else raise a typed error `ElementRefLost` on the feature, carrying the last known name, the guard, and up to N
candidates ranked by geometric distance for the editor to offer ("propose fix", FreeCAD purpose 2). Never silently
pick another entity ("First, do no harm"); this is already our rule ("an error on the feature, never another
face"), keep it.
5. Whenever a repair happens (step 3 or user-accepted candidate), write the new name back into the cell.
Always run the check that the resolved kind and count match, as today.
### 5.5 Staged plan, smallest first
1. **Spike (smallest): resolve through existing deltas, no new storage.** In the Python/C++ boundary add
`resolve_by_history(body_value, node_id, topo_id) -> [faces]` that walks `topo_delta` entries
(`parent_refs`, event) from the picked entity's birth node to the current result. Use only for fillet/chamfer
after boolean/extrude; compare against the geometric recipe on the failing cases found so far (face tags dying
after later ops; kwarg tags lost through fillet). Success = those cases resolve with zero geometry fallback.
Needs no format change.
2. **Persistent names.** Replace the per-run `face_N` with root+chain names as in 5.1; add deterministic ordinals
(5.2). Add the `ElementRef` literal and make `selection_recipe` emit it; keep tag/geometry as `guard`.
3. **Resolver with repair and errors** (5.4), including `ElementRefLost` with candidates; editor UI shows them.
4. **Close the gaps in projection:** lift the face-source gate for user tags and the fillet/chamfer face-channel gap
by feeding them from the same chain, so tags become a *view* over the names instead of a parallel system.
5. **Versioning and tests.** An element-map version string like FreeCAD's (our naming algorithm version + OCCT
version); on mismatch, force full recompute and re-resolve with guard. Regression: reuse the existing editor
selection tests and add a corpus (parameter sweep of a bracket: change widths, add a fillet upstream, insert a
feature mid-tree) asserting resolved-by-history rate and zero wrong picks. Measure delta size and resolve time
on the arm6 benchmark before enabling history on large graphs.
### 5.6 Risks and non-goals
- Cannot be perfect: FreeCAD, with years of work, still documents failures. Target "never silently wrong, mostly
automatic", not "never fails".
- OCCT history is imperfect for some algorithms (sewing, thru-sections, offsets, `BOPAlgo` fuzzy cases); keep per-op
coverage explicit and fall back to guard for those, as FreeCAD does with `ElementMapPolicy::Drop`/special mappers.
- Lofts: per-section correspondence is kernel-matched; do not promise stable side-face names until sections are
named by input wire edges.
- Avoid FreeCAD's string-encoded grammar and its hasher; typed records plus an interned table are simpler for us, but
record growth with chain depth still needs a cap (collapse a chain to its nearest durable anchor, e.g. a tag or a
primitive root).
## Source list
- https://wiki.freecad.org/Topological_naming_problem
- https://wiki.freecad.org/Release_notes_1.0
- https://github.com/realthunder/FreeCAD_assembly3/wiki/Topological-Naming
- https://github.com/realthunder/FreeCAD_assembly3/wiki/Topological-Naming-Algorithm
- https://github.com/FreeCAD/FreeCAD/blob/main/src/App/ElementMap.h
- https://github.com/FreeCAD/FreeCAD/blob/main/src/App/MappedName.h
- https://github.com/FreeCAD/FreeCAD/blob/main/src/App/IndexedName.h
- https://github.com/FreeCAD/FreeCAD/blob/main/src/App/ComplexGeoData.h
- https://github.com/FreeCAD/FreeCAD/blob/main/src/App/GeoFeature.cpp
- https://github.com/FreeCAD/FreeCAD/blob/main/src/App/PropertyLinks.h and PropertyLinks.cpp
- https://github.com/FreeCAD/FreeCAD/blob/main/src/Mod/Part/App/TopoShapeExpansion.cpp
- https://github.com/FreeCAD/FreeCAD/blob/main/src/Mod/PartDesign/App/FeatureDressUp.cpp
- Not read: PR #13705 itself (only its mention in the release notes), the forum thread "Topological Naming, My Take",
and any Onshape/SolidWorks/Fusion documentation.
---
## Addendum: Onshape, read from primary sources (ego-browser, 2026-11-04)
This replaces the Onshape row above, which was written from memory (the first fetch was stopped by a login wall on `cad.onshape.com/FsDoc/queries.html`;
the FeatureScript standard-library reference is readable at `formlabs.onshape.com/FsDoc/library.html`, and the REST guide at
`onshape-public.github.io/docs/api-adv/associativity/`).
**Verified**
- **A reference is a query evaluated against the current history, never a stored entity id.** Features pass `Query` values; a feature's `id` is a
hierarchical path (`id + "extrude1"`) and `qCreatedBy(id + "extrude1", EntityType.FACE)` resolves to whatever that operation created in the
*current* regeneration. Rule from the library docs: "the full id hierarchy must reflect creation history", each Id (and every parent) must cover a
contiguous region of operations, so an id is a position in the operation sequence, not a number on the geometry.
- **Tracking through later operations is explicit and history-based:** `startTracking(context, subquery)` returns a query that evaluates to the entities
that *derive from* the subquery's result (the docs' example: a sketch line `line0` extruded yields a face and two edges); `startTrackingIdentity`
returns the entities that inherit the identity; `makeRobustQuery(context, subquery)` produces "a query robust to identity-preserving changes";
`makeRobustQueriesBatched(..., followSplitMerge)` does it per entity, optionally through splits and merges. This is the same idea as FreeCAD's mapped
names (derivation recorded by the kernel's operation history), exposed as an API instead of an encoded string.
- **Unstable ids are handled by disambiguation:** `setExternalDisambiguation(context, id, query)` for operations whose id has an unstable component
(sketches, planes, points that track no dependency); a pattern instance takes an `identity` entity so it follows its source, not its index.
- **Failure is loud:** `verifyNonemptyQuery` raises a regen error and marks the parameter faulty when a query "no longer resolves to anything"
(the face is not silently replaced by another).
- **Externally there is no persistent id at all.** The REST guide: "Onshape does not expose a persistent ID for any of these entities. When the model
changes, the ID may change", so it offers `POST .../idtranslations` from a source microversion: each id maps to `OK`, `SPLIT` (several targets) or
`FAILED_TO_RESOLVE` (none); the guide stresses "a face may become zero, one or multiple faces". A rollback translates back to the original ids.
**What it means for us**
1. Onshape's answer and FreeCAD's agree in substance: the reference is *derivation through recorded history*, with a three-way outcome (same / split or
merged into several / gone) and no silent retargeting. Geometry matching is a repair step at best.
2. The shape worth copying is Onshape's API: a **reference = (anchor operation id, entity kind, optional tracking)**, resolved by walking the
per-operation history we already store (`TopoDelta`), returning *a list* with a status (`ok` / `split` / `lost`), and a `follow_split_merge` choice.
Our graph node ids are already deterministic positions in the operation sequence, which is what Onshape's hierarchical ids are.
3. The status vocabulary (`OK`, `SPLIT`, `FAILED_TO_RESOLVE`) should be the editor's reference health: green, amber with the candidates, red.
4. Still not read: Onshape's internal algorithm (not public), Parasolid's own attribute mechanism, and the FreeCAD PR threads; the Fusion and
SolidWorks rows stay unverified.