Commit 2a36826
authored
docs(design): Composed-1 M5 — Jepsen route-shuffle workload proposal (#905)
## Summary
- Design doc for **Composed-1 M5** — Jepsen route-shuffle workload, the
integration-level proof from the parent doc's milestone table.
- **Doc only** — no implementation in this PR. Per CLAUDE.md
design-doc-first workflow.
- M5 itself is two phases: M5a (CLI + workload setup, mergeable on its
own), M5b (route-shuffle nemesis + cadence tuning).
## Companion to
- Parent:
[`docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md`](../blob/main/docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md)
- M1+M2+M3+M4 implementation: #900 (currently awaiting human merge after
9 codex review rounds)
## Forward-looking posture (matches parent)
Today's `SplitRange` is same-group only (per CLAUDE.md and
`adapter/distribution_server.go`), so the Composed-1 hazard the M3/M4
guard catches cannot yet be *triggered* in production. M5 ships the
scaffolding so:
1. The current `SplitRange` is exercised under realistic concurrent
multi-shard write load and proved non-regressing — workload finds zero
G1c, which is the baseline M4 contract.
2. When a future PR introduces a route-mutating RPC that DOES shift
ownership across groups (cross-group `SplitRange`, `MoveRange`, online
rebalancer), the M5 workload — with a one-line nemesis swap — becomes
the integration-level proof that M3+M4 hold under cross-group churn.
## Open questions for review
The doc tracks four open questions in §5. The two that benefit most from
reviewer input:
- **OQ-2** — Ship M5a + M5b in a single PR or two? (Two if M5a's CLI
work runs ≥150 lines; one if M5a fits in a single screen.)
- **OQ-4** — Lifecycle of the parent doc post-#900 merge: rename
`*_proposed_*.md` → `*_partial_*.md` (since only M5 remains)? Tentative
yes.
## Test plan
- [x] `gofmt` / lint clean (doc-only, no Go changes)
- [ ] Reviewer: confirm M5a + M5b phasing matches existing repo
conventions
- [ ] Reviewer: confirm `cmd/elastickv-split` as a standalone binary is
preferable to a `cmd/elastickv-admin` subcommand (the doc tentatively
chooses standalone; see §3.1 "Alternative considered")
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added design doc for the Composed-1 M5 milestone introducing a
DynamoDB route-shuffle testing workload.
* Describes multi-shard/multi-group transaction coverage, setup
verification, pass/fail validation criteria (including rejection of
specific anomalies), default shuffle cadence, milestone breakdown, and
remaining open questions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->1 file changed
Lines changed: 476 additions & 0 deletions
0 commit comments