cortex-runtime 0.3.0__tar.gz → 0.4.0__tar.gz

{cortex_runtime-0.3.0 → cortex_runtime-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortex-runtime
-Version: 0.3.0
+Version: 0.4.0
 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

cortex_runtime-0.4.0/cortex/schemas/v1/configuration.schema.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cortex.security/schemas/v1/configuration.schema.json",
+  "title": "CortexDesiredConfiguration",
+  "description": "Normative canonical schema for Cortex Control Plane desired execution state. Excludes derived identity metadata (config_hash, config_generation).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "gateway",
+    "replica_group",
+    "sandbox",
+    "resource_limits"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "enum": ["1.0.0"]
+    },
+    "gateway": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "max_queue_depth",
+        "max_worker_inflight",
+        "queue_timeout_sec",
+        "dispatch_deadline_sec",
+        "selection_policy",
+        "journal_path",
+        "fsync_policy"
+      ],
+      "properties": {
+        "max_queue_depth": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000,
+          "default": 1000,
+          "description": "Maximum aggregate queued invocations across all replica groups before ERR_QUEUE_FULL"
+        },
+        "max_worker_inflight": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "default": 10,
+          "description": "Maximum concurrent inflight invocations assigned per ready worker instance"
+        },
+        "queue_timeout_sec": {
+          "type": "number",
+          "minimum": 0.1,
+          "maximum": 300.0,
+          "default": 30.0,
+          "description": "Timeout in seconds before queued invocation raises ERR_QUEUE_TIMEOUT"
+        },
+        "dispatch_deadline_sec": {
+          "type": "number",
+          "minimum": 0.1,
+          "maximum": 60.0,
+          "default": 5.0,
+          "description": "Maximum seconds allowed to execute atomic dispatch pipeline"
+        },
+        "selection_policy": {
+          "type": "string",
+          "enum": ["least_inflight_deterministic", "round_robin_deterministic"],
+          "default": "least_inflight_deterministic",
+          "description": "Algorithm used by RoutingPolicy for worker selection"
+        },
+        "journal_path": {
+          "type": "string",
+          "pattern": "^/(?:[a-zA-Z0-9_-]+/)*[a-zA-Z0-9._-]+$",
+          "default": "/var/log/cortex/invocation_journal.jsonl",
+          "description": "Absolute filesystem path to append-only JSON-lines invocation state journal"
+        },
+        "fsync_policy": {
+          "type": "string",
+          "enum": ["always", "batch", "never"],
+          "default": "always",
+          "description": "Fsync discipline for persistent ledger journal writes"
+        }
+      }
+    },
+    "replica_group": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "group_id",
+        "min_replicas",
+        "max_replicas",
+        "drain_deadline_sec"
+      ],
+      "properties": {
+        "group_id": {
+          "type": "string",
+          "pattern": "^[a-z0-9_-]+$",
+          "description": "Unique alphanumeric ReplicaGroup identifier"
+        },
+        "min_replicas": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000,
+          "default": 1
+        },
+        "max_replicas": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000,
+          "default": 10
+        },
+        "drain_deadline_sec": {
+          "type": "number",
+          "minimum": 1.0,
+          "maximum": 300.0,
+          "default": 30.0,
+          "description": "Seconds allowed for graceful worker drain before forced SIGKILL"
+        }
+      }
+    },
+    "sandbox": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "profile_name",
+        "required_capabilities",
+        "allowed_syscalls",
+        "landlock_paths",
+        "read_only_root",
+        "allowed_write_paths"
+      ],
+      "properties": {
+        "profile_name": {
+          "type": "string",
+          "enum": ["Profile_A_Linux_Strict"],
+          "description": "Isolation profile name. Permissive/Development profiles MUST NOT be used in production schemas."
+        },
+        "required_capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9_-]+\\.[a-z0-9._-]+$"
+          },
+          "uniqueItems": true,
+          "description": "Explicit capability identifiers (format: namespace.action)"
+        },
+        "allowed_syscalls": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_]+$"
+          },
+          "uniqueItems": true,
+          "description": "Whitelist of allowed Linux system call names for Seccomp filter"
+        },
+        "landlock_paths": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^/(?:[a-zA-Z0-9_-]+/)*[a-zA-Z0-9._-]*$"
+          },
+          "uniqueItems": true,
+          "description": "Filesystem path boundaries restricted by Landlock ABI"
+        },
+        "read_only_root": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enforce read-only root filesystem mounting"
+        },
+        "allowed_write_paths": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^/tmp/sandbox_[a-zA-Z0-9_-]+$"
+          },
+          "default": ["/tmp/sandbox_default"],
+          "uniqueItems": true,
+          "description": "Strictly restricted write path boundaries inside worker mount namespace"
+        }
+      }
+    },
+    "resource_limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "memory_limit_mb",
+        "cpu_quota_percent"
+      ],
+      "properties": {
+        "memory_limit_mb": {
+          "type": "integer",
+          "minimum": 64,
+          "maximum": 32768,
+          "default": 512,
+          "description": "Cgroups v2 hard memory ceiling in megabytes per worker"
+        },
+        "cpu_quota_percent": {
+          "type": "integer",
+          "minimum": 10,
+          "maximum": 1600,
+          "default": 100,
+          "description": "CPU quota allocation percentage per worker"
+        }
+      }
+    }
+  }
+}

