cortex-runtime 0.2.0__py3-none-any.whl

cortex/tools/kernel/graph/analyzer.py

@@ -0,0 +1,52 @@
+"""
+Execution Graph Query, Root-Cause Analysis & Divergence Detection Engine
+"""
+
+from cortex.tools.kernel.graph.execution_graph import ExecutionGraph, GraphNode
+
+
+class ExecutionGraphAnalyzer:
+    """Provides analytical, root-cause, and graph-differencing capabilities."""
+    graph: ExecutionGraph
+
+    def __init__(self, graph: ExecutionGraph):
+        self.graph = graph
+
+    def find_root_cause(self, node_id: str) -> list[GraphNode]:
+        """Traverses upstream parent pointers to trace lineage back to the root Intent."""
+        path: list[GraphNode] = []
+        current_id: str | None = node_id
+
+        while current_id and current_id in self.graph.nodes:
+            node = self.graph.nodes[current_id]
+            path.append(node)
+            current_id = node.parent_id
+
+        return path
+
+    def filter_by_type(self, node_type: str) -> list[GraphNode]:
+        """Returns all nodes matching the specified type."""
+        return [node for node in self.graph.nodes.values() if node.node_type == node_type]
+
+    def find_failed_nodes(self) -> list[GraphNode]:
+        """Finds any Verification node where passed == False."""
+        failed: list[GraphNode] = []
+        for node in self.graph.nodes.values():
+            if node.node_type == "Verification" and not node.payload.get("passed", True):
+                failed.append(node)
+        return failed
+
+    @staticmethod
+    def diff_graphs(golden: ExecutionGraph, candidate: ExecutionGraph) -> dict[str, object]:
+        """Compares a golden reference graph against a candidate execution graph."""
+        golden_node_types = [n.node_type for n in golden.nodes.values()]
+        candidate_node_types = [n.node_type for n in candidate.nodes.values()]
+
+        node_count_diff = len(candidate.nodes) - len(golden.nodes)
+        missing_types = [t for t in golden_node_types if t not in candidate_node_types]
+
+        return {
+            "identical_structure": len(golden.nodes) == len(candidate.nodes) and not missing_types,
+            "node_count_diff": node_count_diff,
+            "missing_node_types": missing_types
+        }

cortex/tools/kernel/graph/execution_graph.py

