cortex-runtime 0.2.0__py3-none-any.whl

cortex/tools/verification/contract.py

@@ -0,0 +1,70 @@
+"""
+YAML Contract Parser & Schema Validator for Verification Runs
+"""
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class VerificationContract:
+    schema_version: str
+    contract_id: str
+    description: str
+    toolchain_requirements: dict[str, str]
+    fuzzing_parameters: dict[str, Any]
+    targets: dict[str, str]
+    oracle: dict[str, Any]
+    output_requirements: dict[str, str]
+
+    @classmethod
+    def load(cls, contract_path: str) -> "VerificationContract":
+        if not os.path.exists(contract_path):
+            raise FileNotFoundError(f"Contract file not found: {contract_path}")
+
+        # Basic lightweight YAML parser without third-party requirement
+        data: dict[str, Any] = {}
+        current_key = None
+
+        with open(contract_path, "r") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+
+                if ":" in line and not line.startswith("-"):
+                    parts = line.split(":", 1)
+                    key = parts[0].strip()
+                    val = parts[1].strip()
+
+                    if val == "":
+                        current_key = key
+                        data[current_key] = {}
+                    else:
+                        # strip quotes if present
+                        if (val.startswith('"') and val.endswith('"')) or (val.startswith("'") and val.endswith("'")):
+                            val = val[1:-1]
+                        elif val.lower() == "true":
+                            val = True
+                        elif val.lower() == "false":
+                            val = False
+                        elif val.isdigit():
+                            val = int(val)
+
+                        if current_key and line.startswith("  "):
+                            data[current_key][key] = val
+                        else:
+                            data[key] = val
+                            current_key = None
+
+        return cls(
+            schema_version=data.get("schema_version", "1.0.0"),
+            contract_id=data.get("contract_id", "default"),
+            description=data.get("description", ""),
+            toolchain_requirements=data.get("toolchain_requirements", {}),
+            fuzzing_parameters=data.get("fuzzing_parameters", {}),
+            targets=data.get("targets", {}),
+            oracle=data.get("oracle", {}),
+            output_requirements=data.get("output_requirements", {})
+        )

cortex/tools/verification/engine.py

