Circuit Breaker 1.0.0 Compatibility Policy
Status: Approved 2026-08-28 under ADR-0002 (architecture, operations, product, release).
The policy is decided; its "Required examples for verification" section is unexercised
because no ACC-12 upgrade procedure has run, so RC-04 stays open on evidence, not on the
decision.
Requirements: RC-04
Companion slice: specs/1.0.0/slices/rc-2-compatibility-service-objectives.md
This policy defines which version combinations are allowed, degraded, upgrade-only, or rejected for
the 1.0.0 release-candidate program. A compatibility row is not supported until ACC-12 exercises it
from release artifacts.
Terms
| Term |
Meaning |
| Allowed |
The combination is expected to work normally after release-candidate evidence passes. |
| Degraded |
The combination may run, but a documented feature set is unavailable and operators receive an explicit warning. |
| Upgrade-only |
The combination is allowed only long enough to complete a documented upgrade path. |
| Rejected |
The component must fail explicitly with an actionable error rather than partially operating. |
API and client compatibility
| Client/API combination |
1.0.0 status |
Behavior |
1.0 UI calling bundled /api/v1 server |
Allowed candidate |
Normal product path. |
cb CLI from the same 1.0 artifact calling the same server |
Allowed candidate |
Local administration path. |
| Browser session or API client using removed/deprecated 0.x fields |
Upgrade-only |
Server may preserve temporary compatibility shims only where ACC-12 proves upgrade safety. |
Third-party client depending on undocumented /api/v1 behavior |
Degraded/unsupported |
/api/v1 exists for the product UI and CLI; it is not a stable public API contract in 1.0.0. |
| Client calling a future major API prefix |
Rejected |
Return 404 or a stable machine-readable unsupported-version error when implemented. |
Database and source-release compatibility
| Source state |
1.0.0 status |
Behavior |
| Fresh 1.0 install |
Allowed candidate |
Migrations run to the 1.0 schema from an empty database. |
Upgrade from 0.3.5 |
Allowed candidate |
Direct upgrade path, pending ACC-12 artifact evidence. |
Upgrade from versions older than 0.3.5 |
Upgrade-only until proven |
Requires either a staged upgrade through 0.3.5 or explicit ACC-12 evidence for that source version. |
Existing database with historical tenant rows or tenant_id columns |
Allowed candidate only as single-tenant data |
The 1.0 application preserves tenant-shaped schema/data as inert compatibility metadata. It must not merge, delete, expose, or isolate tenant data silently. Operators needing separate trust domains must run separate deployments. |
| Existing database that depended on tenant isolation for security |
Rejected for 1.0 operation until split or exported |
Stop before relying on the 1.0 binary as a tenant boundary. Export/split the data into separate deployments or remain on a version whose risks are understood. |
| Database schema ahead of the 1.0 binary |
Rejected |
Startup must fail before serving writes and report incompatible schema. |
| Partially applied or interrupted migration |
Rejected until recovered |
Startup/installer must report the failing revision and follow the ACC-13 recovery path. |
| Downgrade after 1.0 migrations |
Rejected |
Restore a verified pre-upgrade backup instead of running an older binary on a newer schema. |
Minimum directly supported source version for 1.0.0 is 0.3.5 unless ACC-12 expands this table.
Server, worker, agent, and CLI compatibility
| Combination |
1.0.0 status |
Behavior |
| 1.0 server + 1.0 workers from the same artifact |
Allowed candidate |
Normal production path. |
| 1.0 server + older workers |
Rejected |
Workers must be upgraded with the server because queue payload/schema compatibility is not stable. |
1.0 server + 1.0 cb CLI from the same artifact |
Allowed candidate |
Normal administration path. |
1.0 server + older cb CLI |
Degraded |
Read-only commands may work; mutating/admin commands must warn or fail if compatibility cannot be proven. |
| 1.0 server + 1.0 agent |
Allowed candidate |
Normal agent path after AGT acceptance evidence passes. |
1.0 server + 0.3.5 agent during upgrade |
Upgrade-only |
Agent may reconnect long enough for orchestrated upgrade if AGT evidence proves safe behavior. |
| 1.0 server + older unproven agent |
Rejected |
Server must reject enrollment or mark the agent incompatible before dispatching work. |
| Older server + 1.0 agent |
Rejected |
Agent must not assume older servers understand 1.0 frames or capabilities. |
Upgrade order
- Export and verify a backup.
- Upgrade the server binary/container and database schema together.
- Upgrade worker services from the same artifact as the server.
- Upgrade the local
cb CLI.
- Upgrade agents after the server reports ready and the fleet page can show version drift.
- Re-run health, backup, restore, agent reconnect, and core journey checks.
Downgrade and rollback
Binary downgrade is not supported after migrations have run. Rollback means restoring the complete
pre-upgrade backup, including database, vault key, uploads, configuration, and any persistent
deployment volumes. ACC-13 and ACC-15 own failed-upgrade recovery behavior.
Deprecation stages
| Stage |
Required behavior |
| Announcement |
Document the deprecated behavior, replacement, owner, and earliest removal version. |
| Warning |
Emit user-visible and/or log-visible warnings where the deprecated path is used. |
| Measurement |
Track use through logs, metrics, audit events, or release evidence where practical. |
| Minimum window |
Keep non-security deprecations for at least one minor release after announcement. |
| Removal |
Remove only after migration documentation and tests prove the replacement path. |
| Emergency security exception |
Security owner may approve immediate removal when continued support creates unacceptable risk; release notes must name the break. |
Required examples for verification
| Example |
Expected result |
| Fresh 1.0 artifact install on a supported Linux row |
Allowed; server reaches ready and core journeys pass. |
Upgrade 0.3.5 database to 1.0 artifact |
Allowed; migrations complete and data reconciles. |
| Start 0.3.x binary against a 1.0 schema |
Rejected; no writes served. |
| Connect unproven older agent to 1.0 server |
Rejected or marked incompatible; no work dispatched. |
| Use older CLI for a mutating admin command |
Degraded or rejected with an actionable upgrade message. |