# Coherence Engine: Domain-Driven Design

**Version**: 0.3
**Date**: 2026-01-22
**Status**: Draft

---

## Strategic Design

### Domain Vision

The Coherence Engine provides a **continuously updated field of coherence** that shows where action is safe and where action must stop. It replaces probabilistic confidence with mathematical witnesses based on sheaf Laplacian theory.

> **This is not prediction.** The system answers: "Does the world still fit together?" not "What will happen?"

### The Universal Coherence Object

The power lies in a **single underlying coherence object** inside ruvector. Once the math is fixed, everything else becomes interpretation:

| Domain | Nodes Become | Edges Become | Residual Becomes | Gate Becomes |
|--------|--------------|--------------|------------------|--------------|
| **AI Agents** | Facts, hypotheses, beliefs | Citations, logical implication | Contradiction energy | Hallucination refusal |
| **Finance** | Trades, positions, signals | Market dependencies, arbitrage | Regime mismatch | Trading throttle |
| **Medical** | Vitals, diagnoses, treatments | Physiological causality | Clinical disagreement | Escalation trigger |
| **Robotics** | Sensor readings, goals, plans | Physics, kinematics | Motion impossibility | Safety stop |
| **Security** | Identities, permissions, actions | Policy rules, trust chains | Authorization violation | Access denial |
| **Science** | Hypotheses, observations, models | Experimental evidence | Theory inconsistency | Pruning signal |

**Same math, different interpretations. Same residual = contradiction energy. Same gate = refusal mechanism with witness.**

### Core Domain

**Coherence Computation** - The heart of the system, computing edge residuals and aggregating them into global coherence energy scores. **Most updates stay in a low-latency reflex lane; sustained/growing incoherence triggers escalation.**

### Supporting Domains

1. **Knowledge Substrate** - Graph state management (nodes, edges, restriction maps)
2. **Governance** - Policy, witness, and lineage management (signed policy bundles, mandatory witnesses)
3. **Action Execution** - Gated side effects with mandatory witnesses (refusal with proof)
4. **Tile Fabric** - 256-tile WASM distributed computation (cognitum-gate-kernel)
5. **Neural Gating** - Biologically-inspired compute ladder (ruvector-nervous-system)
6. **Adaptive Learning** - Self-optimizing thresholds from real traces (sona)

### Generic Domains

1. **Storage** - PostgreSQL (transactional authority) + ruvector (high-performance vector/graph)
2. **Event Sourcing** - Deterministic replay from signed event log
3. **Distributed Consensus** - Multi-node synchronization (ruvector-raft)

### Application Evolution

The universal coherence object enables a clean spectrum of applications without rewriting the core:

| Timeline | Applications | Key Capability |
|----------|-------------|----------------|
| **Today** | Anti-hallucination guards, market regime throttles, audit-ready compliance proofs | Structural proof, not probability |
| **Next (12-24mo)** | Safety-first drone autonomy, medical monitoring (sustained disagreement), zero-trust security | Proactive detection before alerts |
| **Future (5-10yr)** | Scientific theory pruning, policy stress testing, **self-awareness primitive** | System knows when it doesn't know |

> **Self-Awareness Primitive**: The system eventually knows when it no longer understands itself.

---

## Ruvector Ecosystem Integration Map

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              BOUNDED CONTEXTS                                    │
│                                                                                  │
│  ┌─────────────────────────────────────────────────────────────────────────────┐│
│  │                        TILE FABRIC (cognitum-gate-kernel)                   ││
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐        ┌─────────┐                    ││
│  │  │ Tile 0  │ │ Tile 1  │ │ Tile 2  │  ...   │Tile 255 │                    ││
│  │  │ Shard   │ │ Shard   │ │ Shard   │        │ Shard   │                    ││
│  │  │ E-value │ │ E-value │ │ E-value │        │ E-value │                    ││
│  │  │ Witness │ │ Witness │ │ Witness │        │ Witness │                    ││
│  │  └─────────┘ └─────────┘ └─────────┘        └─────────┘                    ││
│  └─────────────────────────────────────────────────────────────────────────────┘│
│                                      │                                          │
│                                      ▼                                          │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐              │
│  │ COHERENCE        │  │ KNOWLEDGE        │  │ NEURAL GATING    │              │
│  │ COMPUTATION      │◀─│ SUBSTRATE        │──│ (nervous-system) │              │
│  │                  │  │                  │  │                  │              │
│  │ • Energy calc    │  │ • SheafGraph     │  │ • CoherenceGated │              │
│  │ • Spectral       │  │ • Learned ρ(GNN) │  │ • GlobalWorkspace│              │
│  │ • Hyperbolic     │  │ • Hyperbolic idx │  │ • HDC witnesses  │              │
│  │ • Attention wgt  │  │ • MinCut isolate │  │ • Dendrites      │              │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘              │
│           │                    │                      │                         │
│           └────────────────────┼──────────────────────┘                         │
│                                ▼                                                │
│  ┌──────────────────────────────────────────────────────────────────────────┐  │
│  │                    ADAPTIVE LEARNING (sona)                               │  │
│  │  Micro-LoRA (instant) │ Base-LoRA (background) │ EWC++ (no forgetting)   │  │
│  │  ReasoningBank        │ Three learning loops    │ Pattern extraction      │  │
│  └──────────────────────────────────────────────────────────────────────────┘  │
│                                │                                                │
│                                ▼                                                │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐              │
│  │ GOVERNANCE       │  │ ACTION           │  │ DISTRIBUTED      │              │
│  │                  │  │ EXECUTION        │  │ CONSENSUS (raft) │              │
│  │ • PolicyBundle   │  │ • Gate           │  │ • Leader elect   │              │
│  │ • WitnessRecord  │  │ • ComputeLadder  │  │ • Log replicate  │              │
│  │ • LineageRecord  │  │ • Escalation     │  │ • Global energy  │              │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘              │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘
```

### Crate-to-Context Mapping

| Bounded Context | Primary Crate | Supporting Crates |
|-----------------|---------------|-------------------|
| Tile Fabric | `cognitum-gate-kernel` | - |
| Coherence Computation | `ruvector-coherence` (new) | `ruvector-attention`, `ruvector-hyperbolic-hnsw` |
| Knowledge Substrate | `ruvector-graph` | `ruvector-gnn`, `ruvector-mincut`, `ruvector-core` |
| Neural Gating | `ruvector-nervous-system` | - |
| Adaptive Learning | `sona` | `ruvector-gnn` (EWC) |
| Governance | `ruvector-coherence` (new) | - |
| Action Execution | `ruvector-coherence` (new) | `ruvector-nervous-system` |
| Distributed Consensus | `ruvector-raft` | - |

---

## Bounded Contexts

### Context Map

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              COHERENCE ENGINE                                │
│                                                                              │
│  ┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐  │
│  │                  │      │                  │      │                  │  │
│  │  SIGNAL          │─────▶│  KNOWLEDGE       │─────▶│  COHERENCE       │  │
│  │  INGESTION       │      │  SUBSTRATE       │      │  COMPUTATION     │  │
│  │                  │      │                  │      │                  │  │
│  └──────────────────┘      └──────────────────┘      └────────┬─────────┘  │
│           │                         │                          │            │
│           │                         │                          │            │
│           ▼                         ▼                          ▼            │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │                           GOVERNANCE                                  │  │
│  │  Policy Bundles │ Witness Records │ Lineage Records │ Audit Trail    │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│                                      │                                      │
│                                      ▼                                      │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │                        ACTION EXECUTION                               │  │
│  │  Coherence Gate │ Compute Ladder │ Escalation │ Side Effects         │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Context Relationships:
─────▶  Upstream/Downstream (Published Language)
```

---

## Bounded Context 0: Tile Fabric (cognitum-gate-kernel)

### Purpose

