cortex-runtime 0.2.0__py3-none-any.whl

cortex/tools/kernel/services/graph_builder.py

@@ -0,0 +1,81 @@
+"""
+Execution Graph Builder Service
+
+Consumes: IntentEvent, PlanGeneratedEvent, CommandIssuedEvent,
+          DriverTelemetryEvent, VerificationResultEvent (via BaseEvent wildcard)
+Produces: (none — pure projection / read model)
+
+Constructs a real-time Directed Acyclic Graph (DAG) from the stream
+of kernel messages. Each node is linked to its causal parent via the
+message identity fields (intent_id, plan_id, command_id, causation_id).
+"""
+
+from typing import Any
+
+from cortex.tools.kernel.graph.execution_graph import ExecutionGraph
+from cortex.tools.kernel.schema.message import (
+    BaseEvent,
+    CommandIssuedEvent,
+    DriverTelemetryEvent,
+    IntentEvent,
+    PlanGeneratedEvent,
+    VerificationResultEvent,
+)
+
+
+class ExecutionGraphBuilderService:
+    graphs: dict[str, ExecutionGraph]
+
+    def __init__(self):
+        self.graphs = {}
+
+    def record_message(self, msg: Any) -> None:
+        if isinstance(msg, IntentEvent):
+            graph = ExecutionGraph(root_id=msg.intent_id)
+            graph.add_node(
+                node_id=msg.intent_id,
+                node_type="Intent",
+                payload={"goal": msg.goal},
+            )
+            self.graphs[msg.intent_id] = graph
+
+        elif isinstance(msg, PlanGeneratedEvent):
+            graph = self.graphs.get(msg.intent_id)
+            if graph:
+                graph.add_node(
+                    node_id=msg.plan_id,
+                    node_type="Plan",
+                    payload={"step_count": len(msg.steps)},
+                    parent_id=msg.intent_id,
+                )
+
+        elif isinstance(msg, CommandIssuedEvent):
+            for graph in self.graphs.values():
+                if msg.plan_id in graph.nodes:
+                    graph.add_node(
+                        node_id=msg.command_id,
+                        node_type="Command",
+                        payload={"action": msg.action, "params": msg.parameters},
+                        parent_id=msg.plan_id,
+                    )
+                    break
+
+        elif isinstance(msg, BaseEvent):
+            for graph in self.graphs.values():
+                if msg.causation_id and msg.causation_id in graph.nodes:
+                    node_type = "Event"
+                    payload: dict[str, object] = {}
+                    if isinstance(msg, DriverTelemetryEvent):
+                        node_type = "Telemetry"
+                        payload = {"status": msg.status, "data": msg.payload}
+                    elif isinstance(msg, VerificationResultEvent):
+                        node_type = "Verification"
+                        payload = {"passed": msg.passed, "rule": msg.rule_id}
+
+                    graph.add_node(
+                        node_id=msg.event_id,
+                        node_type=node_type,
+                        payload=payload,
+                        parent_id=msg.causation_id,
+                    )
+                    break

cortex/tools/kernel/services/replay.py

@@ -0,0 +1,50 @@
+"""
+Deterministic Replay Subsystem for Kernel Event Streams
+
+Replays recorded event journals and validates that causal lineage
+(event_id, causation_id ordering) is perfectly preserved.
+"""
+
+from cortex.tools.kernel.schema.message import BaseEvent
+from cortex.tools.kernel.transport import EventPublisher
+
+
+class DeterministicReplayEngine:
+    """Executes deterministic replay of recorded event journals."""
+    publisher: EventPublisher
+
+    def __init__(self, publisher: EventPublisher):
+        self.publisher = publisher
+
+    def replay_journal(self, journal: list[BaseEvent]) -> int:
+        """Replays an ordered event journal onto the target transport."""
+        replayed_count = 0
+        for event in journal:
+            self.publisher.publish(event)
+            replayed_count += 1
+        return replayed_count
+
+    @staticmethod
+    def verify_replayed_lineage(
+        original: list[BaseEvent], replayed: list[BaseEvent]
+    ) -> dict[str, object]:
+        """Validates 1:1 causal ID and event sequence immutability."""
+        if len(original) != len(replayed):
+            return {
+                "match": False,
+                "reason": f"Length mismatch: original={len(original)}, replayed={len(replayed)}",
+            }
+
+        for idx, (orig, repl) in enumerate(zip(original, replayed)):
+            if orig.event_id != repl.event_id:
+                return {
+                    "match": False,
+                    "reason": f"Event ID mismatch at index {idx}: {orig.event_id} != {repl.event_id}",
+                }
+            if orig.causation_id != repl.causation_id:
+                return {
+                    "match": False,
+                    "reason": f"Causation ID mismatch at index {idx}: {orig.causation_id} != {repl.causation_id}",
+                }
+
+        return {"match": True, "reason": "100% Deterministic Lineage Preservation Confirmed"}

