Skip to content

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

Open
bootjp wants to merge 3 commits into
mainfrom
docs/composed1-partial-rename
Open

docs(design): rename Composed-1 docs *_proposed_* → *_partial_* (M5a shipped)#927
bootjp wants to merge 3 commits into
mainfrom
docs/composed1-partial-rename

Conversation

@bootjp
Copy link
Copy Markdown
Owner

@bootjp bootjp commented Jun 4, 2026

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):

M5 doc:

親子相互参照リンクの更新

M5 doc の "Parent design" リンクをリネーム後のファイル名に変更。

Body content

CLAUDE.md の lifecycle 規約通り、design 本体は as-shipped record として温存。Status block のみ進化させる。

Test plan

  • git mv で履歴を保持
  • 内部リンクは 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.

… shipped)

Per CLAUDE.md design-doc lifecycle (rename after the first
milestone ships): both Composed-1 design docs move from
*_proposed_* to *_partial_* now that M5a has fully landed on main.

Parent doc:
  2026_05_29_proposed_composed1_cross_group_commit_guard.md
    -> 2026_05_29_partial_composed1_cross_group_commit_guard.md

  Status header updated to record:
    - M1-M4 shipped via PR #900
    - M5a shipped via PRs #911 / #916 / #924 / #925
    - M5b (route-shuffle nemesis) still open

M5 doc:
  2026_06_02_proposed_composed1_m5_jepsen_route_shuffle.md
    -> 2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md

  Status header enumerates the M5a delivery PRs, the cross-PR
  PR #926 fix discovered during E2E, and a separate
  ResourceNotFoundException follow-up issue still under
  investigation.

Parent-doc cross-reference link updated to point at the renamed
partner so internal navigation stays correct after the rename.

Doc-only change.  All other content preserved verbatim per the
lifecycle convention (only the status block evolves; the design
body is the as-shipped record from each milestone).
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Jun 4, 2026

Review Change Stack

Warning

Review limit reached

@bootjp, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 52 minutes and 24 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a0c065fb-39a1-41a8-ae16-dc94dd1b4574

📥 Commits

Reviewing files that changed from the base of the PR and between b527dd5 and 39769a9.

📒 Files selected for processing (1)
  • tla/composed/Composed.tla
📝 Walkthrough

Walkthrough

This PR updates design document references throughout the codebase from "proposed" to "partial" status, reflecting maturity progression of two independent feature initiatives: M5 Jepsen route-shuffle testing and Composed-1 cross-group commit guard. The design documents themselves are updated with status metadata and completion checklists.

Changes

M5 Jepsen Route-Shuffle Design and References

Layer / File(s) Summary
M5 Jepsen design document status update
docs/design/2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md
Design doc front-matter revised from "Proposed" to "Partial", M5a PR checklist added (CLI helpers, multi-table workload variant, route listing/setup hook, local jepsen runner, --host 127.0.0.1 fix), M5b marked still open with tracked ResourceNotFoundException follow-up issue, parent design reference updated to partial variant.
Code and script references to M5 Jepsen design doc
cmd/elastickv-list-routes/main.go, cmd/elastickv-route-key/main.go, cmd/elastickv-split/main.go, jepsen/src/elastickv/dynamodb_multi_table_workload.clj, scripts/run-jepsen-m5-local.sh
Comment references updated from proposed_composed1_m5_jepsen_route_shuffle.md to partial_composed1_m5_jepsen_route_shuffle.md across command utilities, jepsen workload definition, and execution script.

Cross-Group Commit Guard Design and References

Layer / File(s) Summary
Cross-group commit guard design document status update
docs/design/2026_05_29_partial_composed1_cross_group_commit_guard.md
Design doc metadata updated to mark status as "Partial" and document the proposed-to-partial rename on 2026-06-04.
Code references to cross-group commit guard design doc
distribution/engine.go, kv/coordinator.go, kv/coordinator_txn_test.go, kv/fsm.go, kv/route_history.go, kv/sharded_coordinator.go, kv/transcoder.go, main.go, proto/internal.proto
Comment references updated from proposed_composed1_cross_group_commit_guard.md to partial_composed1_cross_group_commit_guard.md in coordinator, fsm, route history, transcoder, and protocol buffer files.

