​
ADR-0003: Canonical Schema Authority

​
Status

Accepted

​
Context

Repeated failures have shown drift between shared types, validators, DB schema, API behavior, and UI assumptions. Without a declared contract order, changes can appear correct locally while still breaking another layer. The same applies to the analytical layer: PostgreSQL remains the canonical source of truth for operational entities and workflow state, while the canonical improvement dataset remains the joined analytics, calibration, continuous improvement, and future ML/RL input layer aligned with the source contracts it summarizes.

​
Decision

Adopt this canonical contract order for operating changes:
  1. shared types
  2. validators or schemas
  3. DB schema or migrations
  4. API route behavior
  5. UI assumptions
  6. docs/wiki
If a change does not flow through the whole chain, the gap must be explicit and justified. For repeated operational learning, treat the joined improvement dataset as canonical for analytics, calibration, continuous improvement, and future ML/RL inputs, but not as a substitute for the underlying shared types, validators, migrations, or route behavior.

​
Consequences

​
Positive

  • drift becomes easier to reason about
  • PR reviewers have a clear checklist for contract-affecting changes
  • schema governance becomes explicit rather than inferred

​
Negative

  • changes may feel slower because contract updates need cross-layer discipline
  • repo contributors must learn the contract order

​
Review Trigger

Revisit if the platform introduces a different canonical contract source or a generated-schema workflow that changes the dependency order.