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

{cortex_runtime-0.2.1 → cortex_runtime-0.3.0}/.gitignore

@@ -33,3 +33,9 @@ venv/
 .idea/
 .clangd
 .ruff_cache/
+
+# Private isolated workspace runtime and generated dirs
+.runtime/
+.generated/
+.cache/
+.artifacts/

cortex_runtime-0.3.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.5
+Name: cortex-runtime
+Version: 0.3.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
+Project-URL: Repository, https://github.com/Iradukunda-Fils/Cortex.git
+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
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+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: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<p align="left">
+  <img src="docs/assets/images/cortex-logo.png" alt="Cortex Logo" width="95" align="left" style="margin-right: 18px; margin-bottom: 10px;" />
+  <h1 style="border: none; margin: 0; padding: 0;">Cortex Platform</h1>
+  <h3 style="border: none; margin: 4px 0 10px 0; font-weight: 600; font-size: 1.15em;">Spatiotemporal Authority & Semantic Verification Framework</h3>
+  <a href="https://pypi.org/project/cortex-runtime/"><img src="https://img.shields.io/pypi/v/cortex-runtime.svg" alt="PyPI Version"></a> <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python Version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a> <a href="https://github.com/microsoft/pyright"><img src="https://img.shields.io/badge/type--checking-pyright-brightgreen.svg" alt="Type Checked: Pyright"></a> <a href="tests/conformance/run_certification.py"><img src="https://img.shields.io/badge/Certification-136%2F136%20PASS-brightgreen.svg" alt="Certification: 136/136 PASS"></a>
+</p>
+<br clear="left"/>
+
+> **Cortex** is a spatiotemporal authority and semantic verification framework designed to enforce execution integrity, capability-negotiated sandboxing, and post-facto deterministic verification across autonomous software runtimes and AI agent architectures.
+
+
+
+
+---
+
+## 📖 System Architecture & Design Overview
+
+Traditional security architectures rely on static user identity roles (POSIX permissions, IAM roles, cgroups) which fail under non-deterministic AI agent workloads and dynamic plugin executions:
+* **Ambient Authority Leakage**: Agents executing inside shell environments inherit full ambient process permissions, allowing unmediated filesystem or network access.
+* **Subshell Script Bypasses**: Malicious or miscalibrated plugins invoke shell scripts (`.sh`), subprocesses, or eval blocks to bypass application-level checks.
+* **Trace Non-Repudiation**: Without cryptographic trace verification, auditing *why* an autonomous agent performed a destructive side-effect is impossible.
+
+Cortex replaces ambient authority with a **Hardware/Kernel-Enforced 4-Layer Security Boundary**:
+
+```text
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+ │ 1. STATIC CAPABILITY NEGOTIATION & STCR MAPPING (Gate K / ADR-008)                          │
+ │ Manifests declare required permissions before plugins access the kernel bus.                │
+ └──────────────────────────────────────────────┬──────────────────────────────────────────────┘
+                                                │ SignedIntent Payload (CBE Format)
+                                                ▼
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+ │ 2. EXECUTION TOKEN INTENT PARITY & ACTUATION GATE (Gate H / P2)                             │
+ │ Single-use ExecutionTokens bind tokens strictly to intent hashes: D3 == D2                  │
+ └──────────────────────────────────────────────┬──────────────────────────────────────────────┘
+                                                │ Governed Side-Effect Execution
+                                                ▼
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+ │ 3. ROLLING CAUSAL WITNESS JOURNALING (Gate I / P3)                                          │
+ │ Emits tamper-evident rolling hash commitments: W_{t+1} = SHA256(W_t || D_E || D_I)          │
+ └──────────────────────────────────────────────┬──────────────────────────────────────────────┘
+                                                │ Raw Evidence Traces (R, E)
+                                                ▼
+ ┌───────────────────────────────────────────────────────────────────────────────────────────────┐
+ │ 4. ZERO-DEPENDENCY INDEPENDENT UNTRUSTED VERIFIER (Gate J / P4)                               │
+ │ Standalone CLI tools/cortex-verifier evaluates traces ➔ VALID (0), INVALID (1), INDETERMINATE │
+ └───────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🗺️ Repository Map & Documentation Architecture
+
+For open-source contributors and systems architects, the codebase is structured logically across normative specifications, architecture records, polyglot engines, and verification suites:
+
+```text
+Cortex Platform Architecture Map
+├── docs/                                    # Master Technical & Specification Portal
+│   ├── architecture/                        # Architectural Audits & Verification Matrices
+│   │   ├── verification_closure_matrix.md   # Master Phase 13 Assurance Status Matrix
+│   │   ├── gate_g_complete_mediation_inventory.md # Complete Mediation Path Analysis
+│   │   └── threat_model.md                  # Threat Vectors & Mitigation Catalog
+│   ├── spec/                                # Normative Protocol & Security Specifications
+│   │   ├── gate_g_remediation_specification.md # Worker Sandbox & Narrow IPC Architecture
+│   │   ├── gate_h_execution_token_specification.md # ExecutionToken & Intent Parity Spec (P2)
+│   │   ├── gate_i_causal_witness_specification.md  # Rolling Witness Chain Specification (P3)
+│   │   ├── gate_j_independent_verifier_specification.md # Untrusted Verifier Engine Spec (P4)
+│   │   └── v03_layer2_streaming_spec.md     # Layer 2 Streaming Protocol Framing
+│   └── adrs/                                # Architectural Decision Records
+│       └── ADR-008-identity-specification-supersession.md # Identity Supersession (UUIDv5/v7)
+│
+├── tools/                                   # Standalone Tooling & Verification Engines
+│   └── cortex_verifier.py                   # Zero-dependency Independent Verifier CLI (Gate J)
+│
+├── tests/conformance/                       # Conformance & Adversarial Certification Suite
+│   ├── run_certification.py                 # Master 74-Check Conformance Test Runner
+│   ├── test_gate_h_adversarial.py           # Gate H Parity & Replay Protection Tests (21/21)
+│   ├── test_gate_i_causal_witness.py        # Gate I Tamper-Evident Witness Chain Tests (7/7)
+│   └── test_gate_j_independent_verifier.py # Gate J Verifier Engine Adversarial Tests (12/12)
+│
+├── cortex/                                  # Python Control Plane & Reference Runtime
+├── cortex-emulator/                         # Rust STCR Hardware State Machine Emulator
+├── cortex-go/                               # Go Layer 2 High-Concurrency Transport Adapter
+└── rtl/                                     # SystemVerilog STCR Hardware Pipeline
+```
+
+---
+
+## 🛡️ The Safety Invariants Matrix ($P1$–$P4$)
+
+| Security Invariant | Mathematical / Normative Definition | Status | Empirical Verification & Test Harness |
+| :--- | :--- | :---: | :--- |
+| **$P1$: Authority Attenuation** | $\Lambda_{t+1} \subseteq \Lambda_t \land w_1 \sqsubseteq w_2$ | **PARTIAL** | Python `PluginContext` & Rust `cortex-emulator` STCR. |
+| **$P2$: Execution Parity** | $D_3 \equiv D_2 \equiv \text{SHA256}(\text{CBE}(\text{SignedIntent}))$ | **CERTIFIED** | 21/21 Gate H Scenarios PASS (`test_gate_h_adversarial.py`). |
+| **$P3$: Causal Witness** | $W_{t+1} = \text{SHA256}(W_t \parallel \text{CBE}(E_{t+1}) \parallel \text{CBE}(I_{t+1}))$ | **CERTIFIED** | 7/7 Gate I Scenarios PASS (`test_gate_i_causal_witness.py`). |
+| **$P4$: Independent Verifier** | $\text{Verify}(R, E) \to \{\text{VALID, INVALID, INDETERMINATE}\}$ | **CERTIFIED** | 12/12 Gate J Scenarios PASS (`tools/cortex_verifier.py`). |
+| **Complete Mediation (Gate G)** | $\forall \text{eff} \in \text{Effects}, \text{eff} \text{ passes through } \text{ExecutionToken}$ | **SPECIFIED** | Sandbox & Narrow IPC Architecture (`gate_g_remediation_specification.md`). |
+
+---
+
+## ⚡ Contributor Quickstart & Test Commands
+
+### 1. Prerequisites & Environment Setup
+Clone the repository and install dependencies via `uv` or standard Python 3.10+:
+
+```bash
+git clone https://github.com/Iradukunda-Fils/Cortex.git
+cd Cortex
+uv venv && source .venv/bin/activate
+uv pip install -e .
+```
+
+### 2. Run Static Analysis & Type Checking
+Ensure 0 type errors across the codebase:
+```bash
+pyright
+```
+
+### 3. Run Master Certification Pipeline
+Execute the full 74-check conformance suite covering golden corpus vectors, Coq/Rust/RTL cycle assertions, Gate H parity, Gate I witness, and Gate J verification:
+```bash
+python3 tests/conformance/run_certification.py
+```
+
+### 4. Run Independent Verifier Engine CLI
+Verify raw untrusted evidence bundles out-of-band without importing runtime modules:
+```bash
+python3 tools/cortex_verifier.py tests/conformance/fixtures/evidence_bundle_valid.json
+# Output: VERDICT: VALID (0) - EVIDENCE_VERIFIED_VALID
+```
+
+---
+
+## 💻 Developer Code Example: End-to-End Governed Execution
+
+Here is how an application mints an intent, acquires an `ExecutionToken`, and enforces $D_3 \equiv D_2$ parity:
+
+```python
+import hashlib
+from cortex.cbe import encode_cbe
+
+# 1. Define SignedIntent
+intent_payload = {
+    "body": {
+        "intent_type": "STORAGE_WRITE",
+        "target_resource": "/data/export.csv",
+        "payload": {"bytes": 1024},
+        "timestamp_ns": 1776274200000000000
+    },
+    "authority_pubkey": "PUBKEY_NODE_01",
+    "signature": "a3f890b..."
+}
+
+# 2. Mint ExecutionToken (D2 = SHA256(CBE(SignedIntent)))
+signed_intent_cbe = encode_cbe(intent_payload)
+intent_hash_d2 = hashlib.sha256(signed_intent_cbe).hexdigest()
+token = {"intent_hash": intent_hash_d2, "epoch": 1, "nonce": "abc123nonce"}
+
+# 3. Actuation Boundary Assertion (D3 == D2)
+d3_hash = hashlib.sha256(encode_cbe(intent_payload)).hexdigest()
+if d3_hash != token["intent_hash"]:
+    raise PermissionError(f"TRAP_INTENT_PARITY_MISMATCH: {d3_hash} != {token['intent_hash']}")
+
+print("✅ Governed Side-Effect Actuated Successfully!")
+```
+
+---
+
+## 📄 License & Governance
+
+Licensed under the **Apache License, Version 2.0**. See [LICENSE](LICENSE) for details.

cortex_runtime-0.3.0/README.md

@@ -0,0 +1,171 @@
+<p align="left">
+  <img src="docs/assets/images/cortex-logo.png" alt="Cortex Logo" width="95" align="left" style="margin-right: 18px; margin-bottom: 10px;" />
+  <h1 style="border: none; margin: 0; padding: 0;">Cortex Platform</h1>
+  <h3 style="border: none; margin: 4px 0 10px 0; font-weight: 600; font-size: 1.15em;">Spatiotemporal Authority & Semantic Verification Framework</h3>
+  <a href="https://pypi.org/project/cortex-runtime/"><img src="https://img.shields.io/pypi/v/cortex-runtime.svg" alt="PyPI Version"></a> <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python Version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a> <a href="https://github.com/microsoft/pyright"><img src="https://img.shields.io/badge/type--checking-pyright-brightgreen.svg" alt="Type Checked: Pyright"></a> <a href="tests/conformance/run_certification.py"><img src="https://img.shields.io/badge/Certification-136%2F136%20PASS-brightgreen.svg" alt="Certification: 136/136 PASS"></a>
+</p>
+<br clear="left"/>
+
+> **Cortex** is a spatiotemporal authority and semantic verification framework designed to enforce execution integrity, capability-negotiated sandboxing, and post-facto deterministic verification across autonomous software runtimes and AI agent architectures.
+
+
+
+
+---
+
+## 📖 System Architecture & Design Overview
+
+Traditional security architectures rely on static user identity roles (POSIX permissions, IAM roles, cgroups) which fail under non-deterministic AI agent workloads and dynamic plugin executions:
+* **Ambient Authority Leakage**: Agents executing inside shell environments inherit full ambient process permissions, allowing unmediated filesystem or network access.
+* **Subshell Script Bypasses**: Malicious or miscalibrated plugins invoke shell scripts (`.sh`), subprocesses, or eval blocks to bypass application-level checks.
+* **Trace Non-Repudiation**: Without cryptographic trace verification, auditing *why* an autonomous agent performed a destructive side-effect is impossible.
+
+Cortex replaces ambient authority with a **Hardware/Kernel-Enforced 4-Layer Security Boundary**:
+
+```text
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+ │ 1. STATIC CAPABILITY NEGOTIATION & STCR MAPPING (Gate K / ADR-008)                          │
+ │ Manifests declare required permissions before plugins access the kernel bus.                │
+ └──────────────────────────────────────────────┬──────────────────────────────────────────────┘
+                                                │ SignedIntent Payload (CBE Format)
+                                                ▼
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+ │ 2. EXECUTION TOKEN INTENT PARITY & ACTUATION GATE (Gate H / P2)                             │
+ │ Single-use ExecutionTokens bind tokens strictly to intent hashes: D3 == D2                  │
+ └──────────────────────────────────────────────┬──────────────────────────────────────────────┘
+                                                │ Governed Side-Effect Execution
+                                                ▼
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+ │ 3. ROLLING CAUSAL WITNESS JOURNALING (Gate I / P3)                                          │
+ │ Emits tamper-evident rolling hash commitments: W_{t+1} = SHA256(W_t || D_E || D_I)          │
+ └──────────────────────────────────────────────┬──────────────────────────────────────────────┘
+                                                │ Raw Evidence Traces (R, E)
+                                                ▼
+ ┌───────────────────────────────────────────────────────────────────────────────────────────────┐
+ │ 4. ZERO-DEPENDENCY INDEPENDENT UNTRUSTED VERIFIER (Gate J / P4)                               │
+ │ Standalone CLI tools/cortex-verifier evaluates traces ➔ VALID (0), INVALID (1), INDETERMINATE │
+ └───────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🗺️ Repository Map & Documentation Architecture
+
+For open-source contributors and systems architects, the codebase is structured logically across normative specifications, architecture records, polyglot engines, and verification suites:
+
+```text
+Cortex Platform Architecture Map
+├── docs/                                    # Master Technical & Specification Portal
+│   ├── architecture/                        # Architectural Audits & Verification Matrices
+│   │   ├── verification_closure_matrix.md   # Master Phase 13 Assurance Status Matrix
+│   │   ├── gate_g_complete_mediation_inventory.md # Complete Mediation Path Analysis
+│   │   └── threat_model.md                  # Threat Vectors & Mitigation Catalog
+│   ├── spec/                                # Normative Protocol & Security Specifications
+│   │   ├── gate_g_remediation_specification.md # Worker Sandbox & Narrow IPC Architecture
+│   │   ├── gate_h_execution_token_specification.md # ExecutionToken & Intent Parity Spec (P2)
+│   │   ├── gate_i_causal_witness_specification.md  # Rolling Witness Chain Specification (P3)
+│   │   ├── gate_j_independent_verifier_specification.md # Untrusted Verifier Engine Spec (P4)
+│   │   └── v03_layer2_streaming_spec.md     # Layer 2 Streaming Protocol Framing
+│   └── adrs/                                # Architectural Decision Records
+│       └── ADR-008-identity-specification-supersession.md # Identity Supersession (UUIDv5/v7)
+│
+├── tools/                                   # Standalone Tooling & Verification Engines
+│   └── cortex_verifier.py                   # Zero-dependency Independent Verifier CLI (Gate J)
+│
+├── tests/conformance/                       # Conformance & Adversarial Certification Suite
+│   ├── run_certification.py                 # Master 74-Check Conformance Test Runner
+│   ├── test_gate_h_adversarial.py           # Gate H Parity & Replay Protection Tests (21/21)
+│   ├── test_gate_i_causal_witness.py        # Gate I Tamper-Evident Witness Chain Tests (7/7)
+│   └── test_gate_j_independent_verifier.py # Gate J Verifier Engine Adversarial Tests (12/12)
+│
+├── cortex/                                  # Python Control Plane & Reference Runtime
+├── cortex-emulator/                         # Rust STCR Hardware State Machine Emulator
+├── cortex-go/                               # Go Layer 2 High-Concurrency Transport Adapter
+└── rtl/                                     # SystemVerilog STCR Hardware Pipeline
+```
+
+---
+
+## 🛡️ The Safety Invariants Matrix ($P1$–$P4$)
+
+| Security Invariant | Mathematical / Normative Definition | Status | Empirical Verification & Test Harness |
+| :--- | :--- | :---: | :--- |
+| **$P1$: Authority Attenuation** | $\Lambda_{t+1} \subseteq \Lambda_t \land w_1 \sqsubseteq w_2$ | **PARTIAL** | Python `PluginContext` & Rust `cortex-emulator` STCR. |
+| **$P2$: Execution Parity** | $D_3 \equiv D_2 \equiv \text{SHA256}(\text{CBE}(\text{SignedIntent}))$ | **CERTIFIED** | 21/21 Gate H Scenarios PASS (`test_gate_h_adversarial.py`). |
+| **$P3$: Causal Witness** | $W_{t+1} = \text{SHA256}(W_t \parallel \text{CBE}(E_{t+1}) \parallel \text{CBE}(I_{t+1}))$ | **CERTIFIED** | 7/7 Gate I Scenarios PASS (`test_gate_i_causal_witness.py`). |
+| **$P4$: Independent Verifier** | $\text{Verify}(R, E) \to \{\text{VALID, INVALID, INDETERMINATE}\}$ | **CERTIFIED** | 12/12 Gate J Scenarios PASS (`tools/cortex_verifier.py`). |
+| **Complete Mediation (Gate G)** | $\forall \text{eff} \in \text{Effects}, \text{eff} \text{ passes through } \text{ExecutionToken}$ | **SPECIFIED** | Sandbox & Narrow IPC Architecture (`gate_g_remediation_specification.md`). |
+
+---
+
+## ⚡ Contributor Quickstart & Test Commands
+
+### 1. Prerequisites & Environment Setup
+Clone the repository and install dependencies via `uv` or standard Python 3.10+:
+
+```bash
+git clone https://github.com/Iradukunda-Fils/Cortex.git
+cd Cortex
+uv venv && source .venv/bin/activate
+uv pip install -e .
+```
+
+### 2. Run Static Analysis & Type Checking
+Ensure 0 type errors across the codebase:
+```bash
+pyright
+```
+
+### 3. Run Master Certification Pipeline
+Execute the full 74-check conformance suite covering golden corpus vectors, Coq/Rust/RTL cycle assertions, Gate H parity, Gate I witness, and Gate J verification:
+```bash
+python3 tests/conformance/run_certification.py
+```
+
+### 4. Run Independent Verifier Engine CLI
+Verify raw untrusted evidence bundles out-of-band without importing runtime modules:
+```bash
+python3 tools/cortex_verifier.py tests/conformance/fixtures/evidence_bundle_valid.json
+# Output: VERDICT: VALID (0) - EVIDENCE_VERIFIED_VALID
+```
+
+---
+
+## 💻 Developer Code Example: End-to-End Governed Execution
+
+Here is how an application mints an intent, acquires an `ExecutionToken`, and enforces $D_3 \equiv D_2$ parity:
+
+```python
+import hashlib
+from cortex.cbe import encode_cbe
+
+# 1. Define SignedIntent
+intent_payload = {
+    "body": {
+        "intent_type": "STORAGE_WRITE",
+        "target_resource": "/data/export.csv",
+        "payload": {"bytes": 1024},
+        "timestamp_ns": 1776274200000000000
+    },
+    "authority_pubkey": "PUBKEY_NODE_01",
+    "signature": "a3f890b..."
+}
+
+# 2. Mint ExecutionToken (D2 = SHA256(CBE(SignedIntent)))
+signed_intent_cbe = encode_cbe(intent_payload)
+intent_hash_d2 = hashlib.sha256(signed_intent_cbe).hexdigest()
+token = {"intent_hash": intent_hash_d2, "epoch": 1, "nonce": "abc123nonce"}
+
+# 3. Actuation Boundary Assertion (D3 == D2)
+d3_hash = hashlib.sha256(encode_cbe(intent_payload)).hexdigest()
+if d3_hash != token["intent_hash"]:
+    raise PermissionError(f"TRAP_INTENT_PARITY_MISMATCH: {d3_hash} != {token['intent_hash']}")
+
+print("✅ Governed Side-Effect Actuated Successfully!")
+```
+
+---
+
+## 📄 License & Governance
+
+Licensed under the **Apache License, Version 2.0**. See [LICENSE](LICENSE) for details.