cortex/tools/kernel/services/verification.py

@@ -0,0 +1,85 @@
+"""
+Verification Service Kernel Contract
+
+Consumes: RawRTLTraceEvent (verification domain), DriverTelemetryEvent (kernel domain)
+Produces: CommitVerifiedEvent (verification domain), VerificationResultEvent (kernel domain)
+
+This service bridges two event hierarchies:
+  1. The verification substrate (event.py: RawRTLTraceEvent → CommitVerifiedEvent)
+  2. The kernel runtime (message.py: DriverTelemetryEvent → VerificationResultEvent)
+
+This is an intentional design decision — the verification service is the
+only component that legitimately spans both domains.
+"""
+
+from collections.abc import Callable
+
+from cortex.tools.kernel.context import RuntimeContext
+from cortex.tools.kernel.schema.contract import ServiceContract
+from cortex.tools.kernel.schema.event import CommitVerifiedEvent, RawRTLTraceEvent
+from cortex.tools.kernel.schema.message import (
+    DriverTelemetryEvent,
+    VerificationResultEvent,
+)
+from cortex.tools.kernel.transport import AnyEvent
+
+
+class VerificationKernelService:
+    context: RuntimeContext
+    publish_cb: Callable[[AnyEvent], object]
+    verified_count: int
+
+    contract = ServiceContract(
+        service_name="VerificationKernelService",
+        consumes=[RawRTLTraceEvent, DriverTelemetryEvent],
+        produces=[CommitVerifiedEvent, VerificationResultEvent],
+    )
+
+    def __init__(self, context: RuntimeContext, publish_cb: Callable[[AnyEvent], object] | None = None):
+        self.context = context
+        self.publish_cb = publish_cb or context.publish
+        self.verified_count = 0
+
+    # -- Verification Domain (event.py hierarchy) --------------------------
+
+    def handle_raw_rtl_trace(self, event: RawRTLTraceEvent) -> None:
+        """Evaluates RTL trace frames against CommitContractV1 invariants."""
+        self.verified_count += 1
+        is_valid = True
+        failing_field = None
+
+        if event.eff_trap and event.trap_cause == 0:
+            is_valid = False
+            failing_field = "trap_cause"
+
+        verified_event = CommitVerifiedEvent(
+            parent_event_id=event.event_id,
+            root_event_id=event.root_event_id or event.event_id,
+            causation_id=event.event_id,
+            correlation_id=event.correlation_id,
+            session_id=event.session_id,
+            step=event.sequence_number,
+            verified=is_valid,
+            failing_field=failing_field,
+        )
+        self.publish_cb(verified_event)
+
+    # -- Kernel Runtime Domain (message.py hierarchy) ----------------------
+
+    def handle_telemetry(self, event: DriverTelemetryEvent) -> VerificationResultEvent:
+        """Evaluates driver telemetry against runtime safety invariants."""
+        self.verified_count += 1
+        raw_pos: object = event.payload.get("position", 0.0)
+        pos = float(str(raw_pos)) if isinstance(raw_pos, (int, float, str)) else 0.0
+        passed = abs(pos) <= 100.0
+
+        result = VerificationResultEvent(
+            causation_id=event.event_id,
+            correlation_id=event.correlation_id,
+            root_id=event.root_id,
+            passed=passed,
+            rule_id="BOUNDS_CHECK_V1",
+            metrics={"position": pos},
+        )
+        self.publish_cb(result)
+        return result

cortex/tools/kernel/transport.py