@@ -0,0 +1,121 @@
+"""
+Core Verification Engine Orchestrator
+"""
+
+import json
+import os
+from typing import Any
+
+from cortex.tools.verification.adapters.coq import CoqAdapter
+from cortex.tools.verification.adapters.rtl import RTLAdapter
+from cortex.tools.verification.adapters.rust import RustAdapter
+from cortex.tools.verification.archive import CounterexampleArchive
+from cortex.tools.verification.contract import VerificationContract
+from cortex.tools.verification.generator.composer import ScenarioComposer
+from cortex.tools.verification.metrics.opcode import OpcodeMetric
+from cortex.tools.verification.metrics.state_space import StateSpaceMetric
+from cortex.tools.verification.metrics.trap import TrapMetric
+from cortex.tools.verification.mutation import FaultMutationEngine
+from cortex.tools.verification.oracle import VerificationOracle
+from cortex.tools.verification.shrink import SemanticShrinker
+
+
+class VerificationEngine:
+    def __init__(self, contract: VerificationContract, seed_val: int):
+        self.contract = contract
+        self.seed_val = seed_val
+        self.oracle = VerificationOracle(
+            version=contract.oracle.get("version", "v2.1.0"),
+            strict_trap_matching=contract.oracle.get("strict_trap_cause_matching", True)
+        )
+        self.shrinker = SemanticShrinker(
+            max_shrunk_steps=contract.fuzzing_parameters.get("max_shrunk_steps", 50)
+        )
+        self.archiver = CounterexampleArchive(
+            archive_dir=contract.output_requirements.get("counterexample_directory", "artifacts/counterexamples/")
+        )
+
+        self.opcode_metric = OpcodeMetric()
+        self.trap_metric = TrapMetric()
+        self.state_metric = StateSpaceMetric()
+
+    def run_verification(
+        self,
+        iterations: int = 100,
+        inject_failure: str | None = None
+    ) -> dict[str, Any]:
+        coq_adapter = CoqAdapter()
+        rust_adapter = RustAdapter()
+        rtl_adapter = RTLAdapter()
+
+        total_steps_evaluated = 0
+
+        for i in range(iterations):
+            iter_seed = self.seed_val + i
+            composer = ScenarioComposer(iter_seed)
+            scenario = composer.compose_scenario(num_instructions=6)
+
+            # Generate temp artifacts
+            os.makedirs("artifacts/temp/", exist_ok=True)
+            composer.export_artifacts(
+                scenario,
+                "artifacts/temp/test_scenario.json",
+                "artifacts/temp/test_payload.bin"
+            )
+
+            # Parse traces
+            coq_trace = coq_adapter.parse_trace("Research/artifacts/phase2/coq_trace.json")
+            rust_trace = rust_adapter.parse_trace("Research/artifacts/phase2/emulator_trace.json")
+            rtl_trace = rtl_adapter.parse_trace("Research/artifacts/phase2/rtl_trace.json")
+
+            # Apply mutation if injected
+            if inject_failure:
+                mutation_engine = FaultMutationEngine(inject_failure)
+                rtl_trace = mutation_engine.apply_mutation(rtl_trace)
+
+            # Record metrics
+            for step in coq_trace:
+                self.opcode_metric.record_step(step)
+                self.trap_metric.record_step(step)
+                self.state_metric.record_step(step)
+                total_steps_evaluated += 1
+
+            # Evaluate equivalence
+            diagnostic = self.oracle.evaluate_equivalence(coq_trace, rust_trace, rtl_trace)
+
+            if diagnostic["status"] == "FAIL":
+                failing_step = diagnostic.get("failing_step", 1)
+                shrunk_scenario = self.shrinker.shrink_scenario(scenario, failing_step)
+                case_hash = self.archiver.archive_failure(
+                    shrunk_scenario,
+                    diagnostic,
+                    seed=f"0x{iter_seed:08X}"
+                )
+                return {
+                    "status": "FAIL",
+                    "iteration": i + 1,
+                    "seed": f"0x{iter_seed:08X}",
+                    "diagnostic": diagnostic,
+                    "counterexample_hash": case_hash
+                }
+
+        # Generate run summary JSON
+        summary = {
+            "seed": f"0x{self.seed_val:08X}",
+            "iterations": iterations,
+            "total_steps_evaluated": total_steps_evaluated,
+            "status": "PASSED",
+            "metrics": {
+                "opcode_coverage": self.opcode_metric.get_summary(),
+                "trap_coverage": self.trap_metric.get_summary(),
+                "state_space_explored": self.state_metric.get_summary()
+            }
+        }
+
+        output_dir = self.contract.output_requirements.get("archive_directory", "artifacts/phase3a/")
+        os.makedirs(output_dir, exist_ok=True)
+        summary_path = os.path.join(output_dir, "run_summary.json")
+        with open(summary_path, "w") as f:
+            json.dump(summary, f, indent=2)
+
+        return summary

cortex/tools/verification/generator/__init__.py

@@ -0,0 +1,3 @@
+"""
+Scenario & Machine State Generators
+"""

cortex/tools/verification/generator/composer.py

@@ -0,0 +1,36 @@
+"""
+Scenario Composer: Merges Machine State and Instruction Stream into Reproducible Payloads
+"""
+
+import json
+import struct
+from typing import Any
+
+from cortex.tools.verification.generator.program import ProgramGenerator
+from cortex.tools.verification.generator.state import StateGenerator
+
+
+class ScenarioComposer:
+    def __init__(self, seed: int):
+        self.seed = seed
+        self.state_gen = StateGenerator(seed)
+        self.prog_gen = ProgramGenerator(seed)
+
+    def compose_scenario(self, num_instructions: int = 8) -> dict[str, Any]:
+        initial_state = self.state_gen.generate_initial_state()
+        program = self.prog_gen.generate_program(num_instructions)
+
+        return {
+            "seed": f"0x{self.seed:08X}",
+            "initial_state": initial_state,
+            "program": program
+        }
+
+    def export_artifacts(self, scenario: dict[str, Any], json_path: str, bin_path: str):
+        with open(json_path, "w") as f:
+            json.dump(scenario, f, indent=2)
+
+        with open(bin_path, "wb") as f:
+            for inst in scenario["program"]:
+                # Big-endian 32-bit instruction word
+                f.write(struct.pack(">I", inst["raw_uint32"]))