Provides the distributed computation substrate using 256 WASM tiles, each maintaining a local graph shard with evidence accumulation and witness fragments.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **Tile** | A ~64KB WASM kernel instance processing a graph shard |
| **Delta** | Incremental update (edge add/remove, observation, weight change) |
| **E-Value** | Evidence value for sequential hypothesis testing |
| **Witness Fragment** | Local contribution to global min-cut witness |
| **Tick** | One deterministic processing cycle of a tile |

### Aggregates (from cognitum-gate-kernel)

#### TileState (Aggregate Root)

```rust
// Directly from cognitum-gate-kernel
use cognitum_gate_kernel::{TileState, Delta, WitnessFragment, TileReport};

/// Adapter for coherence engine integration
pub struct CoherenceTile {
    /// The underlying tile state
    inner: TileState,
    /// Mapping to global node IDs
    node_map: HashMap<LocalNodeId, GlobalNodeId>,
}

impl CoherenceTile {
    /// Create a new coherence tile
    pub fn new(tile_id: u8) -> Self {
        Self {
            inner: TileState::new(tile_id),
            node_map: HashMap::new(),
        }
    }

    /// Ingest a sheaf graph update as a tile delta
    pub fn ingest_node_update(&mut self, node_id: GlobalNodeId, state: &[f32]) -> bool {
        let local_id = self.node_map.entry(node_id)
            .or_insert_with(|| self.allocate_local_id());

        let delta = Delta::observation(Observation::state_update(*local_id, state));
        self.inner.ingest_delta(&delta)
    }

    /// Execute tick and return report
    pub fn tick(&mut self, tick_number: u32) -> TileReport {
        self.inner.tick(tick_number)
    }

    /// Get witness fragment for aggregation
    pub fn witness_fragment(&self) -> WitnessFragment {
        self.inner.get_witness_fragment()
    }

    /// Get current e-value (evidence against coherence hypothesis)
    pub fn e_value(&self) -> f64 {
        self.inner.evidence.global_e_value()
    }
}
```

#### TileFabric (Domain Service)

```rust
/// Orchestrates 256 tiles for distributed coherence
pub struct TileFabric {
    tiles: Vec<CoherenceTile>,
    shard_strategy: ShardStrategy,
}

impl TileFabric {
    /// Create fabric with 256 tiles
    pub fn new(strategy: ShardStrategy) -> Self {
        Self {
            tiles: (0..256).map(|i| CoherenceTile::new(i as u8)).collect(),
            shard_strategy: strategy,
        }
    }

    /// Distribute node to appropriate tile based on sharding strategy
    pub fn route_node(&self, node_id: GlobalNodeId) -> u8 {
        self.shard_strategy.tile_for(node_id)
    }

    /// Parallel tick across all tiles
    pub fn tick_all(&mut self, tick_number: u32) -> FabricReport {
        let reports: Vec<TileReport> = self.tiles
            .par_iter_mut()
            .map(|tile| tile.tick(tick_number))
            .collect();

        FabricReport::aggregate(reports)
    }

    /// Collect all witness fragments
    pub fn collect_witnesses(&self) -> Vec<WitnessFragment> {
        self.tiles.iter()
            .map(|t| t.witness_fragment())
            .collect()
    }
}
```

### Domain Events

| Event | Trigger | Consumers |
|-------|---------|-----------|
| `DeltaIngested` | Tile receives update | Tile processing |
| `TickCompleted` | Tile finishes tick | Fabric aggregation |
| `WitnessGenerated` | Tick produces witness | Global aggregation |
| `EvidenceThresholdCrossed` | E-value exceeds limit | Escalation |

---

## Bounded Context 0.5: Adaptive Learning (sona)

### Purpose

Provides self-optimizing threshold tuning using SONA's three learning loops, with EWC++ to prevent catastrophic forgetting when adapting to new operational regimes.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **Trajectory** | A sequence of energy observations during an operational regime |
| **Micro-LoRA** | Ultra-low rank (1-2) adaptation for instant learning (<0.05ms) |
| **Base-LoRA** | Standard LoRA for background learning |
| **EWC++** | Elastic Weight Consolidation preventing catastrophic forgetting |
| **ReasoningBank** | Pattern storage for past successful configurations |

### Aggregates

#### ThresholdLearner (Aggregate Root)

```rust
use sona::{
    SonaEngine, SonaConfig, TrajectoryBuilder, TrajectoryStep,
    MicroLoRA, BaseLoRA, EwcPlusPlus, ReasoningBank,
};

/// Adaptive threshold learning using SONA
pub struct ThresholdLearner {
    /// SONA engine
    engine: SonaEngine,
    /// Current thresholds
    thresholds: ThresholdConfig,
    /// Active trajectory (if any)
    active_trajectory: Option<TrajectoryBuilder>,
    /// Pattern bank for successful configurations
    patterns: ReasoningBank,
}

impl ThresholdLearner {
    pub fn new(hidden_dim: usize) -> Self {
        let config = SonaConfig {
            hidden_dim,
            embedding_dim: hidden_dim,
            ..Default::default()
        };

        Self {
            engine: SonaEngine::new(config),
            thresholds: ThresholdConfig::default(),
            active_trajectory: None,
            patterns: ReasoningBank::new(PatternConfig::default()),
        }
    }

    /// Start learning when entering new regime
    pub fn begin_regime(&mut self, initial_energy: Vec<f32>) {
        self.active_trajectory = Some(self.engine.begin_trajectory(initial_energy));
    }

    /// Record an observation during the regime
    pub fn observe(&mut self, energy: Vec<f32>, action_taken: Vec<f32>, quality: f32) {
        if let Some(ref mut traj) = self.active_trajectory {
            traj.add_step(energy, action_taken, quality);
        }
    }

    /// End regime and learn from outcome
    pub fn end_regime(&mut self, final_quality: f32) -> DomainEvent {
        if let Some(traj) = self.active_trajectory.take() {
            // Triggers Micro-LoRA instant adaptation
            self.engine.end_trajectory(traj, final_quality);

            if final_quality > 0.8 {
                // Store successful pattern
                self.patterns.store(
                    PatternType::Threshold,
                    &self.thresholds.to_embedding(),
                );
                return DomainEvent::PatternLearned { quality: final_quality };
            }
        }
        DomainEvent::RegimeEnded { quality: final_quality }
    }

    /// Find similar past regime
    pub fn recall_similar(&self, current_energy: &[f32]) -> Option<ThresholdConfig> {
        self.patterns.query(current_energy, 5)
            .first()
            .map(|p| ThresholdConfig::from_embedding(&p.embedding))
    }

    /// Consolidate to prevent forgetting
    pub fn consolidate(&mut self) {
        // EWC++ preserves important weights
        self.engine.consolidate_ewc();
    }

    /// Apply instant adaptation (Micro-LoRA)
    pub fn instant_adapt(&mut self, energy_spike: f32) -> ThresholdAdjustment {
        let input = vec![energy_spike; self.engine.config().hidden_dim];
        let mut output = vec![0.0; self.engine.config().hidden_dim];

        self.engine.apply_micro_lora(&input, &mut output);

        ThresholdAdjustment::from_embedding(&output)
    }
}
```

### Domain Events

| Event | Trigger | Consumers |
|-------|---------|-----------|
| `RegimeStarted` | New operational regime detected | TrajectoryBuilder |
| `ObservationRecorded` | Energy observation added | Active trajectory |
| `RegimeEnded` | Regime completed | Learning consolidation |
| `PatternLearned` | Successful pattern stored | ReasoningBank |
| `ThresholdAdapted` | Micro-LoRA adaptation | Gate configuration |

---

## Bounded Context 0.7: Neural Gating (ruvector-nervous-system)

### Purpose

Provides biologically-inspired gating using the existing CoherenceGatedSystem, GlobalWorkspace for conscious access, and HDC for compact witness encoding.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **CoherenceGatedSystem** | Pre-existing neural gating from ruvector-nervous-system |
| **GlobalWorkspace** | Conscious broadcast mechanism for significant decisions |
| **Hypervector** | 10K-dimensional binary vector for similarity-preserving encoding |
| **Dendrite** | Coincidence detector requiring multiple inputs within time window |
| **Plateau Potential** | Threshold firing when dendritic conditions met |