@@ -0,0 +1,50 @@
+"""
+Transport Layer Abstractions & InMemoryTransport Implementation
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+
+from cortex.compat import override
+from cortex.tools.kernel.schema.event import Event
+from cortex.tools.kernel.schema.message import BaseEvent
+
+AnyEvent = Event | BaseEvent
+EventHandler = Callable[[AnyEvent], None]
+
+class EventPublisher(ABC):
+    @abstractmethod
+    def publish(self, event: AnyEvent) -> None:
+        pass
+
+class EventSubscriber(ABC):
+    @abstractmethod
+    def subscribe(self, event_type: type[AnyEvent], handler: EventHandler) -> None:
+        pass
+
+class InMemoryTransport(EventPublisher, EventSubscriber):
+    _handlers: dict[type[AnyEvent], list[EventHandler]]
+    _history: list[AnyEvent]
+
+    def __init__(self):
+        self._handlers = {}
+        self._history = []
+
+    @override
+    def subscribe(self, event_type: type[AnyEvent], handler: EventHandler) -> None:
+        if event_type not in self._handlers:
+            self._handlers[event_type] = []
+        self._handlers[event_type].append(handler)
+
+    @override
+    def publish(self, event: AnyEvent) -> None:
+        self._history.append(event)
+        # Notify subscribers of exact type or wildcard Event base class
+        for event_cls, handlers in self._handlers.items():
+            if issubclass(type(event), event_cls):
+                for handler in handlers:
+                    handler(event)
+
+    def get_history(self) -> list[AnyEvent]:
+        return list(self._history)
+

cortex/tools/run_phase2_verification.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Cortex Spatiotemporal Authority Core — Phase 2 Audit Verification Runner
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+cd "${ROOT_DIR}"
+
+echo "[+] Building SystemVerilog RTL and C++ Testbench with Verilator..."
+make verilate
+
+echo "[+] Running Verilator RTL Simulation against canonical payload..."
+make run-rtl
+
+echo "[+] Running 3-Way Differential Trace Equivalence Verifier..."
+python3 cortex-emulator/tests/diff_harness.py \
+  Research/artifacts/phase2/coq_trace.json \
+  Research/artifacts/phase2/emulator_trace.json \
+  rtl_trace.json

cortex/tools/verification/__init__.py

@@ -0,0 +1,5 @@
+"""
+Cortex Verification Platform Core Package
+"""
+
+__version__ = "1.0.0"

cortex/tools/verification/adapters/__init__.py

@@ -0,0 +1,3 @@
+"""
+Trace Adapters for Coq, Rust, and SystemVerilog Execution Engines
+"""

cortex/tools/verification/adapters/base.py

@@ -0,0 +1,14 @@
+"""
+Abstract Base Adapter for Target Output Normalization
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from cortex.tools.verification.schema import CanonicalState
+
+
+class BaseAdapter(ABC):
+    @abstractmethod
+    def parse_trace(self, trace_input: Any) -> list[CanonicalState]:
+        """Converts raw engine trace into list of CanonicalState objects."""

cortex/tools/verification/adapters/coq.py

@@ -0,0 +1,73 @@
+"""
+Coq Operational Semantics Trace Adapter
+"""
+
+import json
+from typing import Any
+
+from cortex.tools.verification.adapters.base import BaseAdapter
+from cortex.tools.verification.schema import (
+    CanonicalState,
+    CanonicalSTCR,
+    CanonicalTrap,
+)
+
+
+class CoqAdapter(BaseAdapter):
+    def parse_trace(self, trace_input: Any) -> list[CanonicalState]:
+        if isinstance(trace_input, str):
+            with open(trace_input) as f:
+                data = json.load(f)
+        else:
+            data = trace_input
+
+        canonical_steps = []
+        for frame in data:
+            step_id = frame.get("step_id", frame.get("step", 0))
+            pc = frame.get("pc", 0)
+            reg_hec = frame.get("reg_hec", 0)
+            raw_inst = frame.get("instruction", {}).get("raw_hex", "0x00000000")
+
+            outcome = frame.get("outcome", {})
+            status = outcome.get("status", "OK")
+            is_trap = (status == "EFF_TRAP")
+            trap_cause_name = outcome.get("trap_cause", "None")
+            dest_val = outcome.get("dest_reg_val", 0)
+
+            # Map trap cause name to integer code
+            trap_codes = {
+                "None": 0,
+                "InsufficientSpatialRights": 1,
+                "EpochMismatch": 2,
+                "InvalidCapability": 3,
+                "IllegalInstruction": 15
+            }
+            cause_code = trap_codes.get(trap_cause_name, 1 if is_trap else 0)
+
+            stcr_list = []
+            for stcr in frame.get("stcr_file", []):
+                stcr_list.append(CanonicalSTCR(
+                    index=stcr.get("id", 0),
+                    valid=stcr.get("valid", False),
+                    permissions=stcr.get("spatial_mask", 0),
+                    base_address=stcr.get("base_address", 0),
+                    epoch=stcr.get("max_epoch", 0)
+                ))
+
+            canonical_steps.append(CanonicalState(
+                step=step_id,
+                pc=pc,
+                instruction=raw_inst,
+                privilege_mode="Machine",
+                reg_hec=reg_hec,
+                registers={"dest_val": f"0x{dest_val:016x}"},
+                stcr=stcr_list,
+                trap=CanonicalTrap(
+                    triggered=is_trap,
+                    cause_code=cause_code,
+                    cause_name=trap_cause_name,
+                    trap_val=dest_val
+                )
+            ))
+
+        return canonical_steps

