Implement first knowledge engine runtime slice

src/kontextual_engine/errors.py

@@ -0,0 +1,59 @@
+"""Shared diagnostics and structured errors."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """A structured finding emitted by engine operations."""
+
+    severity: str
+    code: str
+    message: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "severity": self.severity,
+            "code": self.code,
+            "message": self.message,
+            "details": dict(self.details),
+        }
+
+
+class KontextualError(Exception):
+    """Base class for explicit engine failures."""
+
+    code = "kontextual.error"
+
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.details = details or {}
+
+    def diagnostic(self, *, severity: str = "error") -> Diagnostic:
+        return Diagnostic(
+            severity=severity,
+            code=self.code,
+            message=str(self),
+            details=dict(self.details),
+        )
+
+
+class NotFoundError(KontextualError):
+    code = "kontextual.not_found"
+
+
+class DuplicateResourceError(KontextualError):
+    code = "kontextual.duplicate"
+
+
+class ValidationError(KontextualError):
+    code = "kontextual.validation"
+
+
+class AdapterUnavailableError(KontextualError):
+    code = "kontextual.adapter_unavailable"
+