Estimated Code Review Effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly Related PRs

  • bootjp/elastickv#905: Introduces the initial 2026_06_02_proposed_* design docs that this PR renames and updates to partial status.

Poem

🐇 Design docs evolve, from proposed dreams to partial realities,
M5a ships, M5b tracks its mysteries,
Comments hop through the codebase, leaving breadcrumb trails,
Each reference rewritten, each path now partial and bright! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely summarizes the main change: renaming design documentation files from 'proposed' to 'partial' now that M5a milestone has shipped.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/composed1-partial-rename

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates two design documents to transition their status from 'Proposed' to 'Partial', documenting the milestones shipped and updating the file references accordingly. The feedback suggests a Markdown formatting improvement to avoid starting a line with a '#' character (e.g., '#911'), which could be misparsed as a header by some Markdown parsers.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

Comment on lines +3 to +7
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.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Markdownにおいて、行頭が # で始まる文字列(例: #911)は、一部のパーサーによって見出し(Header)として誤って解釈されたり、表示が崩れたりする可能性があります。行頭に # が来ないように改行位置を調整するか、段落を1行にまとめることを推奨します。

Suggested change
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.
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.

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d667b526ea

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

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)
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Update stale references after renaming design docs

Because this commit removes the old *_proposed_* filenames, the remaining repo references now point at missing files; I checked with rg "2026_05_29_proposed_composed1|2026_06_02_proposed_composed1" and found stale paths in implementation comments and scripts such as cmd/elastickv-route-key/main.go, kv/fsm.go, jepsen/src/elastickv/dynamodb_multi_table_workload.clj, and scripts/run-jepsen-m5-local.sh. Anyone following those design-doc pointers from the code will land on nonexistent files unless the references are updated along with this link.

Useful? React with 👍 / 👎.

