Core Concepts

6 min read

Syndrome independence

StateAnchor evaluates every spec push against four independent diff anchors. Each produces a separate syndrome -- a structured record of what changed relative to a different reference point. The gate engine requires a finding to appear in at least one syndrome before it can block; multiple syndrome agreement raises confidence.

The four anchors are independent by design: they cannot all be fooled by the same maneuver. A change that slips past one anchor is caught by another.

The four anchors

1. Parent diff

Reference point: the direct parent commit's spec.
Catches: changes introduced in this specific commit -- the narrowest possible scope. If a field was removed in this commit and only this commit, the parent diff fires.

2. Merge-base diff

Reference point: the common ancestor between the current commit and main (the Git merge base).
Catches: the cumulative net change across the entire branch, not just the last commit. A field can be added in commit A and removed in commit B on the same branch; the parent diff on commit B would show a removal, but the merge-base diff would see no net change. The inverse is also caught: a field removed in commit A and re-added in commit B appears clean to the parent diff but shows a net removal to the merge-base diff relative to the ancestor on main.

3. LKG (last-known-good) diff

Reference point: the last spec snapshot that passed the gate without an ERR verdict.
Catches:drift that accumulated across multiple gate-passing pushes. This is the longitudinal anchor -- it compares today's spec against the last clean baseline, not just the most recent commit. A field that was gradually narrowed across five WARN-level pushes will surface as an ERR in the LKG diff even if each individual push stayed below the WARN threshold.

4. Deployed diff

Reference point: the spec associated with the currently deployed version of the API (sourced from the live-scanner observation plane when available, or from the last deployment tag).
Catches: divergence between the contract as it exists in production and what the new commit proposes. A rollback that re-introduces a previously-removed field would be invisible to the parent and merge-base diffs but would show up as an addition against the deployed snapshot.

Why independence matters: a worked example

Consider a branch that removes GET /users/{id}/email in commit A, then re-adds it in commit B:

• Parent diff on commit B -- sees the field being added back. No ERR.
• Merge-base diff on commit B -- compares against the ancestor on main, where the field exists. Net change: none. No ERR.
• LKG diff on commit B -- the LKG is the last clean gate result, which includes the field. Net change: none. No ERR.
• Deployed diff on commit B -- deployed spec has the field (it was never removed from production). Net change: none. No ERR.

In this case the gate correctly passes -- the field was removed and restored within the same branch before it was ever merged. No consumers were affected.

Now consider a different scenario: commit A removes the field and is merged to main without the gate running (OIDC unavailable, soft-pass). Then commit B on a new branch adds an unrelated field:

• Parent diff -- only sees the unrelated field addition. No ERR.
• Merge-base diff -- compares new branch to main, which now has the removal baked in. No ERR here either (the removal is in the base).
• LKG diff -- the LKG predates the removal (it was the last passing gate before the soft-pass). The LKG diff sees the removal relative to the old baseline and fires ERR.
• Deployed diff -- if the removal is now live, the deployed diff shows no change. But if the removal is not yet deployed, the deployed diff fires ERR.

The LKG anchor catches drift that slipped through on a prior push. This is why the four syndromes are not redundant -- each has a blind spot that the others cover.

Gate decision semantics

The gate blocks if any syndrome produces an ERR finding. A finding appearing in multiple syndromes does not double-count -- the gate lane is categorical, not additive. However, multi-syndrome agreement is displayed in the verdict panel as a confidence signal: a finding corroborated by three out of four syndromes carries higher confidence than one that fires in only one.

Suppressed findings (covered by an active exception) are excluded before the gate evaluates. See Drift Exceptions for how suppression works.

Relationship to ADR-020

The two-independent-dimension requirement is formalized in ADR-020. The gate requires both the categorical lane signal and syndrome agreement before treating an ERR as confirmed. This prevents false positives from transient diff noise in any single anchor.