WASM Bindings

The kairos-wasm crate compiles the Kairos engine to WebAssembly for browser and Node.js environments. It exports two classes: WasmEngine for raw simulation and WasmSession (behind a feature flag) for fly-by-wire evaluation.

Build

# Default build (WasmEngine only)
wasm-pack build crates/kairos-wasm --target web

# With fly-by-wire feature (adds WasmSession)
wasm-pack build crates/kairos-wasm --target web --features fly-by-wire

# For Node.js
wasm-pack build crates/kairos-wasm --target nodejs --features fly-by-wire

Output is an npm-publishable package in pkg/.

Advisory vs Authoritative

The WASM runtime operates in advisory mode:

Aspect	WASM (advisory)	Native (authoritative)
Policy signature	Skipped	Verified
License enforcement	Skipped	Enforced
HITL override tokens	Always rejected	Cryptographically verified
Domain/expiry checks	Skipped	Enforced

WASM bindings are suitable for dashboards, previews, and client-side simulations. Production enforcement must use a native licensed build.

`WasmEngine`

The core simulation engine — no policy evaluation, no Substrate runtime. All methods use camelCase for JavaScript convention.

Constructor

import { WasmEngine } from "kairos-wasm";

const engine = new WasmEngine(
  { columns: 25, rows: 17, lambda: 0.65, gamma: 0.1 },
  { x: 0, y: 0 }
);

Configuration

Method	Returns	Description
`setSeed(seed)`	`void`	Set RNG seed
`getSeed()`	`number`	Get current seed
`setLambda(v)`	`void`	Set $\lambda$ parameter
`getLambda()`	`number`	Get $\lambda$ parameter
`setGamma(v)`	`void`	Set $\gamma$ parameter
`getGamma()`	`number`	Get $\gamma$ parameter
`setGridSize(cols, rows)`	`void`	Override grid dimensions
`setZeroSumEnabled(enabled)`	`void`	Toggle zero-sum attractor capture
`getConfig()`	`object`	Current engine config

State

Method	Returns	Description
`getState()`	`object`	Current engine state (`t`, `b`, `lastMove`, `marker`)
`getWarningSignal()`	`object`	Warning signal (`active`, `level`, `kind`, `metrics`)
`setState(state)`	`void`	Set engine state
`setMarker(marker)`	`void`	Set marker position
`primaryAgentId()`	`string`	Get primary agent ID

Simulation

Method	Returns	Description
`runTick()`	`object`	Execute single-agent tick
`runTickMulti(moves)`	`object`	Execute multi-agent tick
`decideNextMoveForAgent(id)`	`MoveDirection`	Policy-decided move for one agent
`decideAllMoves()`	`object`	Policy-decided moves for all agents

Agent Management

Method	Returns	Description
`getAgentStates()`	`AgentState[]`	All agent states
`resetAgents(setups)`	`void`	Reset agents from setup array
`updateAgentPolicy(id, lambda, gamma)`	`void`	Update per-agent policy overrides

Special Nodes

Method	Returns	Description
`getSpecialNodes()`	`SpecialNode[]`	All attractors and repulsors
`getSpecialNodesInRange(tMin, tMax, bMin, bMax)`	`SpecialNode[]`	Nodes within bounding box
`setSpecialNodes(nodes)`	`void`	Replace all special nodes

Reachability

Method	Returns	Description
`computeReachabilityField(horizon)`	`void`	Compute reachability DP
`getReachabilityTotal(t, b)`	`number`	Reachability value at grid position
`getAllowedMoves(t, b)`	`number`	Allowed moves bitmask at position

Trace Recording

Method	Returns	Description
`startRecording(scenarioId?)`	`void`	Begin trace recording
`stopRecording()`	`object \| null`	End recording and return trace

EDMS Events

Method	Returns	Description
`loadEventScript(events)`	`void`	Load EDMS event script
`isEdmsActive()`	`boolean`	Check if EDMS is active

Loss System

Method	Returns	Description
`getDestroyedBasins()`	`object[]`	Destroyed basin records
`getCaptureEvents()`	`object[]`	Zero-sum capture events

`WasmSession`

Requires the fly-by-wire feature. Combines the engine with Substrate policy evaluation in a stateful session.

Constructor

import { WasmSession } from "kairos-wasm";

const session = new WasmSession(
  { columns: 25, rows: 17, lambda: 0.65, gamma: 0.1 },
  { x: 0, y: 0 },
  artifactJson,   // Calibration artifact JSON string
  policyJson,     // Deployment policy JSON string
  null             // HMAC secret (Uint8Array or null)
);

Evaluation & Stepping

Method	Returns	Description
`evaluate(request)`	`object`	Evaluate request without advancing time
`step(direction)`	`object`	Advance primary actor by one tick
`stepActor(actorId, direction)`	`object`	Advance specific actor by one tick
`stepMulti(moves)`	`object`	Advance all actors with explicit moves
`decideAllMoves()`	`object`	Policy-decided moves for all active actors

Telemetry

Method	Returns	Description
`getTelemetry()`	`object`	Warning signal for primary actor
`getTelemetryForActor(actorId)`	`object`	Warning signal for specific actor
`getTelemetryMap()`	`object`	Warning signals for all active actors

Projections

Method	Returns	Description
`previewProjection(actorId, horizon)`	`object`	Projection preview for actor
`previewProjectionForPrimary(horizon)`	`object`	Projection preview for primary actor
`previewTimelineEvents(horizon)`	`object[]`	Upcoming EDMS timeline events

Actor Management

Method	Returns	Description
`registerActor(setup)`	`void`	Register a new actor
`unregisterActor(actorId)`	`void`	Remove a non-primary actor

Scenario Management

Method	Returns	Description
`loadScenario(scenario)`	`void`	Load scenario into session engine
`loadEventScript(events)`	`void`	Load EDMS event script
`currentTick()`	`number`	Current engine tick

Browser Usage Example

import init, { WasmEngine } from "kairos-wasm";

await init();

const engine = new WasmEngine(
  { columns: 25, rows: 17, lambda: 0.65, gamma: 0.1 },
  { x: 0, y: 0 }
);

engine.setSeed(1207);

for (let i = 0; i < 200; i++) {
  const moves = engine.decideAllMoves();
  const result = engine.runTickMulti(moves);
}

const state = engine.getState();
console.log(`Position: t=${state.t}, b=${state.b}`);

Data Exchange

All complex data crosses the WASM boundary via serde-wasm-bindgen — JavaScript objects map directly to Rust structs without JSON serialization overhead. Rust panics are caught by console_error_panic_hook and surfaced as JavaScript errors.