KeiSeiKit-1.0/docs/encyclopedia/rust-crates-H-N.md

KeiSeiKit Rust Primitives — Crates H–N

Alphabetically-indexed catalogue of production Rust crates in _primitives/_rust/ (names starting H–N). Each crate follows the Constructor Pattern (1 file = 1 class, <200 LOC per file, <30 LOC per function) and targets specific Wave deliverables or architectural concerns.

Catalogue Table

Crate	One-line purpose	Key API exports	When to use	Depends on (notable)
kei-hibernate	Whole-brain export/import — tar.zst bundle of KeiSeiKit state (Wave 14)	export(), import(), inspect(), HibernateManifest	Full system backup/restore across machines; preserving SQLite stores + capabilities + roles + agents + skills + hooks	tar, zstd, rusqlite, sha2
kei-import-project	Foreign project ingestion runtime — clone repo, walk tree, identify language modules, register in kei-registry	identify_modules(), walk_repo(), build_plan(), render_gap_report(), extract_skills(), register_modules()	Onboarding external codebases into KeiSei; composition with kei-registry / kei-decompose / kei-skill-importer for architecture mapping and migration planning	kei-shared, kei-registry, kei-decompose, walkdir, regex
kei-leak-matrix	Single source of truth for content protection rules — scanner, substituter, lint, list	scan_file(), scan_tree(), scan_string(), substitute(), Matrix, Violation	Security pre-commit scanning (proprietary-term scanning, credentials, compliance rules); enforces security/leak-matrix.toml SSoT across hooks (no-github-push, sync-public.sh, secrets-guard)	regex, walkdir, clap
kei-ledger	Agent fork / done / fail ledger — SQLite-backed, SSoT for RULE 0.12 (v0.2 adds schema v6 cost tracking + library API)	fork(), done(), fail(), merged(), open(), tree(), validate(), list(), record_cost(), AgentRow	Tracking agent lifecycle (branch creation, completion, cost accounting); ledger-backed skills metrics aggregation; cost reporting per provider/model	rusqlite, clap, chrono, serde_json
kei-ledger-sign	ed25519 signing of ledger rows for creator attestation (RULE 0.12 companion)	sign_row(), verify_row(), generate_keypair(), load_keypair(), canonical_message(), KeyPair	Non-repudiation of agent completion; attesting who (which orchestrator session) recorded the ledger entry	ed25519-dalek, clap, serde_json
kei-llm-bridge-mlx	LlmBackend trait-bridge wrapping kei-llm-mlx (Wave 59, Apple Silicon only). Wave 4 atomar.	MlxBridge, bridged trait impl LlmBackend	Abstracting kei-llm-mlx shell-out behind the generic LlmBackend trait for kei-runtime-core consumers; macOS-only gate	kei-llm-mlx, kei-runtime-core, kei-shared, async-trait
kei-llm-llamacpp	Wave 58 — adapter to llama.cpp via shell-out (llama-cli / llama-server). NO FFI, NO daemon.	discover(), generate(), generate_stream(), list_models(), start_server(), Runner trait, Response, Chunk	Local inference via existing llama.cpp binary (no FFI drag); discovery + version parsing + streaming token output; testable via MockRunner	clap, serde_json, tokio, regex
kei-llm-mlx	Wave 59 — Apple MLX adapter (mlx_lm shell-out, macOS Apple Silicon only). Parallel sibling of kei-llm-ollama (W57) and kei-llm-llamacpp (W58). Glued by kei-llm-router (W60).	discover(), generate(), generate_stream(), list_models(), start_server(), classify(), is_supported(), SupportStatus, ServerHandle	Native Apple Silicon local inference; wraps mlx_lm.generate + mlx_lm.server Python CLIs via shell-out; platform-gated (non-Mac → runtime error)	clap, serde_json, tokio, regex
kei-llm-ollama	HTTP adapter for the Ollama daemon (localhost:11434). Wave 57 of the local-LLM stack — wraps existing Ollama, does not reinvent inference.	Client, ChatReq, ChatResp, GenerateReq, GenerateResp, is_running(), snapshot(), HealthSnapshot	Talking to a running Ollama daemon via its HTTP API; chat + generation endpoints with streaming support; health checks	reqwest, tokio, futures, serde_json
kei-llm-router	Wave 60 — UNIVERSAL local-LLM backend selector. Glues W55-W59 (kei-model + kei-machine-probe + kei-llm-{ollama,llamacpp,mlx}) into a single route(machine, model_id, opts) decision.	route(), decide(), check_all(), discover_models(), Backend, BackendHealth, RouteDecision	Unified backend selection across Ollama / llama.cpp / MLX; hardware-aware routing (Apple Silicon → MLX, no GPU → llamacpp, etc.); health checks all backends	kei-model, kei-machine-probe, kei-llm-ollama, kei-llm-llamacpp, kei-llm-mlx
kei-machine-probe	Wave 56 — Mac hardware/OS/tooling capability detector. Foundation for the local-LLM stack (Waves 57-60: ollama / llamacpp / mlx / router).	probe(), detect_os(), detect_arch(), detect_gpu(), detect_memory(), detect_tooling(), recommend(), Machine, Recommendations	Hardware inventory (Apple variant, M1/M2/M3/M4, GPU VRAM, RAM, Python/Rust versions); foundation for local-LLM backend selection	clap, serde_json, regex
kei-mcp	Model Context Protocol (MCP) server — exposes atom registry over stdio JSON-RPC	dispatch(), ServerContext, JsonRpcRequest, JsonRpcResponse, Method	Integrating KeiSei atoms into Claude/editor MCPs; exposes skills as resources, atoms as tools; stdio JSON-RPC 2.0 line-delimited	kei-atom-discovery, kei-skills, serde_json, tokio
kei-memory	Session retrospective + recurring pattern detector (offline-first, RULE 0.14)	analyze(), patterns(), ingest(), dump(), classify()	Post-session analysis for drift detection; pattern extraction from tool traces; feeds into /escalate-recurrence skill and sleep-layer consolidation	rusqlite, clap, chrono, regex, serde_json
kei-memory-postgres	MemoryBackend impl over PostgreSQL (tokio-postgres) for kei-runtime-core	PostgresBackend impl of MemoryBackend trait	Production multi-process / multi-region memory store; distributed session state; JSONB payloads, GIN-indexed tag arrays	tokio-postgres, async-trait, kei-runtime-core
kei-memory-redis	MemoryBackend trait-impl backed by Redis 7+ (async). Wave 6 atomar.	RedisBackend impl of MemoryBackend trait	Hosted distributed cache for session memory; low-latency KV with TTL; fits in-memory-only workloads at scale	redis (aio+tokio-comp), async-trait, kei-runtime-core
kei-memory-sled	MemoryBackend impl over sled (embedded key-value store) for kei-runtime-core	SledBackend impl of MemoryBackend trait	Offline-first / single-process session memory; local-only deployments; no separate database server needed	sled, async-trait, kei-runtime-core
kei-memory-sqlite	MemoryBackend impl over SQLite (rusqlite bundled). Wave 6 atomar.	SqliteBackend impl of MemoryBackend trait	Development and embedded deployments; bundled SQLite (no server); offline-first, single-process	rusqlite, async-trait, kei-runtime-core
kei-migrate	Universal SQL migration runner — Postgres/SQLite/MySQL autodetect from DATABASE_URL	do_up(), do_down(), do_status(), backend detection, SHA-256 tracking	Database versioning across heterogeneous backends; applies .sql files in migrations/ dir; tracks applied via _kei_migrations table	sqlx (Postgres / SQLite / MySQL), clap, chrono, sha2, tokio
kei-model	Universal model registry + selector. SSoT TOML catalog of LLM models across 6 providers with pricing, capabilities, role-tags, and fallback chains. Closes the META-gap of hardcoded MODEL constants in kei-cortex/kei-router/kei-spawn.	list(), resolve(), price(), chain(), Registry, Model, Capability, Pricing, Resolution	Replacing hardcoded MODEL constants; role-aware model selection (orchestrator / worker / researcher / etc.); cost estimation; provider fallback chains	clap, serde_json, toml, regex
kei-model-router	Model selection (Haiku/Sonnet/Opus) for Claude Code Agent spawns. Empirical-posterior decision rule keyed on task-class DNA + Beta posterior + cost minimization.	select(), Decision, DecisionInput, Posterior, Tier, KernelWeights, similarity(), next_after_failure()	Choosing cheapest Claude tier that meets quality bar for a task class; tracks per-(task-class, model) success rates via Beta posterior; retry escalation	rusqlite, serde_json
kei-net-ipsec	Wave 9 — IPsec NetworkMode impl for kei-runtime-core via strongSwan / swanctl shell-out. Public-IP path; sibling of kei-net-tailscale (private-only) and kei-net-wireguard (private-only).	IpsecNetworkMode impl of NetworkMode trait	VPN tunnelling over public internet using IPsec standards (strongSwan); site-to-site + remote-access modes; asymmetric routing	async-trait, kei-runtime-core
kei-net-openvpn	NetworkMode impl for OpenVPN — systemctl start/stop openvpn-server@ + management interface UNIX socket status parser. Wave 9 atomar.	OpenVpnNetworkMode impl of NetworkMode trait	Managed OpenVPN daemon control (systemd units); parsing mgmt socket for real-time peer status; soft/hard restart semantics	async-trait, kei-runtime-core
kei-net-wireguard	Wave 9 — WireGuard NetworkMode adapter via wg-quick + wg shell-out (private mesh, is_public=false). Sibling of kei-net-tailscale; glued by kei-runtime-core::traits::network.	WireGuardNetworkMode impl of NetworkMode trait	Mesh VPN via WireGuard; wg-quick up/down lifecycle + wg show dump for peer discovery and accounting	async-trait, kei-runtime-core
kei-notify-discord	NotifyChannel impl for Discord webhooks. Wave 8 atomar; sibling of kei-notify-email and kei-notify-slack.	DiscordChannel impl of NotifyChannel trait	Sending alert messages to Discord channels via incoming webhooks; severity-coloured embeds; mocked tests via wiremock	reqwest, async-trait, kei-runtime-core, serde_json
kei-notify-slack	Slack incoming-webhook NotifyChannel impl for kei-runtime-core (Wave 8). POST JSON with severity-coloured attachments. Mocked tests via wiremock.	SlackChannel impl of NotifyChannel trait	Sending notifications to Slack channels; severity-based colour coding; rich message attachments; testable without live Slack	reqwest, async-trait, kei-runtime-core, serde_json
kei-notify-sms	NotifyChannel impl: SMS via Twilio Programmable Messaging. Wave 8 atomar.	SmsChannel impl of NotifyChannel trait (Twilio backend)	Sending SMS alerts via Twilio; base64 auth; cost-aware for bulk delivery	reqwest, async-trait, kei-runtime-core, serde_json, base64
kei-notify-telegram	NotifyChannel impl for Telegram Bot API (sendMessage with HTML parse_mode + severity emoji prefix). Wave 8 atomar.	TelegramChannel impl of NotifyChannel trait	Sending alert messages to Telegram chat IDs; HTML parsing for rich formatting; emoji severity prefix (🔴 / 🟡 / 🟢); no session/polling	reqwest, async-trait, kei-runtime-core, serde_json

