cortex-runtime 0.2.0__tar.gz → 0.2.1__tar.gz

cortex_runtime-0.2.1/NOTICE

@@ -0,0 +1,9 @@
+Cortex
+Copyright 2024-2026 Iradukunda Fils
+
+This product is licensed under the Apache License, Version 2.0 (the "License").
+You may obtain a copy of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+This product includes software developed by Iradukunda Fils.

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-runtime
-Version: 0.2.0
+Version: 0.2.1
 Summary: Spatiotemporal authority and semantic verification framework for autonomous workflows
 Project-URL: Homepage, https://github.com/Iradukunda-Fils/Cortex
 Project-URL: Documentation, https://github.com/Iradukunda-Fils/Cortex#readme
@@ -9,6 +9,7 @@ Project-URL: Issues, https://github.com/Iradukunda-Fils/Cortex/issues
 Author: Iradukunda Fils
 License: Apache-2.0
 License-File: LICENSE
+License-File: NOTICE
 Keywords: agents,architecture,capability-security,sandbox,spatiotemporal,verification,workflow
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -18,6 +19,8 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Distributed Computing
@@ -27,10 +30,9 @@ Requires-Dist: pyyaml<7.0.0,>=6.0.0
 Requires-Dist: typing-extensions>=4.5.0
 Provides-Extra: dev
 Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
 Requires-Dist: pyright>=1.1.0; extra == 'dev'
-Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
-Requires-Dist: twine>=4.0.0; extra == 'dev'
 Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/__init__.py

@@ -6,6 +6,7 @@ workflow boundary management, sandboxed capability negotiation, and verification
 """
 
 from cortex.client import CortexClient
+from cortex.compat import override
 from cortex.exceptions import (
     CapabilityViolationError,
     CortexError,
@@ -48,4 +49,5 @@ __all__ = [
     "WorkflowExecutionError",
     "WorkflowPolicy",
     "WorkflowState",
+    "override",
 ]

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/client.py

@@ -76,6 +76,12 @@ class CortexClient:
 
     def register_plugin(self, plugin: BasePlugin) -> PluginRegistration:
         """Register a plugin with capability negotiation."""
+        # Prevent duplicate transport subscriptions if exact plugin instance is re-registered
+        if plugin in self.registered_plugins:
+            existing = self.registry.get_plugin(plugin.manifest.name)
+            if existing:
+                return existing
+
         registration = self.registry.register(plugin.manifest)
         if registration.state == PluginState.ACTIVE:
             context = PluginContext(
@@ -99,7 +105,23 @@ class CortexClient:
     def _dispatch_to_plugin(self, plugin: BasePlugin, event: AnyEvent) -> None:
         """Helper to safely dispatch event to plugin if active and consuming."""
         if plugin.context and isinstance(event, BaseEvent) and type(event).__name__ in plugin.manifest.consumes_events:
-            plugin.on_event(event)
+            try:
+                plugin.on_event(event)
+            except Exception as err:
+                failure_event = VerificationResultEvent(
+                    workflow_id=event.workflow_id,
+                    causation_id=event.event_id,
+                    passed=False,
+                    rule_id="PLUGIN_EXECUTION_ERROR",
+                    details={
+                        "plugin": plugin.manifest.name,
+                        "error_type": type(err).__name__,
+                        "error_message": str(err),
+                        "consumed_event_id": event.event_id,
+                        "consumed_event_type": type(event).__name__,
+                    },
+                )
+                self.transport.publish(failure_event)
 
     def create_workflow(self, name: str, goal: str, policy: WorkflowPolicy | None = None) -> Workflow:
         """Instantiate a new Workflow primitive."""

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/compat.py

@@ -2,14 +2,15 @@
 Zero-dependency compatibility helpers for Python 3.10+
 """
 
+import sys
 from collections.abc import Callable
 from typing import TypeVar
 
 F = TypeVar("F", bound=Callable[..., object])
 
-try:
-    from typing import override as override  # type: ignore[attr-defined]
-except ImportError:
+if sys.version_info >= (3, 12):
+    from typing import override as override
+else:
     try:
         from typing_extensions import override as override  # type: ignore[no-redef]
     except ImportError:
