Appearance
ADR 0004: Versioning strategy
- Status: Accepted
- Date: 2026-11-18
- Spec version: 1.0.0
Context
The owner expects the business rules to keep changing: prices, schedule offsets, contract wording, who sees what, auto-approve behaviour. The spec already demands that a price change must not alter a signed contract. Without a deliberate approach, each change risks rewriting history, breaking stored data, or silently changing behaviour for existing clients.
Decision
Treat "things that change" in eight separate layers, each with its own mechanism (Versioning):
| Layer | Mechanism |
|---|---|
| Product rules | Spec is versioned (SPEC_VERSION), chaptered, with a changelog and numbered open decisions |
| Owner-tunable values | Settings registry in code (type, default, decision link) + append-only, effective-dated setting revisions in D1 |
| Prices and document text | Versioned templates (template_version: draft → published → retired), published rows frozen by triggers |
| Sent or signed documents | Frozen snapshots with a SHA-256 hash; never re-derived from current templates |
| Shape of stored JSON and queue messages | { schemaVersion, data } envelopes with upgrade chains; job envelopes carry v |
| Database schema | Append-only migrations, checked in CI; backward-compatible for one release |
| HTTP API | oRPC router namespaced v1; breaking change adds v2.<name> |
| UI components | beUI vendored with a lockfile of hashes and upstream dates |
History tables (setting, audit_log) and published templates are protected by database triggers, not by convention.
Consequences
- Changing a rule is usually a data change (insert a settings revision, publish a template version), not a deploy.
- Features must read rules through the registry and write snapshots when they send or sign something. A hard-coded constant that the owner might change is a review failure.
- A little more ceremony on each schema or settings change; in exchange, "what applied on 3 March?" is always answerable.
Revisit when
Settings revisions become heavy to query (cache the resolved value), or the owner needs approvals/review on settings changes (add a draft state like templates have).