kontextual-engine/src/kontextual_engine/ports/repositories.py

"""Repository ports for governed asset registry state."""

from __future__ import annotations

from typing import Protocol

from kontextual_engine.core import (
    Actor,
    AssetRepresentation,
    AssetVersion,
    AuditEvent,
    ContextEntity,
    CoreRelationship,
    IdempotencyRecord,
    IngestionJob,
    IngestionJobStatus,
    KnowledgeAsset,
    LifecycleState,
    MetadataRecord,
    RepresentationKind,
)


class AssetRegistryRepository(Protocol):
    def save_actor(self, actor: Actor) -> Actor: ...
    def get_actor(self, actor_id: str) -> Actor: ...

    def save_asset(self, asset: KnowledgeAsset) -> KnowledgeAsset: ...
    def get_asset(self, asset_id: str) -> KnowledgeAsset: ...
    def list_assets(
        self,
        *,
        lifecycle: LifecycleState | None = None,
        asset_type: str | None = None,
    ) -> list[KnowledgeAsset]: ...

    def save_representation(self, representation: AssetRepresentation) -> AssetRepresentation: ...
    def get_representation(self, representation_id: str) -> AssetRepresentation: ...
    def list_representations(
        self,
        *,
        asset_id: str | None = None,
        kind: RepresentationKind | None = None,
    ) -> list[AssetRepresentation]: ...

    def save_metadata_record(self, asset_id: str, record: MetadataRecord) -> MetadataRecord: ...
    def list_metadata_records(self, asset_id: str) -> list[MetadataRecord]: ...

    def save_context_entity(self, entity: ContextEntity) -> ContextEntity: ...
    def get_context_entity(self, entity_id: str) -> ContextEntity: ...
    def list_context_entities(self) -> list[ContextEntity]: ...

    def save_relationship(self, relationship: CoreRelationship) -> CoreRelationship: ...
    def get_relationship(self, relationship_id: str) -> CoreRelationship: ...
    def list_relationships(
        self,
        *,
        source_id: str | None = None,
        target_id: str | None = None,
    ) -> list[CoreRelationship]: ...

    def save_version(self, version: AssetVersion) -> AssetVersion: ...
    def list_versions(self, asset_id: str) -> list[AssetVersion]: ...

    def save_audit_event(self, event: AuditEvent) -> AuditEvent: ...
    def get_audit_event(self, event_id: str) -> AuditEvent: ...
    def list_audit_events(
        self,
        *,
        target: str | None = None,
        correlation_id: str | None = None,
    ) -> list[AuditEvent]: ...

    def save_idempotency_record(self, record: IdempotencyRecord) -> IdempotencyRecord: ...
    def get_idempotency_record(self, key: str) -> IdempotencyRecord | None: ...

    def save_ingestion_job(self, job: IngestionJob) -> IngestionJob: ...
    def get_ingestion_job(self, job_id: str) -> IngestionJob: ...
    def list_ingestion_jobs(
        self,
        *,
        status: IngestionJobStatus | None = None,
    ) -> list[IngestionJob]: ...