### Aggregates

#### NeuralGate (Adapter to existing CoherenceGatedSystem)

```rust
use ruvector_nervous_system::{
    CoherenceGatedSystem, GlobalWorkspace, HysteresisTracker,
    OscillatoryRouter, Dendrite, DendriticTree,
    HdcMemory, Hypervector,
};

/// Neural gating using existing ruvector-nervous-system
pub struct NeuralGate {
    /// The existing coherence-gated system
    system: CoherenceGatedSystem,
    /// Global workspace for broadcast
    workspace: GlobalWorkspace,
    /// Hysteresis to prevent oscillation
    hysteresis: HysteresisTracker,
    /// Dendritic coincidence detection
    dendrites: DendriticTree,
    /// HDC memory for witnesses
    hdc: HdcMemory,
}

impl NeuralGate {
    /// Evaluate with biological gating
    pub fn evaluate(&mut self, energy: f32, evidence: &[EvidenceSource]) -> NeuralDecision {
        // Feed evidence to dendrites
        for (i, src) in evidence.iter().enumerate() {
            if src.is_active() {
                self.dendrites.receive_spike(i, src.timestamp);
            }
        }

        // Check for plateau potential (coincidence detection)
        let plateau = self.dendrites.update(evidence[0].timestamp, 1.0);

        // Apply hysteresis to prevent oscillation
        let decision = self.hysteresis.filter(energy, plateau);

        // Broadcast significant decisions
        if decision.is_significant() {
            self.workspace.broadcast(decision.clone());
        }

        decision
    }

    /// Encode witness as hypervector
    pub fn encode_witness(&mut self, witness: &WitnessRecord) -> WitnessHypervector {
        let energy_hv = Hypervector::from_scalar(witness.energy_snapshot.total_energy);
        let decision_hv = Hypervector::random(); // Seed from decision
        let policy_hv = Hypervector::from_bytes(&witness.policy_bundle_ref.as_bytes());

        let encoded = energy_hv.bind(&decision_hv).bind(&policy_hv);

        self.hdc.store(&witness.id.to_string(), encoded.clone());

        WitnessHypervector(encoded)
    }

    /// Find similar past decisions
    pub fn find_similar(&self, query: &Hypervector, threshold: f32) -> Vec<WitnessId> {
        self.hdc.retrieve(query, threshold)
            .into_iter()
            .filter_map(|(id, _)| WitnessId::parse(&id).ok())
            .collect()
    }
}
```

### Domain Events

| Event | Trigger | Consumers |
|-------|---------|-----------|
| `PlateauTriggered` | Dendritic coincidence | Decision evaluation |
| `DecisionBroadcast` | Significant decision | GlobalWorkspace subscribers |
| `WitnessEncoded` | HDC encoding complete | Similarity search |

---

## Bounded Context 1: Signal Ingestion

### Purpose

Validates and normalizes incoming events before they enter the knowledge substrate.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **Signal** | Raw incoming event from external system |
| **Normalized Event** | Validated, typed event ready for processing |
| **Event Schema** | Contract defining valid event structure |
| **Ingestion Pipeline** | Sequence of validation and transformation steps |

### Aggregates

#### SignalProcessor

```rust
/// Root aggregate for signal processing
pub struct SignalProcessor {
    id: ProcessorId,
    schemas: HashMap<EventType, EventSchema>,
    validators: Vec<Box<dyn Validator>>,
    transformers: Vec<Box<dyn Transformer>>,
}

impl SignalProcessor {
    /// Process a raw signal into a normalized event
    pub fn process(&self, signal: RawSignal) -> Result<NormalizedEvent, IngestionError> {
        // Validate against schema
        let schema = self.schemas.get(&signal.event_type)
            .ok_or(IngestionError::UnknownEventType)?;
        schema.validate(&signal)?;

        // Run validators
        for validator in &self.validators {
            validator.validate(&signal)?;
        }

        // Transform to normalized form
        let mut event = NormalizedEvent::from(signal);
        for transformer in &self.transformers {
            event = transformer.transform(event)?;
        }

        Ok(event)
    }
}
```

### Domain Events

| Event | Trigger | Consumers |
|-------|---------|-----------|
| `SignalReceived` | External signal arrives | SignalProcessor |
| `EventNormalized` | Validation passes | Knowledge Substrate |
| `SignalRejected` | Validation fails | Monitoring, Alerting |

### Integration Patterns

- **Anti-Corruption Layer**: Translates external formats to internal domain model
- **Published Language**: JSON Schema for event contracts

---

## Bounded Context 2: Knowledge Substrate

### Purpose

Maintains the sheaf graph representing system state with nodes, edges, and restriction maps. **The same substrate serves all domains** - nodes can be facts, trades, vitals, devices, hypotheses, or beliefs; edges can encode citations, causality, physiology, policy, or physics.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **Sheaf Node** | Entity with fixed-dimensional state vector (domain-agnostic: facts, trades, vitals, hypotheses, beliefs) |
| **Sheaf Edge** | Constraint between two nodes via restriction maps (domain-agnostic: citations, causality, physiology, policy, physics) |
| **Restriction Map** | Lightweight linear transformation encoding how one state constrains another |
| **Stalk** | The state vector at a node (sheaf terminology) |
| **Section** | A consistent assignment of states to nodes |
| **Residual** | **Contradiction energy** - mismatch between projected states |

### Aggregates

#### SheafGraph (Aggregate Root)

```rust
/// The sheaf graph representing system state
pub struct SheafGraph {
    id: GraphId,
    nodes: HashMap<NodeId, SheafNode>,
    edges: HashMap<EdgeId, SheafEdge>,
    namespaces: HashMap<NamespaceId, NodeSet>,
    version: Version,
    fingerprint: Hash,
}

impl SheafGraph {
    /// Add or update a node's state
    pub fn upsert_node(&mut self, node: SheafNode) -> DomainEvent {
        let existed = self.nodes.insert(node.id, node.clone()).is_some();
        self.update_fingerprint();

        if existed {
            DomainEvent::NodeUpdated { node_id: node.id }
        } else {
            DomainEvent::NodeCreated { node_id: node.id }
        }
    }

    /// Add an edge with restriction maps
    pub fn add_edge(&mut self, edge: SheafEdge) -> Result<DomainEvent, DomainError> {
        // Validate nodes exist
        if !self.nodes.contains_key(&edge.source) {
            return Err(DomainError::NodeNotFound(edge.source));
        }
        if !self.nodes.contains_key(&edge.target) {
            return Err(DomainError::NodeNotFound(edge.target));
        }

        // Validate dimension compatibility
        let source_dim = self.nodes[&edge.source].state.len();
        let target_dim = self.nodes[&edge.target].state.len();

        if edge.rho_source.input_dim() != source_dim {
            return Err(DomainError::DimensionMismatch);
        }
        if edge.rho_target.input_dim() != target_dim {
            return Err(DomainError::DimensionMismatch);
        }

        self.edges.insert(edge.id, edge.clone());
        self.update_fingerprint();

        Ok(DomainEvent::EdgeCreated { edge_id: edge.id })
    }

    /// Get subgraph for localized computation
    pub fn subgraph(&self, center: NodeId, hops: usize) -> SheafSubgraph {
        let node_ids = self.bfs_neighbors(center, hops);
        SheafSubgraph {
            nodes: node_ids.iter()
                .filter_map(|id| self.nodes.get(id).cloned())
                .collect(),
            edges: self.edges.values()
                .filter(|e| node_ids.contains(&e.source) && node_ids.contains(&e.target))
                .cloned()
                .collect(),
        }
    }
}
```

#### SheafNode (Entity)

```rust
/// A node in the sheaf graph
pub struct SheafNode {
    id: NodeId,
    state: Vec<f32>,
    metadata: NodeMetadata,
    namespace: NamespaceId,
    created_at: Timestamp,
    updated_at: Timestamp,
}

impl SheafNode {
    /// Invariant: state dimension is fixed after creation
    pub fn update_state(&mut self, new_state: Vec<f32>) -> Result<(), DomainError> {
        if new_state.len() != self.state.len() {
            return Err(DomainError::DimensionMismatch);
        }
        self.state = new_state;
        self.updated_at = Timestamp::now();
        Ok(())
    }
}
```