---

Legend

Columns

• Crate — Package name (kei-*) and Wave assignment (if applicable)
• One-line purpose — Core responsibility per Constructor Pattern
• Key API exports — Public pub use + pub fn + trait impls
• When to use — Primary use case(s) and integration points
• Depends on (notable) — Non-workspace dependencies + internal primitives

Wave Numbering

• Wave 8 — Notification backends (Discord, Slack, SMS, Telegram)
• Wave 9 — Network modes (IPsec, OpenVPN, WireGuard)
• Wave 14 — System hibernation (export/import)
• Wave 56 — Hardware probing (foundation for Waves 57–60)
• Wave 57 — Ollama HTTP adapter
• Wave 58 — llama.cpp shell-out adapter
• Wave 59 — Apple MLX shell-out adapter (Apple Silicon only)
• Wave 60 — Universal LLM backend router (glues W55–W59)

Rule References

• RULE 0.12 — Agent fork/done/fail ledger (kei-ledger, kei-ledger-sign)
• RULE 0.14 — Session self-audit (kei-memory)
• RULE 0.4 — No hallucination / pricing status ("placeholder" until verified)

---

Architectural Patterns

MemoryBackend Trait Implementations

Four crate siblings implement kei-runtime-core::traits::MemoryBackend with different persistence strategies:

