重构 改为标准化输出

backend/app/cad_agent/ports.py

@@ -0,0 +1,109 @@
+"""Ports owned by application code.  Implementations live only in adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from .domain.state import TaskState
+
+
+class AdapterUnavailable(RuntimeError):
+    """A bounded external-service outage; handlers must preserve checkpoints."""
+
+
+@dataclass(frozen=True, slots=True)
+class InvocationRecord:
+    invocation_id: str
+    idempotency_key: str
+    status: str
+    result: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CandidateStage:
+    stage_id: str
+    output_dir: str
+
+
+class UnitOfWork(Protocol):
+    def commit(self) -> None: ...
+    def rollback(self) -> None: ...
+
+
+class TaskRepository(Protocol):
+    def create_task(self, task_id: str, request: str) -> TaskState: ...
+    def get_state(self, task_id: str) -> TaskState | None: ...
+    def get_task_projection(self, task_id: str) -> dict[str, Any] | None: ...
+    def ledger_events(self, task_id: str) -> list[dict[str, Any]]: ...
+    def invocation_records(self, task_id: str) -> list[dict[str, Any]]: ...
+    def compare_and_swap(
+        self,
+        state: TaskState,
+        *,
+        events: list[dict[str, Any]] = (),
+        invocation_id: str | None = None,
+        invocation_result: dict[str, Any] | None = None,
+    ) -> bool: ...
+    def get_invocation(self, task_id: str, invocation_id: str) -> InvocationRecord | None: ...
+    def begin_invocation(self, task_id: str, invocation_id: str, idempotency_key: str) -> InvocationRecord: ...
+    def finish_invocation(self, invocation_id: str, result: dict[str, Any]) -> None: ...
+    def append_outbox(self, task_id: str, event: dict[str, Any]) -> None: ...
+    def pending_outbox(self, limit: int = 100, *, task_id: str | None = None) -> list[dict[str, Any]]: ...
+    def mark_outbox_published(self, event_id: int) -> None: ...
+    def record_usage(self, task_id: str, payload: dict[str, Any]) -> None: ...
+    def record_tool_audit(self, task_id: str, payload: dict[str, Any]) -> None: ...
+    def tool_audits(self, task_id: str) -> list[dict[str, Any]]: ...
+    def running_task_ids(self) -> list[str]: ...
+
+
+class ArtifactStore(Protocol):
+    def initialize_task(self, task_id: str, request: str, *, source_blocks: list[dict[str, Any]] | None = None) -> None: ...
+    def sync_action_ledger(self, task_id: str, events: list[dict[str, Any]]) -> str: ...
+    def write_source_index(self, task_id: str, request: str) -> dict[str, str]: ...
+    def read_source_index(self, task_id: str) -> dict[str, str]: ...
+    def read_source_requirements(self, task_id: str) -> str: ...
+    def read_requirements_draft(self, task_id: str, artifact_path: str = "") -> dict[str, Any]: ...
+    def write_requirements_draft(self, task_id: str, payload: dict[str, Any], *, invocation_id: str) -> str: ...
+    def read_requirements_review(self, task_id: str, artifact_path: str = "") -> dict[str, Any] | None: ...
+    def write_requirements_review(self, task_id: str, payload: dict[str, Any], *, invocation_id: str) -> str: ...
+    def read_requirements_contract(self, task_id: str, artifact_path: str = "") -> dict[str, Any] | None: ...
+    def write_requirements_contract(self, task_id: str, payload: dict[str, Any], *, invocation_id: str = "") -> str: ...
+    def read_json(self, task_id: str, relative_path: str) -> dict[str, Any] | None: ...
+    def write_json_once(self, task_id: str, relative_path: str, payload: dict[str, Any]) -> str: ...
+    def write_text_once(self, task_id: str, relative_path: str, text: str) -> str: ...
+    def read_active_cdsl(self, task_id: str, revision_id: str) -> dict[str, Any] | None: ...
+    def read_topology(self, task_id: str, revision_id: str) -> dict[str, Any] | None: ...
+    def start_candidate_stage(self, task_id: str, idempotency_key: str, payload: dict[str, Any]) -> CandidateStage: ...
+    def stage_output_dir(self, task_id: str, stage_id: str) -> str: ...
+    def write_stage_json(self, task_id: str, stage_id: str, relative_path: str, payload: dict[str, Any]) -> str: ...
+    def read_stage_json(self, task_id: str, stage_id: str, relative_path: str) -> dict[str, Any] | None: ...
+    def publish_candidate(self, task_id: str, stage_id: str, revision_id: str) -> dict[str, str]: ...
+    def find_published_candidate(self, task_id: str, stage_id: str) -> tuple[str, dict[str, Any]] | None: ...
+    def recover_staged_candidates(self, task_id: str, referenced_stage_ids: set[str]) -> None: ...
+
+
+class CadRuntime(Protocol):
+    def supported_atomic_ids(self) -> tuple[str, ...]: ...
+    def operation_contract(self, atomic_id: str) -> dict[str, Any]: ...
+    def selector_tokens(self, topology: dict[str, Any] | None) -> dict[str, dict[str, Any]]: ...
+    def reference_tokens(self, cdsl: dict[str, Any] | None) -> dict[str, str]: ...
+    def materialize_fragment(self, base_cdsl: dict[str, Any] | None, fragment: dict[str, Any], contract: dict[str, Any], selector_tokens: dict[str, dict[str, Any]], reference_tokens: dict[str, str], *, require_through: bool = False) -> tuple[dict[str, Any], dict[str, Any]]: ...
+    def rebuild(self, cdsl: dict[str, Any], output_dir: str, task_id: str, revision_id: str) -> dict[str, Any]: ...
+
+
+class ModelGateway(Protocol):
+    async def call_tool(self, *, messages: list[dict[str, Any]], tool: dict[str, Any], provider_id: str, model_id: str, required_tool_name: str) -> dict[str, Any]: ...
+    async def conformance(self, *, provider_id: str, model_id: str, tools: list[dict[str, Any]]) -> dict[str, Any]: ...
+
+
+class ReviewGateway(Protocol):
+    async def review(self, *, kind: str, payload: dict[str, Any], tool: dict[str, Any], provider_id: str, model_id: str) -> dict[str, Any]: ...
+
+
+class VerifierExecutor(Protocol):
+    def evaluate(self, claims: list[dict[str, Any]], facts: dict[str, Any]) -> list[dict[str, Any]]: ...
+
+
+class EventPublisher(Protocol):
+    async def publish(self, event: dict[str, Any]) -> None: ...