#### RestrictionMap (Value Object)

```rust
/// Linear restriction map: y = Ax + b
#[derive(Clone, PartialEq)]
pub struct RestrictionMap {
    matrix: Matrix,  // m x n where n = input_dim, m = output_dim
    bias: Vec<f32>,  // m-dimensional
}

impl RestrictionMap {
    pub fn new(matrix: Matrix, bias: Vec<f32>) -> Result<Self, DomainError> {
        if matrix.nrows() != bias.len() {
            return Err(DomainError::DimensionMismatch);
        }
        Ok(Self { matrix, bias })
    }

    pub fn apply(&self, input: &[f32]) -> Vec<f32> {
        let result = &self.matrix * &DVector::from_slice(input);
        result.iter()
            .zip(self.bias.iter())
            .map(|(a, b)| a + b)
            .collect()
    }

    pub fn input_dim(&self) -> usize { self.matrix.ncols() }
    pub fn output_dim(&self) -> usize { self.matrix.nrows() }
}
```

### Domain Events

| Event | Trigger | Consumers |
|-------|---------|-----------|
| `NodeCreated` | New node added | Coherence Computation |
| `NodeUpdated` | Node state changed | Coherence Computation (incremental) |
| `EdgeCreated` | New constraint added | Coherence Computation |
| `SubgraphExtracted` | Localized computation needed | Coherence Computation |

### Repository Interface

```rust
#[async_trait]
pub trait SheafGraphRepository {
    async fn find_by_id(&self, id: GraphId) -> Option<SheafGraph>;
    async fn save(&self, graph: &SheafGraph) -> Result<(), PersistenceError>;
    async fn find_nodes_by_namespace(&self, ns: NamespaceId) -> Vec<SheafNode>;
    async fn find_similar_nodes(&self, state: &[f32], k: usize) -> Vec<(NodeId, f32)>;
}
```

---

## Bounded Context 3: Coherence Computation

### Purpose

Computes edge residuals, aggregates energy, and detects structural inconsistencies. This maintains a **continuously updated field of coherence** that shows where action is safe and where action must stop.

> **Key Principle**: Incoherence is computed incrementally as edge-level residuals and aggregated into scoped coherence energy using a sheaf Laplacian operator.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **Residual** | **Contradiction energy** at an edge: r_e = ρ_u(x_u) - ρ_v(x_v) |
| **Energy** | Global incoherence measure: E = Σ w_e\|r_e\|² (lower = more coherent) |
| **Coherence Field** | Continuously updated map showing safe vs. unsafe action regions |
| **Coherence** | Inverse of energy; high coherence = low energy |
| **Fingerprint** | Hash summarizing graph state for change detection |
| **Spectral Drift** | Change in eigenvalue distribution indicating structural shift |

### Aggregates

#### CoherenceEngine (Aggregate Root)

```rust
/// The coherence computation engine
pub struct CoherenceEngine {
    id: EngineId,
    /// Cached residuals for incremental computation
    residual_cache: HashMap<EdgeId, Vec<f32>>,
    /// Subgraph energy summaries
    summary_cache: HashMap<SubgraphId, f32>,
    /// Global fingerprint
    fingerprint: Hash,
    /// Configuration
    config: CoherenceConfig,
}

impl CoherenceEngine {
    /// Compute full coherence energy for a graph
    pub fn compute_energy(&mut self, graph: &SheafGraph) -> CoherenceEnergy {
        // Check if we can use incremental computation
        if self.fingerprint == graph.fingerprint {
            return self.cached_energy();
        }

        // Full recomputation
        let edge_energies: HashMap<EdgeId, f32> = graph.edges
            .par_iter()
            .map(|(id, edge)| {
                let residual = self.compute_residual(graph, edge);
                let energy = edge.weight * residual.iter().map(|x| x * x).sum::<f32>();
                self.residual_cache.insert(*id, residual);
                (*id, energy)
            })
            .collect();

        let total = edge_energies.values().sum();
        self.fingerprint = graph.fingerprint;

        CoherenceEnergy {
            total_energy: total,
            edge_energies,
            scope_energies: self.aggregate_by_scope(graph, &edge_energies),
            fingerprint: self.fingerprint,
            computed_at: Timestamp::now(),
        }
    }

    /// Incremental update when a single node changes
    pub fn update_node(&mut self, graph: &SheafGraph, node_id: NodeId) -> CoherenceEnergy {
        let affected_edges = graph.edges_incident_to(node_id);

        for edge_id in &affected_edges {
            let edge = &graph.edges[edge_id];
            let residual = self.compute_residual(graph, edge);
            self.residual_cache.insert(*edge_id, residual);
        }

        self.recompute_from_cache(graph)
    }

    fn compute_residual(&self, graph: &SheafGraph, edge: &SheafEdge) -> Vec<f32> {
        let source_state = &graph.nodes[&edge.source].state;
        let target_state = &graph.nodes[&edge.target].state;

        let projected_source = edge.rho_source.apply(source_state);
        let projected_target = edge.rho_target.apply(target_state);

        projected_source.iter()
            .zip(projected_target.iter())
            .map(|(a, b)| a - b)
            .collect()
    }
}
```

#### CoherenceEnergy (Value Object)

```rust
/// Immutable snapshot of coherence energy
#[derive(Clone)]
pub struct CoherenceEnergy {
    pub total_energy: f32,
    pub edge_energies: HashMap<EdgeId, f32>,
    pub scope_energies: HashMap<ScopeId, f32>,
    pub fingerprint: Hash,
    pub computed_at: Timestamp,
}

impl CoherenceEnergy {
    /// Get energy for a specific scope
    pub fn scope_energy(&self, scope: &ScopeId) -> f32 {
        self.scope_energies.get(scope).copied().unwrap_or(0.0)
    }

    /// Find edges with highest energy (most incoherent)
    pub fn hotspots(&self, k: usize) -> Vec<(EdgeId, f32)> {
        let mut sorted: Vec<_> = self.edge_energies.iter().collect();
        sorted.sort_by(|a, b| b.1.partial_cmp(a.1).unwrap());
        sorted.into_iter().take(k).map(|(id, e)| (*id, *e)).collect()
    }
}
```

### Domain Services

#### SpectralAnalyzer

```rust
/// Detects structural drift via eigenvalue analysis
pub struct SpectralAnalyzer {
    history: VecDeque<EigenvalueSnapshot>,
    drift_threshold: f32,
    window_size: usize,
}

impl SpectralAnalyzer {
    /// Analyze eigenvalues for drift detection
    pub fn analyze(&mut self, laplacian: &SheafLaplacian) -> SpectralAnalysis {
        let eigenvalues = laplacian.compute_top_eigenvalues(10);
        let snapshot = EigenvalueSnapshot::new(eigenvalues.clone());

        let drift = if let Some(prev) = self.history.back() {
            self.wasserstein_distance(&snapshot.eigenvalues, &prev.eigenvalues)
        } else {
            0.0
        };

        self.history.push_back(snapshot);
        if self.history.len() > self.window_size {
            self.history.pop_front();
        }

        SpectralAnalysis {
            eigenvalues,
            drift_magnitude: drift,
            is_drifting: drift > self.drift_threshold,
            timestamp: Timestamp::now(),
        }
    }
}
```

### Domain Events

| Event | Trigger | Consumers |
|-------|---------|-----------|
| `EnergyComputed` | Full computation completes | Governance, Gate |
| `EnergyUpdated` | Incremental update completes | Governance, Gate |
| `DriftDetected` | Spectral drift exceeds threshold | Alerting, Escalation |
| `HotspotIdentified` | Edge energy exceeds threshold | Debugging, Monitoring |

---

## Bounded Context 4: Governance

