awoooi/docs/adr/ADR-124-global-singleton-decomposition.md

ADR-124: Global Singleton Decomposition for Multi-tenancy

狀態：Accepted 日期：2026-05-03（台北） 決策者：統帥 範圍：13 個 global singleton 的分類、分解策略、Tier 3 安全邊界 關聯：ADR-111（bootstrap order）、ADR-118（RLS）、INV-9

---

背景

INV-9 確認 codebase 中有 13 個 global singleton，全部是模組層級變數（_engine: Optional[X] = None）。這些 singleton 在多租戶環境下有兩個核心問題：

1. Tenant 共用狀態：AnomalyCounter 等組件將所有 tenant 的數據混合在同一個實例中
2. Bootstrap 時機不明確：singleton 在首次呼叫時才初始化，可能在 project_id 未知的情況下被觸發

Tier 3 限制（RED_ZONES.md）：

• DecisionManager（decision_manager.py:1402）— 禁止未經架構審查的修改
• TrustEngine（trust_engine.py:189）— 核心信任計算，修改需要 P10 授權

---

決策

D1 — 四種分解策略

策略 1：Platform Singleton（保留，不分解）

這些 singleton 本就應該是平台層，無需 per-tenant 實例：

Singleton	檔案	原因
TelegramGateway（polling lock）	telegram_gateway.py:1324	Polling leader 是平台層，非 per-tenant
HostRepairAgent	host_repair_agent.py	修復 host 是平台操作，非 per-tenant
AIProviderRegistry	registry.py	Provider 清單是平台層（但需要 __provider 修補，PR-04）
FailoverAlerter	failover_alerter.py	告警路由是平台層

策略 2：Tenant-Scoped Instance（Phase 3，按需實例化）

這些 singleton 需要改為 per-project_id 實例：

# 修改前（全域 singleton）
_anomaly_counter: Optional[AnomalyCounter] = None

def get_anomaly_counter() -> AnomalyCounter:
    global _anomaly_counter
    if _anomaly_counter is None:
        _anomaly_counter = AnomalyCounter()
    return _anomaly_counter

# 修改後（per-tenant，Phase 3）
_anomaly_counters: dict[str, AnomalyCounter] = {}

def get_anomaly_counter(project_id: str) -> AnomalyCounter:
    if project_id not in _anomaly_counters:
        _anomaly_counters[project_id] = AnomalyCounter(project_id=project_id)
    return _anomaly_counters[project_id]

需要此策略的 singleton：

Singleton	檔案	分解難度
AnomalyCounter	anomaly_counter.py:85	LOW（PR-11，Phase 2）
ConsensusEngine	consensus_engine.py:344	MEDIUM（Phase 3）
IntentClassifier	intent_classifier.py	MEDIUM（Phase 3）

策略 3：Context-Injected（Phase 3，依賴注入）

透過 ContextVar 或 FastAPI Depends 注入，不使用模組層級 singleton：

# DecisionManager 不再是全域 singleton，而是 per-request 注入
async def get_decision_manager(
    project_id: str = Depends(get_project_id),
    effective_policy: EffectivePolicy = Depends(get_effective_policy)
) -> DecisionManager:
    return DecisionManager(project_id=project_id, policy=effective_policy)

需要此策略的 singleton：

Singleton	檔案	備註
DecisionManager	decision_manager.py:1402	Tier 3！需要 P10 架構審查
TrustEngine	trust_engine.py:189	Tier 3！需要 P10 授權

策略 4：Module-Level Config（保留 singleton，但 config 注入）

Singleton 保留，但內部狀態改為從 project_id 動態讀取（而不是靜態初始化）：

# DecisionFusionAdapter：不改 singleton 結構，但方法接受 project_id
class DecisionFusionAdapter:
    async def fuse(
        self,
        project_id: str,    # 新增 project_id 參數
        decisions: list[Decision]
    ) -> FusedDecision:
        policy = await get_effective_policy(project_id)
        # 用 policy 而非 self 的靜態 config
        ...

D2 — 分解優先序

立即（Phase 2）：

• PR-04：registry.py _provider → __provider double underscore（INV-9 找到的封裝漏洞）
• PR-11：AnomalyCounter per-project（依賴 PR-10 loop tagging）

Phase 3：

• ConsensusEngine per-tenant instance
• IntentClassifier per-tenant instance
• DecisionFusionAdapter 方法簽名加 project_id

Phase 4+（Tier 3，需 P10 審查）：

