aevum-core 0.2.0__tar.gz

aevum_core-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+*.egg-info/
+
+# Build
+dist/
+build/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Verify scripts (run locally, never commit)
+verify_phase*.py
+scripts/verify_phase*.py

aevum_core-0.2.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: aevum-core
+Version: 0.2.0
+Summary: Aevum — the sealed movement. Replay-first, policy-governed context kernel.
+Project-URL: Homepage, https://aevum.build
+Project-URL: Repository, https://github.com/aevum-labs/aevum
+Project-URL: Issues, https://github.com/aevum-labs/aevum/issues
+License: Apache-2.0
+Keywords: ai,audit,context,governance,provenance,replay
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: cedar
+Requires-Dist: cedarpy>=0.3; extra == 'cedar'
+Provides-Extra: default
+Requires-Dist: aevum-store-oxigraph; extra == 'default'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aevum-core
+
+The Aevum context kernel — five governed functions, cryptographic sigchain, consent ledger, and absolute barriers.
+
+```bash
+pip install aevum-core
+pip install "aevum-core[cedar]"  # + real Cedar consent enforcement
+```
+
+See the [main repository README](https://github.com/aevum-labs/aevum) for a quickstart and architecture overview.

aevum_core-0.2.0/README.md

@@ -0,0 +1,10 @@
+# aevum-core
+
+The Aevum context kernel — five governed functions, cryptographic sigchain, consent ledger, and absolute barriers.
+
+```bash
+pip install aevum-core
+pip install "aevum-core[cedar]"  # + real Cedar consent enforcement
+```
+
+See the [main repository README](https://github.com/aevum-labs/aevum) for a quickstart and architecture overview.

aevum_core-0.2.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "aevum-core"
+version = "0.2.0"
+description = "Aevum — the sealed movement. Replay-first, policy-governed context kernel."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+keywords = ["ai", "governance", "provenance", "audit", "context", "replay"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0,<3.0",
+    "cryptography>=42.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+default = ["aevum-store-oxigraph"]
+cedar = ["cedarpy>=0.3"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "hypothesis>=6.100",
+    "mypy>=1.10",
+    "ruff>=0.9",
+]
+
+[project.urls]
+Homepage = "https://aevum.build"
+Repository = "https://github.com/aevum-labs/aevum"
+Issues = "https://github.com/aevum-labs/aevum/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aevum"]
+
+[tool.uv.sources]
+# aevum-core has no workspace dependencies — it IS the foundation
+aevum-store-oxigraph = { workspace = true }
+
+[tool.mypy]
+mypy_path = "src"
+strict = true
+python_version = "3.11"
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 130
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "B", "SIM", "I", "ANN"]
+ignore = ["ANN401"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--tb=short"
+pythonpath = ["src", "tests"]

aevum_core-0.2.0/src/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-0.2.0/src/aevum/core/audit/__init__.py

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

aevum_core-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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",
+]