### Purpose

Manages policy bundles, witness records, and lineage tracking for auditability.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **Policy Bundle** | Versioned, signed collection of threshold configurations |
| **Witness Record** | Immutable proof of a gate decision |
| **Lineage Record** | Provenance chain for authoritative writes |
| **Approver** | Entity authorized to sign policy bundles |
| **Threshold** | Energy level triggering escalation |

### Aggregates

#### PolicyBundle (Aggregate Root)

```rust
/// Versioned, multi-sig policy configuration
pub struct PolicyBundle {
    id: PolicyBundleId,
    version: SemanticVersion,
    thresholds: HashMap<ScopePattern, ThresholdConfig>,
    escalation_rules: Vec<EscalationRule>,
    signatures: Vec<(ApproverId, Signature)>,
    required_approvals: usize,
    status: PolicyStatus,
    created_at: Timestamp,
    activated_at: Option<Timestamp>,
}

impl PolicyBundle {
    /// Invariant: cannot modify after activation
    pub fn add_threshold(&mut self, scope: ScopePattern, config: ThresholdConfig) -> Result<(), DomainError> {
        if self.status != PolicyStatus::Draft {
            return Err(DomainError::PolicyAlreadyActivated);
        }
        self.thresholds.insert(scope, config);
        Ok(())
    }

    /// Add approver signature
    pub fn sign(&mut self, approver: ApproverId, signature: Signature) -> Result<DomainEvent, DomainError> {
        if self.status != PolicyStatus::Draft {
            return Err(DomainError::PolicyAlreadyActivated);
        }

        // Verify signature
        let content_hash = self.content_hash();
        if !signature.verify(&content_hash, &approver) {
            return Err(DomainError::InvalidSignature);
        }

        self.signatures.push((approver, signature));

        // Check if enough signatures
        if self.signatures.len() >= self.required_approvals {
            self.status = PolicyStatus::Approved;
            return Ok(DomainEvent::PolicyApproved { bundle_id: self.id });
        }

        Ok(DomainEvent::PolicySigned { bundle_id: self.id, approver })
    }

    /// Activate the policy (makes it immutable)
    pub fn activate(&mut self) -> Result<DomainEvent, DomainError> {
        if self.status != PolicyStatus::Approved {
            return Err(DomainError::PolicyNotApproved);
        }

        self.status = PolicyStatus::Active;
        self.activated_at = Some(Timestamp::now());

        Ok(DomainEvent::PolicyActivated { bundle_id: self.id })
    }
}
```

#### WitnessRecord (Entity)

```rust
/// Immutable record of a gate decision
pub struct WitnessRecord {
    id: WitnessId,
    action_hash: Hash,
    energy_snapshot: CoherenceEnergy,
    decision: GateDecision,
    policy_bundle_ref: PolicyBundleRef,
    timestamp: Timestamp,
    previous_witness: Option<WitnessId>,
    content_hash: Hash,
}

impl WitnessRecord {
    pub fn new(
        action: &Action,
        energy: &CoherenceEnergy,
        decision: GateDecision,
        policy_ref: PolicyBundleRef,
        previous: Option<WitnessId>,
    ) -> Self {
        let mut record = Self {
            id: WitnessId::new(),
            action_hash: action.content_hash(),
            energy_snapshot: energy.clone(),
            decision,
            policy_bundle_ref: policy_ref,
            timestamp: Timestamp::now(),
            previous_witness: previous,
            content_hash: Hash::default(),
        };
        record.content_hash = record.compute_content_hash();
        record
    }

    /// Content hash for integrity verification
    fn compute_content_hash(&self) -> Hash {
        let mut hasher = Blake3::new();
        hasher.update(&self.action_hash);
        hasher.update(&self.energy_snapshot.fingerprint);
        hasher.update(&bincode::serialize(&self.decision).unwrap());
        hasher.update(&self.policy_bundle_ref.as_bytes());
        if let Some(prev) = &self.previous_witness {
            hasher.update(&prev.as_bytes());
        }
        hasher.finalize().into()
    }

    /// Verify integrity
    pub fn verify(&self) -> bool {
        self.content_hash == self.compute_content_hash()
    }
}
```

#### LineageRecord (Entity)

```rust
/// Provenance tracking for writes
pub struct LineageRecord {
    id: LineageId,
    entity_ref: EntityRef,
    operation: Operation,
    dependencies: Vec<LineageId>,
    authorizing_witness: WitnessId,
    actor: ActorId,
    timestamp: Timestamp,
}

impl LineageRecord {
    /// Invariant: must have authorizing witness
    pub fn new(
        entity: EntityRef,
        operation: Operation,
        witness: WitnessId,
        actor: ActorId,
        dependencies: Vec<LineageId>,
    ) -> Self {
        Self {
            id: LineageId::new(),
            entity_ref: entity,
            operation,
            dependencies,
            authorizing_witness: witness,
            actor,
            timestamp: Timestamp::now(),
        }
    }
}
```

### Domain Events

| Event | Trigger | Consumers |
|-------|---------|-----------|
| `PolicyCreated` | New bundle drafted | Approvers |
| `PolicySigned` | Approver signs | Policy lifecycle |
| `PolicyApproved` | Enough signatures | Activation |
| `PolicyActivated` | Bundle goes live | Gate |
| `WitnessCreated` | Gate decision made | Audit, Lineage |
| `LineageCreated` | Write authorized | Audit |

### Invariants

1. **No action without witness**: Every external action must have a `witness_id`
2. **No write without lineage**: Every authoritative write must have a `lineage_id`
3. **Policy immutability**: Active policies cannot be modified
4. **Signature validity**: All policy signatures must verify against content hash
5. **Witness chain**: Each witness references its predecessor (except first)

---

## Bounded Context 5: Action Execution

### Purpose

Executes gated side effects with mandatory witness and lineage creation. A **deterministic coherence gate** controls a compute ladder where **most updates stay in a low-latency reflex lane**, while sustained/growing incoherence triggers retrieval, deeper reasoning, or human escalation.

> **Key Principle**: All decisions and external side effects are governed by **signed policy bundles** and produce **mandatory witness and lineage records**, making every action auditable and replayable.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **Action** | External side effect to be executed |
| **Compute Lane** | Escalation level (Reflex → Retrieval → Heavy → Human) |
| **Reflex Lane** | **THE DEFAULT** - most updates stay here (<1ms) |
| **Gate Decision** | Allow/deny with required lane and witness |
| **Escalation** | Promotion to higher compute lane (triggered by **sustained** incoherence) |
| **Refusal** | Action denied due to incoherence - **refusal mechanism with witness** |
| **Witness** | Mandatory proof of every gate decision |

### Aggregates

#### CoherenceGate (Aggregate Root)

```rust
/// Gate controlling action execution
pub struct CoherenceGate {
    id: GateId,
    policy_bundle: PolicyBundle,
    energy_history: EnergyHistory,
    pending_escalations: HashMap<ActionId, Escalation>,
}

impl CoherenceGate {
    /// Evaluate whether an action should proceed
    pub fn evaluate(&mut self, action: &Action, energy: &CoherenceEnergy) -> GateDecision {
        let scope = action.scope();
        let current_energy = energy.scope_energy(&scope);

        // Get thresholds from policy
        let thresholds = self.policy_bundle.thresholds_for(&scope);

        // Determine required lane
        let lane = self.determine_lane(current_energy, &thresholds);

        // Check persistence
        let persistent = self.energy_history.is_persistently_above(
            &scope,
            thresholds.retrieval,
            thresholds.persistence_window,
        );

        // Escalate if persistent incoherence
        let final_lane = if persistent && lane < ComputeLane::Heavy {
            ComputeLane::Heavy
        } else {
            lane
        };

        // Record in history
        self.energy_history.record(scope.clone(), current_energy);

        GateDecision {
            allow: final_lane < ComputeLane::Human,
            lane: final_lane,
            reason: self.decision_reason(current_energy, &thresholds, persistent),
        }
    }

    fn determine_lane(&self, energy: f32, thresholds: &ThresholdConfig) -> ComputeLane {
        if energy < thresholds.reflex {
            ComputeLane::Reflex
        } else if energy < thresholds.retrieval {
            ComputeLane::Retrieval
        } else if energy < thresholds.heavy {
            ComputeLane::Heavy
        } else {
            ComputeLane::Human
        }
    }
}
```

