aevum-core 0.2.0__py3-none-any.whl

aevum/core/__init__.py

@@ -0,0 +1,30 @@
+"""
+aevum.core — The Aevum context kernel.
+
+Usage:
+    from aevum.core import Engine
+    engine = Engine()
+    result = engine.commit(event_type="app.event", payload={}, actor="user-1")
+"""
+
+from __future__ import annotations
+
+from aevum.core.engine import Engine
+from aevum.core.envelope.models import OutputEnvelope
+from aevum.core.exceptions import (
+    AevumError,
+    BarrierViolationError,
+    ConsentRequiredError,
+    ProvenanceRequiredError,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Engine",
+    "OutputEnvelope",
+    "AevumError",
+    "BarrierViolationError",
+    "ConsentRequiredError",
+    "ProvenanceRequiredError",
+]

aevum/core/audit/__init__.py

@@ -0,0 +1 @@
+"""aevum.core.audit — Episodic ledger, sigchain, HLC, AuditEvent."""

aevum/core/audit/event.py

@@ -0,0 +1,77 @@
+"""
+AuditEvent — the 18-field episodic ledger entry. Spec Section 06.2.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+from typing import Any
+
+
+@dataclasses.dataclass(frozen=True)
+class AuditEvent:
+    """Immutable episodic ledger entry. All 18 fields required."""
+
+    event_id: str
+    episode_id: str
+    sequence: int
+    event_type: str
+    schema_version: str
+    valid_from: str
+    valid_to: str | None
+    system_time: int
+    causation_id: str | None
+    correlation_id: str | None
+    actor: str
+    trace_id: str | None
+    span_id: str | None
+    payload: dict[str, Any]
+    payload_hash: str
+    prior_hash: str
+    signature: str
+    signer_key_id: str
+
+    def __post_init__(self) -> None:
+        if not self.actor:
+            raise ValueError("actor MUST NOT be empty")
+        if self.sequence < 1:
+            raise ValueError(f"sequence must be >= 1, got {self.sequence}")
+        if not self.event_type:
+            raise ValueError("event_type MUST NOT be empty")
+
+    @staticmethod
+    def canonical_payload(payload: dict[str, Any]) -> bytes:
+        return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+
+    @staticmethod
+    def hash_payload(payload: dict[str, Any]) -> str:
+        return hashlib.sha3_256(AuditEvent.canonical_payload(payload)).hexdigest()
+
+    @staticmethod
+    def hash_event_for_chain(event: AuditEvent) -> str:
+        """SHA3-256 over all fields (excluding signature) for prior_hash chaining."""
+        fields = {
+            "event_id": event.event_id,
+            "episode_id": event.episode_id,
+            "sequence": event.sequence,
+            "event_type": event.event_type,
+            "schema_version": event.schema_version,
+            "valid_from": event.valid_from,
+            "valid_to": event.valid_to,
+            "system_time": event.system_time,
+            "causation_id": event.causation_id,
+            "correlation_id": event.correlation_id,
+            "actor": event.actor,
+            "trace_id": event.trace_id,
+            "span_id": event.span_id,
+            "payload_hash": event.payload_hash,
+            "prior_hash": event.prior_hash,
+            "signer_key_id": event.signer_key_id,
+        }
+        canonical = json.dumps(fields, sort_keys=True, separators=(",", ":")).encode()
+        return hashlib.sha3_256(canonical).hexdigest()
+
+    def audit_id(self) -> str:
+        return f"urn:aevum:audit:{self.event_id}"

aevum/core/audit/hlc.py

@@ -0,0 +1,36 @@
+"""
+HybridLogicalClock — causal ordering. Spec Section 06.5.
+Timestamp: bits 63-16 = ms since epoch, bits 15-0 = logical counter.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+_lock = threading.Lock()
+_last_ms: int = 0
+_counter: int = 0
+
+
+def now() -> int:
+    global _last_ms, _counter
+    with _lock:
+        ms = int(time.time() * 1000)
+        if ms > _last_ms:
+            _last_ms = ms
+            _counter = 0
+        else:
+            _counter += 1
+            if _counter > 0xFFFF:
+                _last_ms += 1
+                _counter = 0
+        return (_last_ms << 16) | _counter
+
+
+def to_millis(ts: int) -> int:
+    return ts >> 16
+
+
+def to_counter(ts: int) -> int:
+    return ts & 0xFFFF

