# Architecture of CoReason Runtime
`coreason-runtime` serves as the **Tier-1 Kinetic Execution Plane** within the Tripartite Cybernetic Manifold. It is responsible for the deterministic orchestration of multi-agent topologies, the secure execution of exogenous capabilities, and the high-velocity egress of epistemic telemetry.
This document details the core architectural pillars, security invariants, and integration boundaries that govern the runtime.
---
## 1. The Anti-Corruption Layer (Schema Decoupling)
To prevent monolithic fragility and tight coupling, `coreason-runtime` treats the `coreason-manifest` ontology strictly as an **Anti-Corruption Layer** at the API gateways.
* **API Ingress/Egress:** External requests are rigorously validated against `coreason-manifest` Pydantic v2 schemas at the FastAPI routing layer.
* **Native Dictionary Routing:** Once intent crosses the API boundary, all internal Tier-1 kinetic execution modules (including Temporal orchestration loops, WASM enclaves, and telemetry brokers) operate strictly on native Python dictionaries.
* **Impact:** This decoupling eliminates severe Pydantic serialization bottlenecks deep within the orchestration engine and allows the runtime to seamlessly handle multi-version manifest payloads natively.
---
## 2. The Zero-Trust Sandbox
All third-party tools, external MCP servers, and dynamic agent capabilities are treated as untrusted and execute within a strict isolation boundary utilizing Extism WebAssembly (WASM) enclaves.
### Workload Identity & Access Control (SPIFFE/SPIRE + Envoy)
The runtime delegates all cross-boundary identity verification and data-flow access control to the industry-standard CNCF service mesh:
* **SPIFFE/SPIRE** issues cryptographic workload identities (SVIDs) to each agent and execution thread. These replace the previously custom SPIFFE/SPIRE classification hierarchy.
* **Envoy Proxy** handles the physical mTLS handshakes between enterprise Cognitive Topologies, enforcing the Bell-LaPadula "No Write Down" axiom at the network egress boundary.
* The runtime treats all cross-boundary data flows as untrusted until verified by the service mesh sidecar, raising a `SecurityViolationError` if the mTLS handshake or identity verification fails.
### Volumetric Memory Traps
To protect the host Python daemon from memory exhaustion (OOM) attacks by compromised WASM guests, the enclave enforces an `$O(N)$` bounds-verification.
* A strict 10MB limit (`MAX_ALLOCATION_BYTES = 10485760`) is evaluated against the raw byte array returning from the guest.
* This trap is explicitly executed *before* `.decode("utf-8")` or JSON parsing occurs, immediately aborting malicious memory bombs.
### Panic Mitigation
The enclave utilizes a robust `catch_unwind` strategy. Raw Rust/C++ panics from guest binaries are never allowed to leak into the main orchestrator loop. They are caught and deterministically wrapped into standardized `ManifestConformanceError`s.
---
## 3. Ecosystem Integration (The Stateless Substrate)
`coreason-runtime` operates as a stateless kinetic edge node. It maintains no local disk dependencies for its execution capabilities, instead federating directly with the `coreason-ecosystem` governance plane.
### Stateless Capability Acquisition
The runtime utilizes the `EcosystemRegistryClient` to fetch compiled WASM binaries dynamically from the ecosystem's Capability Registry. Rather than loading `.wasm` files from local paths, the enclave invokes `initialize_from_bytes` to stream and instantiate capabilities directly into memory via their universal resource names (URNs).
### Master MCP Publication (Epistemic Crystallization)
Upon the successful synthesis and evaluation of a new dynamic topology or agent DAG, the runtime automatically initiates an Epistemic Crystallization hook.
* The topology is packaged as an `EpistemicPromotionEvent` and published to the `coreason-ecosystem` registry to acquire a permanent, globally resolvable URN.
* The runtime degrades gracefully to local LanceDB caching if the ecosystem network partition is unreachable.
---
## 4. High-Velocity Data Plane (Telemetry & ETL)
To maintain real-time observability over massive concurrent topologies without starving the asynchronous event loop (`uvloop`), the runtime employs an aggressively optimized, Arrow-native telemetry pipeline.
### Deterministic Stream Buffering
The `ContinuousStreamBuffer` manages high-velocity Server-Sent Events (SSE). To prevent distributed State-Based CRDT synchronization forks, the probabilistic forget-gate uses strict spatial hashing (SHA-1 over the token index and string value) rather than stochastic randomness (`random.random()`).
### Vectorized Silver-Layer Idempotence
Entity resolution within the Silver Layer operates natively on Apache Arrow memory via Polars.
* **Zero-GIL Execution:** The runtime strictly adheres to the "Borrow Over Build" mandate, utilizing the `polars-hash` plugin to execute cryptographic hashing natively in Rust, completely bypassing the Python Global Interpreter Lock (GIL).
* **Vectorized UUIDv5 Forgery:** To enforce strict RFC 4122 compliance, the pipeline utilizes vectorized SHA-1 hashing combined with `$O(1)$` regex bitmasking to inject the required Version (`5`) and Variant (`8`) bits.
* **Idempotence Guarantee:** The ETL logic mathematically guarantees that the generated `entity_uuid` outputs are strictly identical regardless of network arrival order or micro-batch chunk sizing.