cortex-runtime 0.2.0__tar.gz

cortex_runtime-0.2.0/.gitignore

@@ -0,0 +1,35 @@
+# Python & Build
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Cortex Local Execution & Traces
+.cortex/
+*.trace.json
+canonical_trace.json
+rtl_trace.json
+tmp_*.json
+test_app/
+
+# Rust & Emulator Build Artifacts
+cortex-emulator/target/
+target/
+obj_dir/
+
+# Verification & Temporary Output
+artifacts/temp/
+tools/verification/temp
+
+# Environments & IDEs
+.venv/
+.uv-venv/
+.uv/
+uv.lock
+venv/
+.vscode/
+.idea/
+.clangd
+.ruff_cache/

cortex_runtime-0.2.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cortex_runtime-0.2.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: cortex-runtime
+Version: 0.2.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
+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: 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: 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'
+Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Cortex Platform: Spatiotemporal Authority & Semantic Verification Framework
+
+[![PyPI Version](https://img.shields.io/pypi/v/cortex-runtime.svg)](https://pypi.org/project/cortex-runtime/)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Type Checked: Pyright](https://img.shields.io/badge/type--checking-pyright-brightgreen.svg)](https://github.com/microsoft/pyright)
+
+> **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.
+
+---
+
+## 📖 Narrative Arc: Why Cortex Exists
+
+### 1. The Problem at Scale
+Traditional security systems rely on static user identities (POSIX permissions, IAM roles, cgroups). However, **autonomous AI agents and non-deterministic software break traditional security models**:
+* **Ambient Authority Leakage**: Agents executing inside shell environments inherit full ambient process permissions, allowing unintended file access or dynamic execution.
+* **Subshell Script Bypasses**: Malicious or miscalibrated agents can invoke shell scripts (`.sh`), subprocesses, or eval blocks to bypass high-level application checks.
+* **Non-Deterministic State Drift**: Without causal trace verification, auditing *why* an autonomous agent performed an action after a failure or security breach is impossible.
+
+### 2. The Cortex Value Proposition
+Cortex replaces ambient authority with a **3-Layer Security Boundary**:
+1. **Static Capability Negotiation**: Manifests declare required permissions before plugins access the kernel bus (`CapabilityNegotiator`).
+2. **Runtime Sandbox Proxy**: Guarded resource drivers evaluate capability tokens before firing raw I/O system calls (`PluginContext`).
+3. **Deterministic Replay Audit**: Post-execution trace verification validates $P1$–$P4$ invariants and causal lineage graphs (`cortex workflow replay`).
+
+### 3. Dual-Layer Framing: Non-Technical Analogy vs. Technical Mechanics
+
+```mermaid
+graph TD
+    subgraph Layer 1: Passport Control
+        M[Plugin Manifest] --> N[CapabilityNegotiator]
+        N -->|Match Policy| G[ACTIVE Plugin]
+        N -->|Policy Mismatch| R[REJECTED Plugin]
+    end
+
+    subgraph Layer 2: Boarding Scanner
+        G --> C[PluginContext]
+        C --> D[Guarded Drivers: File / Net / Exec]
+        D -->|has_capability?| E[Execute Action]
+        D -->|Missing Token| V[CAPABILITY_VIOLATION Event]
+    end
+
+    subgraph Layer 3: Flight Blackbox
+        E --> S[Immutable Event Store]
+        V --> S
+        S --> RE[Deterministic Replay Engine]
+        RE --> INV[P1-P4 Invariant Checks]
+    end
+```
+
+| Security Layer | Non-Technical Analogy | Technical Mechanics |
+| :--- | :--- | :--- |
+| **Layer 1: Static Negotiation** | **Passport & Visa Check**<br/>Validates passport and visa credentials before granting entry into the country. | `CapabilityNegotiator.negotiate()` evaluates `PluginManifest.required_capabilities` against `platform_capabilities`. |
+| **Layer 2: Runtime Sandbox Proxy** | **Boarding Gate Scanner**<br/>Ensures passengers present a valid boarding pass for that specific door before entering the aircraft. | `PluginContext.has_capability()` validates tokens before Guarded Resource Drivers fire I/O system calls. |
+| **Layer 3: Verification & Trace Replay** | **Flight Blackbox Recorder**<br/>Records all flight telemetry in a tamper-evident blackbox for post-flight accident investigation. | `DeterministicReplayEngine` re-simulates event streams (`.cortex/events/*.json`), validating $P1$–$P4$ invariants. |
+
+---
+
+## 🚀 Quickstart & Developer Experience
+
+### 1. Installation
+
+Install via PyPI or fast package manager `uv`:
+
+```bash
+# Standard pip
+pip install cortex-runtime
+
+# Fast installation with Astral uv
+uv pip install cortex-runtime
+
+# Or run directly with uv tool
+uvx cortex-runtime --help
+```
+
+### 2. Scaffold a New Project
+
+```bash
+cortex init my_app --type app
+cd my_app
+```
+
+### 3. Execute, Inspect, and Replay Workflows
+
+```bash
+# Execute workflow
+cortex workflow run workflow.json
+
+# Inspect causal execution graph
+cortex workflow inspect .cortex/events/<workflow_id>.json
+
+# Perform 100% deterministic replay audit
+cortex workflow replay .cortex/events/<workflow_id>.json
+```
+
+---
+
+## 📚 Developer Portal & Quick Links
+
+- 🚀 **[Developer Quickstart Guide](docs/quickstart.md)**: Install `cortex-runtime`, build workflows, and run plugins.
+- 💻 **[CLI Reference Documentation](docs/cli.md)**: Standard CLI command usage (`init`, `workflow run`, `inspect`, `replay`).
+- 🏛️ **[Architecture & Security Model](docs/architecture.md)**: 3-layer security boundary, dual-layer framing, and threat neutralization.
+- 🔐 **[Capability Manifest Specification](docs/manifest_spec.md)**: `PluginManifest` schema and negotiation rules.
+- 🔬 **[Research Documentation](Research/)**: Formal whitepapers, mathematical invariants ($P1$–$P4$), and CS literature taxonomy.
+- 📐 **[Coq Proof Substrate](coq/)**: Interactive formal verification proof scripts.
+- ⚡ **[Rust Emulator Engine](cortex-emulator/)**: Hardware state machine emulator.
+
+---
+
+## 🔬 Adversarial Systems Research: Working Hypothesis ($H_{\text{prop}}$)
+
+This repository houses a rigorous, peer-reviewed adversarial falsification program for autonomous systems. The primary function of this research is to validate the **Working Hypothesis ($H_{\text{prop}}$)**:
+
+> **Does an existing semantic preservation relation characterize when the externally observable effects of an execution remain within the authority constraints delegated to that execution under the stated threat model?**
+>
+> *We posit this may be expressible as a relational hyperproperty over operational traces, but leave its classification strictly open pending empirical literature analysis.*
+
+If adversarial analysis reveals that a composition of existing CS frameworks satisfies all safety properties under $H_{\text{prop}}$, no new semantic layer is required. If the analysis exposes an irreducible semantic gap, that gap defines the formal requirements for a new candidate specification.
+
+---
+
+## 🛡️ The Safety Properties Catalog ($P1$–$P4$)
+
+Every composition is evaluated against four orthogonal, non-overlapping safety properties under the **Generalized Semantic Transition Relation ($\Sigma; \Lambda \vdash I \Longrightarrow e$)** mapping input streams ($I$) to terminal target actions ($e$) through intermediate **Operational Artifacts ($\mathcal{A}$)**:
+
+$$\frac{\Sigma; \Lambda \vdash I \xrightarrow{\text{derive}} \mathcal{A} \quad \quad \mathcal{A} \in \text{Adm}(\Lambda) \quad \quad \Sigma; \Lambda \vdash \mathcal{A} \xrightarrow{\text{enact}} e}{\Sigma; \Lambda \vdash I \Longrightarrow e}$$
+
+*   **P1 — Authority Soundness:** Bounded authority must be delegable and attenuable across downstream context shifts such that a principal cannot execute or delegate permissions beyond its initial envelope.
+*   **P2 — Execution Integrity:** The byte-level parameter state of an executed action must remain structurally unaltered between the generation boundary and the interface enforcement perimeters under the stated threat model.
+*   **P3 — Semantic Consequence Preservation:** Every externally observable, irreversible effect must be demonstrably and traceably derivable from the active delegation constraints: $\Sigma \models \text{Preserves}(\Lambda, e)$.
+*   **P4 — Independent Verifiability:** An external, post-facto verifier must be capable of establishing the validity of P3 without trusting the execution runtime beyond the boundaries of an explicitly declared Trusted Computing Base (TCB).
+
+---
+
+## 🔬 Literature Taxonomy (21 Disciplines)
+
+The research program maps system interactions across 21 distinct computer science areas:
+1. **Capability Security** (Confinement & Ambient Authority Elimination)
+2. **Programming Languages** (Type Safety, Scoped-Use Semantics)
+3. **Delegated Authorization** (Offline-Verifiable Attenuation)
+4. **Authorization Engines** (Relationship Graphs & Relational Logic)
+5. **Data Provenance** (Platform-Independent Derived Lineage)
+6. **Whole-System Provenance** (Kernel-Level Telemetry Interception)
+7. **Systemic Accountability** (Tamper-Evident Non-Repudiation Logs)
+8. **Distributed Transactions** (Atomicity & Consistency Guarantees)
+9. **Workflow Systems** (Durability & State Checkpointing)
+10. **Formal Methods** (Process Calculi & Temporal Logic Modelling)
+11. **Formal Verification** (Mathematical Correctness Proofs)
+12. **Information Flow Control** (Integrity Boundaries & Labels)
+13. **Trusted Computing** (Hardware Enclave Isolation)
+14. **Language-Based Security** (Non-Interference & Secure Compilation)
+15. **Operational Semantics** (Structural Operational Semantics, Evaluation Relations)
+16. **Program Logics** (Hoare Logic, Separation Logic, Refinement Calculi)
+17. **Static Analysis** (Abstract Interpretation, Monadic Effects)
+18. **Proof-Producing Computation** (SMT Solvers, Certified Abstract Interpretation)
+19. **Secure Compilation** (Robust Safety/Hyperproperty Preservation)
+20. **Algebraic & Rewriting Frameworks** (Institution Theory, Maude, K Framework)
+21. **Runtime Verification** (Online Trace Compliance & Enforcement Monitors)
+
+---
+
+## 📊 Evaluation Status Matrix
+
+Evaluating candidate compositions over safety properties P1–P4 led to the lock phase, which confirmed the need for a unified spatiotemporal semantic layer incorporating versioned epochs and step-indexing. This has been formalized as the **Cortex Spatiotemporal Mechanics** (FC_01–FC_09):
+
+| ID | Composition Structure | P1 | P2 | P3 | P4 | Verdict / Current Status |
+| --- | --- | :---: | :---: | :---: | :---: | :---: |
+| **CC-01** | Whole-System Provenance + Capability Security | **✓** | **✓** | **✗** | **✗** | **Complete (Partially Covered)** |
+| **CC-04** | Capability Security + Program Logics | **✓** | **✓** | **~** | **✗** | **Complete (Partially Covered)** |
+| **CC-05** | Language-Based Security + Trusted Computing | - | - | - | - | **FROZEN (Identified Semantic Gaps)** |
+| **CC-08** | Runtime Verification + Capability Security | - | - | - | - | **FROZEN (Identified Semantic Gaps)** |
+| **Cortex** | Spatiotemporal Preorders + Epoch-Indexed Value/Trace Relations | **✓** | **✓** | **✓** | **✓** | **FORMALLY PROVEN & ROADMAPPED** |
+
+*Legend: **✓** (Success)  |  **✗** (Failed)  |  **~** (Partial Success)  |  **-** (Not yet evaluated / Frozen)*
+
+---
+
+## 🛠️ Repository Rules & Governance
+
+1. **LOCKED State:** Foundational survey, model, and formal construction documents are frozen once complete to maintain strict control over confirmation bias.
+2. **No Marketing Syntax:** Language remains strictly technical, quantitative, and neutral.

cortex_runtime-0.2.0/README.md

@@ -0,0 +1,181 @@
+# Cortex Platform: Spatiotemporal Authority & Semantic Verification Framework
+
+[![PyPI Version](https://img.shields.io/pypi/v/cortex-runtime.svg)](https://pypi.org/project/cortex-runtime/)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Type Checked: Pyright](https://img.shields.io/badge/type--checking-pyright-brightgreen.svg)](https://github.com/microsoft/pyright)
+
+> **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.
+
+---
+
+## 📖 Narrative Arc: Why Cortex Exists
+
+### 1. The Problem at Scale
+Traditional security systems rely on static user identities (POSIX permissions, IAM roles, cgroups). However, **autonomous AI agents and non-deterministic software break traditional security models**:
+* **Ambient Authority Leakage**: Agents executing inside shell environments inherit full ambient process permissions, allowing unintended file access or dynamic execution.
+* **Subshell Script Bypasses**: Malicious or miscalibrated agents can invoke shell scripts (`.sh`), subprocesses, or eval blocks to bypass high-level application checks.
+* **Non-Deterministic State Drift**: Without causal trace verification, auditing *why* an autonomous agent performed an action after a failure or security breach is impossible.
+
+### 2. The Cortex Value Proposition
+Cortex replaces ambient authority with a **3-Layer Security Boundary**:
+1. **Static Capability Negotiation**: Manifests declare required permissions before plugins access the kernel bus (`CapabilityNegotiator`).
+2. **Runtime Sandbox Proxy**: Guarded resource drivers evaluate capability tokens before firing raw I/O system calls (`PluginContext`).
+3. **Deterministic Replay Audit**: Post-execution trace verification validates $P1$–$P4$ invariants and causal lineage graphs (`cortex workflow replay`).
+
+### 3. Dual-Layer Framing: Non-Technical Analogy vs. Technical Mechanics
+
+```mermaid
+graph TD
+    subgraph Layer 1: Passport Control
+        M[Plugin Manifest] --> N[CapabilityNegotiator]
+        N -->|Match Policy| G[ACTIVE Plugin]
+        N -->|Policy Mismatch| R[REJECTED Plugin]
+    end
+
+    subgraph Layer 2: Boarding Scanner
+        G --> C[PluginContext]
+        C --> D[Guarded Drivers: File / Net / Exec]
+        D -->|has_capability?| E[Execute Action]
+        D -->|Missing Token| V[CAPABILITY_VIOLATION Event]
+    end
+
+    subgraph Layer 3: Flight Blackbox
+        E --> S[Immutable Event Store]
+        V --> S
+        S --> RE[Deterministic Replay Engine]
+        RE --> INV[P1-P4 Invariant Checks]
+    end
+```
+
+| Security Layer | Non-Technical Analogy | Technical Mechanics |
+| :--- | :--- | :--- |
+| **Layer 1: Static Negotiation** | **Passport & Visa Check**<br/>Validates passport and visa credentials before granting entry into the country. | `CapabilityNegotiator.negotiate()` evaluates `PluginManifest.required_capabilities` against `platform_capabilities`. |
+| **Layer 2: Runtime Sandbox Proxy** | **Boarding Gate Scanner**<br/>Ensures passengers present a valid boarding pass for that specific door before entering the aircraft. | `PluginContext.has_capability()` validates tokens before Guarded Resource Drivers fire I/O system calls. |
+| **Layer 3: Verification & Trace Replay** | **Flight Blackbox Recorder**<br/>Records all flight telemetry in a tamper-evident blackbox for post-flight accident investigation. | `DeterministicReplayEngine` re-simulates event streams (`.cortex/events/*.json`), validating $P1$–$P4$ invariants. |
+
+---
+
+## 🚀 Quickstart & Developer Experience
+
+### 1. Installation
+
+Install via PyPI or fast package manager `uv`:
+
+```bash
+# Standard pip
+pip install cortex-runtime
+
+# Fast installation with Astral uv
+uv pip install cortex-runtime
+
+# Or run directly with uv tool
+uvx cortex-runtime --help
+```
+
+### 2. Scaffold a New Project
+
+```bash
+cortex init my_app --type app
+cd my_app
+```
+
+### 3. Execute, Inspect, and Replay Workflows
+
+```bash
+# Execute workflow
+cortex workflow run workflow.json
+
+# Inspect causal execution graph
+cortex workflow inspect .cortex/events/<workflow_id>.json
+
+# Perform 100% deterministic replay audit
+cortex workflow replay .cortex/events/<workflow_id>.json
+```
+
+---
+
+## 📚 Developer Portal & Quick Links
+
+- 🚀 **[Developer Quickstart Guide](docs/quickstart.md)**: Install `cortex-runtime`, build workflows, and run plugins.
+- 💻 **[CLI Reference Documentation](docs/cli.md)**: Standard CLI command usage (`init`, `workflow run`, `inspect`, `replay`).
+- 🏛️ **[Architecture & Security Model](docs/architecture.md)**: 3-layer security boundary, dual-layer framing, and threat neutralization.
+- 🔐 **[Capability Manifest Specification](docs/manifest_spec.md)**: `PluginManifest` schema and negotiation rules.
+- 🔬 **[Research Documentation](Research/)**: Formal whitepapers, mathematical invariants ($P1$–$P4$), and CS literature taxonomy.
+- 📐 **[Coq Proof Substrate](coq/)**: Interactive formal verification proof scripts.
+- ⚡ **[Rust Emulator Engine](cortex-emulator/)**: Hardware state machine emulator.
+
+---
+
+## 🔬 Adversarial Systems Research: Working Hypothesis ($H_{\text{prop}}$)
+
+This repository houses a rigorous, peer-reviewed adversarial falsification program for autonomous systems. The primary function of this research is to validate the **Working Hypothesis ($H_{\text{prop}}$)**:
+
+> **Does an existing semantic preservation relation characterize when the externally observable effects of an execution remain within the authority constraints delegated to that execution under the stated threat model?**
+>
+> *We posit this may be expressible as a relational hyperproperty over operational traces, but leave its classification strictly open pending empirical literature analysis.*
+
+If adversarial analysis reveals that a composition of existing CS frameworks satisfies all safety properties under $H_{\text{prop}}$, no new semantic layer is required. If the analysis exposes an irreducible semantic gap, that gap defines the formal requirements for a new candidate specification.
+
+---
+
+## 🛡️ The Safety Properties Catalog ($P1$–$P4$)
+
+Every composition is evaluated against four orthogonal, non-overlapping safety properties under the **Generalized Semantic Transition Relation ($\Sigma; \Lambda \vdash I \Longrightarrow e$)** mapping input streams ($I$) to terminal target actions ($e$) through intermediate **Operational Artifacts ($\mathcal{A}$)**:
+
+$$\frac{\Sigma; \Lambda \vdash I \xrightarrow{\text{derive}} \mathcal{A} \quad \quad \mathcal{A} \in \text{Adm}(\Lambda) \quad \quad \Sigma; \Lambda \vdash \mathcal{A} \xrightarrow{\text{enact}} e}{\Sigma; \Lambda \vdash I \Longrightarrow e}$$
+
+*   **P1 — Authority Soundness:** Bounded authority must be delegable and attenuable across downstream context shifts such that a principal cannot execute or delegate permissions beyond its initial envelope.
+*   **P2 — Execution Integrity:** The byte-level parameter state of an executed action must remain structurally unaltered between the generation boundary and the interface enforcement perimeters under the stated threat model.
+*   **P3 — Semantic Consequence Preservation:** Every externally observable, irreversible effect must be demonstrably and traceably derivable from the active delegation constraints: $\Sigma \models \text{Preserves}(\Lambda, e)$.
+*   **P4 — Independent Verifiability:** An external, post-facto verifier must be capable of establishing the validity of P3 without trusting the execution runtime beyond the boundaries of an explicitly declared Trusted Computing Base (TCB).
+
+---
+
+## 🔬 Literature Taxonomy (21 Disciplines)
+
+The research program maps system interactions across 21 distinct computer science areas:
+1. **Capability Security** (Confinement & Ambient Authority Elimination)
+2. **Programming Languages** (Type Safety, Scoped-Use Semantics)
+3. **Delegated Authorization** (Offline-Verifiable Attenuation)
+4. **Authorization Engines** (Relationship Graphs & Relational Logic)
+5. **Data Provenance** (Platform-Independent Derived Lineage)
+6. **Whole-System Provenance** (Kernel-Level Telemetry Interception)
+7. **Systemic Accountability** (Tamper-Evident Non-Repudiation Logs)
+8. **Distributed Transactions** (Atomicity & Consistency Guarantees)
+9. **Workflow Systems** (Durability & State Checkpointing)
+10. **Formal Methods** (Process Calculi & Temporal Logic Modelling)
+11. **Formal Verification** (Mathematical Correctness Proofs)
+12. **Information Flow Control** (Integrity Boundaries & Labels)
+13. **Trusted Computing** (Hardware Enclave Isolation)
+14. **Language-Based Security** (Non-Interference & Secure Compilation)
+15. **Operational Semantics** (Structural Operational Semantics, Evaluation Relations)
+16. **Program Logics** (Hoare Logic, Separation Logic, Refinement Calculi)
+17. **Static Analysis** (Abstract Interpretation, Monadic Effects)
+18. **Proof-Producing Computation** (SMT Solvers, Certified Abstract Interpretation)
+19. **Secure Compilation** (Robust Safety/Hyperproperty Preservation)
+20. **Algebraic & Rewriting Frameworks** (Institution Theory, Maude, K Framework)
+21. **Runtime Verification** (Online Trace Compliance & Enforcement Monitors)
+
+---
+
+## 📊 Evaluation Status Matrix
+
+Evaluating candidate compositions over safety properties P1–P4 led to the lock phase, which confirmed the need for a unified spatiotemporal semantic layer incorporating versioned epochs and step-indexing. This has been formalized as the **Cortex Spatiotemporal Mechanics** (FC_01–FC_09):
+
+| ID | Composition Structure | P1 | P2 | P3 | P4 | Verdict / Current Status |
+| --- | --- | :---: | :---: | :---: | :---: | :---: |
+| **CC-01** | Whole-System Provenance + Capability Security | **✓** | **✓** | **✗** | **✗** | **Complete (Partially Covered)** |
+| **CC-04** | Capability Security + Program Logics | **✓** | **✓** | **~** | **✗** | **Complete (Partially Covered)** |
+| **CC-05** | Language-Based Security + Trusted Computing | - | - | - | - | **FROZEN (Identified Semantic Gaps)** |
+| **CC-08** | Runtime Verification + Capability Security | - | - | - | - | **FROZEN (Identified Semantic Gaps)** |
+| **Cortex** | Spatiotemporal Preorders + Epoch-Indexed Value/Trace Relations | **✓** | **✓** | **✓** | **✓** | **FORMALLY PROVEN & ROADMAPPED** |
+
+*Legend: **✓** (Success)  |  **✗** (Failed)  |  **~** (Partial Success)  |  **-** (Not yet evaluated / Frozen)*
+
+---
+
+## 🛠️ Repository Rules & Governance
+
+1. **LOCKED State:** Foundational survey, model, and formal construction documents are frozen once complete to maintain strict control over confirmation bias.
+2. **No Marketing Syntax:** Language remains strictly technical, quantitative, and neutral.