aevum/core/audit/ledger.py

@@ -0,0 +1,71 @@
+"""
+Episodic ledger — append-only. Barrier 4 enforced here. Spec Section 06.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from aevum.core.audit.event import AuditEvent
+from aevum.core.audit.sigchain import Sigchain
+from aevum.core.exceptions import BarrierViolationError, ReplayNotFoundError
+
+
+class InMemoryLedger:
+    """Thread-safe append-only in-memory episodic ledger. Suitable for development and testing."""
+
+    def __init__(self, sigchain: Sigchain) -> None:
+        self._sigchain = sigchain
+        self._events: list[AuditEvent] = []
+        self._index: dict[str, AuditEvent] = {}
+        self._lock = threading.Lock()
+
+    def append(
+        self,
+        *,
+        event_type: str,
+        payload: dict[str, Any],
+        actor: str,
+        episode_id: str | None = None,
+        causation_id: str | None = None,
+        correlation_id: str | None = None,
+    ) -> AuditEvent:
+        with self._lock:
+            event = self._sigchain.new_event(
+                event_type=event_type,
+                payload=payload,
+                actor=actor,
+                episode_id=episode_id,
+                causation_id=causation_id,
+                correlation_id=correlation_id,
+            )
+            self._events.append(event)
+            self._index[event.audit_id()] = event
+            return event
+
+    def get(self, audit_id: str) -> AuditEvent:
+        event = self._index.get(audit_id)
+        if event is None:
+            raise ReplayNotFoundError(f"No ledger entry for {audit_id!r}")
+        return event
+
+    def all_events(self) -> list[AuditEvent]:
+        with self._lock:
+            return list(self._events)
+
+    def count(self) -> int:
+        with self._lock:
+            return len(self._events)
+
+    def __delitem__(self, key: object) -> None:
+        """Barrier 4: deletion forbidden."""
+        raise BarrierViolationError(
+            "Attempted to delete a ledger entry — Barrier 4 (Audit Immutability) violated."
+        )
+
+    def __setitem__(self, key: object, value: object) -> None:
+        """Barrier 4: overwrite forbidden."""
+        raise BarrierViolationError(
+            "Attempted to overwrite a ledger entry — Barrier 4 (Audit Immutability) violated."
+        )

aevum/core/audit/sigchain.py

@@ -0,0 +1,166 @@
+"""
+Sigchain — Ed25519 signing and SHA3-256 chaining. Spec Section 06.
+"""
+
+from __future__ import annotations
+
+import base64
+import datetime
+import hashlib
+import json
+import os
+import time
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from aevum.core.audit.event import AuditEvent
+from aevum.core.audit.hlc import now as hlc_now
+
+GENESIS_HASH = hashlib.sha3_256(b"aevum:genesis").hexdigest()
+
+
+def _uuid7() -> str:
+    """UUID version 7 (time-ordered). Inline — no external dep."""
+    ts_ms = int(time.time() * 1000) & 0xFFFFFFFFFFFF
+    rand = int.from_bytes(os.urandom(10), "big")
+    rand_a = (rand >> 62) & 0x0FFF
+    rand_b = rand & 0x3FFFFFFFFFFFFFFF
+    hi = (ts_ms << 16) | 0x7000 | rand_a
+    lo = 0x8000000000000000 | rand_b
+    h = f"{hi:016x}{lo:016x}"
+    return f"{h[:8]}-{h[8:12]}-{h[12:16]}-{h[16:20]}-{h[20:]}"
+
+
+class Sigchain:
+    """Per-node Ed25519 signing chain. Append-only by design."""
+
+    def __init__(
+        self,
+        private_key: Ed25519PrivateKey | None = None,
+        key_id: str | None = None,
+    ) -> None:
+        self._private_key = private_key or Ed25519PrivateKey.generate()
+        self._key_id = key_id or _uuid7()
+        self._sequence: int = 0
+        self._prior_hash: str = GENESIS_HASH
+
+    @property
+    def key_id(self) -> str:
+        return self._key_id
+
+    @property
+    def public_key(self) -> Ed25519PublicKey:
+        return self._private_key.public_key()
+
+    def _sign(self, fields: dict[str, Any]) -> str:
+        canonical = json.dumps(fields, sort_keys=True, separators=(",", ":")).encode()
+        sig_bytes = self._private_key.sign(canonical)
+        return base64.urlsafe_b64encode(sig_bytes).rstrip(b"=").decode()
+
+    def new_event(
+        self,
+        *,
+        event_type: str,
+        payload: dict[str, Any],
+        actor: str,
+        episode_id: str | None = None,
+        causation_id: str | None = None,
+        correlation_id: str | None = None,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+        valid_from: str | None = None,
+        valid_to: str | None = None,
+    ) -> AuditEvent:
+        """Append a new signed event to the chain."""
+        self._sequence += 1
+        event_id = _uuid7()
+        ep_id = episode_id or _uuid7()
+        vf = valid_from or datetime.datetime.now(datetime.UTC).isoformat()
+        ts = hlc_now()
+        payload_hash = AuditEvent.hash_payload(payload)
+        prior = self._prior_hash
+
+        signing_fields: dict[str, Any] = {
+            "event_id": event_id,
+            "episode_id": ep_id,
+            "sequence": self._sequence,
+            "event_type": event_type,
+            "schema_version": "1.0",
+            "valid_from": vf,
+            "valid_to": valid_to,
+            "system_time": ts,
+            "causation_id": causation_id,
+            "correlation_id": correlation_id,
+            "actor": actor,
+            "trace_id": trace_id,
+            "span_id": span_id,
+            "payload_hash": payload_hash,
+            "prior_hash": prior,
+            "signer_key_id": self._key_id,
+        }
+        signature = self._sign(signing_fields)
+
+        event = AuditEvent(
+            event_id=event_id,
+            episode_id=ep_id,
+            sequence=self._sequence,
+            event_type=event_type,
+            schema_version="1.0",
+            valid_from=vf,
+            valid_to=valid_to,
+            system_time=ts,
+            causation_id=causation_id,
+            correlation_id=correlation_id,
+            actor=actor,
+            trace_id=trace_id,
+            span_id=span_id,
+            payload=payload,
+            payload_hash=payload_hash,
+            prior_hash=prior,
+            signature=signature,
+            signer_key_id=self._key_id,
+        )
+        self._prior_hash = AuditEvent.hash_event_for_chain(event)
+        return event
+
+    def verify_chain(self, events: list[AuditEvent]) -> bool:
+        """Verify entire chain from genesis. Returns True if intact."""
+        public_key = self.public_key
+        expected_prior = GENESIS_HASH
+        for event in events:
+            if event.prior_hash != expected_prior:
+                return False
+            if AuditEvent.hash_payload(event.payload) != event.payload_hash:
+                return False
+            signing_fields: dict[str, Any] = {
+                "event_id": event.event_id,
+                "episode_id": event.episode_id,
+                "sequence": event.sequence,
+                "event_type": event.event_type,
+                "schema_version": event.schema_version,
+                "valid_from": event.valid_from,
+                "valid_to": event.valid_to,
+                "system_time": event.system_time,
+                "causation_id": event.causation_id,
+                "correlation_id": event.correlation_id,
+                "actor": event.actor,
+                "trace_id": event.trace_id,
+                "span_id": event.span_id,
+                "payload_hash": event.payload_hash,
+                "prior_hash": event.prior_hash,
+                "signer_key_id": event.signer_key_id,
+            }
+            canonical = json.dumps(
+                signing_fields, sort_keys=True, separators=(",", ":")
+            ).encode()
+            try:
+                sig_bytes = base64.urlsafe_b64decode(event.signature + "==")
+                public_key.verify(sig_bytes, canonical)
+            except Exception:
+                return False
+            expected_prior = AuditEvent.hash_event_for_chain(event)
+        return True

aevum/core/barriers.py

@@ -0,0 +1,105 @@
+"""
+Absolute Barriers — hardcoded, unconditional, non-configurable.
+Spec Section 09.3. Canary tests in tests/test_canary.py.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aevum.core.envelope.models import OutputEnvelope, ProvenanceRecord
+
+_CRISIS_KEYWORDS: frozenset[str] = frozenset({
+    "kill myself", "end my life", "want to die", "commit suicide",
+    "hurt someone", "going to hurt", "harm myself",
+    "heart attack", "can't breathe", "i can't breathe",
+    "overdose", "going to shoot", "going to stab",
+})
+
+_CRISIS_SAFE_MESSAGE = (
+    "It sounds like you or someone you know may be going through something "
+    "very difficult. Please reach out to a crisis service — you don't have to face this alone."
+)
+_CRISIS_RESOURCES = [
+    "988 Suicide & Crisis Lifeline: call or text 988 (US)",
+    "Crisis Text Line: text HOME to 741741 (US)",
+    "International Association for Suicide Prevention: https://www.iasp.info/resources/Crisis_Centres/",
+]
+
+
+def _text_from_data(data: dict[str, Any]) -> str:
+    parts = []
+    for v in data.values():
+        parts.append(str(v) if not isinstance(v, str) else v)
+    return " ".join(parts).lower()
+
+
+def _kernel_provenance(audit_id: str) -> ProvenanceRecord:
+    return ProvenanceRecord(
+        source_id="aevum-core", ingest_audit_id=audit_id,
+        chain_of_custody=["aevum-core"], classification=0,
+    )
+
+
+def check_crisis(data: dict[str, Any], audit_id: str) -> OutputEnvelope | None:
+    """Barrier 1 — CRISIS. Returns crisis envelope or None."""
+    if any(kw in _text_from_data(data) for kw in _CRISIS_KEYWORDS):
+        return OutputEnvelope.crisis(
+            audit_id=audit_id,
+            safe_message=_CRISIS_SAFE_MESSAGE,
+            resources=_CRISIS_RESOURCES,
+            provenance=_kernel_provenance(audit_id),
+        )
+    return None
+
+
+def apply_classification_ceiling(
+    results: dict[str, Any],
+    classifications: dict[str, int],
+    actor_clearance: int,
+) -> tuple[dict[str, Any], list[str]]:
+    """Barrier 2 — CLASSIFICATION CEILING. Redacts above-clearance items."""
+    filtered: dict[str, Any] = {}
+    redacted: list[str] = []
+    for entity_id, entity_data in results.items():
+        if classifications.get(entity_id, 0) <= actor_clearance:
+            filtered[entity_id] = entity_data
+        else:
+            redacted.append(entity_id)
+    return filtered, redacted
+
+
+def check_consent(
+    *,
+    subject_id: str,
+    operation: str,
+    grantee_id: str,
+    consent_ledger: Any,
+    audit_id: str,
+) -> OutputEnvelope | None:
+    """Barrier 3 — CONSENT. Returns error envelope or None."""
+    if not consent_ledger.has_consent(
+        subject_id=subject_id, operation=operation, grantee_id=grantee_id
+    ):
+        return OutputEnvelope.error(
+            audit_id=audit_id,
+            error_code="consent_required",
+            error_detail=f"No active consent grant for operation '{operation}' on subject '{subject_id}' by '{grantee_id}'",
+            provenance=_kernel_provenance(audit_id),
+        )
+    return None
+
+
+# Barrier 4 — AUDIT IMMUTABILITY enforced by InMemoryLedger.__delitem__/__setitem__
+
+
+def check_provenance(provenance: dict[str, Any], audit_id: str) -> OutputEnvelope | None:
+    """Barrier 5 — PROVENANCE. Returns error envelope or None."""
+    if not provenance or not provenance.get("source_id"):
+        return OutputEnvelope.error(
+            audit_id=audit_id,
+            error_code="provenance_required",
+            error_detail="Provenance record is missing or has no source_id",
+            provenance=_kernel_provenance(audit_id),
+        )
+    return None

