Skip to content

Commit 2bcb6e7

Browse files
authored
docs(encryption): Stage 6E design proposal — enable-raft-envelope admin RPC + Phase-2 cutover (#893)
## Summary Stage 6E design proposal — lands `enable-raft-envelope` admin RPC + the §7.1 Phase-2 raft cutover end-to-end. Unblocked by Stage 8a (#886), which shipped the v2 snapshot reader that 6E depends on for mid-Phase-2 follower catch-up. ### Why now Every prerequisite has shipped: - 6D — Phase-1 storage envelope cutover - 7 — Writer registry + deterministic nonce - 8a — Snapshot header v2 cutover carriage 6E is the missing piece between sidecar-recorded cutover and on-the-wire wrap/unwrap. ### Sliced into 3 implementation milestones | Milestone | Scope | Why this slice | |---|---|---| | **6E-1** | Admin RPC + sidecar plumbing (no behavior change) | Records cutover index but no wrap/unwrap yet — safe to ship alone | | **6E-2** | Engine unwrap + coord wrap + quiescence barrier | The three pieces are interlocked at the cluster-halt boundary; cannot split | | **6E-3** | 6C-4 fail-closed guards (divergence, not-bootstrapped, epoch-out-of-range) | Dead code without an active Phase 2; bundles after 6E-2 | ### Load-bearing details documented - **Why the barrier's source-tag exemption is required** — a global `Propose` mutex would deadlock on the cutover's own proposal. - **Why dispatch is strict-greater-than `index > cutover`** — the cutover entry at `index == cutover` MUST NOT be unwrapped (chicken/egg with the sidecar update). - **Why `decodeProposalEnvelope` MUST run before unwrap** — wrapping `entry.Data` itself would clobber the proposal-ID handoff to `resolveProposal`; every coordinator write would time out forever. - **Why 6E-2's three pieces cannot ship separately** — either ordering produces cluster-wide halt-apply at cutover. ### Verification action items 8 + 8 + 3 tests across the three milestones, with explicit 5-lens self-review focus per milestone (data loss for 6E-2's barrier window, data consistency for 6E-3's startup divergence refusal). ## Test plan - [ ] Design doc reviewable on its own (no implementation in this PR). - [ ] @claude review for the milestone breakdown, the quiescence-barrier sequencing, and the strict-`>` index dispatch rule. - [ ] Implementation lands in three follow-on PRs (6E-1 → 6E-2 → 6E-3) per CLAUDE.md design-doc-first workflow.
2 parents 3f21f73 + dd0beb2 commit 2bcb6e7

1 file changed

Lines changed: 436 additions & 0 deletions

File tree

0 commit comments

Comments
 (0)