Doctor Commands and Cardinality
A missing cardinality check in our backend allowed multiple “primary” links to be attached to single nodes in our knowledge graph. We didn’t notice the corruption for months because our UI conveniently rendered only the first link it found, silently hiding over 400 data violations from our view.
Invisible state corruption is the most dangerous kind of technical debt, because your test suite often validates the same illusion that the UI presents.
The Illusion of Correctness
In Equill, entities are connected via edges. Certain edge types, like a primary_source link, must have a strict 1:1 cardinality. However, the database schema didn’t enforce this constraint directly, relying on application logic to maintain integrity.
A race condition in the ingestion pipeline began creating duplicate primary edges.
The bug bypassed all our integration tests. The UI queried the graph, received an array of edges, grabbed edges[0], and rendered it perfectly. The application looked completely healthy. Underneath, the database was quietly filling up with contradictory graph relationships, destroying the integrity of our semantic mapping.
The Doctor Will See You Now
We discovered the rot not through a test, but through an explicit health check. We wrote a simple CLI command: equill doctor.
Unlike a unit test that mocks inputs, the doctor command scans the live production database. It iterates through every node and asserts absolute graph invariants: no orphaned edges, no circular dependencies, and strict cardinality limits.
On its first run, doctor instantly flagged 400 cardinality violations.
Unit tests verify that your code can do the right thing. Doctor commands verify that your system has done the right thing. Build explicit commands to interrogate your live state, because your UI will happily lie to you.
Next in the Equill series: why we abandoned an in-memory vector database in favor of brute-force similarity matching in Why We Dropped Local Vector Search.