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

description
Task list for Distributed KVS Consistency Modes

Tasks: Distributed KVS Consistency Modes

Input: Design documents from /specs/003-kvs-consistency/
Prerequisites: plan.md (required), spec.md (user stories), research.md, data-model.md, contracts/

Tests: Required per constitution; include unit/integration tests for mode behaviors (strong/eventual), namespace config, convergence/recovery.

Organization: Tasks are grouped by user story to enable independent implementation and testing.

Format: [ID] [P?] [Story] Description

• [P]: Can run in parallel (different files, no dependencies)
• [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
• Include exact file paths in descriptions

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare config and API surfaces for namespace-level consistency modes.

• T001 Create namespace/mode config schema and defaults in rdb-server/src/config/mod.rs
• T002 Update gRPC proto (if needed) to expose namespace/mode config endpoints in rdb-proto/src/raft_server.proto
• T003 Add config loading/validation for namespace modes in rdb-server/src/main.rs

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core plumbing for mode-aware replication and observability hooks.

• T004 Implement mode flag propagation to peers (strong/eventual per namespace) in rdb-server/src/peer.rs
• T005 Add LWW conflict resolution helper for eventual mode in rdb-server/src/peer.rs
• T006 Emit mode/lag/quorum metrics and structured logs in rdb-server/src/raft_service.rs and rdb-server/src/peer.rs

Checkpoint: Mode flags flow through storage/peers; metrics/log hooks in place.

---

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

Goal: Quorum read/write with immediate visibility; reject writes without quorum.

Tests

• T007 [US1] Add strong-mode integration test (quorum write/read, node failure) in rdb-server/tests/test_consistency.rs

Implementation

• T008 [US1] Enforce quorum writes/reads for strong mode in rdb-server/src/peer.rs
• T009 [US1] Return explicit errors on quorum deficit in strong mode in rdb-server/src/raft_service.rs

Checkpoint: Strong mode test passes; quorum enforcement confirmed.

---

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

Goal: Accept writes under partial availability; converge within target window using LWW.

Tests

• T010 [US2] Add eventual-mode integration test (delayed read then convergence) in rdb-server/tests/test_consistency.rs
• T011 [P] [US2] Add partition/recovery test with LWW resolution in rdb-server/tests/test_consistency.rs

Implementation

• T012 [US2] Implement eventual-mode write acceptance with async replication in rdb-server/src/peer.rs
• T013 [US2] Apply LWW conflict resolution on replay/sync in rdb-server/src/peer.rs
• T014 [US2] Track and expose convergence lag metrics in rdb-server/src/peer_manager.rs

Checkpoint: Eventual mode converges within target window; LWW conflicts resolved.

---

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

Goal: Safe mode changes per namespace and clear observability/state reporting.

Tests

• T015 [US3] Add mode-switch test (namespace strong↔eventual, rolling apply) in rdb-server/tests/test_consistency.rs
• T016 [US3] Add mismatch detection test for inconsistent mode configs in rdb-server/tests/test_consistency.rs

Implementation

• T017 [US3] Support mode configuration updates per namespace (reload/rolling) in rdb-server/src/config/mod.rs
• T018 [US3] Expose mode state and mismatches via logs/metrics/optional gRPC in rdb-server/src/raft_service.rs
• T019 [US3] Provide operator-facing quickstart/CLI instructions for mode ops in specs/003-kvs-consistency/quickstart.md

Checkpoint: Mode switches apply safely; operators can detect/report mismatches.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Hardening, docs, and verification scripts.

• T020 Add contract/OpenAPI updates for mode/config endpoints in specs/003-kvs-consistency/contracts/
• T021 Add data model definitions for ClusterConfig/ConsistencyPolicy/ReplicationState in specs/003-kvs-consistency/data-model.md
• T022 Update verification script to cover mode tests in scripts/verify-raft.sh
• T023 Run full workspace checks (cargo fmt, cargo test -p rdb-server --tests) and document results in specs/003-kvs-consistency/quickstart.md

---

Dependencies & Execution Order

• Phase 2 (Foundational) blocks all user stories.
• US1 (strong) and US2 (eventual) can proceed after foundational; US3 (mode ops) depends on config plumbing from Phases 1–2.
• Tests in each story precede implementation tasks.

Parallel Examples

• T010 and T011 can run in parallel after T006 (tests for eventual mode scenarios).
• T012–T014 can run in parallel once T004–T006 are done (separate code paths for eventual replication and metrics).
• T018 and T019 can run in parallel after mode config plumbing (T017).

Implementation Strategy

1. Lay config/API plumbing (Phases 1–2).
2. Deliver strong mode (US1) and eventual mode (US2) with tests.
3. Add mode switching/observability (US3).
4. Polish: contracts, data model docs, verification script, full test sweep.