cortex/tools/verification/adapters/rtl.py

@@ -0,0 +1,77 @@
+"""
+Verilator SystemVerilog RTL Trace Adapter
+"""
+
+import json
+from typing import Any
+
+from cortex.tools.verification.adapters.base import BaseAdapter
+from cortex.tools.verification.schema import (
+    CanonicalState,
+    CanonicalSTCR,
+    CanonicalTrap,
+)
+
+
+class RTLAdapter(BaseAdapter):
+    def parse_trace(self, trace_input: Any) -> list[CanonicalState]:
+        if isinstance(trace_input, str):
+            with open(trace_input) as f:
+                data = json.load(f)
+        else:
+            data = trace_input
+
+        frames = data.get("trace", data) if isinstance(data, dict) else data
+
+        canonical_steps = []
+        for frame in frames:
+            step_id = frame.get("step", 0)
+            pc = frame.get("pc", 0)
+            reg_hec = frame.get("reg_hec", 0)
+            raw_inst = frame.get("raw_instruction", "0x00000000")
+            is_trap = frame.get("eff_trap", False)
+            cause_code = frame.get("trap_cause", 0)
+
+            cause_names = {
+                0: "None",
+                1: "InsufficientSpatialRights",
+                2: "EpochMismatch",
+                3: "InvalidCapability",
+                15: "IllegalInstruction"
+            }
+            cause_name = cause_names.get(cause_code, "UnknownTrap" if is_trap else "None")
+
+            stcr_list = []
+            raw_stcr_array = frame.get("stcr_registers", [])
+            for reg_id, raw_hex in enumerate(raw_stcr_array):
+                val = int(raw_hex, 16) if isinstance(raw_hex, str) else raw_hex
+                valid = bool((val >> 63) & 1)
+                perms = (val >> 48) & 0x7FFF
+                base = (val >> 16) & 0xFFFFFFFF
+                epoch = val & 0xFFFF
+
+                stcr_list.append(CanonicalSTCR(
+                    index=reg_id,
+                    valid=valid,
+                    permissions=perms,
+                    base_address=base,
+                    epoch=epoch
+                ))
+
+            canonical_steps.append(CanonicalState(
+                step=step_id,
+                pc=pc,
+                instruction=raw_inst,
+                privilege_mode="Machine",
+                reg_hec=reg_hec,
+                registers={},
+                stcr=stcr_list,
+                trap=CanonicalTrap(
+                    triggered=is_trap,
+                    cause_code=cause_code,
+                    cause_name=cause_name,
+                    trap_val=0
+                )
+            ))
+
+        return canonical_steps

cortex/tools/verification/adapters/rust.py

