Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector
git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900

docs/adr/coherence-engine/ADR-CE-001-sheaf-laplacian-coherence.md

@@ -0,0 +1,37 @@
+# ADR-CE-001: Sheaf Laplacian Defines Coherence Witness
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+Traditional AI systems use probabilistic confidence scores to gate decisions. These scores:
+- Can be confidently wrong (hallucination)
+- Don't provide structural guarantees
+- Are not provable or auditable
+
+## Decision
+
+**Sheaf Laplacian defines coherence witness, not probabilistic confidence.**
+
+The coherence energy E(S) = Σ w_e|r_e|² provides a mathematical measure of structural consistency where:
+- r_e = ρ_u(x_u) - ρ_v(x_v) is the edge residual
+- w_e is the edge weight
+- Zero energy means perfect global consistency
+
+## Consequences
+
+### Benefits
+- Mathematical proof of consistency, not statistical guess
+- Every decision has computable witness
+- Residuals pinpoint exact inconsistency locations
+
+### Risks
+- Restriction map design requires domain expertise
+- Initial setup more complex than confidence thresholds
+
+## References
+
+- Hansen & Ghrist (2019), "Toward a spectral theory of cellular sheaves"
+- ADR-014: Coherence Engine Architecture

docs/adr/coherence-engine/ADR-CE-002-incremental-computation.md

@@ -0,0 +1,38 @@
+# ADR-CE-002: Incremental Coherence Computation
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+Recomputing global coherence energy for every update is O(|E|) where |E| is edge count. For large graphs with frequent updates, this is prohibitive.
+
+## Decision
+
+**Incremental computation with stored residuals, subgraph summaries, and global fingerprints.**
+
+Components:
+1. **Stored residuals**: Cache per-edge residuals, update only affected edges
+2. **Subgraph summaries**: Pre-aggregate energy by scope/namespace
+3. **Global fingerprints**: Hash-based staleness detection
+
+When node v changes:
+1. Find edges incident to v: O(degree(v))
+2. Recompute only those residuals: O(degree(v) × d)
+3. Update affected subgraph summaries: O(log n)
+
+## Consequences
+
+### Benefits
+- Single node update: O(degree × d) instead of O(|E| × d)
+- Fingerprints enable efficient cache invalidation
+- Subgraph summaries support scoped queries
+
+### Risks
+- Memory overhead for cached residuals
+- Consistency between cache and graph requires careful management
+
+## References
+
+- ADR-014: Coherence Engine Architecture, Section 2

docs/adr/coherence-engine/ADR-CE-003-hybrid-storage.md

@@ -0,0 +1,37 @@
+# ADR-CE-003: PostgreSQL + Ruvector Unified Substrate
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+The coherence engine requires:
+- Transactional authority for governance data (policies, witnesses, lineage)
+- High-performance vector/graph operations for coherence computation
+- Audit trail with deterministic replay
+
+## Decision
+
+**PostgreSQL + ruvector as unified substrate.**
+
+| Layer | Storage | Purpose |
+|-------|---------|---------|
+| Governance | PostgreSQL | Policy bundles, witnesses, lineage (ACID) |
+| Coherence | ruvector | Node states, edges, HNSW index, residuals |
+| Audit | PostgreSQL | Event log with signatures |
+
+## Consequences
+
+### Benefits
+- PostgreSQL: Battle-tested ACID for governance
+- ruvector: Optimized for vector similarity and graph traversal
+- Clear separation of concerns
+
+### Risks
+- Two systems to maintain
+- Cross-system consistency requires careful transaction handling
+
+## References
+
+- ADR-014: Coherence Engine Architecture, Section 13

docs/adr/coherence-engine/ADR-CE-004-signed-event-log.md

@@ -0,0 +1,42 @@
+# ADR-CE-004: Signed Event Log with Deterministic Replay
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+For audit, debugging, and compliance, the system must support:
+- Complete reconstruction of any past state
+- Verification that events were not tampered with
+- Replay for testing and analysis
+
+## Decision
+
+**Signed event log with deterministic replay.**
+
+Every event is:
+1. Assigned a monotonic sequence ID
+2. Serialized with timestamp and payload
+3. Signed with Blake3 hash including previous event's signature (chain)
+4. Stored append-only in PostgreSQL
+
+Replay:
+- Start from genesis or checkpoint
+- Apply events in sequence order
+- Deterministic: same events → same state
+
+## Consequences
+
+### Benefits
+- Tamper-evident: any modification breaks the hash chain
+- Complete auditability: reconstruct any historical state
+- Debugging: replay and inspect at any point
+
+### Risks
+- Storage grows indefinitely (mitigated by checkpoints)
+- Replay time scales with history length
+
+## References
+
+- ADR-014: Coherence Engine Architecture, Section 13