#### ActionExecutor (Domain Service)

```rust
/// Executes actions with governance enforcement
pub struct ActionExecutor {
    gate: CoherenceGate,
    witness_repository: Arc<dyn WitnessRepository>,
    lineage_repository: Arc<dyn LineageRepository>,
}

impl ActionExecutor {
    /// Execute an action with full governance
    pub async fn execute<A: Action>(
        &mut self,
        action: A,
        energy: &CoherenceEnergy,
    ) -> Result<ExecutionResult<A::Output>, ExecutionError> {
        // Evaluate gate
        let decision = self.gate.evaluate(&action, energy);

        // Create witness (always, even for denials)
        let witness = WitnessRecord::new(
            &action,
            energy,
            decision.clone(),
            self.gate.policy_bundle.reference(),
            self.get_previous_witness().await,
        );
        self.witness_repository.save(&witness).await?;

        // Check if allowed
        if !decision.allow {
            return Err(ExecutionError::Denied {
                witness_id: witness.id,
                reason: decision.reason,
            });
        }

        // Execute the action
        let output = action.execute().await?;

        // Create lineage record for any writes
        if let Some(writes) = output.writes() {
            for write in writes {
                let lineage = LineageRecord::new(
                    write.entity_ref(),
                    write.operation(),
                    witness.id,
                    action.actor(),
                    write.dependencies(),
                );
                self.lineage_repository.save(&lineage).await?;
            }
        }

        Ok(ExecutionResult {
            output,
            witness_id: witness.id,
        })
    }
}
```

### Domain Events

| Event | Trigger | Consumers |
|-------|---------|-----------|
| `ActionAllowed` | Gate allows action | Executor, Monitoring |
| `ActionDenied` | Gate denies action | Alerting, Audit |
| `ActionExecuted` | Execution completes | Lineage, Monitoring |
| `EscalationTriggered` | Persistent incoherence | Human operators |

---

## Bounded Context 6: Learned Restriction Maps (ruvector-gnn)

### Purpose

Enables learning restriction maps (ρ) from data using GNN layers, with EWC to prevent catastrophic forgetting across training epochs.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **RuvectorLayer** | GNN layer implementing learned linear transformation |
| **Replay Buffer** | Experience replay for stable training |
| **Fisher Information** | Importance weight for EWC regularization |

### Aggregates

#### LearnedRestriction (Aggregate Root)

```rust
use ruvector_gnn::{
    RuvectorLayer, ElasticWeightConsolidation, ReplayBuffer,
    Optimizer, OptimizerType, LearningRateScheduler, SchedulerType,
    info_nce_loss, local_contrastive_loss,
};

/// Learned restriction map using GNN
pub struct LearnedRestriction {
    /// Neural network layer
    layer: RuvectorLayer,
    /// EWC for forgetting prevention
    ewc: ElasticWeightConsolidation,
    /// Experience replay
    replay: ReplayBuffer,
    /// Adam optimizer
    optimizer: Optimizer,
}

impl LearnedRestriction {
    /// Apply learned restriction
    pub fn apply(&self, state: &[f32]) -> Vec<f32> {
        self.layer.forward(state)
    }

    /// Train on coherent example pair
    pub fn train(&mut self, source: &[f32], target: &[f32], label: CoherenceLabel) {
        // Add to replay buffer
        self.replay.add(ReplayEntry {
            source: source.to_vec(),
            target: target.to_vec(),
            label,
        });

        // Sample batch
        let batch = self.replay.sample(32);

        // Compute contrastive loss
        let loss = local_contrastive_loss(&batch.embeddings(), &batch.labels(), 0.07);

        // Add EWC regularization
        let ewc_loss = self.ewc.compute_ewc_loss(&self.layer);
        let total_loss = loss + 0.4 * ewc_loss;

        // Update
        self.optimizer.step(&mut self.layer, total_loss);
    }

    /// Consolidate after epoch
    pub fn consolidate(&mut self, importance: f32) {
        self.ewc.update_fisher(&self.layer, importance);
    }
}
```

---

## Bounded Context 7: Hyperbolic Coherence (ruvector-hyperbolic-hnsw)

### Purpose

Provides hierarchy-aware energy computation where deeper nodes (further from origin in Poincaré ball) have higher coherence expectations.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **Poincaré Ball** | Hyperbolic space model where distance increases toward boundary |
| **Depth** | Distance from origin; deeper = further from origin |
| **Curvature** | Negative curvature parameter (typically -1.0) |
| **Tangent Space** | Local Euclidean approximation for fast pruning |

### Aggregates

#### HyperbolicGraph (Aggregate Root)

```rust
use ruvector_hyperbolic_hnsw::{
    HyperbolicHnsw, HyperbolicHnswConfig, ShardedHyperbolicHnsw,
    poincare_distance, project_to_ball, log_map, exp_map,
    HierarchyMetrics, TangentCache,
};

/// Hyperbolic coherence with hierarchy awareness
pub struct HyperbolicGraph {
    /// Hyperbolic index
    index: ShardedHyperbolicHnsw,
    /// Curvature
    curvature: f32,
    /// Tangent cache for fast pruning
    tangent_cache: TangentCache,
}

impl HyperbolicGraph {
    /// Insert node with automatic depth assignment
    pub fn insert(&mut self, node_id: NodeId, state: Vec<f32>, hierarchy_depth: Option<usize>) {
        let projected = project_to_ball(&state, self.curvature);
        self.index.insert(projected, hierarchy_depth).unwrap();
    }

    /// Compute depth-weighted residual energy
    pub fn weighted_residual(&self, edge: &SheafEdge, residual: &[f32]) -> f32 {
        let source_depth = self.depth(&edge.source);
        let target_depth = self.depth(&edge.target);

        // Deeper nodes should be MORE coherent, so weight violations higher
        let depth_weight = 1.0 + ((source_depth + target_depth) / 2.0).ln().max(0.0);

        let norm_sq: f32 = residual.iter().map(|x| x * x).sum();
        edge.weight * norm_sq * depth_weight
    }

    /// Compute node depth (distance from origin)
    fn depth(&self, node_id: &NodeId) -> f32 {
        let state = self.index.get(node_id);
        let origin = vec![0.0; state.len()];
        poincare_distance(&state, &origin, self.curvature)
    }

    /// Build tangent cache for fast neighbor search
    pub fn build_tangent_cache(&mut self) {
        self.index.build_tangent_cache().unwrap();
    }
}
```

---

## Bounded Context 8: Incoherence Isolation (ruvector-mincut)

### Purpose

Efficiently isolates incoherent subgraphs using subpolynomial n^o(1) dynamic min-cut algorithms.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **MinCut** | Minimum weight edge set whose removal disconnects graph |
| **Subpolynomial** | Update time n^o(1), faster than any polynomial |
| **Witness Tree** | Proof structure for cut validity |
| **Cognitive Engine** | SNN-based optimization for cuts |

### Aggregates

#### IncoherenceIsolator (Aggregate Root)

