Contract versioning
CA-A1 architecture record. Updated: 2026-10-05. Versioning policy for CA-OBJ-* shapes and CA-CONTRACT-* seams. A later contract release must never silently change the meaning of previously recorded events.
Version identifiers
- Object shapes version independently:
CA-OBJ-008 v1,v2… - Seam contracts version independently:
CA-CONTRACT-SEL-001 v1… - Records cite the exact version they were created under.
Change classes
| Class | Definition | Example |
|---|---|---|
| Backward-compatible | new optional fields; new enum values appended; relaxed constraints | adding reminder_policy to a campaign |
| Breaking | removed/renamed fields; narrowed constraints; changed semantics of an existing field | changing result shape for a decision method |
Breaking changes produce a new major version of the object/contract. Old versions remain defined — historical records keep interpreting under their original version.
Adapter compatibility at seams
- Version negotiation: engine/adapter declares the contract versions it executes; mismatch is a hard failure (fail-closed, F-06 class), never silent degradation.
- An adapter supporting
SEL-001 v1andv2may serve both; the run record stores which it used. - Adapters translate versions — they must not reinterpret semantics; a v1 record processed by a v2 adapter is recorded as a v1 interpretation.
Historical-record interpretation
- Immutable semantics: recorded events mean what they meant at record-version. Schema evolution cannot rewrite history.
- Migration expectation: migrations may transform storage but must preserve the recorded interpretation — migrations are events, auditable like everything else.
- Where a migration materially changes representation, the migration itself is versioned and digest-linked so reconstruction remains possible.
Deprecation
- Deprecated versions remain readable; new records stop accepting them after a declared deprecation window (recorded as an authority event).
supersededversions stay defined forever — the model’s own history is part of the archive.
Sources
architecture/AUDIT-PROVENANCE.md,architecture/EXTERNAL-INTEGRATIONS.md.