ADR 0002: 1.0.0 Compatibility and Service Objectives¶
Status: Accepted for 1.0.0 Date: 2026-08-10 Approved: 2026-08-28 by shawnji, wearing the architecture, operations, product and release hats (owner-map.md escalation steps 3-5). This project has one codeowner, so approval and review are the same person; EXC-002 records that deviation and the automated gates that stand in for the second reviewer. Requirements: RC-04, RC-05, RC-06 Decision owners: Architecture, operations, product, release
Context¶
The release contract requires users and operators to know how upgrades work, which version
combinations are safe, what health states mean, and what recovery/retention/capacity promises apply.
The current code has useful primitives, including /api/v1/health, automatic migrations, backup
settings, and agent presence, but the release promise must be narrower than the implementation until
artifact evidence proves each row.
Decision¶
Circuit Breaker 1.0.0 will use:
docs/release/1.0.0-compatibility-policy.mdfor API, schema, server/worker, CLI, and agent compatibility.docs/release/1.0.0-service-objectives.mdfor health states, candidate SLOs, RPO/RTO, retention, and scale ceilings.
The direct upgrade floor is 0.3.5 unless ACC-12 proves older source versions. Downgrade after
migration is unsupported; rollback means restoring a complete pre-upgrade backup. Workers must match
the server artifact. Older agents and CLI versions are allowed only where explicit upgrade evidence
proves safe behavior.
Health states are defined by safe user operations, not endpoint color. SRV-03 must separate liveness, startup, readiness, dependency health, and degraded service in runtime behavior.
Rejected alternatives¶
| Alternative | Reason rejected |
|---|---|
| Promise upgrades from every historical beta release immediately | The audit requires artifact-based upgrade evidence, and older migration paths have known defects. |
| Support binary downgrade after migrations | Schema migrations may be irreversible; restore is safer and testable. |
Treat /api/v1 as a stable third-party API |
The endpoint namespace exists for product UI/CLI today, but compatibility windows and contract tests are not complete. |
| Let workers, server, and CLI drift independently | Queue payloads, admin commands, and schema assumptions are not independently versioned for 1.0.0. |
| Define readiness as a health endpoint response | Users need to know which operations are safe under dependency failures; endpoint status is only an observation mechanism. |
| Set fleet-scale or HA objectives before load evidence | RC-1 keeps 1.0 single-node; REL-26 must prove fleet ceilings before support expands. |
Consequences¶
- Upgrade docs must point to the compatibility policy and state the direct source-version floor.
- Backup/restore docs must state candidate RPO/RTO and retain “backup before upgrade/destructive action” guidance.
- Metrics docs must not imply stable public metrics schema for 1.0.0.
- Runtime work remains for SRV-03 to split health endpoints and enforce safe not-ready/degraded behavior.
- ACC and REL evidence may narrow or expand candidate values before RC sign-off.
Migration impact¶
Existing beta users older than 0.3.5 need either a staged upgrade path or explicit ACC-12 evidence.
Users requiring downgrade must retain full pre-upgrade backups and restore them instead of starting
older binaries against a migrated database.