hardbyte / hardbyte/awa

Contract ring-cursor compatibility state in 0.8

Open
#430 0 comments 0 reactions 0 assignees View on GitHub
correctness operational
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.