Skip to content

[ADR-003] Runtime Backend and Substrate Coordinator #318

@ohdearquant

Description

@ohdearquant

Summary

Decouple runtime from concrete DB ownership, introduce backend identity/coordinator routing, clean no_std feature drift, and expose admin/coordinator surfaces needed for multi-backend execution.

Source ADRs

  • F014 ADR-003 (CRIT): khive-runtime has a direct normal dependency on khive-db (from audit-foundation/e2/ADR-003.md)
  • F015 ADR-003 (MAJ): RuntimeConfig has db_path, default_namespace, embedding_model, gate, and packs (from audit-foundation/e2/ADR-003.md)
  • F016 ADR-003 (MAJ): kkernel has only Sync and Pack subcommands (from audit-foundation/e2/ADR-003.md)
  • F017 ADR-003 (MAJ): No SubstrateCoordinator symbol appears in surveyed kkernel, khive-runtime, or pack code (from audit-foundation/e2/ADR-003.md)
  • F018 ADR-003 (MIN): khive-types is #![no_std] in code but its default features include serde and std, and serde is an optional dependency (from audit-foundation/e2/ADR-003.md)
  • F049 ADR-009 (CRIT): khive-runtime depends on concrete khive-db and rusqlite (from audit-foundation/e4/ADR-009.md)
  • F050 ADR-009 (MAJ): RuntimeConfig has one db_path; KhiveRuntime has one backend field; no BackendId or SubstrateCoordinator symbol appears in surveyed runtime/backend code. (from audit-foundation/e4/ADR-009.md)
  • F054 ADR-009 (MAJ): merge_entity operates inside one runtime/backend transaction and has no backend identity check or explicit cross-backend error path. (from audit-foundation/e4/ADR-009.md)
  • F055 ADR-009 (MAJ): Backend tests are inline unit tests under backend.rs (from audit-foundation/e4/ADR-009.md)
  • F155 ADR-027 (MAJ): Pack configuration reads KHIVE_PACKS or defaults to ["kg"] (from audit-platform/e2/ADR-027.md)
  • F157 ADR-028 (CRIT): RuntimeConfig still has one db_path, one embedding_model, and a pack-name list (from audit-platform/e3/ADR-028.md)
  • F160 ADR-029 (MAJ): kkernel exposes only pack_introspect and sync; there is no coordinator module tree under kkernel. (from audit-platform/e3/ADR-029.md)
  • F162 ADR-029 (CRIT): link() validates endpoints and writes a plain edge to self.graph(namespace) on the single runtime backend (from audit-platform/e3/ADR-029.md)
  • F163 ADR-029 (MAJ): search_notes is a single-runtime operation taking namespace: Option<&str> and searching local text/vector indexes (from audit-platform/e3/ADR-029.md)
  • F193 ADR-035 (MAJ): RuntimeConfig only carries db_path, default_namespace, embedding_model, gate, and packs (from audit-rest/r5/ADR-035.md)

Files affected

  • crates/khive-runtime/Cargo.toml (39 sampled LOC)
  • crates/khive-runtime/src/runtime.rs (388 sampled LOC)
  • crates/kkernel/src/main.rs (167 sampled LOC)
  • crates/khive-types/Cargo.toml (21 sampled LOC)
  • crates/khive-runtime/src/curation.rs (1172 sampled LOC)
  • crates/kkernel/src/lib.rs (28 sampled LOC)
  • crates/khive-runtime/src/operations.rs (3728 sampled LOC)
  • crates/khive-db/src/backend.rs (627 sampled LOC)
  • crates/kkernel/src/coordinator/mod.rs (new/planned path)
  • crates/khive-mcp/src/server.rs (404 sampled LOC)
  • crates/khive-runtime/src/fusion.rs (551 sampled LOC)

Acceptance criteria

  • All source findings listed above are addressed exactly once in this cluster.
  • Public types, handlers, schema, and docs touched by the affected files agree on the ADR contract.
  • Regression tests cover happy path and edge cases for the changed public APIs or schema behavior.
  • cargo test -p khive-runtime -p khive-db -p kkernel passes.
  • cargo clippy --workspace -- -D warnings passes.
  • make ci passes.

Dependencies

  • Depends on: #[ADR-002] Edge Ontology, Lifecycle, and Bulk Link Semantics
  • Depends on: #[ADR-004] Note Kind, Storage, and Curation Operations
  • Depends on: #[ADR-005] Storage Capabilities, Sparse Store, and Vector Contract
  • Depends on: #[ADR-004] Event Observable and Provenance Model
  • Depends on: #[ADR-007] Namespace Token and Runtime API Migration
  • Blocks: #[ADR-008] Query Layer Contract
  • Blocks: #[ADR-010] VCS Git-Native Core and Legacy Removal
  • Blocks: #[ADR-004] HandlerDef Pack Contract
  • Blocks: #[ADR-017] Pack Verb Registry, Wire Names, and Introspection
  • Blocks: #[ADR-016] Request Execution Modes and Presentation Envelope
  • Blocks: #[ADR-023] Dynamic Pack Loading, Template, and Pack Binary Inclusion
  • Blocks: #[ADR-004] GTD Pack Schema Plan and Lifecycle Audit
  • Blocks: #[ADR-011] Retrieval, Embed, and Lattice Boundary
  • Blocks: #[ADR-043] Embedding Model Registry and Vector Engine Migration
  • Blocks: #[ADR-034] kkernel Engine and Admin Commands
  • Blocks: #[ADR-035] Import, Export, Remote Resolver, and Sync

LOC estimate

~480 lines added/150 removed; 10 existing affected file(s) sampled at 7125 current LOC via wc -l, plus 1 new/planned path(s).

Risk notes

  • Same-file dependencies must merge first; dependency list includes the exact overlapping paths.
  • 1 affected path(s) are new/planned and were not present in rg --files --hidden; create them in the owning PR rather than in independent parallel work.
  • Contains CRIT findings; do not defer without owner approval.

Auto-generated by ADR alignment triage

Metadata

Metadata

Assignees

No one assigned

    Labels

    adr-alignmentADR v1 series alignment workadvancedAdvanced layer (ADR-031..046)foundationFoundation layer (ADR-001..015)platformPlatform layer (ADR-016..030)

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions