T2-06a：Android core module CRDT 合併引擎 + HLC PoC¶

背景¶

Phase 2a 進入實作階段。業主選定先推進 T2-06 Android Room CRDT PoC。本票為 T2-06 第一段（T2-06a）：建立 core module 的純合併引擎，不含 Room 持久化與網路同步（留待 T2-06b）。

依據規格與介面契約：

• docs/specs/software-stack.md（Kotlin / MVVM / Room / State-based CRDT，皆 已確認；HLC 待驗證 → 抽象層隔離）
• docs/interfaces/hlc-clock.md / crdt-triage-record.md / crdt-merge-strategy.md

變更內容¶

1. Android 專案骨架（android/）¶

• Gradle multi-module 骨架（root + :core，pure Kotlin JVM）
• gradle/libs.versions.toml（Kotlin 1.9.23 / JUnit5 5.10.2）、settings、gradlew
• 未含 gradle-wrapper.jar（二進位需 gradle 環境生成）

2. core module 合併引擎¶

• HLC：HLC(l, c, dev) + tick / recv / compare，嚴格照 hlc-clock.md；含 ERR_HLC_REGRESS 偵測
• TriageRecord schema：Severity / BodyZone enum、FieldState、LogEntry、NoteEntry、TriageDelta
• MergeStrategy 抽象層 + 7 內建策略：MaxCRDT_Severity、MaxCRDT_Severity_ConfirmRequired（Class II fallback）、LWW_HLC、LWW_PerKey、Immutable、AppendOnly_GSet_Cap、Asymmetric_Notes（最小骨架）+ MergeStrategyRegistry
• TriageRecordMerger：per-column 逐欄位查 Registry 套策略，遵守不變式

3. 介面契約裁決落地（system-architect，v0.1.1）¶

實作中發現 2 個契約疑慮，經 system-architect 裁決：

• 疑慮 1（採納）：created_at / created_by 不參與「是否同實體」判斷，只看 (patient_id, task_id) 主鍵。理由：離線分散式下兩節點不可能對同一建立事件產生位元相同的 HLC，用完整 HLC equals 比對會把正常 HLC 差異誤判成 immutable 違規。created_by 差異改走 first-writer-wins + INFO hook，不報錯。
• 疑慮 2（無矛盾）：log_entries（e-Tag 50 筆 G-Set cap）與 notes（e-Tag 10 筆 ring / 100 筆 pending_sync，非 CRDT）為不同欄位不同機制，三份文件一致，原實作正確。
• 更新檔：crdt-triage-record.md、crdt-merge-strategy.md → v0.1.1（新增「同實體判斷規則」專節 + 不變式第 6 條）

4. 對應 merger 修正¶

• ImmutableFieldChanged 只剩 patient_id / task_id 兩觸發點
• created_by 分歧 → onCreatedByDivergence INFO hook（預設 no-op，T2-06b 接 Room audit）

驗收標準¶

• 53 個 JUnit 單元測試在 JDK 17+ 環境 ./gradlew :core:test 全數通過（ 本機/CI 目前無 JDK，尚未實跑，由後續任務追蹤）
• merger ImmutableFieldChanged 僅對 patient_id / task_id 觸發（已核對程式碼）
• HLC tick/recv/compare 實作對齊 hlc-clock.md 契約
• 7 內建策略 + Registry 含 Class II fallback 切換點
• 介面檔 v0.1.1 裁決落地

測試覆蓋（53 案）¶

• HLC：連續 tick 嚴格遞增、recv 四規則、因果序保留、dev tiebreak、ERR_HLC_REGRESS
• Max-CRDT severity：單調升級、不可降
• LWW / per-key LWW：HLC tiebreak、並行 BodyZone 不互蓋
• Immutable：patient_id/task_id 拒絕；created_at/created_by 同實體不報錯（裁決後反轉/新增 6 案）
• AppendOnly cap：e-Tag 50 筆 overflow 警告不丟棄、Tier 0 無上限
• CRDT 三性質：交換律 / 結合律 / 冪等律

已知限制與後續¶

• 未含 gradle-wrapper.jar → 需 gradle 環境補生成
• 53 測試未實跑（無 JDK）→ 待 CI 或本機裝 JDK 17+ 驗證
• T2-06b（下一段）：Room entity/DAO、hlc_state 持久化表、Kotlin Flow、Repository、Asymmetric_Notes 完整 replay、PendingMergeQueue