Architecture

Kairos Substrate is organized as a Rust workspace of 11 crates. Each crate has a focused responsibility, and the dependency graph flows from core simulation logic outward to binding layers.

Crate Map

kairos-engine/
  crates/
    kairos-engine-core/       Core simulation engine (types, tick, reachability, agents, traces)
    kairos-rosetta-inbound/   Substrate runtime, fly-by-wire session, action gating, HITL protocol
    kairos-license/           Cryptographic license validation and RSA-PSS verification
    kairos-sentinel/          Telemetry-to-text translation (template + optional SLM backend)
    kairos-hitl-coordinator/  Authoritative HITL control-plane service
    kairos-llm-adapter/       LLM adapter for AI safety evaluation routing
    kairos-moe-adapter/       MoE adapter mapping expert routing onto the actor model
    kairos-cli/               CLI binary (trace, evaluate, observe, policy, license)
    kairos-wasm/              wasm-bindgen bridge for browser/Node.js
    kairos-ffi/               C FFI exports + cbindgen header generation
    kairos-pylib/             PyO3 Python bindings (built with maturin)

Crate	Output	Purpose
`kairos-engine-core`	`rlib`	Shared simulation logic — all other crates depend on this
`kairos-rosetta-inbound`	`rlib`	Evaluation pipeline, policy resolution, scaling, HITL verification
`kairos-license`	`rlib`	RSA-PSS signature verification, machine fingerprinting, license enforcement
`kairos-sentinel`	`rlib`	Stateless telemetry-to-text translation for operator dashboards
`kairos-hitl-coordinator`	`rlib` + service	Operator-side control plane for override token issuance and redemption
`kairos-llm-adapter`	`rlib`	Maps LLM pipeline actions onto the Substrate actor model
`kairos-moe-adapter`	`rlib`	Maps MoE expert routing onto the Substrate actor model
`kairos-cli`	binary	`kairos` CLI tool
`kairos-wasm`	`cdylib` (WASM)	`WasmEngine` and feature-gated `WasmSession`
`kairos-ffi`	`cdylib` + `staticlib`	C header (`kairos_engine.h`) + shared/static library
`kairos-pylib`	`cdylib` (Python ext)	`kairos_engine` Python package via PyO3

Dependency Flow

                    kairos-engine-core
                           │
                    kairos-license
                           │
                   kairos-rosetta-inbound
                    ╱      │       ╲
          kairos-sentinel  │  kairos-llm-adapter
                           │  kairos-moe-adapter
                           │
            ┌──────────────┼──────────────┐
            │              │              │
       kairos-cli    kairos-ffi    kairos-wasm
                     kairos-pylib

kairos-engine-core sits at the root — it contains all simulation logic (tick execution, reachability analysis, agent management, trace recording) with zero external dependencies beyond serde. Every other crate depends on it.

kairos-rosetta-inbound is the integration layer. It loads calibration artifacts and deployment policies, performs metric scaling, runs the evaluation pipeline, and hosts the optional fly-by-wire session. The fly-by-wire feature gate adds SubstrateSession, action gating, and hazard detection.

The binding crates (kairos-cli, kairos-ffi, kairos-wasm, kairos-pylib) are thin wrappers that expose the evaluation surface to their respective platforms.

Data Flow

The evaluation pipeline processes data in a single pass:

Domain Metrics                  Calibration Artifact
(capabilityIndex, etc.)         (scaling functions)
        │                              │
        └──────────┬───────────────────┘
                   ▼
           Metric Scaling
        (domain → λ, γ values)
                   │
                   ▼
            Engine Tick
     (simulation step, reachability)
                   │
                   ▼
         Telemetry Snapshot
     (warning signal, projections)
                   │
                   ▼
          Escalation Check
     (gamma headroom → routing)
                   │
                   ▼
            Gate Chain
   (state gate → action gate → hazard gate)
                   │
                   ▼
        EvaluationResponse
   (decision, evaluation detail, escalation)

Key Types

EvaluationRequest

The inbound request envelope. All fields use camelCase JSON serialization.

{
  "envelopeVersion": 1,
  "requestId": "req-001",
  "snapshot": {
    "timestamp": "2026-03-21T12:00:00.000Z",
    "signature": null,
    "metrics": {
      "capabilityIndex": 450.0,
      "alignmentScore": 72.0
    }
  },
  "action": null,
  "actorId": "agent-default",
  "overrideToken": null
}

EvaluationResponse

The outbound response envelope.

{
  "envelopeVersion": 1,
  "requestId": "req-001",
  "decision": "PASS",
  "reasonCode": "NONE",
  "mode": "state_gate",
  "policyVersion": 1,
  "adapterVersion": 1,
  "evaluation": {
    "currentGamma": 0.68,
    "gammaFloor": 0.20,
    "currentLambda": 0.89,
    "stability": 2.40,
    "predictedGamma": null,
    "engineTick": 1
  },
  "escalation": null,
  "overrideOutcome": null,
  "timestamp": "2026-03-21T12:00:00.500Z"
}

Decision Codes

Decision	Meaning
`PASS`	Action permitted
`REJECT_STATE`	Gamma below floor threshold
`REJECT_ACTION`	Action preview predicts unsafe outcome
`REJECT_BASIN_COLLAPSE`	Engine preview predicts a loss event (session-only)
`REJECT_PARADOX`	Multi-agent paradox detected (session-only)
`REJECT_STALE_METRICS`	Metric snapshot too old per policy
`REJECT_INVALID_SIGNATURE`	Metric snapshot HMAC verification failed
`REJECT_LICENSE`	License expired, invalid, or domain not permitted
`ERROR`	Internal error during evaluation

Reason Codes

Reason Code	Paired with
`NONE`	`PASS`
`GAMMA_BELOW_FLOOR`	`REJECT_STATE`
`ACTION_PREVIEW_UNSAFE`	`REJECT_ACTION`
`TOTAL_FUTURE_COLLAPSE`	`REJECT_BASIN_COLLAPSE`
`DUAL_ADMINISTRATOR_PARADOX`	`REJECT_PARADOX`
`SNAPSHOT_TOO_OLD`	`REJECT_STALE_METRICS`
`SIGNATURE_MISMATCH`	`REJECT_INVALID_SIGNATURE`
`LICENSE_EXPIRED`	`REJECT_LICENSE`
`DOMAIN_NOT_PERMITTED`	`REJECT_LICENSE`
`INTERNAL_ERROR`	`ERROR`

Design Principles

Determinism — Mulberry32 seeded RNG + IndexMap for deterministic iteration order. Same seed, config, and moves always produce identical traces (validated at $\epsilon = 10^{-6}$ ).
Single codebase, multiple targets — kairos-engine-core contains all simulation logic. Binding crates are thin wrappers.
Memory safety — No unsafe in core engine. FFI boundaries catch all panics.
Thread model — Send but not Sync. Each engine instance is single-threaded. Multiple independent engines can run on separate threads.