stable asset queries, lexical search, filters, contextual entity and relationship retrieval, permission-aware fail-closed behavior, source-grounded snippets, feedback capture, and KPI hooks

src/kontextual_engine/ports/repositories.py

@@ -20,6 +20,7 @@ from kontextual_engine.core import (
     MetadataSchema,
     MetadataSchemaAssignment,
     RepresentationKind,
+    RetrievalFeedbackRecord,
     Sensitivity,
 )
 
@@ -90,6 +91,14 @@ class AssetRegistryRepository(Protocol):
         correlation_id: str | None = None,
     ) -> list[AuditEvent]: ...
 
+    def save_retrieval_feedback(self, record: RetrievalFeedbackRecord) -> RetrievalFeedbackRecord: ...
+    def list_retrieval_feedback(
+        self,
+        *,
+        correlation_id: str | None = None,
+        label: str | None = None,
+    ) -> list[RetrievalFeedbackRecord]: ...
+
     def save_idempotency_record(self, record: IdempotencyRecord) -> IdempotencyRecord: ...
     def get_idempotency_record(self, key: str) -> IdempotencyRecord | None: ...