Create-knowledge-find-decode/decode_content/repository.py

"""Repository contracts for decode-content state."""
from __future__ import annotations

from typing import Any, Protocol
from uuid import UUID

from decode_content.models import (
    ContractSnapshot,
    DecodeJob,
    DecodeResult,
    IngestRecord,
    KnowledgeParticle,
    PayloadDraft,
    ScopeResult,
)


class DecodeRepository(Protocol):
    """Persistence boundary for the formal single-item decode workflow."""

    def create_decode_job(
        self,
        *,
        item_id: UUID,
        status: str = "pending",
        metadata: dict[str, Any] | None = None,
    ) -> DecodeJob:
        ...

    def save_decode_result(
        self,
        *,
        item_id: UUID,
        decode_job_id: UUID | None = None,
        read_result: dict[str, Any] | None = None,
        gate_result: dict[str, Any] | None = None,
        framing_result: dict[str, Any] | None = None,
        status: str = "draft",
    ) -> DecodeResult:
        ...

    def get_decode_result_for_item(self, item_id: UUID) -> DecodeResult:
        ...

    def save_knowledge_particle(
        self,
        *,
        item_id: UUID,
        particle_type: str,
        title: str,
        decode_result_id: UUID | None = None,
        parent_particle_id: UUID | None = None,
        content: dict[str, Any] | None = None,
        status: str = "draft",
    ) -> KnowledgeParticle:
        ...

    def save_scope_result(
        self,
        *,
        scope_type: str,
        scope_value: str,
        particle_id: UUID | None = None,
        item_id: UUID | None = None,
        evidence: dict[str, Any] | None = None,
        status: str = "draft",
    ) -> ScopeResult:
        ...

    def save_payload_draft(
        self,
        *,
        payload: dict[str, Any],
        particle_id: UUID | None = None,
        item_id: UUID | None = None,
        review_status: str = "pending",
        ingest_ready: bool = False,
        status: str = "draft",
    ) -> PayloadDraft:
        ...

    def list_payload_drafts(self, item_id: UUID | None = None) -> list[PayloadDraft]:
        ...

    def mark_payload_draft_ingested(self, payload_draft_id: UUID) -> PayloadDraft:
        ...

    def save_ingest_record(
        self,
        *,
        payload_draft_id: UUID | None = None,
        target_system: str,
        target_id: str | None = None,
        status: str = "pending",
        attempt_count: int = 1,
        response_payload: dict[str, Any] | None = None,
        error_message: str | None = None,
    ) -> IngestRecord:
        ...

    def list_ingest_records(self, item_id: UUID | None = None) -> list[IngestRecord]:
        ...

    def save_contract_snapshot(
        self,
        *,
        contract_name: str,
        contract_type: str,
        version_label: str | None = None,
        content_hash: str | None = None,
        source_path: str | None = None,
        snapshot: dict[str, Any] | None = None,
        pipeline_run_id: UUID | None = None,
    ) -> ContractSnapshot:
        ...