Skip to main content

ADR-0014: Normalized Status/Readiness Contract Enforcement

Status​

Accepted

Date​

2026-02-24

Context​

Evalium now exposes derived koeStatus and proofReadiness blocks across submission, reporting, and glass-box surfaces.
Without a single enforced contract, these risks appear:

  • drift in reason/state strings between services and handlers
  • OpenAPI docs falling out of sync with runtime values
  • inconsistent operator interpretation across lenses

This conflicts with platform invariants around defensibility, explainability, and stable projection contracts.

Decision​

We will enforce a single normalized status/readiness contract through code, tests, and CI:

  1. Canonical status/reason constants live in one shared package (statuscontract).
  2. Runtime surfaces normalize/validate emitted values against that contract.
  3. OpenAPI readiness schemas use explicit enums for states/reasons/logic version.
  4. CI includes a guardrail script that fails on contract drift between code constants and OpenAPI.
  5. Integration tests assert contract validity on submission + defensibility exception responses.

Scope​

Applies to:

  • koeStatus states/reasons
  • proofReadiness states/reasons/logicVersion
  • defensibility exception triage and readiness states

Does not redefine execution truth; this is projection and contract enforcement only.

Consequences​

  • Positive:
    • prevents silent contract drift
    • keeps frontend-facing contracts stable
    • improves auditability and operational consistency
  • Tradeoff:
    • every new status/reason requires touching constants + OpenAPI + tests (intentional friction)