cortex_runtime-0.4.0/cortex/tools/kernel/replica/__init__.py

@@ -0,0 +1,56 @@
+"""
+Cortex Multi-Replica Kernel Subsystem (Phases 1–4)
+
+Provides modular components for execution identity coordinates, Gateway lease fencing,
+durable invocation state ledgers, worker lifecycle state tracking, and routing & dispatch.
+"""
+
+from cortex.tools.kernel.replica.identity import (
+    ExecutionIdentity,
+    OwnershipIdentity,
+    StaleConfigGenerationError,
+)
+from cortex.tools.kernel.replica.lease import LeaseManager, StaleLeaseError
+from cortex.tools.kernel.replica.ledger import (
+    TERMINAL_STATES,
+    InvocationState,
+    InvocationStateLedger,
+    RecoveryBucket,
+)
+from cortex.tools.kernel.replica.lifecycle import WorkerLifecycleStage, WorkerLifecycleTracker
+from cortex.tools.kernel.replica.router import (
+    CandidateResolver,
+    ExecutionClass,
+    GatewayDispatcher,
+    NoEligibleWorkerNow,
+    QueueFullError,
+    QueueTimeoutError,
+    RoutingDecisionEvent,
+    RoutingPolicy,
+    StateDomainKey,
+    WorkerRef,
+)
+
+__all__ = [
+    "ExecutionIdentity",
+    "OwnershipIdentity",
+    "StaleConfigGenerationError",
+    "InvocationState",
+    "RecoveryBucket",
+    "InvocationStateLedger",
+    "TERMINAL_STATES",
+    "LeaseManager",
+    "StaleLeaseError",
+    "WorkerLifecycleStage",
+    "WorkerLifecycleTracker",
+    "WorkerRef",
+    "ExecutionClass",
+    "StateDomainKey",
+    "RoutingDecisionEvent",
+    "CandidateResolver",
+    "RoutingPolicy",
+    "GatewayDispatcher",
+    "NoEligibleWorkerNow",
+    "QueueFullError",
+    "QueueTimeoutError",
+]

cortex_runtime-0.4.0/cortex/tools/kernel/replica/identity.py

@@ -0,0 +1,70 @@
+"""
+Cortex Replica Coordinate System (Phase 1)
+
+Explicitly separates runtime worker execution coordinates (ExecutionIdentity)
+from Gateway lease ownership coordinates (OwnershipIdentity).
+"""
+
+from dataclasses import dataclass
+
+
+class StaleConfigGenerationError(Exception):
+    """Raised when a worker operates under a stale ConfigGeneration or mismatched ConfigHash."""
+
+    pass
+
+
+@dataclass(frozen=True)
+class ExecutionIdentity:
+    """Uniquely identifies a specific worker execution attempt runtime coordinate.
+
+    Every worker carries both a ReplicaGeneration (deployment wave) and a
+    ConfigGeneration (immutable configuration snapshot version + SHA-256 hash).
+    The Gateway rejects workers whose config_generation or config_hash does not
+    match the active deployment.
+    """
+
+    group_id: str
+    instance_id: str
+    generation: int
+    config_generation: int
+    attempt_id: int
+    config_hash: str = ""
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.group_id, str) or not self.group_id.strip():
+            raise ValueError("group_id must be a non-empty string")
+        if not isinstance(self.instance_id, str) or not self.instance_id.strip():
+            raise ValueError("instance_id must be a non-empty string")
+        if not isinstance(self.generation, int) or self.generation < 1:
+            raise ValueError("generation must be a positive integer >= 1")
+        if not isinstance(self.config_generation, int) or self.config_generation < 1:
+            raise ValueError("config_generation must be a positive integer >= 1")
+        if not isinstance(self.attempt_id, int) or self.attempt_id < 1:
+            raise ValueError("attempt_id must be a positive integer >= 1")
+
+    def coordinate_string(self) -> str:
+        """Returns string representation for audit logs."""
+        hash_suffix = f":h{self.config_hash[:8]}" if self.config_hash else ""
+        return f"{self.group_id}:{self.instance_id}:g{self.generation}:cfg{self.config_generation}{hash_suffix}:a{self.attempt_id}"
+
+
+@dataclass(frozen=True)
+class OwnershipIdentity:
+    """Uniquely identifies Gateway authority and lease ownership for an invocation."""
+
+    invocation_id: str
+    lease_id: str
+    lease_epoch: int
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.invocation_id, str) or not self.invocation_id.strip():
+            raise ValueError("invocation_id must be a non-empty string")
+        if not isinstance(self.lease_id, str) or not self.lease_id.strip():
+            raise ValueError("lease_id must be a non-empty string")
+        if not isinstance(self.lease_epoch, int) or self.lease_epoch < 1:
+            raise ValueError("lease_epoch must be a positive integer >= 1")
+
+    def coordinate_string(self) -> str:
+        """Returns string representation for audit logs."""
+        return f"inv:{self.invocation_id}:lease:{self.lease_id}:ep{self.lease_epoch}"