cortex/tools/verification/generator/program.py

@@ -0,0 +1,46 @@
+"""
+Instruction Stream Fuzzing Generator for Cortex Capabilities
+"""
+
+import random
+from typing import Any
+
+
+class ProgramGenerator:
+    def __init__(self, seed: int):
+        self.rng = random.Random(seed)
+
+    def generate_program(self, num_instructions: int = 8) -> list[dict[str, Any]]:
+        instructions = []
+
+        opcodes = [
+            ("INVOKE_CAP", 0x01, 0x04000000),
+            ("RESTRICT_CAP", 0x03, 0x0C000000),
+            ("REVOKE_CAP", 0x05, 0x14000000),
+            ("GRANT_CAP", 0x02, 0x08000000),
+            ("ILLEGAL_OP", 0x0F, 0x00000000),
+        ]
+
+        for _ in range(num_instructions):
+            op_name, op_code, raw_base = self.rng.choice(opcodes)
+            src_reg = self.rng.randint(0, 3)
+            dst_reg = self.rng.randint(0, 3)
+            imm = self.rng.choice([0x0000, 0x1000, 0x2000, 0x4000, 0x7000, 0xFFFF])
+
+            if op_name == "RESTRICT_CAP":
+                raw = raw_base | (src_reg << 16) | imm
+            elif op_name == "INVOKE_CAP" or op_name == "REVOKE_CAP":
+                raw = raw_base | (src_reg << 16)
+            elif op_name == "GRANT_CAP":
+                raw = raw_base | (src_reg << 16) | (dst_reg << 20) | imm
+            else:
+                raw = 0x00000000
+
+            instructions.append({
+                "opcode_name": op_name,
+                "opcode_val": op_code,
+                "raw_hex": f"0x{raw:08x}",
+                "raw_uint32": raw
+            })
+
+        return instructions

cortex/tools/verification/generator/state.py

@@ -0,0 +1,54 @@
+"""
+Initial STCR & Machine Register State Fuzzing Generator
+"""
+
+import random
+from typing import Any
+
+
+class StateGenerator:
+    def __init__(self, seed: int):
+        self.rng = random.Random(seed)
+
+    def generate_initial_state(self) -> dict[str, Any]:
+        stcr_file = []
+
+        # STCR0 always starts as root execution capability by default or random
+        root_v = True
+        root_mask = 0x7000 # READ | WRITE | EXEC (0x4000 | 0x2000 | 0x1000)
+        root_base = 0x2000
+        root_epoch = 0
+
+        stcr_file.append({
+            "index": 0,
+            "valid": root_v,
+            "permissions": root_mask,
+            "base_address": root_base,
+            "epoch": root_epoch
+        })
+
+        for reg_id in range(1, 32):
+            is_valid = self.rng.choice([True, False, False, False]) # 25% chance of valid STCR slot
+            if is_valid:
+                mask = self.rng.choice([0x4000, 0x2000, 0x1000, 0x7000, 0x0000])
+                base = self.rng.choice([0x0, 0x1000, 0x2000, 0x8000, 0xFFFF0000])
+                epoch = self.rng.choice([0, 1, 100, 65534, 65535]) # include boundary epoch limits
+            else:
+                mask = 0
+                base = 0
+                epoch = 0
+
+            stcr_file.append({
+                "index": reg_id,
+                "valid": is_valid,
+                "permissions": mask,
+                "base_address": base,
+                "epoch": epoch
+            })
+
+        return {
+            "pc": 0x1000,
+            "privilege_mode": "Machine",
+            "reg_hec": self.rng.choice([0, 1, 65535]),
+            "stcr_registers": stcr_file
+        }

cortex/tools/verification/invariants/__init__.py

@@ -0,0 +1,3 @@
+"""
+Unary Capability Safety Invariant Plugins
+"""

cortex/tools/verification/invariants/capability.py