docs/adr/coherence-engine/ADR-CE-005-governance-objects.md

@@ -0,0 +1,49 @@
+# ADR-CE-005: First-Class Governance Objects
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+Governance decisions (thresholds, policies, approvals) must be:
+- Versioned and traceable
+- Signed by authorized parties
+- Immutable once approved
+- Addressable for reference in witnesses
+
+## Decision
+
+**Governance objects are first-class, immutable, addressable.**
+
+Three governance object types:
+
+1. **PolicyBundle**: Versioned threshold configurations
+   - Signed by required approvers
+   - Content-addressed (ID = hash of contents)
+   - Immutable once created
+
+2. **WitnessRecord**: Proof of gate decisions
+   - Links to PolicyBundle used
+   - Chains to previous witness (hash chain)
+   - Content-addressed
+
+3. **LineageRecord**: Provenance of writes
+   - Links to authorizing witness
+   - Tracks causal dependencies
+   - Enables "why did this change?" queries
+
+## Consequences
+
+### Benefits
+- Complete audit trail for compliance
+- Multi-party approval for sensitive changes
+- Content addressing prevents substitution attacks
+
+### Risks
+- Cannot modify bad policies (must create new version)
+- Storage overhead for immutable objects
+
+## References
+
+- ADR-014: Coherence Engine Architecture, Section 4

docs/adr/coherence-engine/ADR-CE-006-compute-ladder.md

@@ -0,0 +1,37 @@
+# ADR-CE-006: Coherence Gate Controls Compute Ladder
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+Not all coherence violations require the same response. A minor transient spike differs from sustained structural breakdown. The system needs graduated responses.
+
+## Decision
+
+**Coherence gate controls explicit compute ladder: Reflex → Retrieval → Heavy → Human.**
+
+| Lane | Latency | Trigger | Action |
+|------|---------|---------|--------|
+| 0: Reflex | <1ms | E < θ_reflex | Proceed, local update |
+| 1: Retrieval | ~10ms | θ_reflex ≤ E < θ_retrieval | Fetch evidence, lightweight reasoning |
+| 2: Heavy | ~100ms | θ_retrieval ≤ E < θ_heavy | Multi-step planning, spectral analysis |
+| 3: Human | Async | E ≥ θ_heavy or persistent | Escalate to human, block action |
+
+## Consequences
+
+### Benefits
+- Most operations stay fast (Lane 0)
+- Graduated response matches severity
+- Human escalation for truly difficult cases
+- Every escalation has witness
+
+### Risks
+- Threshold tuning requires domain knowledge
+- Over-sensitive thresholds cause unnecessary escalation
+
+## References
+
+- ADR-014: Coherence Engine Architecture, Section 3
+- ADR-CE-014: Reflex Lane Default

docs/adr/coherence-engine/ADR-CE-007-threshold-autotuning.md

@@ -0,0 +1,46 @@
+# ADR-CE-007: Thresholds Auto-Tuned from Production Traces
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+Fixed thresholds become stale as:
+- System behavior evolves
+- New edge types are added
+- Domain characteristics change
+
+Manual tuning is expensive and error-prone.
+
+## Decision
+
+**Thresholds auto-tuned from production traces with governance approval.**
+
+Process:
+1. **Collect traces**: Energy values, gate decisions, outcomes
+2. **Analyze**: SONA identifies optimal threshold candidates
+3. **Propose**: System generates new PolicyBundle with updated thresholds
+4. **Approve**: Required approvers sign the bundle
+5. **Deploy**: New thresholds become active
+
+Constraints:
+- Auto-tuning proposes, humans approve
+- Changes tracked in audit log
+- Rollback supported via new PolicyBundle
+
+## Consequences
+
+### Benefits
+- Thresholds adapt to changing conditions
+- Governance maintained (human approval required)
+- Historical analysis enables data-driven decisions
+
+### Risks
+- Bad traces lead to bad proposals
+- Approval bottleneck if too many proposals
+
+## References
+
+- ADR-014: Coherence Engine Architecture, Section 6
+- ADR-CE-015: Adapt Without Losing Control