@@ -18,3 +19,4 @@ except ImportError:
 
 
 __all__ = ["override"]
+

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/__init__.py

@@ -1,3 +1,5 @@
 """
 Cortex Developer Tools and Verification Services Package
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/cli/__init__.py

@@ -1,3 +1,5 @@
 """
 Cortex Developer CLI Package
 """
+
+__all__: list[str] = []

cortex_runtime-0.2.1/cortex/tools/cli/main.py

@@ -0,0 +1,233 @@
+"""
+Cortex Developer CLI Command Entrypoint
+
+Usage:
+    cortex init <project_name> [--type {app|plugin}] [--json]
+    cortex workflow run <workflow_file> [--output <file>] [--json]
+    cortex workflow inspect <workflow_id_or_file> [--json]
+    cortex workflow replay <workflow_id_or_file> [--json]
+"""
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Sequence
+from typing import cast
+
+from cortex.exceptions import (
+    CapabilityViolationError,
+    CortexError,
+    ManifestError,
+    WorkflowExecutionError,
+)
+from cortex.tools.cli.runner import inspect_workflow, replay_workflow, run_workflow_file
+from cortex.tools.cli.scaffolder import scaffold_project
+
+
+def _handle_cli_error(err: Exception, json_mode: bool = False) -> int:
+    """Standardized CLI error renderer and exit code mapper.
+
+    Outputs formatted diagnostic blocks or machine JSON strictly to sys.stderr.
+    """
+    if isinstance(err, CapabilityViolationError):
+        error_code = "CAPABILITY_VIOLATION"
+        exit_code = err.exit_code  # 2
+        message = err.message
+        cause = f"Action requested capability '{err.capability}' which was denied or not declared."
+        remediation = f"Add capability '{err.capability}' to required_capabilities in your plugin manifest."
+        details: dict[str, object] | None = {"capability": err.capability} if err.capability else None
+    elif isinstance(err, ManifestError):
+        error_code = "INVALID_MANIFEST"
+        exit_code = err.exit_code  # 3
+        message = err.message
+        cause = "Plugin manifest failed structural validation checks."
+        remediation = "Ensure plugin manifest contains non-empty 'name', 'version', and valid collections."
+        details = None
+    elif isinstance(err, WorkflowExecutionError):
+        error_code = "WORKFLOW_FAILED"
+        exit_code = err.exit_code  # 1
+        message = err.message
+        cause = "Workflow execution was aborted or failed verification checks."
+        remediation = "Inspect trace log using 'cortex workflow inspect <trace>' for failed verification nodes."
+        details = {"workflow_id": err.workflow_id} if err.workflow_id else None
+    elif isinstance(err, CortexError):
+        error_code = "CORTEX_ERROR"
+        exit_code = err.exit_code  # 1
+        message = err.message
+        cause = "Cortex framework error occurred."
+        remediation = "Verify workflow specification and input parameters."
+        details = None
+    else:
+        error_code = "GENERAL_ERROR"
+        exit_code = getattr(os, "EX_SOFTWARE", 1)
+        message = str(err) or "An unexpected runtime error occurred."
+        cause = f"Uncaught exception of type '{type(err).__name__}'."
+        remediation = "Check environment setup, dependencies, and command line arguments."
+        details = {"error_type": type(err).__name__}
+
+    if json_mode:
+        payload: dict[str, object] = {
+            "status": "error",
+            "error_code": error_code,
+            "exit_code": exit_code,
+            "message": message,
+            "cause": cause,
+            "remediation": remediation,
+        }
+        if details is not None:
+            payload["details"] = details
+        print(json.dumps(payload, indent=2), file=sys.stderr)
+    else:
+        print("=================================================================", file=sys.stderr)
+        print("               CORTEX CLI DIAGNOSTIC ERROR REPORT                ", file=sys.stderr)
+        print("=================================================================", file=sys.stderr)
+        print(f"[!] ERROR CODE:   {error_code} (Exit Code {exit_code})", file=sys.stderr)
+        print(f"[!] MESSAGE:      {message}", file=sys.stderr)
+        print(f"[!] CAUSE:        {cause}", file=sys.stderr)
+        print(f"[!] REMEDIATION:  {remediation}", file=sys.stderr)
+        print("=================================================================", file=sys.stderr)
+
+    return exit_code
+
+
+def cli_entrypoint() -> None:
+    """Console script entrypoint for PyPI cortex-runtime executable."""
+    sys.exit(main())
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Main CLI entrypoint for Cortex framework."""
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="cortex",
+        description="Cortex Platform Developer CLI & Workflow Engine",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output machine-readable JSON format",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    # cortex init
+    init_parser = subparsers.add_parser("init", help="Scaffold a new Cortex plugin or application")
+    _ = init_parser.add_argument("project_name", help="Name of the project directory to create")
+    _ = init_parser.add_argument(
+        "--type",
+        choices=["app", "plugin"],
+        default="app",
+        help="Type of project to scaffold (default: app)",
+    )
+
+    # cortex workflow
+    wf_parser = subparsers.add_parser("workflow", help="Workflow execution and inspection management")
+    wf_sub = wf_parser.add_subparsers(dest="wf_command", help="Workflow subcommand")
+
+    # cortex workflow run
+    wf_run = wf_sub.add_parser("run", help="Trigger workflow execution from spec file")
+    _ = wf_run.add_argument("workflow_file", help="Path to workflow definition JSON file")
+    _ = wf_run.add_argument("--output", "-o", help="Optional path to save event journal JSON trace")
+
+    # cortex workflow inspect
+    wf_inspect = wf_sub.add_parser("inspect", help="Inspect execution graph and lineage for workflow ID or file")
+    _ = wf_inspect.add_argument("workflow_id", help="Workflow ID or path to event trace JSON file")
+
+    # cortex workflow replay
+    wf_replay = wf_sub.add_parser("replay", help="Deterministically replay workflow execution trace")
+    _ = wf_replay.add_argument("workflow_id", help="Workflow ID or path to event trace JSON file")
+
+    args = parser.parse_args(argv)
+    cmd = str(getattr(args, "command", ""))
+    wf_cmd = str(getattr(args, "wf_command", ""))
+    json_mode = bool(getattr(args, "json", False))
+
+    try:
+        if cmd == "init":
+            p_name = str(getattr(args, "project_name", "my_cortex_app"))
+            p_type = str(getattr(args, "type", "app"))
+            path = scaffold_project(p_name, project_type=p_type)
+            if json_mode:
+                print(json.dumps({"status": "success", "command": "init", "project": p_name, "path": path}))
+            else:
+                print(f"[+] Successfully scaffolded Cortex {p_type} project at: {path}")
+            return 0
+
+        elif cmd == "workflow":
+            if wf_cmd == "run":
+                wf_file = str(getattr(args, "workflow_file", ""))
+                out_file = cast(str | None, getattr(args, "output", None))
+                res = run_workflow_file(wf_file, output_file=out_file)
+                if json_mode:
+                    print(json.dumps({"status": "success", "command": "workflow run", "result": res}))
+                else:
+                    print("[+] Workflow execution finished.")
+                    print(f"    ID:          {res['workflow_id']}")
+                    print(f"    State:       {res['state']}")
+                    print(f"    Events Log:  {res['event_count']}")
+                    print(f"    Trace Saved: {res['output_file']}")
+                return 0
+
+            elif wf_cmd == "inspect":
+                wf_id = str(getattr(args, "workflow_id", ""))
+                res = inspect_workflow(wf_id)
+                if json_mode:
+                    print(json.dumps({"status": "success", "command": "workflow inspect", "result": res}))
+                else:
+                    causality_tree = cast(list[str], res.get("causality_tree", []))
+                    failed_nodes = cast(list[dict[str, object]], res.get("failed_nodes", []))
+
+                    print("=== Cortex Execution Graph Inspection ===")
+                    print(f"Workflow ID:   {res['workflow_id']}")
+                    print(f"Name:          {res['name']}")
+                    print(f"Goal:          {res['goal']}")
+                    print(f"State:         {res['state']}")
+                    print(f"Total Nodes:   {res['node_count']}")
+                    print("\n--- Causality Tree ---")
+                    for line in causality_tree:
+                        print(f"  {line}")
+                    if failed_nodes:
+                        print(f"\n[!] Verification Failures ({len(failed_nodes)}):")
+                        for node in failed_nodes:
+                            print(f"    - Node {node['id']}: {node['payload']}")
+                    else:
+                        print("\n[+] Verification Status: ALL PASSED")
+                return 0
+
+            elif wf_cmd == "replay":
+                wf_id = str(getattr(args, "workflow_id", ""))
+                res = replay_workflow(wf_id)
+                is_deterministic = bool(res.get("deterministic", False))
+                if json_mode:
+                    print(json.dumps({"status": "success" if is_deterministic else "error", "command": "workflow replay", "result": res}))
+                else:
+                    print("=== Cortex Deterministic Replay Engine ===")
+                    print(f"Workflow ID:      {res['workflow_id']}")
+                    print(f"Events Replayed:  {res['events_replayed']}")
+                    print(f"Status:           {'SUCCESS' if is_deterministic else 'FAILED'}")
+                    print(f"Result:           {res['verification_result']}")
+
+                if not is_deterministic:
+                    if not json_mode:
+                        _ = _handle_cli_error(WorkflowExecutionError(f"Replay divergence detected for workflow trace: {wf_id}"), json_mode=False)
+                    return 1
+                return 0
+
+            else:
+                wf_parser.print_help(sys.stderr if not json_mode else sys.stdout)
+                return _handle_cli_error(WorkflowExecutionError("Missing or invalid workflow subcommand"), json_mode=json_mode)
+
+        else:
+            parser.print_help(sys.stderr if not json_mode else sys.stdout)
+            return _handle_cli_error(WorkflowExecutionError("Missing or invalid command"), json_mode=json_mode)
+
+    except Exception as err:
+        return _handle_cli_error(err, json_mode=json_mode)
+
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/cli/runner.py

