docs(design): rename Composed-1 docs *_proposed_* → *_partial_* (M5a shipped) (#927)

bootjp · web-flow · commit c4924d9c0823 · 2026-06-05T17:17:05.000+09:00
CLAUDE.md の design-doc lifecycle 規約に従い、Composed-1 関連の 2 つの design doc を `*_proposed_*` → `*_partial_*` にリネーム。M5a が main にランドしたタイミング。 ## Renames ``` 2026_05_29_proposed_composed1_cross_group_commit_guard.md → 2026_05_29_partial_composed1_cross_group_commit_guard.md 2026_06_02_proposed_composed1_m5_jepsen_route_shuffle.md → 2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md ``` ## Status header の更新 **親 doc (cross-group commit guard):** - M1–M4 shipped via PR #900 - M5a shipped via PRs #911 / #916 / #924 / #925 - M5b (route-shuffle nemesis) still open **M5 doc:** - M5a 全 PR 列挙 + 子細 - PR #926 (cross-PR `--host` fix) を E2E 中に発見 - Workers の `ResourceNotFoundException` follow-up issue を tracked separately として記載 ## 親子相互参照リンクの更新 M5 doc の "Parent design" リンクをリネーム後のファイル名に変更。 ## Body content CLAUDE.md の lifecycle 規約通り、design 本体は as-shipped record として温存。Status block のみ進化させる。 ## Test plan - [x] `git mv` で履歴を保持 - [x] 内部リンクは renamed partner を指す  ## Summary by CodeRabbit * **Documentation** * Updated internal design document references across the codebase to reflect current milestone status. No functional changes or user-facing features affected.
diff --git a/cmd/elastickv-list-routes/main.go b/cmd/elastickv-list-routes/main.go
@@ -4,7 +4,7 @@
 // table-route keys on the expected Raft groups before any workload
 // op runs.
 //
-// Per the design doc (docs/design/2026_06_02_proposed_composed1_m5_jepsen_route_shuffle.md
+// Per the design doc (docs/design/2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md
 // §3.3), the Jepsen client's setup! shells out to this tool rather
 // than re-implementing the gRPC client in Clojure: a JSON contract is
 // stable across versions and a future ListRoutes schema change shows
diff --git a/cmd/elastickv-route-key/main.go b/cmd/elastickv-route-key/main.go
@@ -1,7 +1,7 @@
 // elastickv-route-key prints the byte-string of a DynamoDB
 // table-route key for a given table name.  Used by the Composed-1
 // M5 launch script (`scripts/run-jepsen-local.sh`) and OQ-7
-// (docs/design/2026_06_02_proposed_composed1_m5_jepsen_route_shuffle.md)
+// (docs/design/2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md)
 // to compute `--shardRanges` boundary keys without inlining the
 // base64-encoding logic in shell — the encoding is part of the
 // routing surface and any drift would silently mis-route.
diff --git a/cmd/elastickv-split/main.go b/cmd/elastickv-split/main.go
@@ -1,7 +1,7 @@
 // elastickv-split is a single-shot CLI that invokes the
 // Distribution.SplitRange RPC on a running elastickv cluster.  Per
 // the Composed-1 M5 design doc
-// (docs/design/2026_06_02_proposed_composed1_m5_jepsen_route_shuffle.md
+// (docs/design/2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md
 // §3.1), the Jepsen route-shuffle nemesis shells out to this tool
 // rather than re-implementing the gRPC client in Clojure: keeping
 // the request construction and the SplitRangeRequest field
diff --git a/distribution/engine.go b/distribution/engine.go
@@ -37,7 +37,7 @@ type Engine struct {
 	ts               atomic.Uint64
 	hotspotThreshold uint64
 	// history is the M2 versioned-snapshot ring for Composed-1
-	// (docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md
+	// (docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md
 	// §M2).  Keyed by catalogVersion; populated on every successful
 	// ApplySnapshot and seeded by NewEngineWithDefaultRoute so a
 	// transaction that observed catalogVersion = 0 (the engine's
diff --git a/docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md b/docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md
@@ -1,8 +1,8 @@
 # Composed-1 — cross-group commit-time ownership guard
 
-Status: Proposed
+Status: Partial — M1–M4 shipped via PR #900; M5a shipped via PRs #911 / #916 / #924 / #925; M5b (route-shuffle nemesis) still open.  See companion doc `2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md` for the detailed M5 design and per-milestone state.
 Author: bootjp
-Date: 2026-05-29
+Date: 2026-05-29 (renamed *_proposed_* → *_partial_* on 2026-06-04)
 
 > **Forward-looking proposal.** Today's implementation is vacuously
 > safe with respect to Composed-1 because `SplitRange` is the only
diff --git a/docs/design/2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md b/docs/design/2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md
@@ -1,10 +1,25 @@
 # Composed-1 M5 — Jepsen route-shuffle workload
 
-Status: Proposed
+Status: Partial.  M5a shipped:
+  - PR #911 — `cmd/elastickv-split` + `cmd/elastickv-route-key` CLI helpers
+  - PR #916 — `dynamodb-append-multi-table-workload` (Clojure)
+  - PR #925 — `cmd/elastickv-list-routes` + setup-hook
+    `verify-multi-group-routing!`
+  - PR #924 — `scripts/run-jepsen-m5-local.sh` single-process
+    two-group launcher (with cross-PR integration to #925)
+  - PR #926 (separate) — `--host 127.0.0.1` fix discovered during
+    M5a E2E
+
+M5b (route-shuffle nemesis) is still open.  Plus one known follow-up
+issue from M5a E2E: workers report `ResourceNotFoundException` for
+every txn despite `create-all-tables!` reporting success and ListRoutes
+showing the expected two-group catalog — likely a CreateTable
+race / sync issue under 5-parallel client setup; tracked separately.
+
 Author: bootjp
-Date: 2026-06-02
+Date: 2026-06-02 (renamed *_proposed_* → *_partial_* on 2026-06-04)
 Parent design:
-[`2026_05_29_proposed_composed1_cross_group_commit_guard.md`](2026_05_29_proposed_composed1_cross_group_commit_guard.md)
+[`2026_05_29_partial_composed1_cross_group_commit_guard.md`](2026_05_29_partial_composed1_cross_group_commit_guard.md)
 
 > **Forward-looking proposal, same posture as the parent doc.**
 > Today's `SplitRange` is same-group only (per CLAUDE.md and
diff --git a/jepsen/src/elastickv/dynamodb_multi_table_workload.clj b/jepsen/src/elastickv/dynamodb_multi_table_workload.clj
@@ -2,7 +2,7 @@
   "Composed-1 M5a multi-table variant of the DynamoDB list-append workload.
 
    Why a separate workload exists (see
-   docs/design/2026_06_02_proposed_composed1_m5_jepsen_route_shuffle.md §3.3):
+   docs/design/2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md §3.3):
    the single-table elastickv.dynamodb-workload cannot exercise the 2PC
    path because kv/shard_key.go normalises every DynamoDB table-meta,
    item, and GSI key for one table to a single per-table route key
diff --git a/kv/coordinator.go b/kv/coordinator.go
@@ -1085,7 +1085,7 @@ func elemToMutation(req *Elem[OP]) *pb.Mutation {
 // was captured at — flows into pb.Request.ObservedRouteVersion so the M3
 // Composed-1 FSM apply-time gate can re-validate ownership against the
 // route catalog snapshot at txn-begin (M1 plumbing, see
-// docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md).
+// docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md).
 // Zero is the legacy "unpinned" sentinel.
 func onePhaseTxnRequestWithPrevCommit(startTS, commitTS, prevCommitTS uint64, primaryKey []byte, reqs []*Elem[OP], readKeys [][]byte, observedRouteVersion uint64) *pb.Request {
 	muts := make([]*pb.Mutation, 0, len(reqs)+1)
diff --git a/kv/coordinator_txn_test.go b/kv/coordinator_txn_test.go
@@ -145,7 +145,7 @@ func TestCoordinateDispatchTxn_PassesReadKeysToRaftEntry(t *testing.T) {
 // through the dispatchTxn boundary into pb.Request.ObservedRouteVersion.
 //
 // This is the M1 round-trip witness for the Composed-1 plumbing per
-// docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md
+// docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md
 // §M1: at this milestone the FSM ignores the field, so the only assertion
 // is that the value survives the encoder.  M3 will add the FSM apply-time
 // gate that *uses* this value.
diff --git a/kv/fsm.go b/kv/fsm.go
@@ -72,7 +72,7 @@ type kvFSM struct {
 	// short-circuit as "unpinned" (no Composed-1 enforcement) —
 	// matching the pre-feature behaviour byte-for-byte.  Concrete
 	// production type is *distribution.Engine.  See
-	// docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md
+	// docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md
 	// §4.2 prerequisite block + §M2.
 	routes RouteHistory
 	// shardGroupID is the Raft group ID this FSM serves.  Used by
@@ -222,7 +222,7 @@ func WithCutoverSource(src CutoverSource) FSMOption {
 // historical owner-of-key resolution.  Zero is reserved for the
 // not-wired case.
 //
-// See docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md
+// See docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md
 // §M2 + §4.2 prerequisite block.
 func WithRouteHistory(routes RouteHistory, shardGroupID uint64) FSMOption {
 	return func(f *kvFSM) {
@@ -602,7 +602,7 @@ func (f *kvFSM) handleTxnRequest(ctx context.Context, r *pb.Request, commitTS ui
 }
 
 // verifyComposed1 is the M3 apply-time Composed-1 gate per
-// docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md
+// docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md
 // §4.2(a) + §4.4.  Runs two checks before the txn's writes land:
 //
 //	(a) Observed-version owner — the txn's read-set was captured
diff --git a/kv/route_history.go b/kv/route_history.go
@@ -20,7 +20,7 @@ import (
 // kv.RouteHistory bypass the wrapper entirely and implement the kv
 // interface directly.
 //
-// See docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md
+// See docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md
 // §M2.
 func WrapDistributionEngine(e *distribution.Engine) RouteHistory {
 	if e == nil {
diff --git a/kv/sharded_coordinator.go b/kv/sharded_coordinator.go
@@ -593,7 +593,7 @@ func (c *ShardedCoordinator) Dispatch(ctx context.Context, reqs *OperationGroup[
 
 // dispatchTxnWithComposed1Retry runs the M4 Composed-1 retry loop
 // (design doc
-// docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md
+// docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md
 // §M4).  Pins reqs.ObservedRouteVersion to the engine's current
 // catalog version on the FIRST attempt when the caller left it at the
 // zero sentinel — every txn that flows through ShardedCoordinator
diff --git a/kv/transcoder.go b/kv/transcoder.go
@@ -46,7 +46,7 @@ type OperationGroup[T OP] struct {
 	// "unpinned" — every existing caller leaves it at zero so this
 	// is behaviour-neutral on the M1 plumbing PR.  M3 of the
 	// Composed-1 design
-	// (docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md)
+	// (docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md)
 	// will gate the FSM apply path on this version so a route shift
 	// between BeginTxn and Commit is caught before it can produce a
 	// G1c anomaly across a cross-group MoveRange / SplitRange.
diff --git a/main.go b/main.go
@@ -846,7 +846,7 @@ func buildShardGroups(
 		// verifyComposed1 apply-time gate can resolve the
 		// observed-version owner-of-key without further plumbing
 		// work. At M2 the FSM stores both but does not consult them;
-		// see docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md
+		// see docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md
 		// §M2.
 		sm := kv.NewKvFSMWithHLC(st, clock,
 			kv.WithEncryption(applier),
diff --git a/proto/internal.pb.go b/proto/internal.pb.go
diff --git a/proto/internal.proto b/proto/internal.proto
@@ -48,7 +48,7 @@ message Request {
   // transaction's read set was captured at (set on BeginTxn from
   // distribution.Engine.Version()). Zero means "unpinned" (legacy
   // callers + read-only paths). M3 of the Composed-1 design
-  // (docs/design/2026_05_29_proposed_composed1_cross_group_commit_guard.md)
+  // (docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md)
   // will gate the FSM apply path on it; M1 (this field's introduction)
   // is plumbing only — the FSM ignores the value, so all existing
   // callers see no behaviour change.
diff --git a/scripts/run-jepsen-m5-local.sh b/scripts/run-jepsen-m5-local.sh
@@ -5,7 +5,7 @@
 # Why this script exists separately from run-jepsen-local.sh: the M5
 # workload requires a multi-Raft-group cluster topology that the
 # existing 3-node single-group layout cannot provide.  Per the design
-# doc (docs/design/2026_06_02_proposed_composed1_m5_jepsen_route_shuffle.md
+# doc (docs/design/2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md
 # §3.3), today's `validateShardRanges` / `buildShardGroups` only
 # support a "single process hosts all groups" model — separate
 # processes per group fail validation or race on Raft listeners.
diff --git a/tla/composed/Composed.tla b/tla/composed/Composed.tla
@@ -90,7 +90,7 @@ VARIABLES
                             \* observed-version check and the apply-time
                             \* current-version cross-version-read fence
                             \* (Composed-1a; see docs/design/
-                            \* 2026_05_29_proposed_composed1_cross_group_commit_guard.md
+                            \* 2026_05_29_partial_composed1_cross_group_commit_guard.md
                             \* §4.4 and §5).
     opCount
 
