Kairo

Kairo is being rewritten as a Rust-first actor framework inspired by Apache Pekko/Akka. The active implementation lives in kairo-next. The legacy root crates/ tree was removed after the M13 removal gates were verified. Its historical sources remain available through Git history and are not part of the normal workspace build.

The rewrite is intentionally typed and modular:

• local actors use ActorRef<M> and synchronous Actor::receive turns;
• local-only messages do not require serialization;
• remote messages use stable manifests, versions, serializer ids, and registered codecs;
• cluster membership is gossip plus local failure-detector observations, not etcd or another central store;
• sharding routes business messages through EntityRef<M> and ShardingEnvelope<M> so entity ids do not need to be embedded in every business message.

See docs/goal.md for the product roadmap, kairo-next/ARCHITECTURE.md for the technical contract, and docs/progress.md for current implementation status. Migration guidance from the historical implementation to the new facade lives in docs/migration.md.

Current Workspace

The normal workspace is under kairo-next/crates/* and includes:

• kairo: facade crate for common users and feature-gated subsystem entry points.
• kairo-actor: typed local actor runtime, lifecycle, supervision, timers, adapters, ask, event stream, receptionist, and coordinated shutdown.
• kairo-actor-macros: derive and attribute macros for stable remote-message manifests and ergonomic protocol declarations.
• kairo-serialization: stable remote message metadata and codec registry.
• kairo-remote: remote actor refs, associations, TCP framing, and remote death watch.
• kairo-cluster: gossip membership, vector clocks, reachability, failure detection, convergence, leader actions, and downing hooks.
• kairo-distributed-data: CRDT replication, delta/full-state propagation, pruning, and TCP peer bootstrap.
• kairo-cluster-sharding: entity refs, shard regions, coordinators, allocation, handoff, passivation, remember-entity storage, and routed remote region envelopes.
• kairo-cluster-tools: singleton and distributed pubsub tools.
• kairo-testkit: deterministic probes and manual-time test support.
• kairo-examples: runnable vertical slices for local actors, configuration, remoting, cluster membership, distributed data, sharding, and cluster tools.
• kairo-benchmarks: dependency-light M13 benchmark runner for actor tell, typed remote send, gossip merge, EntityRef sharding route throughput, and shard passivation buffering.

Facade Features

The kairo facade is the recommended user entry point. Its default feature set enables local actors, macros, and TOML configuration loading. Distributed runtime layers are opt-in and preserve the architecture dependency order:

Feature	Enables
default	actor, macros, config
serialization	stable remote-message metadata and codec registry
remote	actor, serialization, remote refs and associations
cluster	remote, gossip membership and downing hooks
distributed-data	cluster, CRDT replication
cluster-sharding	cluster, distributed-data, cluster-tools, entity routing
cluster-tools	cluster, distributed-data, singleton and pubsub
testkit	local actor test utilities without distributed runtime layers
full	every public facade feature for integration checks

Running Examples

From the repository root:

cargo run -p kairo-examples --example local_counter
cargo run -p kairo-examples --example configured_counter
cargo run -p kairo-examples --example ask_pipe_to_self
cargo run -p kairo-examples --example remote_ping_pong
cargo run -p kairo-examples --example ddata_counter
cargo run -p kairo-examples --example cluster_membership
cargo run -p kairo-examples --example cluster_tools_local
cargo run -p kairo-examples --example cluster_tools_singleton
cargo run -p kairo-examples --example cluster_tools_distributed
cargo run -p kairo-examples --example cluster_sharding_local
cargo run -p kairo-examples --example cluster_sharding_tcp
cargo run -p kairo-examples --example cluster_tcp_peer_bootstrap
cargo run -p kairo-examples --example ddata_tcp_peer_bootstrap
cargo run -p kairo-examples --example cluster_tools_tcp_peer_bootstrap

The ask_pipe_to_self example demonstrates local request/reply through Context::ask and external work returning to the actor through Context::pipe_to_self.

The configured_counter example demonstrates TOML-first facade settings discovered from the standard examples/kairo.toml plus examples/kairo.local.toml pair, including actor dispatcher settings, dead-letter diagnostics, remote transport settings, sharding timing helpers, and least-shard allocation limits, while keeping runtime configuration in format-neutral structs.

The remote_ping_pong example demonstrates two local TCP remoting actor systems exchanging typed messages through stable remote manifests and an explicit codec registered through the format-neutral Registry::register_with helper.

The ddata_counter example demonstrates a local distributed-data ReplicatorActor<GCounter> update, change notification, and readback.

The cluster_membership example demonstrates cluster-event subscription, initial snapshot delivery, member-up publication, member removal, and current-state request through the public cluster facade.

The cluster_tools_local example demonstrates local cluster-tools workflows: pubsub subscribe/publish/topic listing and singleton manager startup with typed access to the running singleton child.

The cluster_tools_singleton example demonstrates a two-manager singleton handover workflow: the new oldest requests handover, the previous oldest stops its singleton child, and the new oldest starts its replacement only after the previous child has stopped.

The cluster_tools_distributed example demonstrates two distributed pubsub mediators exchanging registry deltas, remote topic publish delivery, and one-message-per-group routing across local and remote groups.

The cluster_tools_tcp_peer_bootstrap example demonstrates loopback TCP routes for cluster-tools system traffic, including distributed pubsub publish and registered-path Send/SendToAll delivery through stable remote envelopes. The cluster, distributed-data, and cluster-tools TCP bootstrap binaries also print their coordinated-shutdown observation, including the before/after route counts that prove bootstrap-owned association routes are cleared before shutdown reports success.

The cluster_sharding_local example demonstrates:

EntityRef<String> -> ShardingEnvelope<String> -> ShardRegionActor
  -> EntityShardActor -> typed entity child

It also exercises entity passivation and restart through the same EntityRef<String>, then runs a two-region graceful local shard movement that rehosts a remembered entity on the surviving region.

The cluster_sharding_tcp example runs the distributed acceptance workflow on three ActorSystems sharing the composed TCP, cluster, distributed-data, singleton, and sharding lifecycle. It forms through seed contact, replicates remembered entities, periodically rebalances an existing shard, gracefully removes the oldest node, and proves its remembered entity starts on a survivor before the next business message is sent.

Configuration

Kairo starts with TOML file loading while keeping runtime settings format-neutral. Applications can discover the standard kairo.toml plus kairo.local.toml pair, load one explicit file, layer explicit base and local overrides, or parse inline configuration text before converting the result into runtime builders:

use kairo::prelude::{
    load_standard_toml_files, load_toml_file, load_toml_files, parse_toml_str,
};

let standard_settings = load_standard_toml_files(".")?;
let file_settings = load_toml_file("kairo.local.toml")?;
let layered_settings = load_toml_files(["kairo.toml", "kairo.local.toml"])?;
let inline_settings = parse_toml_str("[actor.dispatchers.default]\nthroughput = 8")?;

let system = layered_settings.actor_system_builder("app")?.build()?;

KairoSettings stores actor, remote, cluster, sharding, cluster-tools, and diagnostics settings without exposing TOML-specific concepts, so future configuration loaders can project into the same runtime model. For dependency-free observability bridges, the facade also exposes DiagnosticCounters for metrics-style category counts and DiagnosticTextSink for stable single-line diagnostic records that applications can forward into their own logging or tracing stack.

Validation

The GitHub Actions validation matrix mirrors the normal next-workspace development surface and pins Rust 1.88 as the minimum supported Rust version (MSRV):

Format: cargo fmt --all -- --check
Clippy: cargo clippy --workspace --all-targets --all-features -- -D warnings
Test: cargo test --workspace --all-targets --all-features
Platform Test: full workspace tests on Ubuntu, Windows, and macOS
MSRV 1.88: cargo check --workspace --all-targets --all-features
Facade Features:
  cargo check -p kairo --all-targets --no-default-features
  cargo check -p kairo --all-targets
  for feature in actor macros config serialization remote cluster distributed-data cluster-tools cluster-sharding testkit full; do
    cargo check -p kairo --all-targets --no-default-features --features "$feature"
  done
Examples and Multi-Node:
  cargo test -p kairo-examples --all-targets --all-features
  cargo test --doc --workspace --all-features
  cargo test -p kairo-examples --doc --all-features
  cargo test -p kairo-testkit multi_node --all-targets --all-features
Rustdoc: RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps
Package: cargo package --workspace --all-features --exclude kairo-examples --exclude kairo-benchmarks --no-verify
Benchmark Smoke: KAIRO_BENCH_ITERS=100 cargo run -p kairo-benchmarks --release -- all

Run the same default full validation target locally from the repository root:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features

Focused development usually runs the relevant crate target first, for example:

cargo test -p kairo-cluster-sharding --all-targets --all-features
cargo clippy -p kairo-cluster-sharding --all-targets --all-features -- -D warnings

Examples and local multi-node harness coverage can be validated directly:

cargo test -p kairo-examples --all-targets --all-features
cargo test --doc --workspace --all-features
cargo test -p kairo-examples --doc --all-features
cargo test -p kairo-testkit multi_node --all-targets --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps
cargo package --workspace --all-features --exclude kairo-examples --exclude kairo-benchmarks --no-verify
KAIRO_BENCH_ITERS=100 cargo run -p kairo-benchmarks --release -- all

Benchmarks

The kairo-benchmarks crate provides a dependency-light baseline for the M13 performance surface: actor tell throughput, typed remote-ref serialization and outbound send overhead, gossip merge cost, and EntityRef sharding route throughput, plus shard passivation-buffer throughput across many entities.

cargo run -p kairo-benchmarks -- --help
cargo run -p kairo-benchmarks --release -- all
KAIRO_BENCH_ITERS=10000 cargo run -p kairo-benchmarks --release -- actor-tell
KAIRO_BENCH_ITERS=10000 cargo run -p kairo-benchmarks --release -- remote-send
KAIRO_BENCH_ITERS=10000 cargo run -p kairo-benchmarks --release -- gossip-merge
KAIRO_BENCH_ITERS=10000 cargo run -p kairo-benchmarks --release -- sharding-route
KAIRO_BENCH_ITERS=10000 cargo run -p kairo-benchmarks --release -- shard-passivation

The current M13 dependency and license audit is tracked in docs/dependency-audit.md.