Governed asset registry slice with asset creation, representations, metadata, lifecycle transitions, policy authorization, fail-closed denial, audit events, and version records

src/kontextual_engine/ports/__init__.py

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

src/kontextual_engine/ports/policy.py

@@ -0,0 +1,38 @@
+"""Policy decision ports for application services."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from kontextual_engine.core import OperationContext, PolicyDecision
+
+
+class PolicyGateway(Protocol):
+    def authorize(
+        self,
+        context: OperationContext,
+        action: str,
+        resource: str,
+        *,
+        resource_metadata: dict[str, Any] | None = None,
+    ) -> PolicyDecision: ...
+
+
+class AllowAllPolicyGateway:
+    """Deterministic default for local development and tests."""
+
+    def authorize(
+        self,
+        context: OperationContext,
+        action: str,
+        resource: str,
+        *,
+        resource_metadata: dict[str, Any] | None = None,
+    ) -> PolicyDecision:
+        return PolicyDecision.allow(
+            context.actor.id,
+            action,
+            resource,
+            context={"gateway": "allow-all", "resource_metadata": resource_metadata or {}},
+        )
+

src/kontextual_engine/ports/repositories.py

@@ -0,0 +1,54 @@
+"""Repository ports for governed asset registry state."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from kontextual_engine.core import (
+    Actor,
+    AssetRepresentation,
+    AssetVersion,
+    AuditEvent,
+    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_version(self, version: AssetVersion) -> AssetVersion: ...
+    def list_versions(self, asset_id: str) -> list[AssetVersion]: ...
+
+    def save_audit_event(self, event: AuditEvent) -> AuditEvent: ...
+    def list_audit_events(
+        self,
+        *,
+        target: str | None = None,
+        correlation_id: str | None = None,
+    ) -> list[AuditEvent]: ...
+