photoncloud-monorepo/flaredb/specs/003-kvs-consistency/spec.md

Feature Specification: Distributed KVS Consistency Modes

Feature Branch: 003-kvs-consistency
Created: 2025-12-01
Status: Draft
Input: User description: "とりあえず分散KVSの部分を使えるようにし、強整合性モードと結果整合性モードを実用可能な状態に持っていくまでの仕様を考えてください。"

User Scenarios & Testing (mandatory)

User Story 1 - 強整合性クラスタを安全に稼働 (Priority: P1)

SRE/オペレータは、固定メンバー（例: 3ノード）のKVSクラスタを強整合性モードで起動し、書き込み・読み出しが常に最新状態で返ることを保証したい。

Why this priority: 強整合性がS3メタデータやSNSイベントの正確さの土台になるため。

Independent Test: 少なくとも3ノード構成で、リーダー経由のPut/Getが直ちに反映し、ダウン直後もコミット済みデータが失われないことを検証。

Acceptance Scenarios:

1. Given 3ノードが強整合性モードで起動済み、When リーダーにキーを書き込み、Then 即座に全ノードで最新値が読み出せる（リーダーからの再取得）。
2. Given 1ノードを停止、When 残り2ノードで読み書き、Then コミットは継続しデータ欠損がない（クォーラム成立時のみコミット）。

---

User Story 2 - 結果整合性モードで高スループット運用 (Priority: P1)

オペレータは、イベント処理や一時的なスパイク負荷向けに結果整合性モードを選択し、高スループットな書き込みを許容しつつ、一定時間内に最終的に同期させたい。

Why this priority: 書き込み偏重ワークロードでの性能確保とコスト最適化のため。

Independent Test: 結果整合性モードで大量Put後、一定のタイムウィンドウ内に全ノードへ反映し、古い値が一定時間内に整合することを確認。

Acceptance Scenarios:

1. Given 結果整合性モードでキーを書き込み、When 1秒以内に別ノードから読み出し、Then 必ずしも最新とは限らないが一定時間後（例: 数秒以内）に最新値へ収束する。
2. Given ネットワーク分断後に復旧、When 再同期処理が走る、Then コンフリクトは定義済みポリシー（例: last-write-wins）で解決される。

---

User Story 3 - モード切替と運用観測 (Priority: P2)

オペレータは、環境やワークロードに応じて強整合性/結果整合性モードを設定単位で切り替え、状態監視と異常検知ができることを望む。

Why this priority: 運用現場での柔軟性と安全性の両立が必要なため。

Independent Test: モード設定変更後の再起動またはローリング適用で、設定が反映され、メトリクス/ログで確認できる。

Acceptance Scenarios:

1. Given クラスタ設定を強整合性→結果整合性に変更、When ローリングで適用、Then 全ノードが新モードで稼働し、メトリクスにモードが反映される。
2. Given モード不一致のノードが存在、When オペレータが状況を確認、Then 管理UI/CLI/ログで不一致を検知でき、是正手順が明示される。

Edge Cases

• メンバー数がクォーラムを下回った状態での書き込み要求（強整合性では拒否、結果整合性ではキューイング/部分反映）。
• ネットワーク分断後の再結合時、双方が進んだログを持つ場合の解決順序。
• モード切替途中に障害が発生した場合のリカバリ手順と一貫性確保。
• データサイズやホットキー偏重時のスロットリング/バックプレッシャー挙動。

Requirements (mandatory)

Functional Requirements

• FR-001: システムは強整合性モードでクォーラム書き込み/読み出しを行い、コミット済みデータを即時参照可能にする。
• FR-002: システムは結果整合性モードで書き込みを受け付け、定義された収束時間内に全ノードへ反映させる。
• FR-003: モード設定は名前空間単位で指定でき、クラスタは複数モードを同居させられる。
• FR-004: 結果整合性モードのコンフリクト解決はデフォルトで last-write-wins（LWW）を採用し、設定で他方式を選択できる。
• FR-005: モード変更は安全な手順（ローリング適用または再起動）で反映され、途中失敗時はロールバック手段がある。
• FR-006: 強整合性モードではクォーラム未達時に書き込みを拒否し、明示的なエラーを返す。
• FR-007: 結果整合性モードではクォーラム未達時も書き込みを受け付け、後続の同期で補填し、未反映の可能性をクライアントに示せる。
• FR-008: 再起動/障害復旧後、保存されたログ/スナップショットから整合した状態へ自動復元し、必要な再同期を実行する。
• FR-009: モード別の観測指標（レイテンシ、未同期レプリカ数、収束時間、拒否率）をメトリクス/ログとして出力する。
• FR-010: 運用者がモード状態や不一致を確認できるCLI/ログ/メトリクス情報を提供する。

Key Entities

• ClusterConfig: クラスタID、ノード一覧、レプリカ数、現在の整合性モード、適用ステータス。
• ConsistencyPolicy: モード種別（強整合/結果整合）、コンフリクト解決ポリシー、収束目標時間、適用範囲（クラスタ/名前空間）。
• ReplicationState: ノードごとのログ進行度、未同期エントリ数、最後の収束時刻、ヘルス状態。

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 強整合性モードでの書き込み→読み出しがクォーラム成立時に最新値を即時返し、可用ノードがクォーラム未満なら明示的に失敗を返すことが確認できる。
• SC-002: 結果整合性モードでの書き込みは、許容する収束時間内（例: 数秒以内）に全レプリカへ反映し、反映遅延をメトリクスで観測できる。
• SC-003: ネットワーク分断からの復旧時、コンフリクト解決ポリシーに従ってデータが一貫した状態に自動で収束することをテストで確認できる。
• SC-004: モード変更操作が安全に完了し、変更後のモードと各ノードの適用状況をメトリクス/ログで確認できる。