@@ -10,8 +10,8 @@ import os
 from typing import cast
 
 from cortex.client import CortexClient
-from cortex.exceptions import WorkflowExecutionError
-from cortex.schema import IntentEvent, WorkflowPolicy
+from cortex.exceptions import CapabilityViolationError, WorkflowExecutionError
+from cortex.schema import IntentEvent, VerificationResultEvent, WorkflowPolicy, WorkflowState
 
 
 def run_workflow_file(workflow_file: str, output_file: str | None = None) -> dict[str, str | int]:
@@ -55,6 +55,23 @@ def run_workflow_file(workflow_file: str, output_file: str | None = None) -> dic
 
     saved_path = client.save_trace(executed_wf.workflow_id, output_file, name=wf_name, goal=wf_goal)
 
+    if executed_wf.state == WorkflowState.FAILED:
+        cap_failures = [
+            e for e in client.event_store.get_log()
+            if isinstance(e, VerificationResultEvent) and not e.passed and (e.rule_id == "CAPABILITY_VIOLATION" or "capability" in e.details)
+        ]
+        if cap_failures:
+            detail = cap_failures[0].details
+            cap_name = str(detail.get("capability", detail.get("required_capability", "unknown")))
+            raise CapabilityViolationError(
+                f"Workflow execution failed due to capability violation: '{cap_name}'",
+                capability=cap_name,
+            )
+        raise WorkflowExecutionError(
+            f"Workflow '{wf_name}' ({executed_wf.workflow_id}) failed verification checks.",
+            workflow_id=executed_wf.workflow_id,
+        )
+
     return {
         "workflow_id": executed_wf.workflow_id,
         "state": executed_wf.state.value,

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/kernel/__init__.py

@@ -1,3 +1,5 @@
 """
 Cortex Kernel Runtime Core
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/kernel/actors/__init__.py

@@ -1,3 +1,5 @@
 """
 Kernel Actors Infrastructure
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/kernel/drivers/__init__.py

@@ -1,3 +1,5 @@
 """
 Kernel Drivers & Adapters
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/kernel/graph/__init__.py

@@ -1,3 +1,5 @@
 """
 Kernel Causal Execution Graph Engine
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/kernel/plugin/__init__.py

@@ -1,3 +1,5 @@
 """
 Kernel Plugin Runtime & Capability Negotiation
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/kernel/plugin/loader.py

@@ -9,7 +9,7 @@ to their declared capabilities — never raw kernel internals.
 import enum
 from dataclasses import dataclass, field
 
-from cortex.tools.kernel.plugin.manifest import PluginManifest
+from cortex.tools.kernel.plugin.manifest import PluginManifest, validate_manifest
 
 
 class PluginState(str, enum.Enum):
@@ -40,6 +40,7 @@ class CapabilityNegotiator:
     def negotiate(self, manifest: PluginManifest) -> PluginRegistration:
         """Evaluates a plugin manifest and returns a PluginRegistration
         with granted/denied capability sets."""
+        validate_manifest(manifest)
         registration = PluginRegistration(manifest=manifest, state=PluginState.NEGOTIATING)
 
         granted: set[str] = set()

cortex_runtime-0.2.1/cortex/tools/kernel/plugin/manifest.py

@@ -0,0 +1,93 @@
+"""
+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)
+
+
+def validate_manifest(manifest: PluginManifest) -> None:
+    """Validates the structural integrity of a PluginManifest.
+
+    Raises:
+        ManifestError: If any manifest field violates structural constraints.
+    """
+    from cortex.exceptions import ManifestError
+
+    if not isinstance(manifest, PluginManifest):
+        raise ManifestError(f"Expected PluginManifest instance, got {type(manifest).__name__}")
+
+    if not isinstance(manifest.name, str) or not manifest.name.strip():
+        raise ManifestError("Plugin manifest 'name' must be a non-empty string")
+
+    if not isinstance(manifest.version, str) or not manifest.version.strip():
+        raise ManifestError("Plugin manifest 'version' must be a non-empty string")
+
+    if not isinstance(manifest.description, str):
+        raise ManifestError("Plugin manifest 'description' must be a string")
+
+    if not isinstance(manifest.consumes_events, (list, tuple)):
+        raise ManifestError("Plugin manifest 'consumes_events' must be a sequence of strings")
+    for item in manifest.consumes_events:
+        if not isinstance(item, str) or not item.strip():
+            raise ManifestError("Plugin manifest 'consumes_events' elements must be non-empty strings")
+
+    if not isinstance(manifest.produces_events, (list, tuple)):
+        raise ManifestError("Plugin manifest 'produces_events' must be a sequence of strings")
+    for item in manifest.produces_events:
+        if not isinstance(item, str) or not item.strip():
+            raise ManifestError("Plugin manifest 'produces_events' elements must be non-empty strings")
+
+    if not isinstance(manifest.required_capabilities, (list, tuple)):
+        raise ManifestError("Plugin manifest 'required_capabilities' must be a sequence of strings")
+    for item in manifest.required_capabilities:
+        if not isinstance(item, str) or not item.strip():
+            raise ManifestError("Plugin manifest 'required_capabilities' elements must be non-empty strings")
+
+
+
+# -----------------------------------------------------------------------
+# 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_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/kernel/schema/__init__.py