@@ -0,0 +1,62 @@
+"""
+Capability Safety Invariants Engine
+"""
+
+from dataclasses import dataclass
+
+from cortex.tools.verification.schema.event import CommitEventV1
+
+# Define invariant boundary constants to avoid magic numbers
+MIN_EPOCH = 0
+MAX_EPOCH = 65535
+NEUTRAL_TRAP_EXPECTED_VAL = 0
+MIN_RETIREMENT_STEP = 1
+
+@dataclass
+class InvariantResult:
+    passed: bool
+    invariant_id: str
+    error_message: str = ""
+
+    @classmethod
+    def PASS(cls, invariant_id: str) -> "InvariantResult":
+        return cls(passed=True, invariant_id=invariant_id)
+
+    @classmethod
+    def FAIL(cls, invariant_id: str, error_message: str) -> "InvariantResult":
+        return cls(passed=False, invariant_id=invariant_id, error_message=error_message)
+
+
+class EpochMonotonicityInvariant:
+    """INV_03: Capability epochs must remain in valid 16-bit range."""
+    def check(self, event: CommitEventV1) -> InvariantResult:
+        if event.architectural is None:
+            return InvariantResult.FAIL("INV_03_ATOMIC_STCR_UPDATE", "Missing architectural state")
+        for stcr in event.architectural.stcr:
+            epoch = stcr.get("epoch", stcr.get("max_epoch", 0))
+            if not isinstance(epoch, int) or epoch < MIN_EPOCH or epoch > MAX_EPOCH:
+                return InvariantResult.FAIL("INV_03_ATOMIC_STCR_UPDATE", f"Epoch {epoch} out of 16-bit bounds")
+        return InvariantResult.PASS("INV_03_ATOMIC_STCR_UPDATE")
+
+
+class NeutralTrapInvariant:
+    """INV_02: Verifies that committed neutral traps maintain trap_val == 0."""
+    def check(self, event: CommitEventV1) -> InvariantResult:
+        if event.architectural is None:
+            return InvariantResult.FAIL("INV_02_NEUTRAL_TRAP_ZERO_VAL", "Missing architectural state")
+        trap = event.architectural.trap
+        is_triggered = trap.get("triggered", False)
+        trap_val = trap.get("trap_val", 0)
+        if is_triggered and trap_val != NEUTRAL_TRAP_EXPECTED_VAL:
+            return InvariantResult.FAIL("INV_02_NEUTRAL_TRAP_ZERO_VAL", f"Non-zero trap_val {trap_val} on neutral trap")
+        return InvariantResult.PASS("INV_02_NEUTRAL_TRAP_ZERO_VAL")
+
+
+class SingleRetirementInvariant:
+    """INV_01: Exactly one architectural retirement event per execution step."""
+    def check(self, event: CommitEventV1) -> InvariantResult:
+        if event.observation is None:
+            return InvariantResult.FAIL("INV_01_SINGLE_RETIREMENT", "Missing observation metadata")
+        if event.observation.step < MIN_RETIREMENT_STEP:
+            return InvariantResult.FAIL("INV_01_SINGLE_RETIREMENT", f"Invalid retirement step {event.observation.step}")
+        return InvariantResult.PASS("INV_01_SINGLE_RETIREMENT")

cortex/tools/verification/metrics/__init__.py

@@ -0,0 +1,3 @@
+"""
+Multi-Dimensional Metric Plugins
+"""

cortex/tools/verification/metrics/base.py