…ten Status (codex P2 + gemini medium on PR #927)

codex P2 — 16 ファイルに古い *_proposed_* パス参照が残存。 全部
*_partial_* に更新 (cmd/, distribution/, jepsen/, kv/, main.go,
proto/, scripts/).  generated proto/internal.pb.go は source
proto/internal.proto の同期更新と一致するため sed で同時置換
(regen 不要)。

gemini medium — markdown 行頭の '#911' が見出しとして誤解釈
される懸念。 親 doc の Status section を 1 行にまとめて回避。

go build ./... -> exit 0
@bootjp
Copy link
Copy Markdown
Owner Author

bootjp commented Jun 4, 2026

Pushed as b527dd5 — codex P2 + gemini medium on d667b52 addressed.

codex P2 — リネーム後の stale references 16 ファイル一括修正:
cmd/elastickv-list-routes, cmd/elastickv-route-key, cmd/elastickv-split, distribution/engine.go, jepsen/src/elastickv/dynamodb_multi_table_workload.clj, kv/coordinator.go, kv/coordinator_txn_test.go, kv/fsm.go, kv/route_history.go, kv/sharded_coordinator.go, kv/transcoder.go, main.go, proto/internal.proto (+ generated .pb.go を sed で同期), scripts/run-jepsen-m5-local.sh

rg "2026_(05_29|06_02)_proposed_composed1" で残存 0 確認。

gemini medium — markdown 行頭 #911 の見出し誤解釈リスク。 親 doc の Status section を 1 行にまとめて回避。

go build ./... → exit 0

@claude review

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jun 4, 2026

TLA+ spec divergence review (auto-triggered)

This PR touches files that the TLA+ safety spec has an anchor on (per
docs/design/2026_05_28_partial_tla_safety_spec.md §3),
so an AI review is requested below to verify the implementation has not drifted
from the model.

Anchored files changed in this PR head (b527dd5):

  • distribution/engine.go
  • kv/coordinator.go
  • kv/fsm.go
  • kv/sharded_coordinator.go

What to check, by subsystem:

  • kv/hlc*.goNext() must respect the HLC-4 preconditions (i)/(ii)/(iii) from the design doc: bounded skew, logical-counter handoff on leader change (strategy (c) Observe(MaxAppliedHLC)), and the commit-time ceiling fence (fail-closed when wall_now >= physicalCeiling). Any change to the bit layout (48/16), the CAS loop, or the ceiling getter/setter is in scope.
  • kv/coordinator.go, kv/sharded_coordinator.goRunHLCLeaseRenewal, hlcRenewalInterval, hlcPhysicalWindowMs constants, and the new-term detection that calls Observe(fsm.MaxAppliedHLC()) (strategy (c)). Any change to renewal cadence, group selection, or fail-closed behaviour is in scope.
  • kv/transaction.go, kv/lock_resolver.go — OCC commit-ts assignment, lock-map encoding (key, lock_ts) -> start_ts, and the LockResolver action OCC-3 depends on. (M2 spec will land OCC-1..OCC-5; until then the spec doc §5.2 is the contract.)
  • kv/fsm.go — FSM apply of HLC lease entries (SetPhysicalCeiling), and any future MaxAppliedHLC() accessor that strategy (c) needs.
  • store/mvcc_store.go — version visibility, snapshot install, and the MVCC-1..MVCC-4 invariants (M3 scope).
  • distribution/** — route catalog versioning, SplitRange atomicity, and CatalogWatcher async fan-out (M4 scope).

If the change is correct but requires a spec update, edit tla/hlc/HLC.tla (or the corresponding M2..M5 module once landed) and the design doc in the same PR. The tla-check workflow runs the TLC model check on the same paths.


@claude review please verify TLA+ spec divergence per the checklist above.

@codex review please verify TLA+ spec divergence per the checklist above.

@chatgpt-codex-connector
Copy link
Copy Markdown

To use Codex here, create a Codex account and connect to github.

@claude
Copy link
Copy Markdown

claude Bot commented Jun 4, 2026

Claude finished @bootjp's task in 1m 49s —— View job


Review — docs/composed1-partial-rename (b527dd5)

  • Gather context — reading diff and changed files
  • Review design doc renames and status updates
  • Review stale-reference fixes across Go/Clojure/proto/script files
  • Verify markdown formatting fix (gemini feedback)
  • Post findings

Summary

The rename + stale-reference sweep is solid. One file was missed in the rg scan.


Finding: one remaining stale reference — tla/composed/Composed.tla

tla/composed/Composed.tla:93 still holds the old _proposed_ filename:

\* 2026_05_29_proposed_composed1_cross_group_commit_guard.md

The trigger comment says rg "2026_(05_29|06_02)_proposed_composed1" returned 0, but that pattern appears to have missed .tla files (ripgrep respects .gitignore; check if tla/ is excluded, or the glob was accidentally scoped).

Fix this →


Everything else looks good

Renamed docs — content correct:

  • 2026_05_29_partial_composed1_cross_group_commit_guard.md: Status collapsed to one line (gemini fix applied cleanly — no more #911 at line start). Companion-doc link updated to *_partial_*.
  • 2026_06_02_partial_composed1_m5_jepsen_route_shuffle.md: M5a shipped-PR list is complete and accurate. Parent-design link updated. ResourceNotFoundException follow-up is noted as tracked separately, which is appropriate.

Code reference updates (15 files): All mechanical _proposed__partial_ swaps. Each surrounding sentence is unmodified — no accidental context drift.

proto/internal.pb.go: Comment-only sync with internal.proto. Consistent with how the file is managed in this repo (comment edits don't need make gen to regenerate the Go types).

go build ./... → exit 0 as reported in the trigger comment; the reference updates are comment/doc-only so no compilation risk.


…927)

claude[bot] review of b527dd5 flagged tla/composed/Composed.tla:93
as a missed reference.  My earlier rg sweep was scoped to
--include=*.go/*.clj/*.sh/*.md and did not match .tla files.

$ grep -rn '2026_(05_29|06_02)_proposed_composed1' . -> 0 hits
after this fix.
@bootjp
Copy link
Copy Markdown
Owner Author

bootjp commented Jun 4, 2026

Pushed as 39769a9 — claude[bot] が指摘した tla/composed/Composed.tla:93 の missed reference 修正。

以前の rg sweep は --include=*.go/*.clj/*.sh/*.md でスコープしたため .tla を取りこぼし。 fix 後 grep -rn '2026_(05_29|06_02)_proposed_composed1' . → 0 hits 確認。

@claude review

@claude
Copy link
Copy Markdown

claude Bot commented Jun 4, 2026

Claude finished @bootjp's task in 1m 20s —— View job


Review — docs/composed1-partial-rename (39769a9)

  • Check the tla/composed/Composed.tla fix (39769a9)
  • Verify no remaining _proposed_ references in the repo
  • Final pass on overall PR diff
  • Post findings

LGTM — fix is correct, repo is clean

tla/composed/Composed.tla:93 fix (39769a9):

-\* 2026_05_29_proposed_composed1_cross_group_commit_guard.md
+\* 2026_05_29_partial_composed1_cross_group_commit_guard.md

Correct surgical fix. The commit message accurately documents the root cause (the earlier rg sweep was scoped to *.go/*.clj/*.sh/*.md, missing .tla files).

Final scan result:

grep -rn "2026_05_29_proposed_composed1\|2026_06_02_proposed_composed1" .
→ 0 hits (all file types, including .tla)

All 18 changed files across the three commits in this PR are consistent. The other _proposed_ occurrences elsewhere in docs/design/ are for unrelated docs that are legitimately still in proposed state — not in scope for this rename.

This PR is ready to merge.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jun 4, 2026

TLA+ spec divergence review (auto-triggered)

This PR touches files that the TLA+ safety spec has an anchor on (per
docs/design/2026_05_28_partial_tla_safety_spec.md §3),
so an AI review is requested below to verify the implementation has not drifted
from the model.

Anchored files changed in this PR head (39769a9):

  • distribution/engine.go
  • kv/coordinator.go
  • kv/fsm.go
  • kv/sharded_coordinator.go

What to check, by subsystem:

  • kv/hlc*.goNext() must respect the HLC-4 preconditions (i)/(ii)/(iii) from the design doc: bounded skew, logical-counter handoff on leader change (strategy (c) Observe(MaxAppliedHLC)), and the commit-time ceiling fence (fail-closed when wall_now >= physicalCeiling). Any change to the bit layout (48/16), the CAS loop, or the ceiling getter/setter is in scope.
  • kv/coordinator.go, kv/sharded_coordinator.goRunHLCLeaseRenewal, hlcRenewalInterval, hlcPhysicalWindowMs constants, and the new-term detection that calls Observe(fsm.MaxAppliedHLC()) (strategy (c)). Any change to renewal cadence, group selection, or fail-closed behaviour is in scope.
  • kv/transaction.go, kv/lock_resolver.go — OCC commit-ts assignment, lock-map encoding (key, lock_ts) -> start_ts, and the LockResolver action OCC-3 depends on. (M2 spec will land OCC-1..OCC-5; until then the spec doc §5.2 is the contract.)
  • kv/fsm.go — FSM apply of HLC lease entries (SetPhysicalCeiling), and any future MaxAppliedHLC() accessor that strategy (c) needs.
  • store/mvcc_store.go — version visibility, snapshot install, and the MVCC-1..MVCC-4 invariants (M3 scope).
  • distribution/** — route catalog versioning, SplitRange atomicity, and CatalogWatcher async fan-out (M4 scope).

If the change is correct but requires a spec update, edit tla/hlc/HLC.tla (or the corresponding M2..M5 module once landed) and the design doc in the same PR. The tla-check workflow runs the TLC model check on the same paths.


@claude review please verify TLA+ spec divergence per the checklist above.

@codex review please verify TLA+ spec divergence per the checklist above.

@chatgpt-codex-connector
Copy link
Copy Markdown

To use Codex here, create a Codex account and connect to github.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant