Skip to content

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 Swarms, 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 ManifestConformanceErrors.

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 swarm 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 swarms 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.