Contract drift
A spec diff tells you something broke. It cannot tell you who breaks.
Every breaking-change tool compares two versions of one document. That is the easy half. The question you actually have on the morning of a release is which of your services is about to fall over, and a spec diff has no idea.
One field, one week
-
Tuesday
A field goes optional
An agent tightens a handler and the response schema loses a field that was always there. The pull request is green. The change is correct in isolation.
-
Tuesday
The spec is versioned, not just diffed
The published document is captured as a snapshot with a digest, its elements extracted, and compared against the baseline. The comparison answers compatible or not, and names every change that made it so.
-
Tuesday
The graph says who cares
Three services declare a dependency on the one that publishes this contract. That is not a guess from a spec diff. It is read from their own manifests.
-
Friday
What used to happen instead
The mobile team finds out in staging, or a customer finds out in production, and someone spends the afternoon working out which release did it.
The record
What a change carries
A comparison answers whether the two versions are compatible, and every change inside it is a record you can act on rather than a line of prose.
- classification
- What kind of change this is, so a rename and a removal are not filed as the same event.
- severity
- How much it matters, carried on the change itself rather than inferred later by whoever reads it.
- summary
- What moved, in a line, so a reviewer does not have to diff two documents by eye.
- before / after element
- The exact element on each side. A change must name something it affected or it is not recorded.
- confidence
- Between 0 and 1. Uncertainty is stated rather than rounded away.
- evidence
- The source and revision behind the finding, so it can be checked instead of trusted.
The joint
The contract knows what changed. The graph knows who depends on it.
Neither half is unusual on its own. Holding both in one record is the part that answers the question you actually have.
The published interface
Captured with a digest and a revision, its elements extracted, compared against the version before it.
Joined in one graph
Under one scope, traversable in a single bounded query
The services that consume it
Read from the manifests those repositories publish, with the file behind every edge on the record.
Where you meet it
In review, on the change that caused it
A finding on a published interface is weighted by what the graph says depends on it. A break on a contract three services consume is not the same finding as one on an internal helper.
In your assistant, before the change is written
Contracts are one of the sources a context pack draws on, so an agent asking what a change touches gets the interface and its consumers alongside the code.
Put your system on the record
Run the open core on your own infrastructure, or start on the hosted workspace. The graph is portable either way.