Feature Flags

Kairos Substrate uses Cargo feature flags to control which capabilities are compiled into each target. This keeps binary sizes small and dependencies minimal — you only pay for what you use.

Per-Crate Feature Matrix

Crate	Feature	Default	Description
kairos-engine-core	license	Yes	Enables kairos-license dependency for license validation
kairos-engine-core	testing	No	Exposes Engine::new_unchecked() for tests — do not use in production
kairos-rosetta-inbound	license	Yes	Turns on native policy/license/HITL cryptographic verification
kairos-rosetta-inbound	fly-by-wire	No	Enables SubstrateSession, action gating, hazard gating, session-side HITL with replay guard
kairos-rosetta-inbound	dynamic-config	No	Enables load_artifact() from filesystem at runtime
kairos-rosetta-inbound	static-config	No	Embeds the artifact at compile time via get_artifact()
kairos-cli	tui	No	Enables kairos observe TUI dashboard (pulls in ratatui, crossterm)
kairos-wasm	fly-by-wire	No	Exposes WasmSession for browser/Node.js fly-by-wire
kairos-ffi	fly-by-wire	No	Exposes KairosSession FFI handle and all kairos_session_* functions
kairos-ffi	dynamic-config	No	Enables research-mode constructors that accept runtime artifact paths
kairos-sentinel	slm	No	Enables local SLM narrative backend (SmolLM2-1.7B via candle)

Feature Dependencies

Some features automatically enable features in dependency crates:

kairos-cli/tui
  └─ kairos-rosetta-inbound/fly-by-wire
       └─ kairos-engine-core (full engine)

kairos-wasm/fly-by-wire
  └─ kairos-rosetta-inbound/fly-by-wire

kairos-ffi/fly-by-wire
  └─ kairos-rosetta-inbound/fly-by-wire

Build Profile Comparison

Setting	release	release-native
opt-level	z (size)	3 (speed)
lto	true	true
codegen-units	1	1
strip	true	true
Target	WASM only	CLI, FFI, Python

Caution

Using --release for native targets silently degrades performance by 20–40%. Always use --profile release-native for non-WASM builds. Benchmarks must also use release-native.

Common Build Configurations

Minimal CLI (state gate only)

cargo build -p kairos-cli --profile release-native

No TUI, no fly-by-wire. Supports evaluate, trace, policy, license, and scenario commands.

Full CLI (with observe TUI)

cargo build -p kairos-cli --features tui --profile release-native

Adds kairos observe with live telemetry, projections, Sentinel panel, and HITL operator mode.

Native library (production)

cargo build -p kairos-ffi --profile release-native

C FFI with state gate evaluation. No session support.

Native library (full fly-by-wire)

cargo build -p kairos-ffi --profile release-native --features fly-by-wire

Adds KairosSession handle type with stateful evaluation, action preview, and hazard detection.

Native library (research mode)

cargo build -p kairos-ffi --profile release-native --features fly-by-wire,dynamic-config

Adds runtime artifact loading for rapid iteration without recompilation.

WASM (advisory evaluation)

wasm-pack build crates/kairos-wasm --release

Browser/Node.js evaluation without fly-by-wire session.

WASM (advisory fly-by-wire)

wasm-pack build crates/kairos-wasm --release --features fly-by-wire

Adds WasmSession for browser-side telemetry. Advisory only — no license enforcement.

Compile-Time vs Runtime Configuration

Aspect	Compile-time (features)	Runtime (files)
Session support	fly-by-wire feature	—
TUI dashboard	tui feature	—
SLM backend	slm feature	Model bundle path
License validation	license feature (default on)	License key file
Calibration artifact	static-config or dynamic-config	JSON file path
Deployment policy	—	JSON file path
HITL authorities	—	In deployment policy JSON
Enforcement mode	—	In deployment policy JSON
Gamma floor	—	In deployment policy JSON

Feature flags are compile-time decisions — they control which code paths exist in the binary. Everything else (calibration parameters, policy thresholds, HITL keys) is runtime configuration loaded from files.