cortex_runtime-0.4.0/cortex/tools/kernel/replica/lease.py

@@ -0,0 +1,227 @@
+"""
+Linearizable Gateway Lease Manager (Phase 2 & 4)
+
+Enforces atomic, mutually exclusive commit and revocation fencing bound to monotonic
+LeaseEpoch counters. Stale commits are rejected with StaleLeaseError.
+
+LINEARIZABILITY DOMAIN: Single Gateway Authority Domain.
+Future multi-process or multi-node Gateway implementations MUST preserve
+linearizable mutually exclusive commit and revocation fencing at this boundary.
+"""
+
+import threading
+import uuid
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Dict, Optional
+
+from cortex.tools.kernel.replica.identity import OwnershipIdentity
+from cortex.tools.kernel.replica.lifecycle import WorkerLifecycleStage
+
+if TYPE_CHECKING:
+    from cortex.tools.kernel.replica.router import WorkerRef
+
+
+class StaleLeaseError(Exception):
+    """Raised when a commit attempt uses a revoked or stale lease epoch (ERR_STALE_LEASE_EPOCH)."""
+
+    pass
+
+
+@dataclass
+class LeaseRecord:
+    ownership_identity: OwnershipIdentity
+    assigned_worker_id: str
+    active: bool = True
+    committed: bool = False
+
+
+class LeaseManager:
+    """Thread-safe, linearizable Gateway Lease Authority (Single Gateway Authority Domain)."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        # invocation_id -> LeaseRecord
+        self._active_leases: Dict[str, LeaseRecord] = {}
+        # invocation_id -> current_epoch
+        self._latest_epoch: Dict[str, int] = {}
+        # worker_id -> WorkerRef (active registered Gateway worker state)
+        self._worker_registry: Dict[str, "WorkerRef"] = {}
+
+    def register_worker_state(self, worker_ref: "WorkerRef") -> None:
+        """Register or update active worker replica state in the Gateway TCB registry."""
+        with self._lock:
+            self._worker_registry[worker_ref.instance_id] = worker_ref
+
+    def unregister_worker(self, worker_id: str) -> None:
+        """Remove worker replica from Gateway TCB registry on eviction or process death."""
+        with self._lock:
+            self._worker_registry.pop(worker_id, None)
+
+    def revalidate_candidate(
+        self,
+        worker_ref: "WorkerRef",
+        active_config_gen: int,
+        active_config_hash: str,
+        active_sandbox_hash: str,
+        active_cap_hash: str,
+        max_inflight: int = 10,
+    ) -> bool:
+        """Atomically revalidate a proposed candidate snapshot inside the Gateway TCB lock."""
+        with self._lock:
+            return self._revalidate_unlocked(
+                worker_ref=worker_ref,
+                active_config_gen=active_config_gen,
+                active_config_hash=active_config_hash,
+                active_sandbox_hash=active_sandbox_hash,
+                active_cap_hash=active_cap_hash,
+                max_inflight=max_inflight,
+            )
+
+    def _revalidate_unlocked(
+        self,
+        worker_ref: "WorkerRef",
+        active_config_gen: int,
+        active_config_hash: str,
+        active_sandbox_hash: str,
+        active_cap_hash: str,
+        max_inflight: int,
+    ) -> bool:
+        registered = self._worker_registry.get(worker_ref.instance_id)
+        if not registered:
+            return False
+
+        if registered.lifecycle_version != worker_ref.lifecycle_version:
+            return False
+
+        if registered.stage != WorkerLifecycleStage.READY:
+            return False
+
+        if registered.config_generation != active_config_gen:
+            return False
+
+        if registered.config_hash != active_config_hash:
+            return False
+
+        if registered.sandbox_profile_hash != active_sandbox_hash:
+            return False
+
+        if registered.capability_envelope_hash != active_cap_hash:
+            return False
+
+        active_count = sum(
+            1 for rec in self._active_leases.values()
+            if rec.assigned_worker_id == worker_ref.instance_id and rec.active and not rec.committed
+        )
+        if active_count >= max_inflight:
+            return False
+
+        return True
+
+    def grant_lease_with_revalidation(
+        self,
+        invocation_id: str,
+        worker_ref: "WorkerRef",
+        active_config_gen: int,
+        active_config_hash: str,
+        active_sandbox_hash: str,
+        active_cap_hash: str,
+        max_inflight: int = 10,
+    ) -> Optional[OwnershipIdentity]:
+        """Atomically revalidates candidate AND grants lease inside a single lock acquisition (Linearization Point)."""
+        with self._lock:
+            if not self._revalidate_unlocked(
+                worker_ref=worker_ref,
+                active_config_gen=active_config_gen,
+                active_config_hash=active_config_hash,
+                active_sandbox_hash=active_sandbox_hash,
+                active_cap_hash=active_cap_hash,
+                max_inflight=max_inflight,
+            ):
+                return None
+
+            current_epoch = self._latest_epoch.get(invocation_id, 0) + 1
+            self._latest_epoch[invocation_id] = current_epoch
+
+            lease_id = str(uuid.uuid4())
+            ownership = OwnershipIdentity(
+                invocation_id=invocation_id,
+                lease_id=lease_id,
+                lease_epoch=current_epoch,
+            )
+
+            record = LeaseRecord(
+                ownership_identity=ownership,
+                assigned_worker_id=worker_ref.instance_id,
+                active=True,
+                committed=False,
+            )
+            self._active_leases[invocation_id] = record
+            return ownership
+
+    def grant_lease(self, invocation_id: str, worker_id: str) -> OwnershipIdentity:
+        """Atomically grants an epoch-bound lease to a worker for an invocation."""
+        with self._lock:
+            current_epoch = self._latest_epoch.get(invocation_id, 0) + 1
+            self._latest_epoch[invocation_id] = current_epoch
+
+            lease_id = str(uuid.uuid4())
+            ownership = OwnershipIdentity(
+                invocation_id=invocation_id,
+                lease_id=lease_id,
+                lease_epoch=current_epoch,
+            )
+
+            record = LeaseRecord(
+                ownership_identity=ownership,
+                assigned_worker_id=worker_id,
+                active=True,
+                committed=False,
+            )
+            self._active_leases[invocation_id] = record
+            return ownership
+
+    def commit_invocation(self, invocation_id: str, lease_epoch: int) -> bool:
+        """Atomically commits an invocation under a specific lease epoch.
+
+        Must be mutually exclusive with revoke_lease. If lease_epoch != active lease epoch,
+        or lease is inactive, raises StaleLeaseError.
+        """
+        with self._lock:
+            record = self._active_leases.get(invocation_id)
+            if not record:
+                raise StaleLeaseError(f"ERR_STALE_LEASE_EPOCH: No active lease found for {invocation_id}")
+
+            if not record.active:
+                raise StaleLeaseError(f"ERR_STALE_LEASE_EPOCH: Lease for {invocation_id} has been revoked")
+
+            if record.ownership_identity.lease_epoch != lease_epoch:
+                raise StaleLeaseError(
+                    f"ERR_STALE_LEASE_EPOCH: Commit epoch {lease_epoch} does not match active epoch {record.ownership_identity.lease_epoch}"
+                )
+
+            record.committed = True
+            record.active = False
+            return True
+
+    def revoke_lease(self, invocation_id: str, lease_epoch: int) -> bool:
+        """Atomically revokes a lease for an invocation under a specific lease epoch.
+
+        Must be mutually exclusive with commit_invocation. Returns True if lease was revoked.
+        """
+        with self._lock:
+            record = self._active_leases.get(invocation_id)
+            if not record:
+                return False
+
+            if record.ownership_identity.lease_epoch == lease_epoch and record.active:
+                record.active = False
+                return True
+            return False
+
+    def is_lease_valid(self, invocation_id: str, lease_epoch: int) -> bool:
+        """Returns True iff the lease is active and matches lease_epoch."""
+        with self._lock:
+            record = self._active_leases.get(invocation_id)
+            if not record:
+                return False
+            return record.active and record.ownership_identity.lease_epoch == lease_epoch