Engineering 1 min read
Why our node IDs never get renumbered
A comparison is only useful if you can tell what changed since the last one. That depends on identity, and identity is harder than it looks.
Afara Engineering, Engineering team
A wireframe is a graph: screens and steps as nodes, the order between them as edges. The first version of Afara numbered nodes as it found them. It worked well until the second time anyone ran it.
Regenerate a feature after a small change, and the model might find the same seven steps in a slightly different order. Number them as you go and node 4 is now node 5. Every finding that pointed at node 4 now points at the wrong thing, decisions people made on findings get attached to the wrong code, and the dashboard shows churn where nothing really changed.
Identity is part of the contract
So we made a rule: node IDs are stable across regenerations and never reindexed. A node’s ID describes what it is (pay.c.confirm, step.retry-authorisation), not where it appeared. When a feature is regenerated, existing nodes keep their IDs and only genuinely new behaviour gets new ones.
The same rule applies on the story side. If a ticket hasn’t changed since it was linked, afara compare reuses the story wireframe read at link time instead of reading it again. Finding IDs stay the same between runs, so an accepted finding stays accepted.
Features get the same treatment
Feature IDs are derived from the name the first time you run afara generate --feature. Rename the feature later and the ID stays put, along with its history. That’s why the CLI asks you to pick a name your team will recognise: it becomes the label everywhere, but it isn’t the key.
None of this is visible when it works. It’s the reason a comparison from last Tuesday and one from today can be read side by side.