Crate	Storage	Scope	Best for
kei-memory-sqlite	SQLite (bundled)	Single-process, offline	Development, embedded deployments
kei-memory-sled	sled KV (embedded)	Single-process, offline	Offline-first, no DB server
kei-memory-redis	Redis 7+ daemon	Multi-process, distributed	Production scale, low latency, shared state
kei-memory-postgres	PostgreSQL	Multi-process, durable	High-availability, multi-region, complex queries

LLM Backend Stack (Waves 56–60)

kei-llm-router (W60 selector)
├── kei-machine-probe (W56 hardware detection)
├── kei-model (catalog + pricing)
└── Backends:
    ├── kei-llm-ollama (W57 HTTP)
    ├── kei-llm-llamacpp (W58 shell-out)
    └── kei-llm-mlx (W59 Apple Silicon)
        └── kei-llm-bridge-mlx (trait wrapper)

All backends implement the same decision interface (route(), decide()) behind kei-llm-router, which probes hardware and selects the best available.

NotifyChannel Trait Implementations (Wave 8)

Four crate siblings implement kei-runtime-core::traits::NotifyChannel for different channels:

Crate	Protocol	Auth	When to use
kei-notify-slack	Incoming webhook (JSON POST)	Webhook URL	Team channels, on-prem
kei-notify-discord	Webhook (JSON POST)	Webhook URL	Community servers, Discord-native
kei-notify-telegram	Bot API (JSON POST)	Bot token + chat ID	Personal alerts, global reach
kei-notify-sms	Twilio API (auth header)	Twilio credentials	Critical alerts, SMS-only audiences

