# kkernel Design

**Last reviewed**: 2026-06-06

## ADR Compliance

### ADR-003: System Architecture (kernel/MCP split)

- `kkernel` is the admin/management binary; `khive-mcp` is the MCP stdio server.
- They share the `khive-runtime` crate but have separate entry points.
- Pack crates do not depend on `kkernel` or its coordinator module — they receive
  a single-backend `KhiveRuntime` from the MCP layer.
- The anti-pattern of packs depending on the coordinator is explicitly guarded by the
  module boundary: `coordinator` is `kkernel`-internal.

### ADR-009 / ADR-028: Multi-backend configuration

- `BackendRegistry` holds registered backends. Constructed at boot from `khive.toml`.
- `kkernel backend list` and `kkernel backend info` expose the registry to operators.
- Current v1 implementation exposes a single default backend. Full `khive.toml`-driven
  multi-backend enumeration is deferred to a follow-up milestone.

### ADR-010 / ADR-020: VCS and sync

- `kkernel sync` delegates to `khive_vcs::sync::run_sync` — the NDJSON-to-SQLite
  rebuild logic is owned by `khive-vcs`, not by `kkernel`.
- `kkernel kg fetch` (alias: `kkernel kg sync`) fetches a remote KG archive and
  populates the local remote cache under `.khive/kg/remotes/<remote>/`.

### ADR-015: Schema migrations

- `KhiveRuntime::new()` runs `run_migrations()` internally — constructing the runtime
  is sufficient to apply all pending migrations.
- `kkernel db migrate` wraps this; `kkernel db check` uses a read-only runtime to
  report schema state without writing.

### ADR-017: Pack standard (vocabulary + handlers)

- `pack_introspect` module builds an in-memory `VerbRegistry` from all `inventory!`-
  registered packs and exposes `list_packs()` and `pack_handler(name)`.
- Handler `visibility` distinguishes MCP-exposed `Verb` entries from internal
  `Subhandler` entries (e.g. `memory.recall_embed`).

### ADR-023: Verb namespace contract

- The kg substrate pack owns 16 bare verb names (no dot prefix): `create`, `get`,
  `list`, `stats`, `update`, `delete`, `search`, `link`, `neighbors`, `traverse`,
  `query`, `merge`, `propose`, `review`, `withdraw`, `verbs`.
- Every other pack must prefix verbs with `<pack>.` (e.g. `memory.recall`).
- Sub-variants use underscore, not nested dots: `memory.recall_embed`, not
  `memory.recall.embed`.
- Enforced by the integration test in `tests/verb_namespace_contract.rs`.

### ADR-027: Dynamic pack loading (self-registration via inventory!)

- Pack crates self-register using `inventory::submit!`. The linker drops crates whose
  symbols aren't referenced, so `kkernel/lib.rs` and the contract test binary both
  include explicit `use PackName as _` anchors to prevent dead-stripping.
- `PackRegistry::discovered_names()` returns all self-registered pack names at runtime.

### ADR-029: SubstrateCoordinator

- `coordinator/mod.rs` implements D1 (BackendRegistry), D2 (LocatorCache), and D3
  (fan-out search with RRF).
- D4 (cross-backend traversal), D5 (WAL cascade delete), and D6 (health map) are
  deferred; sub-modules (`edges`, `traversal`, `curation`, `health`) are reserved.
- See `docs/coordinator.md` for implementation phase detail.

### ADR-034 / ADR-035: KG validation and init

- `kkernel kg validate` runs three built-in structural checks (duplicate UUIDs, sort
  order, referential integrity) plus configurable rules from `rules.toml`.
- `kkernel kg init` creates `.khive/kg/` and writes `khive.toml` with defaults.
- See `docs/kg-rules.md` for the rule TOML format.

### ADR-036 / ADR-037: KG status and fetch/sync alias

- `kkernel kg status` computes a content hash of the DB state and the NDJSON files and
  reports whether they match.
- `kkernel kg fetch` has a `visible_alias = "sync"` so `kkernel kg sync --repin <remote>`
  reaches the same handler.

### ADR-043: Embedding model lifecycle

- `kkernel engine list/status` expose `_embedding_models` table data.
- `kkernel engine migrate` and `kkernel engine drift-check` are deferred to follow-up
  #380 (EmbedMigrationWorker and lattice_transport integration).
- No MCP verbs are exposed for engine management — these are operator-only commands.

### ADR-044: Vector store capabilities and orphan sweep

- `kkernel vector capabilities` emits the sqlite-vec baseline capability flags.
  Values match `SqliteVecStore::capabilities()` in `khive-db`.
- `kkernel vector sweep` is deferred to follow-up #381; `SqliteVecStore` returns
  `Unsupported` for the orphan-sweep operation.

### ADR-046: Proposal lifecycle

- The kg pack exposes `propose`, `review`, and `withdraw` verbs as part of the
  16 kg-substrate bare verbs. These are validated by the contract test.

## Consistency Notes

- `kkernel db migrate --dry-run` delegates to `cmd_db_check` rather than implementing
  a separate dry-run path. The `--check` flag makes the check exit nonzero if behind.
- The `cmd_vector_capabilities` function hard-codes baseline sqlite-vec values
  rather than instantiating a runtime — this is intentional for the v1 implementation
  but means the output does not reflect operator-configured backends.
- `coordinator/mod.rs` cannot be split into sub-files because `SubstrateCoordinator`
  has a `#[cfg(test)]` field (`fail_backend_id`) that tests access directly; making it
  `pub(crate)` would expose the failure-injection mechanism to integration tests.
- Edge weights are validated in the [0.0, 1.0] closed interval with finite-number
  checks. NaN and infinity are explicitly rejected with descriptive error messages.