aevum/core/complications/__init__.py

@@ -0,0 +1,46 @@
+"""
+aevum.core.complications — Complication governance lifecycle.
+
+  ComplicationRegistry  — 7-state machine: install/approve/suspend/decommission
+  CircuitBreaker        — threshold-based, monotonic clock
+  ManifestValidator     — schema + Ed25519 (optional)
+  ConflictDetector      — capability overlap, fail-closed
+  WebhookRegistry       — register/dispatch review events
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+from typing import Any
+
+from aevum.core.complications.circuit_breaker import CircuitBreaker
+from aevum.core.complications.conflict import ConflictDetector
+from aevum.core.complications.manifest_validator import ManifestValidator
+from aevum.core.complications.registry import ComplicationRegistry, ComplicationState
+from aevum.core.complications.webhook import WebhookRegistry
+
+
+def _run_coro(coro: Any) -> Any:
+    """
+    Run a coroutine from sync context.
+    Handles the case where we are already inside a running event loop
+    (e.g. FastAPI handlers) by delegating to a thread pool.
+    """
+    try:
+        asyncio.get_running_loop()
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(asyncio.run, coro).result()
+    except RuntimeError:
+        return asyncio.run(coro)
+
+
+__all__ = [
+    "ComplicationRegistry",
+    "ComplicationState",
+    "CircuitBreaker",
+    "ManifestValidator",
+    "ConflictDetector",
+    "WebhookRegistry",
+    "_run_coro",
+]

aevum/core/complications/circuit_breaker.py

@@ -0,0 +1,83 @@
+"""
+CircuitBreaker — per-complication threshold-based circuit breaker.
+
+States: CLOSED (normal) → OPEN (tripped) → HALF_OPEN (testing recovery).
+Uses monotonic clock — no clock drift issues.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from enum import Enum, auto
+
+
+class CBState(Enum):
+    CLOSED    = auto()  # Normal — calls pass through
+    OPEN      = auto()  # Tripped — calls fail immediately
+    HALF_OPEN = auto()  # Recovery probe — one call allowed
+
+
+class CircuitBreaker:
+    """
+    Thread-safe circuit breaker for a single complication.
+
+    Args:
+        failure_threshold: Consecutive failures before opening (default 5)
+        recovery_seconds: Seconds before attempting half-open probe (default 30)
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        recovery_seconds: float = 30.0,
+    ) -> None:
+        self._threshold = failure_threshold
+        self._recovery = recovery_seconds
+        self._state = CBState.CLOSED
+        self._failures = 0
+        self._opened_at: float | None = None
+        self._lock = threading.Lock()
+
+    @property
+    def state(self) -> CBState:
+        with self._lock:
+            self._check_recovery()
+            return self._state
+
+    @property
+    def is_open(self) -> bool:
+        return self.state == CBState.OPEN
+
+    def record_success(self) -> None:
+        """Call after a successful complication invocation."""
+        with self._lock:
+            self._failures = 0
+            self._state = CBState.CLOSED
+            self._opened_at = None
+
+    def record_failure(self) -> None:
+        """Call after a failed complication invocation."""
+        with self._lock:
+            self._failures += 1
+            if self._failures >= self._threshold:
+                self._state = CBState.OPEN
+                self._opened_at = time.monotonic()
+
+    def allow_request(self) -> bool:
+        """Return True if a request should be allowed through."""
+        with self._lock:
+            self._check_recovery()
+            return self._state in (CBState.CLOSED, CBState.HALF_OPEN)
+
+    def _check_recovery(self) -> None:
+        """Transition OPEN → HALF_OPEN if recovery period has elapsed."""
+        if self._state == CBState.OPEN and self._opened_at is not None and time.monotonic() - self._opened_at >= self._recovery:
+            self._state = CBState.HALF_OPEN
+
+    def reset(self) -> None:
+        """Manual reset — for admin use."""
+        with self._lock:
+            self._state = CBState.CLOSED
+            self._failures = 0
+            self._opened_at = None

aevum/core/complications/conflict.py

@@ -0,0 +1,43 @@
+"""
+ConflictDetector — detect capability conflicts at install time.
+Fail-closed: if a conflict exists, installation is refused.
+Spec Section 11.2 (reapproval triggers).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ConflictDetector:
+    """
+    Checks for capability conflicts before a new complication is installed.
+
+    A conflict occurs when two ACTIVE complications claim the same capability.
+    Fail-closed: the new complication is rejected, not the existing one.
+    """
+
+    def check(
+        self,
+        new_manifest: dict[str, Any],
+        active_manifests: list[dict[str, Any]],
+    ) -> list[str]:
+        """
+        Check new_manifest against all currently active manifests.
+
+        Returns a list of conflict descriptions. Empty list = no conflicts.
+        """
+        new_capabilities = set(new_manifest.get("capabilities", []))
+        conflicts: list[str] = []
+
+        for existing in active_manifests:
+            existing_name = existing.get("name", "unknown")
+            existing_capabilities = set(existing.get("capabilities", []))
+            overlap = new_capabilities & existing_capabilities
+            if overlap:
+                conflicts.append(
+                    f"Capability conflict with '{existing_name}': "
+                    f"both claim {sorted(overlap)}"
+                )
+
+        return conflicts