Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/crates/ruQu/docs/ddd/DDD-001-coherence-gate-domain.md

@@ -0,0 +1,562 @@
+# DDD-001: Coherence Gate Domain Model
+
+**Status**: Proposed
+**Date**: 2026-01-17
+**Authors**: ruv.io, RuVector Team
+**Related ADR**: ADR-001-ruqu-architecture
+
+---
+
+## Overview
+
+This document defines the Domain-Driven Design model for the Coherence Gate—the core decision-making subsystem that determines whether a quantum system region is coherent enough to trust action.
+
+---
+
+## Strategic Design
+
+### Domain Vision Statement
+
+> The Coherence Gate domain provides real-time, microsecond-scale structural awareness of quantum system health, enabling adaptive control decisions that were previously impossible with static policies.
+
+### Core Domain
+
+**Coherence Assessment** is the core domain. This is what differentiates ruQu from all other quantum control approaches:
+
+- Not decoding (that's a supporting domain)
+- Not syndrome collection (that's infrastructure)
+- **The novel capability**: Answering "Is this region still internally consistent enough to trust action?"
+
+### Supporting Domains
+
+| Domain | Role | Boundary |
+|--------|------|----------|
+| **Syndrome Ingestion** | Collect and buffer syndrome data | Generic, infrastructure |
+| **Graph Maintenance** | Keep operational graph current | Generic, infrastructure |
+| **Cryptographic Receipts** | Audit trail and permits | Generic, security |
+| **Decoder Integration** | Apply corrections | External, existing |
+
+### Generic Subdomains
+
+- Logging and observability
+- Configuration management
+- Communication protocols
+
+---
+
+## Ubiquitous Language
+
+### Core Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Coherence** | The property of a quantum system region being internally consistent and operationally trustworthy | Domain core |
+| **Gate Decision** | The output of coherence assessment: PERMIT, DEFER, or DENY | Domain core |
+| **Permit Token** | A signed capability authorizing action on a coherent region | Domain core |
+| **Witness** | Cryptographic proof of the graph state at decision time | Domain core |
+| **Quarantine** | Isolation of an incoherent region from action | Domain core |
+
+### Structural Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Operational Graph** | A weighted graph capturing all elements affecting coherence | Model |
+| **Min-Cut** | The minimum weight of edges separating healthy from unhealthy partitions | Algorithm |
+| **Cut Value** | Numeric measure of structural fragility—low value means boundary forming | Metric |
+| **Boundary** | The set of edges in the min-cut, identifying the fracture point | Diagnostic |
+
+### Statistical Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Shift** | Aggregate nonconformity indicating distribution drift | Filter 2 |
+| **E-Value** | Running evidence accumulator for anytime-valid testing | Filter 3 |
+| **Threshold** | Decision boundary for each filter | Configuration |
+
+### Architectural Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Tile** | A processing unit handling a graph shard | Architecture |
+| **TileZero** | The coordinator tile that merges reports and makes global decisions | Architecture |
+| **Worker Tile** | One of 255 tiles processing local graph shards | Architecture |
+| **Fabric** | The full 256-tile processing array | Architecture |
+
+---
+
+## Bounded Contexts
+
+### Context Map
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           COHERENCE GATE CONTEXT                            │
+│                              (Core Domain)                                  │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
+│  │  Decision   │  │   Filter    │  │   Graph     │  │   Permit    │        │
+│  │   Engine    │  │  Pipeline   │  │   Model     │  │   Manager   │        │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
+└─────────────────────────────────────────────────────────────────────────────┘
+          │                 │                 │                 │
+          │ Upstream        │ Upstream        │ Upstream        │ Downstream
+          ▼                 ▼                 ▼                 ▼
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+│    SYNDROME     │ │   CALIBRATION   │ │    HARDWARE     │ │    DECODER      │
+│    CONTEXT      │ │    CONTEXT      │ │    CONTEXT      │ │    CONTEXT      │
+│  (Supporting)   │ │  (Supporting)   │ │   (External)    │ │   (External)    │
+└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
+```
+
+### Coherence Gate Context (Core)
+
+**Responsibility**: Make coherence decisions and issue permits
+
+**Key Aggregates**:
+- GateDecision
+- PermitToken
+- CoherenceState
+
+**Anti-Corruption Layers**:
+- Syndrome Adapter (translates raw syndromes to events)
+- Hardware Adapter (translates hardware state to graph updates)
+- Decoder Adapter (translates decisions to decoder commands)
+
+### Syndrome Context (Supporting)
+
+**Responsibility**: Collect, buffer, and deliver syndrome streams
+
+**Key Aggregates**:
+- SyndromeRound
+- SyndromeBuffer
+- DetectorMap
+
+**Relationship**: Conforms to Coherence Gate Context
+
+### Calibration Context (Supporting)
+
+**Responsibility**: Manage calibration state and trigger recalibration
+
+**Key Aggregates**:
+- CalibrationSnapshot
+- DriftIndicator
+- CalibrationTrigger
+
+**Relationship**: Customer-Supplier with Coherence Gate Context
+
+---
+
+## Aggregates
+
+### GateDecision (Root Aggregate)
+
+The central aggregate representing a coherence assessment outcome.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      GATE DECISION                              │
+│                    (Aggregate Root)                             │
+├─────────────────────────────────────────────────────────────────┤
+│  decision_id: DecisionId                                        │
+│  timestamp: Timestamp                                           │
+│  verdict: Verdict { Permit | Defer | Deny }                     │
+│  region_mask: RegionMask                                        │
+│  filter_results: FilterResults                                  │
+│  witness: Option<Witness>                                       │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ FilterResults (Value Object)                            │   │
+│  │  structural: StructuralResult { cut_value, boundary }   │   │
+│  │  shift: ShiftResult { pressure, affected_regions }      │   │
+│  │  evidence: EvidenceResult { e_value, confidence }       │   │
+│  └─────────────────────────────────────────────────────────┘   │
+├─────────────────────────────────────────────────────────────────┤
+│  Invariants:                                                    │
+│  - All three filters must be evaluated                          │
+│  - PERMIT requires all filters pass                             │
+│  - DENY requires at least one filter hard-fail                  │
+│  - Witness required for DENY decisions                          │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### PermitToken (Aggregate)
+
+A signed capability authorizing action.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      PERMIT TOKEN                               │
+│                    (Aggregate Root)                             │
+├─────────────────────────────────────────────────────────────────┤
+│  token_id: TokenId                                              │
+│  decision_id: DecisionId                                        │
+│  action_id: ActionId                                            │
+│  region_mask: RegionMask                                        │
+│  issued_at: Timestamp                                           │
+│  expires_at: Timestamp                                          │
+│  signature: Ed25519Signature                                    │
+│  witness_hash: Blake3Hash                                       │
+├─────────────────────────────────────────────────────────────────┤
+│  Invariants:                                                    │
+│  - Signature must be valid Ed25519 (64 bytes)                   │
+│  - expires_at > issued_at                                       │
+│  - TTL bounded by configuration                                 │
+│  - witness_hash matches decision witness                        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### OperationalGraph (Aggregate)
+
+The graph model of system coherence.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                   OPERATIONAL GRAPH                             │
+│                    (Aggregate Root)                             │
+├─────────────────────────────────────────────────────────────────┤
+│  graph_id: GraphId                                              │
+│  version: Version (monotonic)                                   │
+│  vertices: Map<VertexId, Vertex>                                │
+│  edges: Map<EdgeId, Edge>                                       │
+│  partitions: Map<PartitionId, Partition>                        │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ Vertex (Entity)                                         │   │
+│  │  vertex_id: VertexId                                    │   │
+│  │  vertex_type: VertexType { Qubit | Coupler | ... }      │   │
+│  │  health_state: HealthState { Healthy | Degraded | ... } │   │
+│  │  metadata: VertexMetadata                               │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ Edge (Entity)                                           │   │
+│  │  edge_id: EdgeId                                        │   │
+│  │  source: VertexId                                       │   │
+│  │  target: VertexId                                       │   │
+│  │  weight: EdgeWeight (coherence coupling strength)       │   │
+│  │  edge_type: EdgeType { Coupling | Crosstalk | ... }     │   │
+│  └─────────────────────────────────────────────────────────┘   │
+├─────────────────────────────────────────────────────────────────┤
+│  Invariants:                                                    │
+│  - Version only increases                                       │
+│  - No orphan vertices (all must be reachable)                   │
+│  - Edge weights non-negative                                    │
+│  - Partition assignment complete (every vertex in one partition)│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Value Objects
+
+### RegionMask
+
+Identifies which regions are affected by a decision.
+
+```rust
+struct RegionMask {
+    bits: u256,  // One bit per tile (256 tiles)
+}
+
+impl RegionMask {
+    fn all() -> Self;
+    fn none() -> Self;
+    fn from_tiles(tiles: &[TileId]) -> Self;
+    fn intersects(&self, other: &RegionMask) -> bool;
+    fn union(&self, other: &RegionMask) -> RegionMask;
+}
+```
+
+### Verdict
+
+The three-valued decision outcome.
+
+```rust
+enum Verdict {
+    Permit,  // Action authorized
+    Defer,   // Needs human review
+    Deny,    // Action blocked
+}
+```
+
+### CutValue
+
+The min-cut metric with its interpretation.
+
+```rust
+struct CutValue {
+    value: f64,
+    threshold: f64,
+    boundary_edges: Vec<EdgeId>,
+}
+
+impl CutValue {
+    fn is_coherent(&self) -> bool {
+        self.value >= self.threshold
+    }
+
+    fn fragility(&self) -> f64 {
+        self.threshold / self.value.max(0.001)
+    }
+}
+```
+
+### EvidenceAccumulator
+
+Running e-value with anytime-valid properties.
+
+```rust
+struct EvidenceAccumulator {
+    log_e_value: f64,
+    samples_seen: u64,
+    wealth_sequence: VecDeque<f64>,
+}
+
+impl EvidenceAccumulator {
+    fn update(&mut self, score: f64);
+    fn current_e(&self) -> f64;
+    fn verdict(&self, tau_permit: f64, tau_deny: f64) -> Option<Verdict>;
+}
+```
+
+---
+
+## Domain Events
+
+### Core Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `CoherenceAssessed` | Every cycle | decision_id, verdict, filter_results |
+| `PermitIssued` | PERMIT decision | token, action_id, region_mask |
+| `QuarantineInitiated` | DENY decision | region_mask, witness, recovery_mode |
+| `DeferEscalated` | DEFER decision | decision_id, reason, suggested_reviewer |
+
+### Graph Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `GraphUpdated` | Syndrome arrival | version, delta |
+| `VertexDegraded` | Health change | vertex_id, old_state, new_state |
+| `EdgeWeightChanged` | Coupling drift | edge_id, old_weight, new_weight |
+| `PartitionSplit` | Cut detected | old_partition, new_partitions |
+
+### Filter Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `StructuralBoundaryForming` | Cut dropping | cut_value, boundary_edges, trend |
+| `ShiftPressureRising` | Drift detected | shift_value, affected_regions |
+| `EvidenceThresholdCrossed` | E-value crosses τ | e_value, direction, decision |
+
+---
+
+## Domain Services
+
+### CoherenceGateService
+
+The orchestrating service that runs the three-filter pipeline.
+
+```rust
+trait CoherenceGateService {
+    /// Evaluate coherence for the current cycle
+    async fn evaluate(&self, cycle: CycleId) -> GateDecision;
+
+    /// Issue a permit token for an action
+    async fn issue_permit(&self, action: ActionContext) -> Result<PermitToken, GateError>;
+
+    /// Verify a permit token
+    fn verify_permit(&self, token: &PermitToken) -> Result<(), VerifyError>;
+
+    /// Get current coherence state
+    fn current_state(&self) -> CoherenceState;
+}
+```
+
+### FilterPipelineService
+
+Runs the three stacked filters.
+
+```rust
+trait FilterPipelineService {
+    /// Run structural filter (min-cut)
+    fn evaluate_structural(&self, graph: &OperationalGraph) -> StructuralResult;
+
+    /// Run shift filter (conformal)
+    fn evaluate_shift(&self, syndromes: &SyndromeBuffer) -> ShiftResult;
+
+    /// Run evidence filter (e-value)
+    fn evaluate_evidence(&self, accumulator: &EvidenceAccumulator) -> EvidenceResult;
+
+    /// Combine filter results into verdict
+    fn combine(&self, structural: StructuralResult, shift: ShiftResult, evidence: EvidenceResult) -> Verdict;
+}
+```
+
+### WitnessService
+
+Generates cryptographic witnesses for decisions.
+
+```rust
+trait WitnessService {
+    /// Generate witness for current graph state
+    fn generate(&self, graph: &OperationalGraph, decision: &GateDecision) -> Witness;
+
+    /// Verify witness against historical state
+    fn verify(&self, witness: &Witness, receipt_chain: &ReceiptChain) -> Result<(), WitnessError>;
+}
+```
+
+---
+
+## Repositories
+
+### GateDecisionRepository
+
+```rust
+trait GateDecisionRepository {
+    async fn store(&self, decision: GateDecision) -> Result<(), StoreError>;
+    async fn find_by_id(&self, id: DecisionId) -> Option<GateDecision>;
+    async fn find_by_cycle(&self, cycle: CycleId) -> Option<GateDecision>;
+    async fn find_in_range(&self, start: CycleId, end: CycleId) -> Vec<GateDecision>;
+}
+```
+
+### PermitTokenRepository
+
+```rust
+trait PermitTokenRepository {
+    async fn store(&self, token: PermitToken) -> Result<(), StoreError>;
+    async fn find_by_id(&self, id: TokenId) -> Option<PermitToken>;
+    async fn find_active(&self) -> Vec<PermitToken>;
+    async fn revoke(&self, id: TokenId) -> Result<(), RevokeError>;
+}
+```
+
+### OperationalGraphRepository
+
+```rust
+trait OperationalGraphRepository {
+    async fn current(&self) -> OperationalGraph;
+    async fn at_version(&self, version: Version) -> Option<OperationalGraph>;
+    async fn apply_delta(&self, delta: GraphDelta) -> Result<Version, ApplyError>;
+}
+```
+
+---
+
+## Factories
+
+### GateDecisionFactory
+
+```rust
+impl GateDecisionFactory {
+    fn create_permit(
+        filter_results: FilterResults,
+        region_mask: RegionMask,
+    ) -> GateDecision {
+        GateDecision {
+            decision_id: DecisionId::new(),
+            timestamp: Timestamp::now(),
+            verdict: Verdict::Permit,
+            region_mask,
+            filter_results,
+            witness: None,
+        }
+    }
+
+    fn create_deny(
+        filter_results: FilterResults,
+        region_mask: RegionMask,
+        boundary: Vec<EdgeId>,
+    ) -> GateDecision {
+        let witness = WitnessService::generate_for_boundary(&boundary);
+        GateDecision {
+            decision_id: DecisionId::new(),
+            timestamp: Timestamp::now(),
+            verdict: Verdict::Deny,
+            region_mask,
+            filter_results,
+            witness: Some(witness),
+        }
+    }
+}
+```
+
+---
+
+## Invariants and Business Rules
+
+### Decision Invariants
+
+1. **Three-Filter Agreement**: PERMIT requires all three filters to pass
+2. **Witness on Deny**: Every DENY decision must have a witness
+3. **Monotonic Sequence**: Decision sequence numbers only increase
+4. **Bounded Latency**: Decision must complete within 4μs budget
+
+### Token Invariants
+
+1. **Valid Signature**: Token signature must verify with TileZero public key
+2. **Temporal Validity**: Token only valid between issued_at and expires_at
+3. **Region Consistency**: Token region_mask must match decision region_mask
+4. **Single Use**: Token action_id must be unique (no replay)
+
+### Graph Invariants
+
+1. **Version Monotonicity**: Graph version only increases
+2. **Edge Consistency**: Edges reference valid vertices
+3. **Partition Completeness**: Every vertex belongs to exactly one partition
+4. **Weight Non-Negativity**: All edge weights ≥ 0
+
+---
+
+## Anti-Corruption Layers
+
+### Syndrome ACL
+
+Translates raw hardware syndromes to domain events.
+
+```rust
+impl SyndromeAntiCorruptionLayer {
+    fn translate(&self, raw: RawSyndromePacket) -> SyndromeEvent {
+        SyndromeEvent {
+            round: self.extract_round(raw),
+            detectors: self.decode_detectors(raw),
+            timestamp: self.normalize_timestamp(raw),
+        }
+    }
+}
+```
+
+### Decoder ACL
+
+Translates gate decisions to decoder commands.
+
+```rust
+impl DecoderAntiCorruptionLayer {
+    fn translate(&self, decision: &GateDecision) -> DecoderCommand {
+        match decision.verdict {
+            Verdict::Permit => DecoderCommand::NormalMode,
+            Verdict::Defer => DecoderCommand::ConservativeMode,
+            Verdict::Deny => DecoderCommand::Pause(decision.region_mask),
+        }
+    }
+}
+```
+
+---
+
+## Context Boundaries Summary
+
+| Boundary | Upstream | Downstream | Integration Pattern |
+|----------|----------|------------|---------------------|
+| Syndrome → Gate | Syndrome Context | Gate Context | Published Language (SyndromeEvent) |
+| Gate → Decoder | Gate Context | Decoder Context | ACL (DecoderCommand) |
+| Gate → Calibration | Gate Context | Calibration Context | Domain Events (DriftDetected) |
+| Hardware → Gate | Hardware Context | Gate Context | ACL (GraphDelta) |
+
+---
+
+## References
+
+- ADR-001: ruQu Architecture
+- Evans, Eric. "Domain-Driven Design." Addison-Wesley, 2003.
+- Vernon, Vaughn. "Implementing Domain-Driven Design." Addison-Wesley, 2013.