Naming faces is hard: stable topological references

You put a fillet on an edge, change a dimension higher up the tree, and… the fillet shows up somewhere else, or fails. It's one of the classic parametric-CAD bugs, and it has a name: the topological naming problem. Here's how we tackle it in KapyCAD.

The index problem

When you pick a face to fillet, the intuitive thing would be to store something like "face number 4". The problem is that number is fragile. The solid is rebuilt from the feature tree every time you edit something, and operations like a boolean or a geometry change reorder the list of faces. The old "face 4" may now be a different one.

The result is the worst thing that can happen in an editor: the operation gets applied to the wrong face silently. Your fillet has moved on its own.

A reference that isn't a number

The fix is to reference by identity, not by position. KapyCAD stores a TopoId: a stable identifier that describes how that face or edge was created (which operation it came from, and from what), not the slot it occupies in a list. It's the difference between "the fourth in the row" and "Marta": if the row gets reordered, Marta is still Marta.

Resolving after a regen

Every time the model regenerates, KapyCAD re-resolves each TopoId against the freshly built geometry: it looks for the face matching that identity and applies the operation to it. If it finds it, everything stays put. If the part changed so much that nothing matches anymore, resolution fails with a clear error (an ERR_* code) instead of picking some arbitrary face.

diagram

Failing in plain sight is a feature

That resolution can fail on purpose isn't a defect: it's what prevents the silent bug. We'd rather tell you "this reference no longer exists, check it" than move your fillet to a face you didn't choose and let you discover it when you print the part.

Why it matters to you as a user

You don't have to think about any of this, and that's exactly the point. It means you can go back up the tree, change an early measurement, and trust that your fillets, chamfers and other operations still point where you told them to — or, if something genuinely broke, that you'll find it flagged, not hidden.