Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Persistent naming: a proposal from a second implementation (#7990)

Derek Van Allena66a517c40b8
diff --git a/docs/design/persistent-naming-proposal.md b/docs/design/persistent-naming-proposal.md
new file mode 100644
index 0000000000..e9de812e9f
--- /dev/null
+++ b/docs/design/persistent-naming-proposal.md
@@ -0,0 +1,238 @@
+# Persistent naming: what a second implementation suggests
+
+Status: proposal, not adopted. Nothing here is built in SolidCraft. Related: #4341, #5198, #5308,
+#5857, #5858, #5860, #5861, #23.
+
+This note comes from building persistent naming for Form Studio, a T-spline modeling tool with its
+own feature timeline, rollback marker, suppression, and editing of earlier features. Its kernel is
+a control mesh, not a B-rep, so its entities are the vertices, edges and faces of a cage. A
+feature's picks still have to survive the same upstream edits SolidCraft's do.
+
+Form Studio is LGPL-2.1. Rule 2 of CONTRIBUTING.md says not to read it, so this note links none of
+its code and contains none of it. What follows is method and measured results, written by the
+code's author and offered under MIT OR Apache-2.0. No commercial CAD was driven or read for any of
+it.
+
+## What SolidCraft already gets right
+
+The hard parts are done. Names follow the history each kernel operation reports (#136), not
+sampled geometry. Faces are named by their role in the feature that made them (`F2:side:l4`).
+Pieces are told apart by the faces around them, a merged face still answers to its old names, and
+a feature says when a reference was split or found only by geometry. Form Studio follows the same
+rules.
+
+The failures still open sit in three places: what happens when a name is gone, how a name is
+written down, and where an ordinal comes from. Six changes follow, the most harmful failure first.
+
+## 1. When a name is gone, fall back by lineage, never by geometry alone
+
+SolidCraft already has this rule for one kind of reference. A sketch's link to a projected edge
+whose name is gone "keeps its last geometry ... it does not take whichever edge is nearest now"
+(`docs/book/src/dev/naming.md`). Blends don't follow it yet. Read at 49c0faa, not run:
+
+- A blend edge whose name no longer resolves falls back to "the edge at the picked point"
+ (`crates/doc/src/eval.rs:4128`).
+- A blend with no stored body takes the body with the nearest edge (`blend_target`,
+ `eval.rs:3951`), and `named_body` (`eval.rs:3997`) ends with the nearest candidate.
+
+Either path can put a fillet on an edge of an unrelated body. That is #4341: suppress Extrude1, or
+move Sketch1 500 mm, and Chamfer1 lands on Body2. The warning is honest, but the geometry is
+wrong, and every later feature builds on it.
+
+Form Studio resolves a stored reference with the first of these four steps that finds something:
+
+1. **Exact.** The entity with that name.
+2. **Pieces.** The name is gone because an earlier feature split the entity. The result is every
+ live piece its history leads to, including pieces that were split again (see change 5).
+3. **Lineage guess.** Nothing was split from it, but its maker rebuilt it differently, for example
+ a subdivision changed from 2 × 2 to 3 × 3. A candidate must come from the same feature and
+ share either the role or at least one origin with the stored reference. Scoring starts at 4 for
+ the same feature, then adds 2 for the same role, 2 for each shared origin and 1 for the same
+ ordinal. Distance to the stored point only breaks ties. The result is one entity, never every
+ candidate that matches.
+4. **Lost.** No candidate. The pick resolves to nothing, the feature says so, and its other picks
+ still apply. A feature with every pick lost is in error, and the document passes through it
+ unchanged.
+
+What step 3 leaves out matters most: no entity made by another feature can stand in, however close
+it is. In SolidCraft terms, a stored reference keeps one level of what its name was made from
+(feature, role, the names of its origins, ordinal). After the name is lost, the lookup searches the
+rebuilt faces that feature made. It doesn't search space. Change 3 describes where that recipe is
+kept.
+
+The stored point stays useful in three ways: it breaks ties, it raises the existing "found by
+geometry, not exact history; check it" note, and it is the only key for references saved without a
+name. It should never choose a body or an edge on its own. Freezing a lost reference at its last
+geometry, as sketches already do, is fine, because nothing new gets picked.
+
+**Measured in Form Studio,** before names existed, when picks were raw indices (2026-10-05, 3
+scripted histories, 18 features):
+
+| Test | Result |
+|---|---|
+| Replay from the start | byte-identical to every recorded state |
+| Edit earlier features' numbers, topology unchanged | all 33 later features on the same entities |
+| Insert a subdivision upstream | of 60 later features: 0 kept exactly, 19 kept by position, 25 refused, 16 ran on a different entity with no error |
+
+The 16 silent wrong results came from indices that now pointed at other entities. An index, like a
+picked point, records where something was, not what it was. After names were built, six rebuild
+tests pin the rules down. All six pass today:
+
+- An unchanged rebuild finds every pick exactly.
+- A subdivision inserted before a move of the face it splits: the move takes every piece.
+- A feature inserted elsewhere leaves every later name unchanged.
+- Deleting the feature that made a picked face leaves the later feature in error, with the
+ document passing through it.
+- A subdivision changed from 2 × 2 to 3 × 3: a move of its corner piece moves the new corner piece.
+- A loop inserted before a crease of the edge it cuts: both halves are creased.
+
+We have not re-run the 60-feature insert test since names were built.
+
+## 2. A suppressed maker is not a lost reference
+
+When the feature that made a referenced face or edge is suppressed, or sits past the rollback
+marker, the reference isn't lost. It is waiting. Form Studio reads the maker from the feature id
+in the stored recipe:
+
+- **Maker suppressed.** The pick stays on the dependent feature and is shown as suppressed. That
+ feature is not in error, and nothing is re-pointed. Unsuppress the maker and the pick resolves
+ exactly again.
+- **Maker deleted.** The pick is shown as missing. The user can clear missing references or pick
+ again.
+
+Neither case falls back to geometry. SolidCraft names already start with their maker (`F2:...`),
+so it can tell these cases apart with no new data. #4341's first repro (suppress Extrude1) is this
+case.
+
+## 3. Store a name as data, and keep the text for people
+
+#5857 and #5858 are problems with the text form: where a nested name's suffix belongs, and an id
+that contains `|`. #5861 plans a better grammar for both. The text form has one more hazard, read
+from source and not run. `later_suffixes` (`crates/doc/src/persistent_name/parser.rs:74`) decides
+which face a piece qualifier belongs to by comparing feature numbers (`*f > feature`). Feature
+numbers follow creation order (`Document::next_id`), and `timeline.reorder` moves a feature
+without renumbering it. After a reorder, the same text can therefore be read the other way.
+
+Form Studio never parses a name. This would take two steps here, each useful on its own:
+
+1. **Save `FaceName` and `EdgeName` as structured values, not text.** `persistent_name.rs`
+ already reads names into a tree; the design file would keep that tree instead of a string. A
+ tree has no ambiguous suffix (#5857), a curve id is a field and can hold `|` (#5858), and no
+ rule has to compare feature numbers. #5861's migration then happens once: read old text with
+ today's rules and write the tree. The parenthesized text becomes the display form for
+ `model.faces`, MCP and messages. A command given that text looks it up in the live model, and
+ nothing parses text back into an identity.
+2. **Make every name one level deep.** In Form Studio, each entity's name is a fixed-length token
+ derived from a one-level recipe: feature, kind, role, origins (the tokens of its parents) and
+ ordinal. The recipe stays in the body's name table while the entity lives. A stored reference
+ keeps the token, the recipe and the picked point. Depth lives in the table: a piece of a piece
+ of a blend is a chain of one-level records. A stored reference is then the same size however
+ many splits came before it (#5860; the `MAX_NAME_LEN` comment notes that a face engraved with
+ text passes 4 KiB today). The recipe is also the data change 1's lineage guess needs.
+
+Form Studio uses a 53-bit hash and redraws on a collision within a mesh. A Rust version needs a
+hash whose output is fixed across platforms and releases (not `std`'s `DefaultHasher`), and 64
+bits or more.
+
+## 4. Ordinals come from the feature, never from the kernel's face order
+
+In #5198 the same design names a face `F3:bottom#1` on one kernel and `F3:bottom#2` on the other,
+so the reference picks the other cap. The `#k` that breaks a remaining tie follows the kernel's
+face order (`naming.md`: "else in kernel order and then unverified"). We suggest two rules:
+
+- **No two faces of one feature share a role and origins.** When two do, the role table is too
+ coarse. An extrude's two caps are `start` and `end`, whichever way it points.
+- **A real tie gets its ordinal from the feature's own definition.** For example, a closed
+ curve's wall split by a seam is ordered by the curve parameter where each piece starts, and
+ caps along a direction by their distance along it. The order a kernel returns faces in is
+ never used.
+
+In Form Studio the ordinal counts what one edit made with the same feature, role and origins, in
+the tool's own construction order. Form Studio has only one kernel, so we set this rule in advance
+and never saw it fail. A gate for it: build each design in the naming tests on both kernels and
+compare every name. The kernel switch (#3992, #4012) needs that gate, and it lives in the
+document and engine tests, not in `crates/kernel/`.
+
+## 5. A split pick resolves to all its pieces
+
+When a named face or edge was split, SolidCraft takes the piece nearest the stored point
+(`name_lookup.rs`; `locate_edge`: "the piece of it nearest `near`"). Form Studio takes every
+piece. The user picked the whole entity, and after a split the whole entity is its pieces:
+
+- A fillet on an edge that an upstream slot now interrupts should round both remaining runs.
+- A shell that opened a face should open both halves.
+
+A consumer that needs exactly one entity, such as a sketch plane or a joint, takes the piece
+nearest the stored point from that list and says so, as it does today.
+
+This changes what some saved designs rebuild to, so it raises the `Changes a default` question
+(see Questions below).
+
+## 6. A body's identity is not its name
+
+In #5308, references to a body use its display name. Features already keep the two apart: a
+minted id (`F12`) and a name the user edits. Bodies can do the same, and bluecmd's plan on #5308
+does it: an id minted from `next_id` and stored with the feature slot by slot, with the name
+becoming a label. That is better than deriving the identity from the creating feature and the
+lump's place, as an earlier version of this note proposed, because a stored id survives later
+changes to how lumps and faces are named. Form Studio does the same for features: the id is
+minted once and kept through renames, and a rename never rewrites a reference.
+
+A stored id is only as stable as the step that decides which lump fills which slot. Today the
+pieces of a split body are assigned in the order of their least face name
+(`crates/doc/src/lineage.rs:554` at 33281cf), and text order says nothing about which piece is the
+original. Suppose an upstream edit makes a cut slice a small piece off a body, and that piece's
+names sort first. The piece then takes the body's id, and with it the material and appearance.
+Assigning slots by lineage keeps the id on the main piece:
+
+- Each face contributes its own name and the names of the faces it was split from.
+- When a slot is pinned, the feature stores a MinHash signature of that set beside `body_names`.
+- On evaluation, each slot takes the lump whose signature overlaps its own the most.
+
+The details are in the
+[#5308 discussion](https://github.com/tangency-labs/solidcraft/issues/5308#issuecomment-6470264793).
+
+## Measuring it
+
+Classify every reference resolution the engine performs: exact, merged, pieces, lineage guess,
+geometry only, or lost. "Geometry only" is the class that can be silently wrong. Count it in the
+naming tests (`crates/engine/src/naming_history_tests.rs`, from #23) and in the action-matrix
+corpus, and ratchet it down to zero for references that have a name. The count changes no
+behavior, so it can land first and show what each later change buys.
+
+## Order of work
+
+Each step is a small PR on one topic:
+
+1. Classify and count resolutions. No behavior change.
+2. Suppressed versus missing (change 2; #4341, first repro).
+3. Lineage fallback for blend edges, then for face references (change 1; #4341, second repro).
+4. Structured names, together with #5861's step 2 (change 3).
+5. Cap roles and ordinals from the feature (change 4; #5198).
+6. Body identity (change 6), which bluecmd plans on #5308, then slots assigned by lineage.
+
+Steps 3, 4 and 6 save something new in a design, so each adds a file under
+`crates/doc/src/format/pending/`. Steps 3 and 5 change what some saved designs rebuild to.
+
+## Questions for maintainers
+
+1. Where today's point fallback lands on some edge, a lost reference would apply nowhere and the
+ feature would report it. Is that acceptable for saved designs, or should it sit behind a
+ preference?
+2. Should names be saved as structured values before #5861's step 2, or instead of it?
+3. Should a split pick resolve to all its pieces by default?
+
+## Background
+
+- J. Kripac, "A mechanism for persistently naming topological entities in history-based
+ parametric solid models", *Computer-Aided Design* 29(2), 1997.
+- V. Capoyleas, X. Chen, C. M. Hoffmann, "Generic naming in generative, constraint-based design",
+ *Computer-Aided Design* 28(1), 1996.
+- D. Marcheix, G. Pierra, "A survey of the persistent naming problem", *Proceedings of the
+ Seventh ACM Symposium on Solid Modeling and Applications*, 2002.
+
+## What was read and what was run
+
+SolidCraft was read at 49c0faa (2026-10-28 UTC). It was not built or run, so the mechanisms given for
+#4341 and for reordering come from reading the source. Form Studio's six rebuild tests were run on
+2026-10-27 and all pass. The insert measurement is from 2026-10-05, before names existed.