first ingestion/normalization slice

src/kontextual_engine/ports/__init__.py

@@ -1,11 +1,14 @@
 """Stable ports owned by the engine."""
 
+from .ingestion import DirectorySourceConnector, FormatExtractor, SourceConnector
 from .policy import AllowAllPolicyGateway, PolicyGateway
 from .repositories import AssetRegistryRepository
 
 __all__ = [
     "AllowAllPolicyGateway",
     "AssetRegistryRepository",
+    "DirectorySourceConnector",
+    "FormatExtractor",
     "PolicyGateway",
+    "SourceConnector",
 ]
-

src/kontextual_engine/ports/ingestion.py

@@ -0,0 +1,34 @@
+"""Connector and extractor ports for ingestion."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from kontextual_engine.core import (
+    ConnectorCapability,
+    ExtractionResult,
+    ExtractorCapability,
+    SourcePayload,
+)
+
+
+class SourceConnector(Protocol):
+    name: str
+
+    def capabilities(self) -> ConnectorCapability: ...
+
+    def fetch(self, source_uri: str) -> SourcePayload: ...
+
+
+class DirectorySourceConnector(SourceConnector, Protocol):
+    def iter_files(self, source_uri: str, *, recursive: bool = True) -> list[str]: ...
+
+
+class FormatExtractor(Protocol):
+    name: str
+
+    def capabilities(self) -> ExtractorCapability: ...
+
+    def supports(self, media_type: str) -> bool: ...
+
+    def extract(self, payload: SourcePayload) -> ExtractionResult: ...

src/kontextual_engine/ports/repositories.py

@@ -12,6 +12,8 @@ from kontextual_engine.core import (
     ContextEntity,
     CoreRelationship,
     IdempotencyRecord,
+    IngestionJob,
+    IngestionJobStatus,
     KnowledgeAsset,
     LifecycleState,
     MetadataRecord,
@@ -71,3 +73,11 @@ class AssetRegistryRepository(Protocol):
 
     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]: ...