cortex_runtime-0.3.0/cortex/_research/__init__.py

@@ -0,0 +1,8 @@
+"""
+Cortex Internal Research Package (_research)
+
+Private internal research modules for empirical fault boundary research.
+Strictly non-public: NOT exported in cortex.__all__.
+"""
+
+__all__: list[str] = []

cortex_runtime-0.3.0/cortex/_research/architecture_gate.py

@@ -0,0 +1,141 @@
+"""
+Architecture Research Gate & Synthesis Module (Post Issue #12)
+
+Synthesizes empirical findings from Issues #10, #11, and #12 to evaluate:
+1. State recovery & EventStore guarantees
+2. Side-effect semantics & IN_DOUBT state contracts
+3. Recovery contract specification
+4. Comparative topology analysis (Tiered Hybrid Isolation vs Process-per-Plugin)
+"""
+
+import json
+import os
+import platform
+import sys
+import time
+from typing import Any
+
+
+def generate_architecture_gate_synthesis() -> dict[str, Any]:
+    """Generates the structured Architecture Gate research synthesis data."""
+    env_metadata = {
+        "python_version": sys.version.split()[0],
+        "os": platform.system(),
+        "arch": platform.machine(),
+    }
+
+    empirical_evidence = {
+        "issue_10_telemetry": {
+            "baseline_p50_ms": 0.2265,
+            "multistage_p50_ms": 0.5014,
+            "tail_p99_ms": 4.0892,
+            "event_propagation_scaling": "Observed approximately linear growth over tested workload range",
+            "public_api_symbols": 21,
+        },
+        "issue_11_crash_semantics": {
+            "ordinary_python_exception_trapped": True,
+            "cortex_error_classification_preserved": True,
+            "capability_rejection_security_intact": True,
+            "chained_execution_prior_events_preserved": True,
+            "subsequent_workflow_isolated": True,
+            "single_process_limit": "Low-level process crashes (SIGSEGV, sys.exit) escape single-process boundary",
+        },
+        "issue_12_timeout_cancellation": {
+            "pre_execution_cancellation_clean": True,
+            "mid_workflow_cooperative_halt": True,
+            "event_journal_lineage_post_cancellation_intact": True,
+            "subsequent_workflow_healthy": True,
+            "deterministic_cancellation": True,
+            "single_process_limitation": "Non-cooperative thread blocking (time.sleep, GIL loops) stalls main event thread",
+        },
+    }
+
+    five_architectural_questions = {
+        "q1_recovery_targets": {
+            "authoritative_source": "EventStore append-only journal log",
+            "volatile_components": ["In-memory event queues", "Active plugin handler frames", "Transient client state"],
+            "persistent_components": ["EventStore journal log", "Workflow dataclass state", "PluginManifest records"],
+            "state_reconstruction_method": "Replaying event journal from t=0 to crash point t_crash",
+        },
+        "q2_eventstore_guarantees": {
+            "persistence_model": "Synchronous append upon context.publish()",
+            "lineage_integrity": "Strict DAG ordering via event_id -> causation_id -> correlation_id",
+            "replay_determinism": "Replaying log against clean client reproduces identical state machine sequence",
+            "crash_point_semantics": {
+                "pre_side_effect_crash": "Operation unexecuted; safe to re-run on restart",
+                "mid_side_effect_crash": "Operation partially performed; event missing -> requires IN_DOUBT state",
+                "post_side_effect_crash": "Operation complete; event committed -> safe replay",
+            },
+        },
+        "q3_side_effect_semantics": {
+            "unconfirmed_side_effect_problem": "Runtime crashes after external side effect but before completion event is persisted",
+            "chosen_contract_option": "Option B (IN_DOUBT state) + Option C (Required Idempotency Keys)",
+            "rationale": "Prevents catastrophic double-execution of non-idempotent external operations while giving operators explicit CLI resolution tools.",
+        },
+        "q4_recovery_contract_spec": {
+            "event_delivery": "At-least-once with deduplication by event_id",
+            "plugin_execution": "At-most-once per event emission",
+            "workflow_recovery": "Deterministic EventStore journal replay",
+            "side_effects": "Idempotency keys required for side-effect capabilities",
+            "crash_point": "Arbitrary instruction / signal boundary",
+            "state_reconstruction": "Pure function of EventStore log: S_t = f(S_0, E_1, ..., E_t)",
+            "unknown_operation": "Explicit IN_DOUBT workflow state",
+            "cancellation": "Cooperative (in-process) / Forced (SIGKILL worker process)",
+            "recovery_control": "Automatic for deterministic events; Operator-assisted for IN_DOUBT operations",
+        },
+        "q5_architectural_topology_comparison": {
+            "topologies_evaluated": [
+                {
+                    "name": "Topology 1: Process-per-Plugin",
+                    "pros": "Maximum isolation; crashed plugin cannot kill host or peer plugins",
+                    "cons": "High process creation & IPC latency overhead",
+                    "cortex_fit": "Suitable for untrusted / high-risk plugins only",
+                },
+                {
+                    "name": "Topology 2: Shared Worker Pool",
+                    "pros": "Lower process overhead than 1:1",
+                    "cons": "Crash in worker process affects all plugins assigned to worker",
+                    "cortex_fit": "Suitable for medium-risk plugin groups",
+                },
+                {
+                    "name": "Topology 3: Tiered / Hybrid Isolation (RECOMMENDED)",
+                    "pros": "Sub-millisecond performance (P50 = 0.226ms) for trusted plugins in-process; SIGKILL preemption and fault containment for untrusted / heavy plugins in worker processes",
+                    "cons": "Requires trust/isolation metadata in capability manifests",
+                    "cortex_fit": "PERFECT FIT with Cortex capability security model",
+                },
+            ],
+            "recommended_architecture": "Topology 3: Tiered Hybrid Isolation Model",
+        },
+    }
+
+    readiness_decision = {
+        "architecture_gate_passed": True,
+        "recommendation": "Proceed to Issue #13 (Runtime Restart & Workflow Recovery Semantics) with IN_DOUBT state contracts and Tiered Hybrid Architecture principles established.",
+        "issue_13_authorized": True,
+    }
+
+    return {
+        "timestamp_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "environment": env_metadata,
+        "empirical_evidence": empirical_evidence,
+        "synthesis": five_architectural_questions,
+        "gate_decision": readiness_decision,
+    }
+
+
+def generate_architecture_gate_artifacts(json_output_path: str) -> dict[str, Any]:
+    """Generates and writes research/synthesis/architecture_gate_synthesis.json."""
+    data = generate_architecture_gate_synthesis()
+    os.makedirs(os.path.dirname(os.path.abspath(json_output_path)), exist_ok=True)
+    with open(json_output_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+    return data
+
+
+if __name__ == "__main__":
+    report_file = os.path.join("research", "synthesis", "architecture_gate_synthesis.json")
+    res = generate_architecture_gate_artifacts(report_file)
+    print(f"Architecture Gate Decision: Passed={res['gate_decision']['architecture_gate_passed']}")
+    print(
+        f"Recommended v0.3 Topology: {res['synthesis']['q5_architectural_topology_comparison']['recommended_architecture']}"
+    )