@@ -1,3 +1,5 @@
 """
 Kernel Schema & Domain Event Hierarchy
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/kernel/schema/workflow.py

@@ -9,6 +9,11 @@ from dataclasses import dataclass, field
 
 
 class WorkflowState(str, enum.Enum):
+    """Lifecycle state of a Cortex workflow execution.
+
+    Transitions: PENDING → RUNNING → COMPLETED | FAILED | ABORTED
+    """
+
     PENDING = "PENDING"
     RUNNING = "RUNNING"
     COMPLETED = "COMPLETED"

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/kernel/services/__init__.py

@@ -1,3 +1,5 @@
 """
 Kernel Services Layer
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/kernel/services/event_store.py

@@ -7,6 +7,12 @@ from cortex.tools.kernel.transport import AnyEvent
 
 
 class EventStoreService:
+    """Append-only event journal that records all domain events for a workflow.
+
+    Provides ordered event retrieval for trace persistence, inspection,
+    and deterministic replay. This is the public EventStore interface
+    re-exported as ``cortex.EventStore``.
+    """
     _log: list[AnyEvent]
 
     contract: ServiceContract = ServiceContract(

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/verification/__init__.py

@@ -3,3 +3,5 @@ Cortex Verification Platform Core Package
 """
 
 __version__ = "1.0.0"
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/verification/adapters/__init__.py

@@ -1,3 +1,5 @@
 """
 Trace Adapters for Coq, Rust, and SystemVerilog Execution Engines
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/verification/generator/__init__.py

@@ -1,3 +1,5 @@
 """
 Scenario & Machine State Generators
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/verification/invariants/__init__.py

@@ -1,3 +1,5 @@
 """
 Unary Capability Safety Invariant Plugins
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/verification/metrics/__init__.py

@@ -1,3 +1,5 @@
 """
 Multi-Dimensional Metric Plugins
 """
+
+__all__: list[str] = []

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/cortex/tools/verification/schema/__init__.py

@@ -2,6 +2,9 @@
 Typed Verification Schemas Package
 """
 
+__all__: list[str] = []
+
+
 from dataclasses import asdict, dataclass
 
 

{cortex_runtime-0.2.0 → cortex_runtime-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cortex-runtime"
-version = "0.2.0"
+version = "0.2.1"
 description = "Spatiotemporal authority and semantic verification framework for autonomous workflows"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -30,6 +30,8 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Security",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: System :: Distributed Computing",
@@ -44,9 +46,8 @@ dependencies = [
 dev = [
     "ruff>=0.1.0",
     "pyright>=1.1.0",
-    "pytest>=7.0.0",
     "build>=1.0.0",
-    "twine>=4.0.0",
+    "pre-commit>=3.0.0",
     "types-pyyaml>=6.0.0",
 ]
 docs = [

cortex_runtime-0.2.0/cortex/tools/cli/main.py

@@ -1,139 +0,0 @@
-"""
-Cortex Developer CLI Command Entrypoint
-
-Usage:
-    cortex init <project_name> [--type {app|plugin}]
-    cortex workflow run <workflow_file> [--output <file>]
-    cortex workflow inspect <workflow_id_or_file>
-    cortex workflow replay <workflow_id_or_file>
-"""
-
-import argparse
-import os
-import sys
-from collections.abc import Sequence
-from typing import cast
-
-from cortex.exceptions import CortexError
-from cortex.tools.cli.runner import inspect_workflow, replay_workflow, run_workflow_file
-from cortex.tools.cli.scaffolder import scaffold_project
-
-
-def cli_entrypoint() -> None:
-    """Console script entrypoint for PyPI cortex-runtime executable."""
-    sys.exit(main())
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    """Main CLI entrypoint for Cortex framework."""
-    if argv is None:
-        argv = sys.argv[1:]
-
-    parser = argparse.ArgumentParser(
-        prog="cortex",
-        description="Cortex Platform Developer CLI & Workflow Engine",
-    )
-    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
-
-    # cortex init
-    init_parser = subparsers.add_parser("init", help="Scaffold a new Cortex plugin or application")
-    _ = init_parser.add_argument("project_name", help="Name of the project directory to create")
-    _ = init_parser.add_argument(
-        "--type",
-        choices=["app", "plugin"],
-        default="app",
-        help="Type of project to scaffold (default: app)",
-    )
-
-    # cortex workflow
-    wf_parser = subparsers.add_parser("workflow", help="Workflow execution and inspection management")
-    wf_sub = wf_parser.add_subparsers(dest="wf_command", help="Workflow subcommand")
-
-    # cortex workflow run
-    wf_run = wf_sub.add_parser("run", help="Trigger workflow execution from spec file")
-    _ = wf_run.add_argument("workflow_file", help="Path to workflow definition JSON file")
-    _ = wf_run.add_argument("--output", "-o", help="Optional path to save event journal JSON trace")
-
-    # cortex workflow inspect
-    wf_inspect = wf_sub.add_parser("inspect", help="Inspect execution graph and lineage for workflow ID or file")
-    _ = wf_inspect.add_argument("workflow_id", help="Workflow ID or path to event trace JSON file")
-
-    # cortex workflow replay
-    wf_replay = wf_sub.add_parser("replay", help="Deterministically replay workflow execution trace")
-    _ = wf_replay.add_argument("workflow_id", help="Workflow ID or path to event trace JSON file")
-
-    args = parser.parse_args(argv)
-    cmd = str(getattr(args, "command", ""))
-    wf_cmd = str(getattr(args, "wf_command", ""))
-
-    try:
-        if cmd == "init":
-            p_name = str(getattr(args, "project_name", "my_cortex_app"))
-            p_type = str(getattr(args, "type", "app"))
-            path = scaffold_project(p_name, project_type=p_type)
-            print(f"[+] Successfully scaffolded Cortex {p_type} project at: {path}")
-            return 0
-
-        elif cmd == "workflow":
-            if wf_cmd == "run":
-                wf_file = str(getattr(args, "workflow_file", ""))
-                out_file = cast(str | None, getattr(args, "output", None))
-                res = run_workflow_file(wf_file, output_file=out_file)
-                print("[+] Workflow execution finished.")
-                print(f"    ID:          {res['workflow_id']}")
-                print(f"    State:       {res['state']}")
-                print(f"    Events Log:  {res['event_count']}")
-                print(f"    Trace Saved: {res['output_file']}")
-                return 0
-
-            elif wf_cmd == "inspect":
-                wf_id = str(getattr(args, "workflow_id", ""))
-                res = inspect_workflow(wf_id)
-                causality_tree = cast(list[str], res.get("causality_tree", []))
-                failed_nodes = cast(list[dict[str, object]], res.get("failed_nodes", []))
-
-                print("=== Cortex Execution Graph Inspection ===")
-                print(f"Workflow ID:   {res['workflow_id']}")
-                print(f"Name:          {res['name']}")
-                print(f"Goal:          {res['goal']}")
-                print(f"State:         {res['state']}")
-                print(f"Total Nodes:   {res['node_count']}")
-                print("\n--- Causality Tree ---")
-                for line in causality_tree:
-                    print(f"  {line}")
-                if failed_nodes:
-                    print(f"\n[!] Verification Failures ({len(failed_nodes)}):")
-                    for node in failed_nodes:
-                        print(f"    - Node {node['id']}: {node['payload']}")
-                else:
-                    print("\n[+] Verification Status: ALL PASSED")
-                return 0
-
-            elif wf_cmd == "replay":
-                wf_id = str(getattr(args, "workflow_id", ""))
-                res = replay_workflow(wf_id)
-                print("=== Cortex Deterministic Replay Engine ===")
-                print(f"Workflow ID:      {res['workflow_id']}")
-                print(f"Events Replayed:  {res['events_replayed']}")
-                print(f"Status:           {'SUCCESS' if res['deterministic'] else 'FAILED'}")
-                print(f"Result:           {res['verification_result']}")
-                return 0 if res["deterministic"] else 1
-
-            else:
-                wf_parser.print_help(sys.stderr)
-                return 1
-
-        else:
-            parser.print_help(sys.stderr)
-            return 1
-
-    except CortexError as err:
-        print(f"[!] Cortex Error: {err.message}", file=sys.stderr)
-        return err.exit_code
-    except Exception as err:
-        print(f"[!] Unexpected Error: {err}", file=sys.stderr)
-        return getattr(os, "EX_SOFTWARE", 1)
-
-
-if __name__ == "__main__":
-    sys.exit(main())

cortex_runtime-0.2.0/cortex/tools/kernel/plugin/manifest.py

@@ -1,53 +0,0 @@
-"""
-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"],
-)