@@ -0,0 +1,72 @@
+"""
+Rust Reference Emulator Trace Adapter
+"""
+
+import json
+from typing import Any
+
+from cortex.tools.verification.adapters.base import BaseAdapter
+from cortex.tools.verification.schema import (
+    CanonicalState,
+    CanonicalSTCR,
+    CanonicalTrap,
+)
+
+
+class RustAdapter(BaseAdapter):
+    def parse_trace(self, trace_input: Any) -> list[CanonicalState]:
+        if isinstance(trace_input, str):
+            with open(trace_input) as f:
+                data = json.load(f)
+        else:
+            data = trace_input
+
+        canonical_steps = []
+        for frame in data:
+            step_id = frame.get("step_id", frame.get("step", 0))
+            pc = frame.get("pc", 0)
+            reg_hec = frame.get("reg_hec", 0)
+            raw_inst = frame.get("instruction", {}).get("raw_hex", "0x00000000")
+
+            outcome = frame.get("outcome", {})
+            status = outcome.get("status", "OK")
+            is_trap = (status == "EFF_TRAP")
+            trap_cause_name = outcome.get("trap_cause", "None")
+            dest_val = outcome.get("dest_reg_val", 0)
+
+            trap_codes = {
+                "None": 0,
+                "InsufficientSpatialRights": 1,
+                "EpochMismatch": 2,
+                "InvalidCapability": 3,
+                "IllegalInstruction": 15
+            }
+            cause_code = trap_codes.get(trap_cause_name, 1 if is_trap else 0)
+
+            stcr_list = []
+            for stcr in frame.get("stcr_file", []):
+                stcr_list.append(CanonicalSTCR(
+                    index=stcr.get("id", 0),
+                    valid=stcr.get("valid", False),
+                    permissions=stcr.get("spatial_mask", 0),
+                    base_address=stcr.get("base_address", 0),
+                    epoch=stcr.get("max_epoch", 0)
+                ))
+
+            canonical_steps.append(CanonicalState(
+                step=step_id,
+                pc=pc,
+                instruction=raw_inst,
+                privilege_mode="Machine",
+                reg_hec=reg_hec,
+                registers={"dest_val": f"0x{dest_val:016x}"},
+                stcr=stcr_list,
+                trap=CanonicalTrap(
+                    triggered=is_trap,
+                    cause_code=cause_code,
+                    cause_name=trap_cause_name,
+                    trap_val=dest_val
+                )
+            ))
+
+        return canonical_steps

cortex/tools/verification/archive.py

@@ -0,0 +1,58 @@
+"""
+Index-backed Counterexample Database Archiver
+"""
+
+import hashlib
+import json
+import os
+from typing import Any
+
+
+class CounterexampleArchive:
+    def __init__(self, archive_dir: str = "artifacts/counterexamples/"):
+        self.archive_dir = archive_dir
+        self.index_path = os.path.join(self.archive_dir, "index.json")
+        os.makedirs(self.archive_dir, exist_ok=True)
+        if not os.path.exists(self.index_path):
+            with open(self.index_path, "w") as f:
+                json.dump({"counterexamples": []}, f, indent=2)
+
+    def archive_failure(
+        self,
+        scenario: dict[str, Any],
+        diagnostic: dict[str, Any],
+        seed: str,
+        commit_id: str = "a484b94"
+    ) -> str:
+        payload_str = json.dumps(scenario, sort_keys=True).encode("utf-8")
+        entry_hash = hashlib.sha256(payload_str).hexdigest()[:12]
+
+        case_dir = os.path.join(self.archive_dir, entry_hash)
+        os.makedirs(case_dir, exist_ok=True)
+
+        case_file = os.path.join(case_dir, "scenario.json")
+        diag_file = os.path.join(case_dir, "diagnostic.json")
+
+        with open(case_file, "w") as f:
+            json.dump(scenario, f, indent=2)
+
+        with open(diag_file, "w") as f:
+            json.dump(diagnostic, f, indent=2)
+
+        # Update index.json
+        with open(self.index_path, "r") as f:
+            index_data = json.load(f)
+
+        index_data["counterexamples"].append({
+            "hash": entry_hash,
+            "seed": seed,
+            "commit_id": commit_id,
+            "error_type": diagnostic.get("error_type", "Unknown"),
+            "mismatched_field": diagnostic.get("mismatched_field", "Unknown"),
+            "failing_step": diagnostic.get("failing_step", 0)
+        })
+
+        with open(self.index_path, "w") as f:
+            json.dump(index_data, f, indent=2)
+
+        return entry_hash

cortex/tools/verification/bus.py

@@ -0,0 +1,28 @@
+"""
+Typed Append-Only Event Bus for Broadcasting Immutable CommitEventV1 Instances
+"""
+
+from collections.abc import Callable
+
+from cortex.tools.verification.schema.event import CommitEventV1
+
+SubscriberCallback = Callable[[CommitEventV1], None]
+
+class EventBus:
+    def __init__(self):
+        self._subscribers: list[SubscriberCallback] = []
+        self._history: list[CommitEventV1] = []
+
+    def subscribe(self, callback: SubscriberCallback) -> None:
+        self._subscribers.append(callback)
+
+    def publish(self, event: CommitEventV1) -> None:
+        self._history.append(event)
+        for subscriber in self._subscribers:
+            subscriber(event)
+
+    def get_history(self) -> list[CommitEventV1]:
+        return list(self._history)
+
+    def clear(self) -> None:
+        self._history.clear()