@@ -0,0 +1,18 @@
+"""
+Base Metric Plugin Interface
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from cortex.tools.verification.schema import CanonicalState
+
+
+class BaseMetric(ABC):
+    @abstractmethod
+    def record_step(self, step: CanonicalState):
+        pass
+
+    @abstractmethod
+    def get_summary(self) -> dict[str, Any]:
+        pass

cortex/tools/verification/metrics/opcode.py

@@ -0,0 +1,25 @@
+"""
+Instruction Opcode Coverage Metric Tracker
+"""
+
+from typing import Any
+
+from cortex.tools.verification.metrics.base import BaseMetric
+from cortex.tools.verification.schema import CanonicalState
+
+
+class OpcodeMetric(BaseMetric):
+    def __init__(self):
+        self.seen_opcodes: set[str] = set()
+        self.total_opcodes = 18
+
+    def record_step(self, step: CanonicalState):
+        self.seen_opcodes.add(step.instruction)
+
+    def get_summary(self) -> dict[str, Any]:
+        count = len(self.seen_opcodes)
+        pct = min(100.0, (count / float(self.total_opcodes)) * 100.0)
+        return {
+            "unique_opcodes_seen": count,
+            "coverage_percentage": round(pct, 1)
+        }

cortex/tools/verification/metrics/state_space.py

@@ -0,0 +1,26 @@
+"""
+Unique Architectural State Explorer Metric Tracker
+"""
+
+import hashlib
+import json
+from typing import Any
+
+from cortex.tools.verification.metrics.base import BaseMetric
+from cortex.tools.verification.schema import CanonicalState
+
+
+class StateSpaceMetric(BaseMetric):
+    def __init__(self):
+        self.visited_states: set[str] = set()
+
+    def record_step(self, step: CanonicalState):
+        state_dict = step.to_dict()
+        state_str = json.dumps(state_dict, sort_keys=True).encode("utf-8")
+        state_hash = hashlib.sha256(state_str).hexdigest()[:16]
+        self.visited_states.add(state_hash)
+
+    def get_summary(self) -> dict[str, Any]:
+        return {
+            "unique_states_explored": len(self.visited_states)
+        }

cortex/tools/verification/metrics/trap.py

@@ -0,0 +1,26 @@
+"""
+Trap Cause Path Coverage Metric Tracker
+"""
+
+from typing import Any
+
+from cortex.tools.verification.metrics.base import BaseMetric
+from cortex.tools.verification.schema import CanonicalState
+
+
+class TrapMetric(BaseMetric):
+    def __init__(self):
+        self.seen_trap_codes: set[int] = set()
+        self.total_trap_codes = 5
+
+    def record_step(self, step: CanonicalState):
+        if step.trap.triggered:
+            self.seen_trap_codes.add(step.trap.cause_code)
+
+    def get_summary(self) -> dict[str, Any]:
+        count = len(self.seen_trap_codes)
+        pct = min(100.0, (count / float(self.total_trap_codes)) * 100.0)
+        return {
+            "trap_cause_codes_seen": sorted(list(self.seen_trap_codes)),
+            "coverage_percentage": round(pct, 1)
+        }

cortex/tools/verification/mutation.py

@@ -0,0 +1,48 @@
+from dataclasses import replace
+
+from cortex.tools.verification.schema import CanonicalState
+
+
+class FaultMutationEngine:
+    failure_vector: str
+
+    def __init__(self, failure_vector: str):
+        self.failure_vector = failure_vector
+
+    def apply_mutation(self, rtl_trace: list[CanonicalState]) -> list[CanonicalState]:
+        """
+        Injects synthetic faults into engine traces to verify pipeline sensitivity.
+        """
+        if not rtl_trace:
+            return rtl_trace
+
+        mutated: list[CanonicalState] = []
+        for step in rtl_trace:
+            stcr_clone = [replace(s) for s in step.stcr]
+            trap_clone = replace(step.trap)
+            c_step = CanonicalState(
+                step=step.step,
+                pc=step.pc,
+                instruction=step.instruction,
+                privilege_mode=step.privilege_mode,
+                reg_hec=step.reg_hec,
+                registers=dict(step.registers),
+                stcr=stcr_clone,
+                trap=trap_clone
+            )
+            mutated.append(c_step)
+
+        if self.failure_vector == "rtl.trap_suppress":
+            # Suppress trap flag on step 3
+            for step in mutated:
+                if step.step == 3:
+                    step.trap.triggered = False
+                    step.trap.cause_code = 0
+                    step.trap.cause_name = "None"
+        elif self.failure_vector == "rtl.stcr0.epoch_mismatch":
+            # Off-by-one epoch mismatch on step 2
+            for step in mutated:
+                if step.step == 2 and step.stcr:
+                    step.stcr[0].epoch += 1
+
+        return mutated