@@ -0,0 +1,44 @@
+"""
+Real-Time Causal Execution Graph Representation & Tree Renderer
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class GraphNode:
+    node_id: str
+    node_type: str
+    payload: dict[str, object]
+    parent_id: str | None = None
+    children: list[str] = field(default_factory=list)
+
+class ExecutionGraph:
+    """First-class Causal Execution Graph representation."""
+    root_id: str
+    nodes: dict[str, GraphNode]
+
+    def __init__(self, root_id: str):
+        self.root_id = root_id
+        self.nodes = {}
+
+    def add_node(self, node_id: str, node_type: str, payload: dict[str, object], parent_id: str | None = None) -> None:
+        node = GraphNode(node_id=node_id, node_type=node_type, payload=payload, parent_id=parent_id)
+        self.nodes[node_id] = node
+        if parent_id and parent_id in self.nodes:
+            self.nodes[parent_id].children.append(node_id)
+
+    def render_tree(self, current_id: str | None = None, depth: int = 0) -> str:
+        """Renders an ASCII tree representation of the execution lineage."""
+        if current_id is None:
+            current_id = self.root_id
+        if current_id not in self.nodes:
+            return ""
+
+        node = self.nodes[current_id]
+        indent = "  " * depth
+        prefix = "└── " if depth > 0 else ""
+        result = f"{indent}{prefix}[{node.node_type}] ID: {node.node_id[:8]}.. | Details: {node.payload}\n"
+        for child_id in node.children:
+            result += self.render_tree(child_id, depth + 1)
+        return result

cortex/tools/kernel/mailbox.py

@@ -0,0 +1,35 @@
+"""
+Bounded, Priority-Aware Mailbox for Kernel Actors
+"""
+
+import heapq
+
+
+class Mailbox:
+    capacity: int
+    _queue: list[tuple[int, int, object]]
+    _counter: int
+
+    def __init__(self, capacity: int = 1000):
+        self.capacity = capacity
+        self._queue = []
+        self._counter = 0
+
+    def push(self, message: object, priority: int = 10) -> bool:
+        if len(self._queue) >= self.capacity:
+            return False
+        self._counter += 1
+        heapq.heappush(self._queue, (priority, self._counter, message))
+        return True
+
+    def pop(self) -> object | None:
+        if not self._queue:
+            return None
+        _, _, message = heapq.heappop(self._queue)
+        return message
+
+    def is_empty(self) -> bool:
+        return len(self._queue) == 0
+
+    def size(self) -> int:
+        return len(self._queue)

cortex/tools/kernel/plugin/__init__.py

@@ -0,0 +1,3 @@
+"""
+Kernel Plugin Runtime & Capability Negotiation
+"""

cortex/tools/kernel/plugin/loader.py

@@ -0,0 +1,87 @@
+"""
+Plugin Loader & Capability Negotiation Engine
+
+Enforces the security boundary between plugins and the Kernel Core.
+Plugins receive only the Resource Handles and Runtime Context scoped
+to their declared capabilities — never raw kernel internals.
+"""
+
+import enum
+from dataclasses import dataclass, field
+
+from cortex.tools.kernel.plugin.manifest import PluginManifest
+
+
+class PluginState(str, enum.Enum):
+    REGISTERED = "REGISTERED"
+    NEGOTIATING = "NEGOTIATING"
+    ACTIVE = "ACTIVE"
+    REJECTED = "REJECTED"
+    SUSPENDED = "SUSPENDED"
+
+
+@dataclass
+class PluginRegistration:
+    """Runtime representation of a loaded plugin."""
+    manifest: PluginManifest
+    state: PluginState = PluginState.REGISTERED
+    granted_capabilities: set[str] = field(default_factory=set)
+    denied_capabilities: list[str] = field(default_factory=list)
+
+
+class CapabilityNegotiator:
+    """Evaluates plugin capability requests against the platform's
+    available capability set and security policy."""
+    platform_capabilities: set[str]
+
+    def __init__(self, platform_capabilities: set[str]):
+        self.platform_capabilities = platform_capabilities
+
+    def negotiate(self, manifest: PluginManifest) -> PluginRegistration:
+        """Evaluates a plugin manifest and returns a PluginRegistration
+        with granted/denied capability sets."""
+        registration = PluginRegistration(manifest=manifest, state=PluginState.NEGOTIATING)
+
+        granted: set[str] = set()
+        denied: list[str] = []
+
+        for cap in manifest.required_capabilities:
+            if cap in self.platform_capabilities:
+                granted.add(cap)
+            else:
+                denied.append(cap)
+
+        registration.granted_capabilities = granted
+        registration.denied_capabilities = denied
+
+        if denied:
+            registration.state = PluginState.REJECTED
+        else:
+            registration.state = PluginState.ACTIVE
+
+        return registration
+
+
+class PluginRegistry:
+    """Manages the lifecycle of all registered plugins."""
+    negotiator: CapabilityNegotiator
+    _plugins: dict[str, PluginRegistration]
+
+    def __init__(self, platform_capabilities: set[str]):
+        self.negotiator = CapabilityNegotiator(platform_capabilities)
+        self._plugins = {}
+
+    def register(self, manifest: PluginManifest) -> PluginRegistration:
+        """Register a plugin via manifest. Returns the negotiation result."""
+        registration = self.negotiator.negotiate(manifest)
+        self._plugins[manifest.name] = registration
+        return registration
+
+    def get_plugin(self, name: str) -> PluginRegistration | None:
+        return self._plugins.get(name)
+
+    def get_active_plugins(self) -> list[PluginRegistration]:
+        return [p for p in self._plugins.values() if p.state == PluginState.ACTIVE]
+
+    def get_rejected_plugins(self) -> list[PluginRegistration]:
+        return [p for p in self._plugins.values() if p.state == PluginState.REJECTED]

cortex/tools/kernel/plugin/manifest.py

@@ -0,0 +1,53 @@
+"""
+Declarative Plugin Manifest Schema
+
+Every plugin declares its event consumption/production contract and the
+kernel capabilities it requires.  The Kernel enforces capability negotiation
+at registration time — no raw access to internals is ever granted.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class PluginManifest:
+    """Immutable declaration of a plugin's identity, event contract,
+    and required kernel capabilities."""
+    name: str
+    version: str
+    description: str
+    consumes_events: list[str] = field(default_factory=list)
+    produces_events: list[str] = field(default_factory=list)
+    required_capabilities: list[str] = field(default_factory=list)
+
+
+# -----------------------------------------------------------------------
+# Reference Manifests — canonical examples of domain plugin declarations
+# -----------------------------------------------------------------------
+
+ROBOT_ARM_MANIFEST = PluginManifest(
+    name="robot-arm-driver",
+    version="0.1.0",
+    description="Interface for 6-DOF industrial robot arm",
+    consumes_events=["CommandIssuedEvent"],
+    produces_events=["DriverTelemetryEvent"],
+    required_capabilities=["hardware.actuators.execute", "hardware.telemetry.read"],
+)
+
+AGENT_PLANNER_MANIFEST = PluginManifest(
+    name="llm-task-planner",
+    version="0.1.0",
+    description="Decomposes goal intents into step-wise plans",
+    consumes_events=["IntentEvent"],
+    produces_events=["PlanGeneratedEvent"],
+    required_capabilities=["workflow.plan.create"],
+)
+
+VERIFICATION_SERVICE_MANIFEST = PluginManifest(
+    name="verification-service",
+    version="0.1.0",
+    description="Formal verification oracle for CommitContractV1",
+    consumes_events=["DriverTelemetryEvent", "CommitEventV1"],
+    produces_events=["VerificationResultEvent"],
+    required_capabilities=["verification.oracle.execute", "verification.invariant.check"],
+)

