ADR-0052: Cross-stack contracts guarded by drift tests, not codegen
Status
AcceptedTags
architecture, cross-stack, contracts, testing, drift, codegen, seam, ciDecision
A cross-stack contract is a rule or vocabulary that Go, Bun, the SolidStart/Astro frontends, and Flutter each re-implement in their own language, because they are separate processes and cannot share code. Examples: the AI errorcode taxonomy, the FieldForce Task status/event wire values, the auth roles-ordering rule, and the token-revocation boundary.
These copies are kept honest by drift-detection tests, not by generating them from one source and not by leaving them synced only by comments. Two shapes, chosen by who owns the contract:
-
Asymmetric — one owner emits, clients consume. Go is authoritative; clients hold read-only copies. A Go test references the real Go constants, reads the client source files as text, and asserts client ⊆ Go (a client may never reference a value Go does not emit). No shared artifact — the Go source of truth is the fixture. Lives in
backend/go/internal/contracts/. -
Symmetric — the rule is genuinely shared, no single owner. e.g. Bun mints a token and Go/mobile verify it across a trust boundary; both must apply the same roles ordering and the same revocation boundary. A shared golden fixture in
contracts/(repo root) is read by both a Go test and a Bun test. Deliberately divergent policy (Go fails open on a Redis outage, Bun fails closed) is left out of the fixture — only the shared decision is pinned.
Why
The same contracts were previously synchronized only by prose — twin comments literally reading “mirrors the other side.” An architecture review found the AI error-code taxonomy defined 3× in Go and re-hardcoded in 4+ frontend files, the Task status values in 5 places, and the revocation<= boundary duplicated in Go and Bun by comment. Real drift had already shipped: the frontend matched provider_overloaded, a code Go emits nowhere.
The reflexive fix — one schema that generates Go/TS/Dart types at build — was rejected. It buys compile-time safety but costs a codegen pipeline across three languages plus build wiring, for contracts that change a few times a year. The actual pain was never that copies exist; it was that drift was silent. A test removes the silence at a fraction of the cost.
Rejected alternatives:
- Codegen (one source → Go/TS/Dart). Strongest, but a 3-language generator + build integration is disproportionate to how often these contracts change. Reconsider only if the contract count grows large or drift keeps recurring despite the tests.
- Server-served manifest (clients fetch codes/edges at runtime). Removes the copies but adds a runtime dependency and a cache-staleness question, and gives no compile-time or CI signal. Overkill for static vocabularies.
- Consolidate within each language only, no cross-stack check. Reduces surface but leaves cross-seam drift undetected — the exact failure mode we hit.
- Do nothing (keep the “mirrors the other side” comments). The status quo that shipped the
provider_overloadeddrift. Rejected.
How it works
Adding or changing a cross-stack contract:- Decide the shape. One authoritative owner (Go) → asymmetric. Rule replicated across a trust boundary with no single owner → symmetric.
- Asymmetric: add the value to the Go source of truth, then to the client copy. The Go test in
backend/go/internal/contracts/asserts client ⊆ Go. If a client references a value Go never emits, the test fails. - Symmetric: add a case to the fixture in
contracts/; the Go test and the Bun test both read it and assert their implementation matches.
Known limitations
- Fixed client-file list. The asymmetric tests scan a hardcoded set of client files. A brand-new client file that matches codes must be added to the list, or its drift goes unseen. This is the accepted ceiling of “keep copies + test” versus codegen.
- Text extraction is regex-based. A client file that reshapes how it declares the vocabulary can require a test tweak. Kept tractable by scanning only known error-handling/enum files, not the whole tree.
- Detection, not prevention. Drift is caught in CI after it is written, not made unrepresentable at compile time (which only codegen would give).
- Error-handling policy is out of scope for symmetric fixtures — only the shared decision is pinned; intentional divergence (fail-open vs fail-closed) stays in each side’s own tests.
Rules for agents
- When adding a value that another stack must also know (an error
code, a status/event wire value, a shared auth rule), add or extend the matching contract test in the same change — do not rely on a comment to keep the sides in sync. - Do not introduce a cross-language codegen pipeline for these contracts without revisiting this ADR.
contracts/(repo root) holds only symmetric fixtures. Asymmetric contracts need no artifact — the Go source of truth is the fixture.- Keep the direction client ⊆ Go for asymmetric contracts; do not make it strict equality (many Go values are intentionally not client-facing).