```rust
use ruvector_mincut::{
    SubpolynomialMinCut, SubpolyConfig, MinCutResult, MinCutBuilder,
    CognitiveMinCutEngine, EngineConfig, WitnessTree,
    DynamicGraph, VertexId, Weight,
};

/// Isolates incoherent regions with n^o(1) updates
pub struct IncoherenceIsolator {
    /// Subpolynomial mincut
    mincut: SubpolynomialMinCut,
    /// For SNN-based continuous monitoring
    cognitive: Option<CognitiveMinCutEngine>,
}

impl IncoherenceIsolator {
    /// Build graph from high-energy edges
    pub fn from_energy(energy: &CoherenceEnergy, threshold: f32) -> Self {
        let config = SubpolyConfig::default();
        let mut mincut = SubpolynomialMinCut::new(config);

        for (edge_id, edge_energy) in &energy.edge_energies {
            if *edge_energy > threshold {
                mincut.insert_edge(
                    edge_id.source().into(),
                    edge_id.target().into(),
                    *edge_energy as f64,
                ).ok();
            }
        }

        Self { mincut, cognitive: None }
    }

    /// Find isolation cut
    pub fn isolate(&mut self) -> IsolationResult {
        let result = self.mincut.min_cut();

        IsolationResult {
            cut_value: result.value,
            partition: result.partition,
            cut_edges: result.cut_edges,
            is_exact: result.is_exact,
        }
    }

    /// Dynamic update (amortized n^o(1))
    pub fn update_edge(&mut self, source: u64, target: u64, weight: f64) -> f64 {
        self.mincut.insert_edge(source, target, weight)
            .unwrap_or(self.mincut.min_cut_value())
    }

    /// Enable SNN monitoring
    pub fn enable_cognitive(&mut self, graph: DynamicGraph) {
        self.cognitive = Some(CognitiveMinCutEngine::new(graph, EngineConfig::default()));
    }

    /// Run SNN optimization
    pub fn cognitive_optimize(&mut self, ticks: u32) -> Vec<Spike> {
        self.cognitive.as_mut()
            .map(|c| c.run(ticks))
            .unwrap_or_default()
    }
}
```

---

## Bounded Context 9: Attention-Weighted Coherence (ruvector-attention)

### Purpose

Weights residuals by structural importance using topology-gated attention, MoE routing, and PDE-based diffusion.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **TopologyGatedAttention** | Attention that considers graph structure |
| **MoE** | Mixture of Experts for specialized processing |
| **PDE Attention** | Diffusion-based energy propagation |
| **Flash Attention** | Memory-efficient attention computation |

### Aggregates

#### AttentionWeighter (Aggregate Root)

```rust
use ruvector_attention::{
    TopologyGatedAttention, TopologyGatedConfig, AttentionMode,
    MoEAttention, MoEConfig, Expert, TopKRouting,
    DiffusionAttention, DiffusionConfig, GraphLaplacian,
    FlashAttention, AttentionMask,
};

/// Attention-weighted coherence
pub struct AttentionWeighter {
    /// Topology-gated attention
    topo: TopologyGatedAttention,
    /// MoE for specialized weighting
    moe: MoEAttention,
    /// PDE diffusion
    diffusion: DiffusionAttention,
}

impl AttentionWeighter {
    /// Compute attention scores for nodes
    pub fn compute_scores(&self, states: &[&[f32]]) -> HashMap<NodeId, f32> {
        self.topo.compute_scores(states)
    }

    /// Weight residuals by attention
    pub fn weight_residuals(
        &self,
        residuals: &HashMap<EdgeId, Vec<f32>>,
        attention: &HashMap<NodeId, f32>,
    ) -> HashMap<EdgeId, f32> {
        residuals.iter()
            .map(|(edge_id, r)| {
                let src_attn = attention.get(&edge_id.source()).unwrap_or(&1.0);
                let tgt_attn = attention.get(&edge_id.target()).unwrap_or(&1.0);
                let weight = (src_attn + tgt_attn) / 2.0;

                let norm: f32 = r.iter().map(|x| x * x).sum();
                (*edge_id, norm * weight)
            })
            .collect()
    }

    /// Route through MoE
    pub fn moe_process(&self, residual: &[f32]) -> Vec<f32> {
        self.moe.forward(residual)
    }

    /// Diffuse energy across graph
    pub fn diffuse(&self, energy: &mut CoherenceEnergy, steps: usize) {
        self.diffusion.propagate(energy, steps);
    }
}
```

---

## Bounded Context 10: Distributed Consensus (ruvector-raft)

### Purpose

Synchronizes sheaf state across multiple nodes using Raft consensus for fault-tolerant distributed coherence.

### Ubiquitous Language

| Term | Definition |
|------|------------|
| **Leader** | Node responsible for log replication |
| **Follower** | Node receiving replicated entries |
| **Log Entry** | Serialized graph update |
| **Commit** | Entry replicated to majority |

### Aggregates

#### DistributedSheaf (Aggregate Root)

```rust
use ruvector_raft::{RaftNode, RaftConfig, LogEntry, ConsensusState};

/// Distributed sheaf graph with Raft consensus
pub struct DistributedSheaf {
    /// Local Raft node
    raft: RaftNode,
    /// Local graph copy
    local: SheafGraph,
}

impl DistributedSheaf {
    /// Propose update to cluster
    pub async fn propose(&mut self, update: GraphUpdate) -> Result<(), ConsensusError> {
        let entry = LogEntry::new(bincode::serialize(&update)?);
        self.raft.propose(entry).await
    }

    /// Apply committed entries
    pub fn apply_committed(&mut self) {
        while let Some(entry) = self.raft.next_committed() {
            let update: GraphUpdate = bincode::deserialize(&entry.data).unwrap();
            self.local.apply(update);
        }
    }

    /// Global energy (leader aggregates)
    pub async fn global_energy(&self) -> Result<f32, ConsensusError> {
        if self.raft.is_leader() {
            let local = self.local.compute_energy().total_energy;
            let remote: f32 = self.raft.collect_from_followers(|n| n.local_energy()).await?
                .into_iter().sum();
            Ok(local + remote)
        } else {
            self.raft.forward_to_leader(Query::GlobalEnergy).await
        }
    }
}
```

---

## Cross-Cutting Concerns

### Event Sourcing

All domain events are persisted to the event log for deterministic replay:

```rust
pub struct EventLog {
    storage: PostgresEventStore,
}

impl EventLog {
    /// Append event with signature
    pub async fn append(&self, event: DomainEvent, signer: &Signer) -> Result<SequenceId, Error> {
        let payload = bincode::serialize(&event)?;
        let signature = signer.sign(&payload);

        self.storage.insert(EventRecord {
            event_type: event.event_type(),
            payload,
            signature,
            timestamp: Timestamp::now(),
        }).await
    }

    /// Replay events from a sequence point
    pub async fn replay_from(&self, seq: SequenceId) -> impl Stream<Item = DomainEvent> {
        self.storage.stream_from(seq)
            .map(|record| bincode::deserialize(&record.payload).unwrap())
    }
}
```

### Multi-Tenancy

Isolation at data, policy, and execution boundaries:

```rust
pub struct TenantContext {
    tenant_id: TenantId,
    namespace_prefix: String,
    policy_bundle: PolicyBundleRef,
    resource_limits: ResourceLimits,
}

impl TenantContext {
    /// Scope a graph query to this tenant
    pub fn scope_query(&self, query: Query) -> Query {
        query.with_namespace_prefix(&self.namespace_prefix)
    }
}
```

### Observability

```rust
pub struct CoherenceMetrics {
    /// Energy by scope
    energy_gauge: GaugeVec,
    /// Gate decisions
    gate_decisions: CounterVec,
    /// Computation latency
    compute_latency: HistogramVec,
    /// Witness creation rate
    witness_rate: Counter,
}

impl CoherenceMetrics {
    pub fn record_energy(&self, scope: &ScopeId, energy: f32) {
        self.energy_gauge.with_label_values(&[scope.as_str()]).set(energy as f64);
    }

    pub fn record_gate_decision(&self, lane: ComputeLane, allowed: bool) {
        let labels = [lane.as_str(), if allowed { "allowed" } else { "denied" }];
        self.gate_decisions.with_label_values(&labels).inc();
    }
}
```

---

## Module Structure

