ADR-0052: Cross-stack contracts guarded by drift tests, not codegen

Status

Accepted

Tags

architecture, cross-stack, contracts, testing, drift, codegen, seam, ci

Decision

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 error code 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.
The copies remain. The test makes their drift fail CI instead of shipping silently.

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_overloaded drift. Rejected.

How it works

Adding or changing a cross-stack contract:
  1. Decide the shape. One authoritative owner (Go) → asymmetric. Rule replicated across a trust boundary with no single owner → symmetric.
  2. 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.
  3. Symmetric: add a case to the fixture in contracts/; the Go test and the Bun test both read it and assert their implementation matches.
The direction is client ⊆ Go for asymmetric contracts: a client may handle a subset of Go’s values (many Go codes are not user-facing), but may never invent one. Go values with no client handler are allowed on purpose.

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).