Contract ring-cursor compatibility state in 0.8
- Dominant language
- Rust
- Stars
- 32
- Forks
- 5
- Avg merge
- 15h 21m
- Merged PRs (30d)
- 21
Description
Follow-up to #371, ADR-040, and the v043 staged upgrade in #425.
v043 retains the pre-ledger cursor columns so 0.6.2 and 0.7 binaries can
operate concurrently before the authority flip. A 0.8 contract migration may
remove those columns only after each database proves that every queue-storage
schema has ledger authority and the released 0.7 artifact has been verified
against the contracted schema.
## Release boundary
The schema contract and runtime cleanup have different compatibility windows.
- The 0.8 binary must remain operable on an unmigrated v043 schema in both
`columns` and `ledger` authority. Keep the compat, reconciliation, flip, and
serializer paths in the 0.8 runtime so binary-first rollout remains valid.
- The contracted 0.8 schema must remain fully operable by released 0.7
binaries. Preserve the schema objects that 0.7 reads directly:
`{schema}.ring_cursor_authority` pinned to `ledger`, a ledger-only
`{schema}.ring_cursor(TEXT)`, and compatible `awa.ring_authority_status()` /
`awa.flip_ring_authority()` signatures.
- Keep `awa.runtime_instances.binary_version` and `awa.semver_rank()`. ADR-041
designates them as the reusable capability-evidence channel.
- Remove the now-unreachable runtime compatibility code and its transition
models in 0.9, when 0.8 is the N-1 baseline.
## N-1 analysis and migration gate
Verify the released 0.7 artifact, not only current source, across cursor
rotation, pruning, ledger folding, claim and producer SQL, maintenance, and
the storage CLI.
Before changing any schema, the migration must assert
`ring_cursor_authority.authority = 'ledger'` for every installed queue-storage
schema and refuse with remediation if any schema remains in `columns`
authority. This per-schema authority assertion is the hard safety condition.
A `MIGRATION_RUNTIME_VERSION_FLOORS` entry for 0.7 may additionally reject
fresh older runtimes during the migration transaction. It is an overridable
rollout check, not capability proof; external migration procedures must apply
the corresponding check and race boundary themselves.
Only if the N-1 analysis cannot produce this rolling-compatible shape should
the migration use `EXCLUSIVE_WINDOW_MIGRATIONS`, with the ADR-041 exception
justification and operator procedure.
## 0.8 contract migration
- Replace `awa.install_queue_storage_substrate` so schemas prepared after the
contract use the ledger-only shape and do not recreate retired columns or
triggers.
- For every existing queue-storage schema, lock and verify ledger authority
before applying the contract.
- Drop `reject_compat_ring_cursor_update_after_flip` triggers and their
per-schema trigger function.
- Drop `current_slot` and `generation` from `queue_ring_state`,
`lease_ring_state`, and `claim_ring_state`.
- Drop `generation` from `queue_ring_slots`, `lease_ring_slots`, and
`claim_ring_slots`.
- Rewrite `{schema}.ring_cursor(TEXT)` as a ledger-only resolver while
preserving its signature for 0.7 callers.
- Keep `ring_cursor_authority` as a ledger tombstone and keep the 0.7-visible
status and idempotent flip interfaces through the 0.8 release.
- Update ADR-040's contract note, which currently presumes an exclusive
window, to match ADR-041's N-1 analysis requirement.
## 0.9 cleanup
Once 0.8 is the N-1 baseline, remove:
- the `RingAuthority::Columns` branches, singleton-first flip serializer,
reconciliation writes, flip/status APIs, CLI command, maintenance auto-flip,
and builder settings;
- the remaining authority tombstones and ring-specific flip SQL;
- the compat, `FlipAuthority`, `MixedFleet`, and singleton-first transition
actions from the TLA+ models; and
- the retired 0.6 artifact scripts and transition-only tests.
## Validation
Before the 0.8 release:
- run 0.8 binaries on an unmigrated v043 schema in both authorities;
- run released 0.7 and current 0.8 workers concurrently before migration;
- verify migration refusal while any schema remains in `columns` authority;
- run released 0.7 workers against the contracted schema under live traffic;
- cover migrate-first and binary-first rollout orderings, including kill and
rescue behavior from the #427 matrix;
- prepare a new queue-storage schema after contraction and prove the retired
columns are absent;
- verify a returning 0.6 binary fails before rotating or pruning; and
- restore the unconditional `receipt_plane_regression_gate` write-free
assertion for contracted schemas while retaining pre-contract coverage for
the 0.8 binary.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with ADR-040, ADR-041, and the v043 staged upgrade in #425, then trace awa.install_queue_storage_substrate and the named ring authority, migration, serializer, CLI, and receipt-plane paths. Validate the #427 rollout matrix with released 0.7 and current 0.8 artifacts before changing schemas. Done means the authority gate and 0.7-compatible contracted shape pass, retired columns and triggers are absent from new schemas, and both rollout orderings are covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- postgresql, rust
- Domain
- backend, databases, distributed-systems, release
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100