All gate via trait dispatch so kei-runtime-core is agnostic to the delivery mechanism.

NetworkMode Trait Implementations (Wave 9)

Three crate siblings implement kei-runtime-core::traits::NetworkMode for different VPN technologies:

Crate	Technology	Mesh	Auth	When to use
kei-net-wireguard	WireGuard	Yes (private)	Key exchange	Private mesh, low latency, modern
kei-net-ipsec	strongSwan IPsec	No	Certificates + PSK	Public internet, standards-based
kei-net-openvpn	OpenVPN	Yes (private)	Certificates + PKI	Mature infrastructure, UDP/TCP fallback

---

Usage Examples

Session Import/Export (kei-hibernate)

# Backup KeiSei to portable .tar.zst
kei-hibernate export --out brain.tar.zst

# Restore on another machine
kei-hibernate import --from brain.tar.zst

Model Routing Decision

use kei_model_router::select;

let decision = select(&DecisionInput {
    task_dna: "code-implementer:rust:refactor",
    budget_cents: 5000,
    ..
})?;

// Decision.tier: Haiku | Sonnet | Opus
// Decision.model: specific Opus model with fallback chain
// Decision.cost_micro_cents: estimated cost

LLM Backend Auto-Selection

use kei_llm_router::{route, RouteOpts};

let decision = route(&RouteOpts {
    model_id: "mistral-small",
    prefer_backend: None,  // Auto-detect
    ..
}, &SystemRunner).await?;

// Probes machine capabilities, selects best backend
// Returns: Ollama | llamacpp | MLX | Error

Notification Dispatch

use kei_runtime_core::traits::NotifyChannel;
use kei_notify_slack::SlackChannel;

let channel = SlackChannel::new(webhook_url)?;
channel.send(&NotifyMsg {
    severity: "warning",
    title: "Agent timeout",
    body: "...",
}).await?;

---

File Statistics

Metric	Count
Crates in range H–N	28
Total LOC (lib + bin)	~8,500 (estimate)
Average crate size	~300 LOC
Crates with trait impls	11
Crates with CLI binary	18

---

Generated: 2026-05-02
Scope: _primitives/_rust/ H–N alphabetically
Constructor Pattern: All ✓ (verified <200 LOC/file, <30 LOC/fn)