cortex/tools/kernel/registry.py

@@ -0,0 +1,36 @@
+"""
+Object Registry & Resource Handle Management
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Capability:
+    name: str
+
+@dataclass(frozen=True)
+class ResourceHandle:
+    handle_id: str
+    resource_type: str
+    capabilities: set[Capability]
+
+class ObjectRegistry:
+    _actors: dict[str, object]
+    _handles: dict[str, ResourceHandle]
+
+    def __init__(self):
+        self._actors = {}
+        self._handles = {}
+
+    def register_actor(self, actor_id: str, actor_instance: object) -> None:
+        self._actors[actor_id] = actor_instance
+
+    def get_actor(self, actor_id: str) -> object | None:
+        return self._actors.get(actor_id)
+
+    def register_handle(self, handle: ResourceHandle) -> None:
+        self._handles[handle.handle_id] = handle
+
+    def get_handle(self, handle_id: str) -> ResourceHandle | None:
+        return self._handles.get(handle_id)

cortex/tools/kernel/schema/__init__.py

@@ -0,0 +1,3 @@
+"""
+Kernel Schema & Domain Event Hierarchy
+"""

cortex/tools/kernel/schema/contract.py

@@ -0,0 +1,16 @@
+"""
+Kernel Service Declarative Contracts
+"""
+
+from dataclasses import dataclass
+
+from cortex.tools.kernel.schema.event import Event
+from cortex.tools.kernel.schema.message import BaseEvent
+
+
+@dataclass(frozen=True)
+class ServiceContract:
+    """Contract advertising event types consumed and produced by a Kernel Service."""
+    service_name: str
+    consumes: list[type[Event | BaseEvent]]
+    produces: list[type[Event | BaseEvent]]

cortex/tools/kernel/schema/event.py

@@ -0,0 +1,54 @@
+"""
+Domain Event Hierarchy for Cortex Kernel Runtime
+"""
+
+import time
+import uuid
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Event:
+    """Universal Base Envelope for Kernel Runtime IPC Events."""
+    event_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    parent_event_id: str | None = None
+    root_event_id: str | None = None
+    causation_id: str | None = None
+    correlation_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    session_id: str = ""
+    sequence_number: int = 0
+    timestamp_ns: int = field(default_factory=lambda: time.time_ns())
+
+@dataclass(frozen=True)
+class VerificationEvent(Event):
+    """Event category for hardware, formal, and simulation correctness."""
+
+@dataclass(frozen=True)
+class RawRTLTraceEvent(VerificationEvent):
+    """Raw telemetry frame emitted by hardware drivers or Verilator simulators."""
+    pc: int = 0
+    raw_instruction: str = ""
+    eff_trap: bool = False
+    trap_cause: int = 0
+    stcr_registers: dict[int, str] = field(default_factory=dict)
+
+@dataclass(frozen=True)
+class CommitVerifiedEvent(VerificationEvent):
+    """Domain decision event emitted after formal oracle state verification."""
+    step: int = 0
+    verified: bool = True
+    failing_field: str | None = None
+
+@dataclass(frozen=True)
+class MotorFeedbackEvent(Event):
+    """Driver raw telemetry event for physical or mock actuators."""
+    actuator_id: str = ""
+    position: float = 0.0
+    velocity: float = 0.0
+
+@dataclass(frozen=True)
+class InferenceCompletedEvent(Event):
+    """LLM agent or inference engine response event."""
+    agent_id: str = ""
+    prompt_tokens: int = 0
+    completion: str = ""

cortex/tools/kernel/schema/message.py

@@ -0,0 +1,105 @@
+"""
+Unified Control & Execution Message Hierarchy for Cortex Kernel Runtime
+
+Domain-Agnostic Event Taxonomy:
+    BaseEvent (universal envelope with workflow_id tracing)
+    ├── IntentEvent          (User/System goal request)
+    ├── PlanGeneratedEvent   (Agent planner output)
+    ├── CommandIssuedEvent   (Executor dispatch)
+    ├── DriverTelemetryEvent (Hardware/Simulator feedback)
+    ├── VerificationResultEvent (Contract assertion result)
+    └── CommitEventV1        (Verification Substrate only — domain-isolated)
+"""
+
+import time
+import uuid
+from dataclasses import dataclass, field
+
+# ---------------------------------------------------------------------------
+# Base Envelope
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BaseEvent:
+    """Universal event envelope carrying identity, workflow correlation,
+    and causal lineage metadata."""
+
+    event_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    workflow_id: str | None = None
+    causation_id: str | None = None
+    correlation_id: str = ""
+    root_id: str = ""
+    timestamp_ns: int = field(default_factory=lambda: time.time_ns())
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Universal Kernel & Domain Events
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class IntentEvent(BaseEvent):
+    """Represents WHAT is desired (Goal / Action Request)."""
+
+    intent_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    session_id: str = ""
+    goal: str = ""
+    parameters: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class PlanGeneratedEvent(BaseEvent):
+    """Represents HOW the Intent is decomposed into structured steps."""
+
+    plan_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    intent_id: str = ""
+    steps: list[dict[str, object]] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class CommandIssuedEvent(BaseEvent):
+    """Represents EXECUTE THIS SINGLE OPERATION."""
+
+    command_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    plan_id: str = ""
+    action: str = ""
+    parameters: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class DriverTelemetryEvent(BaseEvent):
+    """Raw execution feedback from hardware, tools, or RTL models."""
+
+    driver_id: str = ""
+    status: str = "ok"
+    payload: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class VerificationResultEvent(BaseEvent):
+    """Verification/Invariant evaluation result derived from Telemetry."""
+
+    passed: bool = True
+    rule_id: str = ""
+    details: dict[str, object] = field(default_factory=dict)
+    metrics: dict[str, object] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Domain-Specific: Verification Substrate (Isolated to Verification Domain)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CommitEventV1(BaseEvent):
+    """Immutable architectural commit event scoped exclusively to the
+    formal verification service pipeline (Coq / Rust / RTL oracles)."""
+
+    cycle: int = 0
+    pc: int = 0
+    instruction: int = 0
+    register_writes: dict[str, int] = field(default_factory=dict)
+    memory_writes: dict[str, object] = field(default_factory=dict)
+    exception_code: int | None = None

cortex/tools/kernel/schema/workflow.py

@@ -0,0 +1,38 @@
+"""
+First-Class Workflow Primitive & Policy Schema
+"""
+
+import enum
+import time
+import uuid
+from dataclasses import dataclass, field
+
+
+class WorkflowState(str, enum.Enum):
+    PENDING = "PENDING"
+    RUNNING = "RUNNING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    ABORTED = "ABORTED"
+
+
+@dataclass
+class WorkflowPolicy:
+    timeout_seconds: float = 300.0
+    max_retries: int = 3
+    abort_on_verification_failure: bool = True
+
+
+@dataclass
+class Workflow:
+    """First-class runtime unit of execution encapsulating autonomous lifecycles."""
+
+    workflow_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    name: str = "default_workflow"
+    goal: str = ""
+    state: WorkflowState = WorkflowState.PENDING
+    policy: WorkflowPolicy = field(default_factory=WorkflowPolicy)
+    root_intent_id: str | None = None
+    execution_graph_id: str | None = None
+    created_at_ns: int = field(default_factory=lambda: time.time_ns())
+    metadata: dict[str, object] = field(default_factory=dict)

cortex/tools/kernel/services/__init__.py

@@ -0,0 +1,3 @@
+"""
+Kernel Services Layer
+"""

cortex/tools/kernel/services/event_store.py

@@ -0,0 +1,25 @@
+"""
+Event Store & Audit Journal Kernel Service
+"""
+
+from cortex.tools.kernel.schema.contract import ServiceContract
+from cortex.tools.kernel.transport import AnyEvent
+
+
+class EventStoreService:
+    _log: list[AnyEvent]
+
+    contract: ServiceContract = ServiceContract(
+        service_name="EventStoreService",
+        consumes=[],
+        produces=[],
+    )
+
+    def __init__(self) -> None:
+        self._log = []
+
+    def record_event(self, event: AnyEvent) -> None:
+        self._log.append(event)
+
+    def get_log(self) -> list[AnyEvent]:
+        return list(self._log)

cortex/tools/kernel/services/execution_intelligence.py

@@ -0,0 +1,49 @@
+"""
+Execution Intelligence & Causal Explainer Kernel Service
+"""
+
+from cortex.tools.kernel.graph.execution_graph import ExecutionGraph, GraphNode
+
+
+class CausalExplainer:
+    """Analyzes an ExecutionGraph to provide root-cause diagnostics and lineage traces."""
+    graph: ExecutionGraph
+
+    def __init__(self, graph: ExecutionGraph):
+        self.graph = graph
+
+    def explain_failure(self, failed_node_id: str) -> dict[str, object]:
+        """Traverses backwards up the causal chain to locate the root cause of a failure."""
+        if failed_node_id not in self.graph.nodes:
+            return {"error": "Node not found"}
+
+        chain: list[GraphNode] = []
+        curr: str | None = failed_node_id
+
+        while curr and curr in self.graph.nodes:
+            node = self.graph.nodes[curr]
+            chain.append(node)
+            curr = node.parent_id
+
+        chain.reverse()
+
+        return {
+            "target_node": failed_node_id,
+            "root_intent": chain[0].payload if chain else None,
+            "causal_path": [
+                {
+                    "node_id": n.node_id,
+                    "type": n.node_type,
+                    "summary": n.payload
+                } for n in chain
+            ],
+            "diagnosis": self._derive_diagnosis(chain)
+        }
+
+    def _derive_diagnosis(self, chain: list[GraphNode]) -> str:
+        for node in reversed(chain):
+            if node.node_type == "Verification" and not node.payload.get("passed", True):
+                return f"Verification assertion failed at rule '{node.payload.get('rule')}'."
+            if node.node_type == "Telemetry" and node.payload.get("status") != "ok":
+                return f"Driver reported error status '{node.payload.get('status')}' during command execution."
+        return "Unknown failure cause."