• DecisionManager → 依賴注入重構（大型工程，需要獨立 ADR）
• TrustEngine → 依賴注入重構（Tier 3，必須有首席架構師授權）

D3 — AnomalyCounter 分解設計（Phase 2，PR-11）

AnomalyCounter 是最安全的分解起點（影響範圍小，沒有 Tier 3 限制）：

# anomaly_counter.py
_anomaly_counters: dict[str, AnomalyCounter] = {}
_counters_lock = asyncio.Lock()

async def get_anomaly_counter(project_id: str) -> AnomalyCounter:
    async with _counters_lock:
        if project_id not in _anomaly_counters:
            _anomaly_counters[project_id] = AnomalyCounter(
                project_id=project_id,
                redis_prefix=f"anomaly:{project_id}:"  # per-tenant Redis key
            )
        return _anomaly_counters[project_id]

Redis key 遷移（INV-1 P2 keys）：

舊：anomaly:counter:{metric}
新：anomaly:{project_id}:counter:{metric}

D4 — DecisionManager + TrustEngine 的保護措施（Phase 2 前）

在真正分解前，Phase 2 的保護措施：

1. Context 注入：確保所有 DecisionManager 方法的 project_id 都從 contextvars 讀取
2. Redis key 隔離：DecisionManager 內部的 Redis key 改為帶 project_id prefix（PR-06 已覆蓋部分）
3. 禁止直接呼叫 global：在 Tier 3 檔案頂部加警告 comment（不是程式碼，是文件）

D5 — ConsensusEngine Redis Key 遷移（PR-06）

INV-9 確認 ConsensusEngine 的 CONSENSUS_PREFIX 沒有 project 隔離：

# 修改前（consensus_engine.py）
CONSENSUS_PREFIX = "consensus:"

# 修改後（PR-06，Phase 2）
def get_consensus_prefix(project_id: str) -> str:
    return f"consensus:{project_id}:"

---

13 Singleton 完整分解計畫

Singleton	策略	優先級	Phase	Tier
TelegramGateway	Platform Singleton（保留）	-	-	-
HostRepairAgent	Platform Singleton（保留）	-	-	-
AIProviderRegistry	Platform Singleton + PR-04	P1	Phase 2	-
FailoverAlerter	Platform Singleton（保留）	-	-	-
AnomalyCounter	Tenant-Scoped	P1	Phase 2	-
ConsensusEngine	Tenant-Scoped + PR-06	P1	Phase 3	-
IntentClassifier	Tenant-Scoped	P2	Phase 3	-
DecisionFusionAdapter	Config-Injected	P2	Phase 3	-
AIRouter	Config-Injected	P2	Phase 3	-
AIRouterExecutor	Config-Injected	P2	Phase 3	-
DecisionManager	Context-Injected	P3	Phase 4+	Tier 3
TrustEngine	Context-Injected	P3	Phase 4+	Tier 3
TelegramGateway（messages）	Context-Injected	P2	Phase 3	-

---

後果

Benefits

• AnomalyCounter per-tenant：EwoooC 和 AWOOOI 的異常計數互不干擾
• ConsensusEngine Redis key 隔離（PR-06）：共識決策不跨 tenant 污染
• Tier 3 singleton（DecisionManager / TrustEngine）有清晰的分解路徑，但保護好不急躁

Costs

• AnomalyCounter per-tenant 需要 Redis key migration（舊格式的 counter 會被遺棄）
• Phase 3+ 的大規模 singleton 分解是重大工程（每個需要獨立 PR + critic 審查）

Risks

• _anomaly_counters: dict 本身沒有 GC 機制，長期運行可能累積 tenant 實例
• 緩解：WeakValueDictionary 或定期清理（tenant 長時間無活動則清除實例）
• Tier 3 singleton 分解失敗 → 架構回退需要 hotfix
• 緩解：Tier 3 必須先有完整測試覆蓋才能動手

---

驗收標準

• PR-04：registry.py _provider → __provider（Phase 2）
• PR-06：ConsensusEngine Redis prefix 加 project_id（Phase 2）
• PR-11：AnomalyCounter per-tenant（Phase 2）
• Phase 3 前：ConsensusEngine / IntentClassifier tenant-scoped 完成
• Phase 4+ 前：DecisionManager / TrustEngine 分解有獨立 ADR + P10 授權

關聯

• ADR-111（bootstrap order，singleton 初始化時機）
• ADR-118（RLS，tenant 隔離需要正確的 project_id context）
• INV-9（13 singleton 完整清單 + 檔案位置）
• PR-04/PR-06/PR-11（AnoooP Phase 2 具體 PR）