docs/adr/coherence-engine/ADR-CE-008-multi-tenant-isolation.md

@@ -0,0 +1,38 @@
+# ADR-CE-008: Multi-Tenant Isolation
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+Enterprise deployments require multiple tenants sharing infrastructure while maintaining:
+- Data isolation (tenant A cannot see tenant B's data)
+- Policy isolation (different thresholds per tenant)
+- Execution isolation (one tenant's load doesn't affect another)
+
+## Decision
+
+**Multi-tenant isolation at data, policy, and execution boundaries.**
+
+| Boundary | Mechanism |
+|----------|-----------|
+| Data | Tenant ID on all rows, row-level security |
+| Policy | PolicyBundle scoped to tenant |
+| Execution | Tile assignment, rate limiting |
+| Graph | Subgraph partitioning by tenant |
+
+## Consequences
+
+### Benefits
+- Single deployment serves multiple tenants
+- Clear isolation boundaries
+- Per-tenant customization
+
+### Risks
+- Noisy neighbor problems (mitigated by rate limiting)
+- Complexity in cross-tenant operations (by design: not allowed)
+
+## References
+
+- ADR-014: Coherence Engine Architecture

docs/adr/coherence-engine/ADR-CE-009-single-coherence-object.md

@@ -0,0 +1,44 @@
+# ADR-CE-009: Single Coherence Object
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+Building domain-specific coherence systems (one for AI, one for finance, one for medical) leads to:
+- Duplicated effort
+- Inconsistent semantics
+- Maintenance burden
+
+## Decision
+
+**Single coherence object - once math is fixed, everything is interpretation.**
+
+The Universal Coherence Object:
+- Nodes: d-dimensional state vectors
+- Edges: Restriction maps ρ_u, ρ_v
+- Energy: E(S) = Σ w_e|r_e|²
+- Gate: E < θ → allow
+
+Domain-specific interpretation:
+| Domain | Nodes | Edges | Residual | Gate |
+|--------|-------|-------|----------|------|
+| AI | Beliefs | Citations | Contradiction | Refusal |
+| Finance | Trades | Arbitrage | Regime mismatch | Throttle |
+| Medical | Vitals | Physiology | Clinical disagreement | Escalation |
+
+## Consequences
+
+### Benefits
+- One implementation, many applications
+- Proven math applies everywhere
+- Domain experts focus on interpretation, not implementation
+
+### Risks
+- Abstraction may not fit all domains perfectly
+- Requires mapping domain concepts to universal structure
+
+## References
+
+- ADR-014: Coherence Engine Architecture, "Universal Coherence Object"

docs/adr/coherence-engine/ADR-CE-010-domain-agnostic-substrate.md

@@ -0,0 +1,56 @@
+# ADR-CE-010: Domain-Agnostic Nodes and Edges
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+To support multiple domains with a single substrate, the node and edge types must be generic enough to represent:
+- AI agent beliefs and citations
+- Financial trades and market dependencies
+- Medical vitals and physiological relationships
+- Security identities and policy rules
+
+## Decision
+
+**Domain-agnostic nodes/edges - facts, trades, vitals, hypotheses all use same substrate.**
+
+Node structure:
+```rust
+pub struct SheafNode {
+    pub id: NodeId,
+    pub state: Vec<f32>,      // Fixed-dimension embedding
+    pub metadata: Metadata,   // Domain-specific tags
+    pub updated_at: Timestamp,
+}
+```
+
+Edge structure:
+```rust
+pub struct SheafEdge {
+    pub source: NodeId,
+    pub target: NodeId,
+    pub weight: f32,
+    pub rho_source: RestrictionMap,
+    pub rho_target: RestrictionMap,
+}
+```
+
+Domain mapping happens in metadata and restriction map design.
+
+## Consequences
+
+### Benefits
+- Single codebase for all domains
+- Type safety through metadata validation
+- Restriction maps encode domain semantics
+
+### Risks
+- Embedding dimension must be chosen carefully
+- Metadata schema needs governance
+
+## References
+
+- ADR-014: Coherence Engine Architecture, Section 1
+- ADR-CE-009: Single Coherence Object

docs/adr/coherence-engine/ADR-CE-011-residual-contradiction-energy.md

@@ -0,0 +1,38 @@
+# ADR-CE-011: Residual = Contradiction Energy
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+The edge residual r_e = ρ_u(x_u) - ρ_v(x_v) measures local mismatch. This mathematical quantity needs a universal interpretation across domains.
+
+## Decision
+
+**Residual = contradiction energy - universal interpretation across domains.**
+
+The residual represents:
+- **AI Agents**: Logical contradiction between belief and evidence
+- **Finance**: Regime mismatch between positions
+- **Medical**: Clinical disagreement between vitals and diagnosis
+- **Robotics**: Physical impossibility between sensor and plan
+- **Security**: Authorization violation between permission and action
+
+The weighted residual norm |r_e|² is always "how much these two things disagree."
+
+## Consequences
+
+### Benefits
+- Universal semantics: "disagreement" makes sense everywhere
+- Quantitative: larger residual = bigger problem
+- Localizable: can identify which edges contribute most
+
+### Risks
+- Restriction map design determines what "disagreement" means
+- Poor maps give meaningless residuals
+
+## References
+
+- ADR-014: Coherence Engine Architecture
+- ADR-CE-009: Single Coherence Object

docs/adr/coherence-engine/ADR-CE-012-gate-refusal-witness.md

@@ -0,0 +1,48 @@
+# ADR-CE-012: Gate = Refusal Mechanism with Witness
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+When coherence energy exceeds threshold, the system must refuse action. This refusal needs to be:
+- Deterministic (same inputs → same decision)
+- Auditable (why was it refused?)
+- Provable (cryptographic witness)
+
+## Decision
+
+**Gate = refusal mechanism with witness - every refusal is provable.**
+
+Gate evaluation produces:
+```rust
+pub struct GateDecision {
+    pub allow: bool,
+    pub lane: ComputeLane,
+    pub witness: WitnessRecord,
+    pub denial_reason: Option<String>,
+}
+```
+
+The WitnessRecord includes:
+- Energy snapshot at decision time
+- Policy bundle that defined thresholds
+- Hash chain to previous witness
+- Content hash for integrity
+
+## Consequences
+
+### Benefits
+- Every refusal has cryptographic proof
+- Can reconstruct exactly why any decision was made
+- Compliance-ready audit trail
+
+### Risks
+- Witness storage overhead
+- Must handle witness retrieval at scale
+
+## References
+
+- ADR-014: Coherence Engine Architecture, Section 3
+- ADR-CE-005: First-Class Governance Objects

docs/adr/coherence-engine/ADR-CE-013-not-prediction.md

@@ -0,0 +1,46 @@
+# ADR-CE-013: Not Prediction
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+Most AI systems try to predict what will happen. This is fundamentally limited:
+- Future is uncertain
+- Predictions can be confidently wrong
+- No structural guarantees
+
+## Decision
+
+**Not prediction - system shows safe/unsafe action, not what will happen.**
+
+The coherence engine answers a different question:
+
+| Prediction Systems | Coherence Systems |
+|--------------------|-------------------|
+| "What will happen?" | "Does the world still fit together?" |
+| Probabilistic confidence | Mathematical consistency |
+| Can be confidently wrong | Knows when it doesn't know |
+| Trust the model | Trust the math |
+
+The coherence field shows:
+- Where action is safe (low energy)
+- Where action must stop (high energy)
+
+It does NOT predict outcomes.
+
+## Consequences
+
+### Benefits
+- Honest uncertainty: "I don't know" is a valid answer
+- No false confidence in predictions
+- Structural guarantees, not statistical ones
+
+### Risks
+- Users may expect predictions
+- Requires education on coherence vs. confidence
+
+## References
+
+- ADR-014: Coherence Engine Architecture, "The Coherence Vision"

docs/adr/coherence-engine/ADR-CE-014-reflex-lane-default.md

@@ -0,0 +1,46 @@
+# ADR-CE-014: Reflex Lane Default
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+A coherence system that escalates too often becomes:
+- Slow (every operation waits for heavy compute)
+- Noisy (constant human escalations)
+- Ignored (users bypass the system)
+
+## Decision
+
+**Reflex lane default - most updates stay low-latency, escalation only on sustained incoherence.**
+
+Design principles:
+1. **Default to Lane 0**: Most operations complete in <1ms
+2. **Transient spikes tolerated**: Brief energy increases don't escalate
+3. **Persistence triggers escalation**: Only sustained/growing incoherence moves up lanes
+4. **Human lane is last resort**: Lane 3 only when automated systems cannot resolve
+
+Persistence detection:
+```rust
+fn is_escalation_needed(history: &EnergyHistory, window: Duration) -> bool {
+    history.is_above_threshold(threshold, window) ||
+    history.is_trending_up(window)
+}
+```
+
+## Consequences
+
+### Benefits
+- System stays responsive under normal operation
+- Escalation is meaningful (not noise)
+- Users trust the system (it's not crying wolf)
+
+### Risks
+- Might miss real problems that appear transient
+- Persistence window requires tuning
+
+## References
+
+- ADR-014: Coherence Engine Architecture, Section 3
+- ADR-CE-006: Compute Ladder

docs/adr/coherence-engine/ADR-CE-015-adapt-without-losing-control.md

@@ -0,0 +1,44 @@
+# ADR-CE-015: Adapt Without Losing Control
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+Static systems become stale. Adaptive systems can drift or be gamed. The coherence engine needs to:
+- Learn from experience
+- Improve over time
+- Maintain governance and control
+
+## Decision
+
+**Adapt without losing control - persistent tracking enables learning within governance.**
+
+Adaptation mechanisms:
+1. **Threshold autotuning**: SONA proposes, humans approve
+2. **Learned restriction maps**: GNN training with EWC++ (no forgetting)
+3. **ReasoningBank patterns**: Store successful approaches
+4. **Deterministic replay**: Verify adaptations against history
+
+Control mechanisms:
+1. **Policy bundles require signatures**: No unauthorized changes
+2. **Witness chain is immutable**: Cannot hide past decisions
+3. **Lineage tracking**: Every adaptation has provenance
+4. **Rollback support**: Can revert to previous policy
+
+## Consequences
+
+### Benefits
+- System improves with experience
+- Governance maintained throughout
+- Can audit all adaptations
+
+### Risks
+- Adaptation speed limited by approval process
+- Learning quality depends on trace quality
+
+## References
+
+- ADR-014: Coherence Engine Architecture
+- ADR-CE-007: Threshold Autotuning

docs/adr/coherence-engine/ADR-CE-016-ruvllm-coherence-validator.md

@@ -0,0 +1,52 @@
+# ADR-CE-016: RuvLLM CoherenceValidator Uses Sheaf Energy
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+RuvLLM's `CoherenceValidator` currently uses heuristic scoring to detect:
+- Semantic inconsistency
+- Factual contradictions
+- Logical errors
+
+These heuristics are:
+- Pattern-based (can be fooled)
+- Not mathematically grounded
+- Difficult to explain
+
+## Decision
+
+**RuvLLM CoherenceValidator uses sheaf energy, not heuristic scores.**
+
+Integration:
+```rust
+pub struct SheafCoherenceValidator {
+    graph: SheafGraph,
+    gate: CoherenceGate,
+    inner: CoherenceValidator,  // Fallback
+}
+```
+
+Process:
+1. Convert context and response to sheaf nodes
+2. Add edges for semantic implications
+3. Compute coherence energy
+4. Gate decision replaces heuristic score
+
+## Consequences
+
+### Benefits
+- Mathematical proof of inconsistency, not pattern matching
+- Explainable: can show which edges have high residuals
+- Unified with Prime-Radiant governance
+
+### Risks
+- Requires embedding quality for node states
+- Edge creation logic needs domain expertise
+
+## References
+
+- ADR-014: Coherence Engine Architecture, "RuvLLM Integration"
+- ruvllm/src/quality/coherence.rs

docs/adr/coherence-engine/ADR-CE-017-unified-audit-trail.md

@@ -0,0 +1,51 @@
+# ADR-CE-017: Unified Audit Trail
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+RuvLLM has `WitnessLog` for inference audit. Prime-Radiant has `WitnessRecord` for coherence decisions. Two separate audit trails create:
+- Fragmented compliance story
+- Difficult cross-referencing
+- Duplicate storage
+
+## Decision
+
+**WitnessLog and Prime-Radiant governance share single audit trail.**
+
+Unified structure:
+```rust
+pub struct UnifiedWitnessLog {
+    coherence_witnesses: Vec<WitnessRecord>,
+    inference_witnesses: WitnessLog,
+}
+
+pub struct GenerationWitness {
+    inference: InferenceWitness,
+    coherence: WitnessRecord,
+    hash_chain: Hash,
+}
+```
+
+Every LLM generation links:
+- Inference witness (what was generated)
+- Coherence witness (why it was allowed)
+- Hash chain (tamper-evident ordering)
+
+## Consequences
+
+### Benefits
+- Single audit trail for compliance
+- Cross-reference inference ↔ coherence decisions
+- Reduced storage (shared chain)
+
+### Risks
+- Migration from two systems to one
+- Both systems must agree on witness format
+
+## References
+
+- ADR-014: Coherence Engine Architecture, "RuvLLM Integration"
+- ADR-CE-005: First-Class Governance Objects

docs/adr/coherence-engine/ADR-CE-018-pattern-restriction-bridge.md

@@ -0,0 +1,48 @@
+# ADR-CE-018: Pattern-to-Restriction Bridge
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+RuvLLM's `ReasoningBank` stores successful patterns with verdicts. Prime-Radiant's restriction maps define constraints. These can reinforce each other:
+- Successful patterns → what "coherence" looks like
+- Failed patterns → what "incoherence" looks like
+
+## Decision
+
+**ReasoningBank patterns feed learned restriction map training.**
+
+Bridge process:
+```rust
+impl PatternToRestrictionBridge {
+    fn learn_from_verdict(&mut self, pattern_id: PatternId, verdict: Verdict) {
+        if verdict.success_score > 0.8 {
+            // Success: train ρ to produce zero residual
+            self.restriction_maps[pattern_id]
+                .train(source, target, zero_residual);
+        } else {
+            // Failure: train ρ to produce high residual
+            self.restriction_maps[pattern_id]
+                .train(source, target, failure_residual);
+        }
+    }
+}
+```
+
+## Consequences
+
+### Benefits
+- Experience improves constraint accuracy
+- Successful patterns define "good" coherence
+- Failed patterns help detect future failures
+
+### Risks
+- Biased patterns lead to biased constraints
+- Need sufficient positive and negative examples
+
+## References
+
+- ADR-014: Coherence Engine Architecture, "RuvLLM Integration"
+- ruvllm/src/reasoning_bank/

docs/adr/coherence-engine/ADR-CE-019-memory-as-nodes.md

@@ -0,0 +1,55 @@
+# ADR-CE-019: Memory as Nodes
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+RuvLLM has three memory types:
+- `AgenticMemory`: Long-term patterns
+- `WorkingMemory`: Current context
+- `EpisodicMemory`: Conversation history
+
+These memories can contradict each other. Currently no systematic way to detect.
+
+## Decision
+
+**AgenticMemory, WorkingMemory, EpisodicMemory become sheaf nodes.**
+
+Integration:
+```rust
+pub struct MemoryCoherenceLayer {
+    agentic: AgenticMemory,
+    working: WorkingMemory,
+    episodic: EpisodicMemory,
+    graph: SheafGraph,
+}
+```
+
+When memory is added:
+1. Create sheaf node with memory embedding
+2. Add edges to related memories
+3. Compute coherence energy
+4. Alert if incoherent memory detected
+
+Edge types:
+- Temporal: Episode N should be consistent with N-1
+- Semantic: Related facts should agree
+- Hierarchical: Specific facts consistent with general patterns
+
+## Consequences
+
+### Benefits
+- Detect contradictory memories before they cause problems
+- Unified coherence across all memory types
+- Can query "is my context self-consistent?"
+
+### Risks
+- Overhead for every memory write
+- Edge creation requires semantic analysis
+
+## References
+
+- ADR-014: Coherence Engine Architecture, "RuvLLM Integration"
+- ruvllm/src/context/

docs/adr/coherence-engine/ADR-CE-020-confidence-from-energy.md

@@ -0,0 +1,49 @@
+# ADR-CE-020: Confidence from Energy
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+RuvLLM's `ConfidenceChecker` produces confidence scores, but:
+- Scores are heuristic-based
+- "Confidence" is often miscalibrated
+- No mathematical grounding
+
+Coherence energy provides a principled alternative.
+
+## Decision
+
+**Confidence scores derived from coherence energy with sigmoid mapping.**
+
+Mapping:
+```rust
+fn confidence_from_energy(energy: f32, scale: f32, threshold: f32) -> f32 {
+    // Low energy → high confidence
+    // High energy → low confidence
+    let scaled = scale * (energy - threshold);
+    1.0 / (1.0 + scaled.exp())
+}
+```
+
+Properties:
+- Energy = 0 → Confidence ≈ 1.0 (perfectly coherent)
+- Energy = threshold → Confidence = 0.5 (uncertain)
+- Energy >> threshold → Confidence → 0 (incoherent)
+
+## Consequences
+
+### Benefits
+- Confidence has mathematical grounding
+- "I don't know" is provable (high energy)
+- Calibration through energy scale tuning
+
+### Risks
+- Sigmoid parameters need tuning
+- Different domains may need different mappings
+
+## References
+
+- ADR-014: Coherence Engine Architecture, "RuvLLM Integration"
+- ADR-CE-013: Not Prediction

docs/adr/coherence-engine/ADR-CE-021-shared-sona.md

@@ -0,0 +1,52 @@
+# ADR-CE-021: Shared SONA
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+Both RuvLLM and Prime-Radiant use SONA for adaptive tuning:
+- RuvLLM: Quality thresholds, routing weights
+- Prime-Radiant: Coherence thresholds, escalation triggers
+
+Running two SONA instances wastes resources and may learn conflicting adaptations.
+
+## Decision
+
+**SonaIntegration shared between ruvllm and Prime-Radiant.**
+
+Shared components:
+- `SonaEngine`: Single instance with multiple learning targets
+- `ReasoningBank`: Unified pattern storage
+- `EWC++`: Consolidated knowledge across both systems
+
+Configuration:
+```rust
+pub struct SharedSona {
+    engine: SonaEngine,
+    llm_targets: Vec<LlmLearningTarget>,
+    coherence_targets: Vec<CoherenceLearningTarget>,
+}
+```
+
+Learning coordination:
+- Both systems contribute trajectories
+- EWC++ prevents forgetting across domains
+- Patterns accessible to both systems
+
+## Consequences
+
+### Benefits
+- Unified adaptation reduces resource usage
+- Cross-domain learning (LLM patterns help coherence, vice versa)
+- Consistent behavior across systems
+
+### Risks
+- Coupling between systems
+- Bad learning in one domain affects both
+
+## References
+
+- ADR-014: Coherence Engine Architecture, "RuvLLM Integration"
+- sona crate documentation

docs/adr/coherence-engine/ADR-CE-022-failure-learning.md

@@ -0,0 +1,56 @@
+# ADR-CE-022: Failure Learning
+
+**Status**: Accepted
+**Date**: 2026-01-22
+**Parent**: ADR-014 Coherence Engine Architecture
+
+## Context
+
+RuvLLM's `ErrorPatternLearner` detects:
+- Repeated error patterns
+- Systematic failures
+- Edge cases that cause problems
+
+This knowledge should improve Prime-Radiant's detection.
+
+## Decision
+
+**ErrorPatternLearner updates restriction maps on failure detection.**
+
+Process:
+1. ErrorPatternLearner identifies failure pattern
+2. Extract embeddings from failure context
+3. Compute what residual "should have been" (high, since failure)
+4. Train restriction map to produce high residual for similar inputs
+5. Future similar inputs trigger coherence warning
+
+Integration:
+```rust
+impl ErrorPatternLearner {
+    fn on_error_pattern_detected(&self, pattern: ErrorPattern) {
+        let bridge = self.restriction_bridge.lock();
+        bridge.learn_failure_pattern(
+            pattern.context_embedding,
+            pattern.output_embedding,
+            pattern.severity,
+        );
+    }
+}
+```
+
+## Consequences
+
+### Benefits
+- System learns from mistakes
+- Future similar failures detected proactively
+- Restriction maps become smarter over time
+
+### Risks
+- False positive errors teach wrong constraints
+- Need to distinguish systematic vs. random failures
+
+## References
+
+- ADR-014: Coherence Engine Architecture, "RuvLLM Integration"
+- ADR-CE-018: Pattern-to-Restriction Bridge
+- ruvllm/src/reflection/error_pattern.rs