rebuild(stage-15): complete governance and handoff

next/backend/llm/gateway.py

@@ -5,19 +5,53 @@ import uuid
 from collections.abc import Iterator
 from dataclasses import dataclass
 from datetime import datetime
+from typing import Protocol
 from zoneinfo import ZoneInfo
 
 from backend.database.connection import Database
 from backend.errors import BusinessError
-from backend.features.accounts.model_pool import ModelPoolService
-from backend.features.accounts.models import Principal
-from backend.features.accounts.service import MembershipService
 from backend.llm.provider import OpenAICompatibleClient, ProviderFailure
 from backend.llm.repository import LLMRepository
 
 SHANGHAI = ZoneInfo("Asia/Shanghai")
 
 
+class PrincipalUser(Protocol):
+    id: int
+
+
+class PrincipalAccess(Protocol):
+    user: PrincipalUser
+
+
+class MembershipViewAccess(Protocol):
+    quota_exempt: bool
+    daily_limit: int
+
+
+class MembershipAccess(Protocol):
+    def view_for(self, principal: PrincipalAccess) -> MembershipViewAccess: ...
+
+    def can_use_smart_features(self, principal: PrincipalAccess) -> bool: ...
+
+
+class ModelRecordAccess(Protocol):
+    id: int
+    base_url: str
+    model_identifier: str
+
+
+class ModelRuntimeAccess(Protocol):
+    primary: ModelRecordAccess | None
+    fallback: ModelRecordAccess | None
+
+
+class ModelPoolAccess(Protocol):
+    def runtime_config(self) -> ModelRuntimeAccess: ...
+
+    def decrypt_api_key(self, record: ModelRecordAccess) -> str: ...
+
+
 class LLMGatewayError(RuntimeError):
     def __init__(self, code: str, message: str, *, partial: bool = False) -> None:
         super().__init__(message)
@@ -60,8 +94,8 @@ class LLMGateway:
         self,
         database: Database,
         repository: LLMRepository,
-        memberships: MembershipService,
-        model_pool: ModelPoolService,
+        memberships: MembershipAccess,
+        model_pool: ModelPoolAccess,
         provider: OpenAICompatibleClient | None = None,
     ) -> None:
         self._database = database
@@ -72,7 +106,7 @@ class LLMGateway:
 
     def prepare(
         self,
-        principal: Principal,
+        principal: PrincipalAccess,
         *,
         feature: str,
         prompt_version: str,