ruvector/docs/adr/ADR-141-coherence-engine-kernel-integration.md

ADR-141: Coherence Engine — Kernel Integration and Runtime Pipeline

Status: Accepted Date: 2026-04-04 Authors: Claude Code (Opus 4.6) Related: ADR-132 (DC-1, DC-2, DC-4, DC-6), ADR-133 (Split/Merge), ADR-136 (Memory Tiers)

---

Context

ADR-132 specifies that the coherence engine is optional (DC-1) and provides two scheduling signals (DC-4): deadline urgency and cut-pressure boost. The engine was implemented in rvm-coherence as a standalone crate with graph, mincut, scoring, and adaptive modules — but no runtime integration existed. The kernel had no mechanism to:

1. Feed real-time communication patterns into the coherence graph
2. Propagate coherence scores to partition objects and the scheduler
3. Act on split/merge recommendations
4. Decay stale edges to prevent graph corruption
5. Enforce security gates on coherence-driven operations

Decision

1. Unified CoherenceEngine with Pluggable Backends

The CoherenceEngine<MCB, CB> is generic over two backend traits:

• MinCutBackend — pluggable mincut algorithm (default: Stoer-Wagner)
• CoherenceBackend — pluggable coherence scoring (default: ratio-based)

When the ruvector feature is enabled, stub backends (RuVectorMinCut, SpectralCoherence) become available. These will delegate to the ruvector ecosystem crates once they gain no_std support.

Type aliases DefaultCoherenceEngine and RuVectorCoherenceEngine provide ergonomic access.

2. IPC → Coherence Graph Auto-Feeding

Every ipc_send() call automatically increments the coherence graph edge weight for the sender→receiver pair (weight += 1). This means the coherence graph always reflects the actual communication topology without manual instrumentation. The IpcManager also tracks cumulative weights per channel.

3. Edge Weight Decay

Edge weights decay by 5% per epoch (decay_bp = 500). Edges that reach zero weight are automatically pruned. This prevents stale communication patterns from dominating the graph and ensures the coherence engine tracks the current topology, not historical patterns.

4. Score Propagation to Partition Objects

On every tick(), the kernel calls sync_partition_scores() which pushes the coherence engine's per-partition CoherenceScore and CutPressure values into the Partition struct fields. Downstream consumers (scheduler priority computation, security gates, tier placement) always see fresh values.

5. Coherence-Driven Split/Merge Execution

The kernel provides:

• execute_split(source) — creates a child partition, registers in graph, emits StructuralSplit witness
• execute_merge(absorber, absorbed) — validates preconditions (coherence threshold, adjacency, resources), emits StructuralMerge witness
• apply_decision(decision) — dispatcher that takes a CoherenceDecision from tick() and executes the appropriate operation

6. Scheduler Integration

enqueue_partition(cpu, id, deadline_urgency) automatically injects the partition's coherence-derived CutPressure into the scheduler's priority computation: priority = deadline_urgency + cut_pressure_boost.

7. Security-Gated Operations

Capability-checked variants of kernel operations:

• checked_create_partition(config, token) — requires Partition type + WRITE rights
• checked_ipc_send(edge, msg, token) — requires Partition type + WRITE rights
• Denials emit ProofRejected witness records via the SecurityGate pipeline

8. Degraded Mode (DC-6)

enter_degraded_mode() / exit_degraded_mode() with witness records. In degraded mode, the scheduler zeroes CutPressure for all enqueue operations, falling back to deadline-only scheduling.

9. Memory Tier Integration

The TierManager is wired into tick():

• Epoch advance + recency decay (200 bp per epoch)
• update_region_cut_value() bridges coherence scores → tier placement
• Residency rule: cut_value + recency_score drives Hot/Warm/Dormant/Cold decisions

Runtime Pipeline

IPC message
    │
    ▼
ipc_send() ──→ coherence graph (edge weight += 1)
    │
    ▼
tick() ──→ decay_weights(5%) ──→ recompute scores ──→ sync_partition_scores()
    │                                                         │
    ▼                                                         ▼
EpochResult {                                      Partition.coherence
  summary: scheduler epoch                         Partition.cut_pressure
  decision: Split/Merge/NoAction                   TierManager.decay_recency()
}
    │
    ▼
apply_decision() ──→ execute_split() / execute_merge()
                         │
                         ▼
                    Witness record (StructuralSplit / StructuralMerge)

Consequences

• The coherence engine is now a live, feedback-driven system rather than a static analysis tool
• Stale edges decay naturally, preventing graph corruption from historical traffic
• Security gates are enforced before privileged operations
• Degraded mode provides a clean fallback when coherence is unavailable
• 645 tests pass across the full workspace with 0 clippy warnings

Test Coverage

Component	Tests	Key Assertions
CoherenceEngine	14	Creation, add/remove, tick, score, pressure, split/merge decisions
Bridge backends	14	Builtin + ruvector stubs, mincut, scoring, fallback identity
Edge decay	4	Reduce, prune at zero, 100% prune, zero is noop
Kernel integration	62	IPC→graph, score propagation, security gates, degraded mode, tier management
P3 deep proof	4	Root pass, derivation chain, nonexistent, revoked ancestor