Commit 2bcb6e7
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.1 file changed
Lines changed: 436 additions & 0 deletions
0 commit comments