```
crates/ruvector-coherence/
├── Cargo.toml
├── README.md
├── src/
│   ├── lib.rs                    # Public API exports
│   │
│   ├── tiles/                    # Tile Fabric (cognitum-gate-kernel)
│   │   ├── mod.rs
│   │   ├── fabric.rs             # TileFabric orchestrator
│   │   ├── adapter.rs            # CoherenceTile adapter
│   │   ├── shard.rs              # Sharding strategy
│   │   └── witness_aggregator.rs # Fragment aggregation
│   │
│   ├── sona_tuning/              # Adaptive Learning (sona)
│   │   ├── mod.rs
│   │   ├── learner.rs            # ThresholdLearner aggregate
│   │   ├── coordinator.rs        # Three-loop coordinator
│   │   └── patterns.rs           # Pattern extraction
│   │
│   ├── neural_gate/              # Neural Gating (ruvector-nervous-system)
│   │   ├── mod.rs
│   │   ├── gate.rs               # NeuralGate adapter
│   │   ├── hdc.rs                # HDC witness encoding
│   │   └── dendrite.rs           # Coincidence detection
│   │
│   ├── learned_rho/              # Learned Restriction (ruvector-gnn)
│   │   ├── mod.rs
│   │   ├── restriction.rs        # LearnedRestriction aggregate
│   │   ├── training.rs           # Training pipeline
│   │   └── ewc.rs                # EWC integration
│   │
│   ├── hyperbolic/               # Hyperbolic Coherence (ruvector-hyperbolic-hnsw)
│   │   ├── mod.rs
│   │   ├── graph.rs              # HyperbolicGraph aggregate
│   │   ├── depth.rs              # Depth computation
│   │   └── weighting.rs          # Hierarchy weighting
│   │
│   ├── mincut/                   # Incoherence Isolation (ruvector-mincut)
│   │   ├── mod.rs
│   │   ├── isolator.rs           # IncoherenceIsolator aggregate
│   │   ├── cognitive.rs          # SNN optimization
│   │   └── witness.rs            # Cut witness
│   │
│   ├── attention/                # Attention Weighting (ruvector-attention)
│   │   ├── mod.rs
│   │   ├── weighter.rs           # AttentionWeighter aggregate
│   │   ├── moe.rs                # MoE routing
│   │   └── diffusion.rs          # PDE propagation
│   │
│   ├── distributed/              # Distributed Consensus (ruvector-raft)
│   │   ├── mod.rs
│   │   ├── sheaf.rs              # DistributedSheaf aggregate
│   │   ├── replication.rs        # Log replication
│   │   └── queries.rs            # Global queries
│   │
│   ├── signal/                   # Signal Ingestion context
│   │   ├── mod.rs
│   │   ├── processor.rs          # SignalProcessor aggregate
│   │   ├── schema.rs             # EventSchema value object
│   │   └── validators.rs         # Validation chain
│   │
│   ├── substrate/                # Knowledge Substrate context
│   │   ├── mod.rs
│   │   ├── graph.rs              # SheafGraph aggregate
│   │   ├── node.rs               # SheafNode entity
│   │   ├── edge.rs               # SheafEdge entity
│   │   ├── restriction.rs        # RestrictionMap value object
│   │   └── repository.rs         # Repository trait
│   │
│   ├── coherence/                # Coherence Computation context
│   │   ├── mod.rs
│   │   ├── engine.rs             # CoherenceEngine aggregate
│   │   ├── energy.rs             # CoherenceEnergy value object
│   │   ├── spectral.rs           # SpectralAnalyzer service
│   │   └── incremental.rs        # Incremental computation
│   │
│   ├── governance/               # Governance context
│   │   ├── mod.rs
│   │   ├── policy.rs             # PolicyBundle aggregate
│   │   ├── witness.rs            # WitnessRecord entity
│   │   ├── lineage.rs            # LineageRecord entity
│   │   └── repository.rs         # Repository traits
│   │
│   ├── execution/                # Action Execution context
│   │   ├── mod.rs
│   │   ├── gate.rs               # CoherenceGate aggregate
│   │   ├── executor.rs           # ActionExecutor service
│   │   ├── action.rs             # Action trait
│   │   └── ladder.rs             # ComputeLane enum
│   │
│   ├── storage/                  # Storage infrastructure
│   │   ├── mod.rs
│   │   ├── postgres.rs           # PostgreSQL implementation
│   │   ├── ruvector.rs           # Ruvector integration
│   │   └── event_log.rs          # Event sourcing
│   │
│   ├── events.rs                 # All domain events
│   ├── error.rs                  # Domain errors
│   └── types.rs                  # Shared types (IDs, timestamps)
│
├── tests/
│   ├── integration/
│   │   ├── tiles_tests.rs        # Tile fabric tests
│   │   ├── sona_tests.rs         # Adaptive learning tests
│   │   ├── neural_tests.rs       # Neural gate tests
│   │   ├── graph_tests.rs
│   │   ├── coherence_tests.rs
│   │   └── governance_tests.rs
│   └── property/
│       ├── coherence_properties.rs
│       ├── hyperbolic_properties.rs
│       └── mincut_properties.rs
│
└── benches/
    ├── tile_bench.rs             # 256-tile throughput
    ├── sona_bench.rs             # Micro-LoRA latency
    ├── mincut_bench.rs           # Subpolynomial verification
    ├── residual_bench.rs
    └── energy_bench.rs
```

### Dependency Graph

```
ruvector-coherence
├── cognitum-gate-kernel     (tiles/)
├── sona                     (sona_tuning/)
├── ruvector-nervous-system  (neural_gate/)
├── ruvector-gnn             (learned_rho/)
├── ruvector-hyperbolic-hnsw (hyperbolic/)
├── ruvector-mincut          (mincut/)
├── ruvector-attention       (attention/)
├── ruvector-raft            (distributed/)
├── ruvector-core            (substrate/, storage/)
└── ruvector-graph           (substrate/)
```

---

## Testing Strategy

### Property-Based Tests

```rust
#[quickcheck]
fn residual_symmetry(graph: ArbitraryGraph) -> bool {
    // r_e for edge (u,v) should be negation of r_e for edge (v,u)
    // when restriction maps are transposed
    for edge in graph.edges() {
        let r_forward = edge.residual(&graph);
        let r_reverse = edge.reversed().residual(&graph);

        if !r_forward.iter().zip(r_reverse.iter())
            .all(|(a, b)| (a + b).abs() < 1e-6) {
            return false;
        }
    }
    true
}

#[quickcheck]
fn energy_non_negative(graph: ArbitraryGraph) -> bool {
    let energy = graph.compute_energy();
    energy.total_energy >= 0.0
}

#[quickcheck]
fn consistent_section_zero_energy(section: ConsistentSection) -> bool {
    // A consistent section (where all nodes agree) should have zero energy
    let graph = section.to_graph();
    let energy = graph.compute_energy();
    energy.total_energy < 1e-6
}
```

### Replay Determinism

```rust
#[test]
fn replay_produces_identical_state() {
    let events = load_event_log("test_events.log");

    // First replay
    let state1 = replay_events(&events);

    // Second replay
    let state2 = replay_events(&events);

    assert_eq!(state1.fingerprint, state2.fingerprint);
    assert_eq!(state1.energy, state2.energy);
}
```

### Chaos Testing

```rust
#[test]
fn throttling_under_chaos() {
    let gate = CoherenceGate::new(test_policy());
    let mut rng = rand::thread_rng();

    for _ in 0..10000 {
        // Random energy spikes
        let energy = if rng.gen_bool(0.1) {
            CoherenceEnergy::random_high(&mut rng)
        } else {
            CoherenceEnergy::random_normal(&mut rng)
        };

        let decision = gate.evaluate(&random_action(), &energy);

        // Verify escalation happens for high energy
        if energy.total_energy > gate.heavy_threshold() {
            assert!(decision.lane >= ComputeLane::Heavy);
        }
    }
}
```

---

## References

1. Evans, E. (2003). "Domain-Driven Design: Tackling Complexity in the Heart of Software."
2. Vernon, V. (2013). "Implementing Domain-Driven Design."
3. Hansen, J., & Ghrist, R. (2019). "Toward a spectral theory of cellular sheaves."
4. Original Architecture Gist: https://gist.github.com/ruvnet/e511e4d7015996d11ab1a1ac6d5876c0