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.

vendor/ruvector/crates/ruQu/docs/ddd/DDD-002-syndrome-processing-domain.md

@@ -0,0 +1,704 @@
+# DDD-002: Syndrome Processing Domain Model
+
+**Status**: Proposed
+**Date**: 2026-01-17
+**Authors**: ruv.io, RuVector Team
+**Related ADR**: ADR-001-ruqu-architecture
+**Related DDD**: DDD-001-coherence-gate-domain
+
+---
+
+## Overview
+
+This document defines the Domain-Driven Design model for the Syndrome Processing subsystem—the high-throughput data pipeline that ingests, buffers, and transforms quantum error syndromes into coherence-relevant signals.
+
+---
+
+## Strategic Design
+
+### Domain Vision Statement
+
+> The Syndrome Processing domain provides reliable, low-latency ingestion and transformation of quantum syndrome data, enabling the Coherence Gate to make real-time structural assessments at microsecond timescales.
+
+### Supporting Domain
+
+Syndrome Processing is a **supporting domain** to the core Coherence Gate domain. It provides:
+
+- Data acquisition infrastructure
+- Buffering and flow control
+- Format transformation
+- Temporal alignment
+
+### Relationship to Core Domain
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    COHERENCE GATE (Core)                        │
+│                                                                 │
+│  Consumes: SyndromeEvents, GraphDeltas                          │
+│  Produces: Decisions, Permits                                   │
+└─────────────────────────────────────────────────────────────────┘
+                              ▲
+                              │ Conforms
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│               SYNDROME PROCESSING (Supporting)                  │
+│                                                                 │
+│  Consumes: RawSyndromes, DetectorMaps                           │
+│  Produces: SyndromeEvents, GraphDeltas                          │
+└─────────────────────────────────────────────────────────────────┘
+                              ▲
+                              │ Upstream
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                  HARDWARE INTERFACE (External)                  │
+│                                                                 │
+│  Produces: RawSyndromes, Timestamps, Status                     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Ubiquitous Language
+
+### Core Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Syndrome** | A binary vector indicating which stabilizer measurements detected errors | Data |
+| **Round** | A complete cycle of syndrome measurements (typically 1μs) | Temporal |
+| **Detector** | A single stabilizer measurement outcome (0 or 1) | Atomic |
+| **Flipped Detector** | A detector that fired (value = 1), indicating potential error | Signal |
+
+### Buffer Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Ring Buffer** | Circular buffer holding recent syndrome rounds | Storage |
+| **Window** | A sliding view over recent rounds for analysis | View |
+| **Watermark** | The oldest round still in the buffer | Temporal |
+| **Backpressure** | Flow control when buffer nears capacity | Control |
+
+### Transform Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Delta** | Change in syndrome state between rounds | Derivative |
+| **Correlation** | Statistical relationship between detector firings | Analysis |
+| **Cluster** | Group of spatially correlated detector firings | Pattern |
+| **Hot Spot** | Region with elevated detector firing rate | Anomaly |
+
+### Graph Integration Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Graph Delta** | Update to operational graph from syndrome analysis | Output |
+| **Edge Weight Update** | Modification to edge weight based on correlations | Output |
+| **Vertex Health Update** | Modification to vertex health based on syndromes | Output |
+
+---
+
+## Bounded Context
+
+### Context Map
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       SYNDROME PROCESSING CONTEXT                           │
+│                          (Supporting Domain)                                │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
+│  │  Ingestion  │  │   Buffer    │  │  Transform  │  │   Publish   │        │
+│  │   Layer     │──│   Layer     │──│   Layer     │──│   Layer     │        │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
+└─────────────────────────────────────────────────────────────────────────────┘
+          ▲                                                   │
+          │ Raw Data                                          │ Events
+          │                                                   ▼
+┌─────────────────┐                                 ┌─────────────────┐
+│    HARDWARE     │                                 │  COHERENCE GATE │
+│    INTERFACE    │                                 │    CONTEXT      │
+└─────────────────┘                                 └─────────────────┘
+```
+
+---
+
+## Aggregates
+
+### SyndromeRound (Root Aggregate)
+
+Represents a complete syndrome measurement cycle.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     SYNDROME ROUND                              │
+│                    (Aggregate Root)                             │
+├─────────────────────────────────────────────────────────────────┤
+│  round_id: RoundId                                              │
+│  cycle: CycleId                                                 │
+│  timestamp: Timestamp (hardware clock)                          │
+│  received_at: Timestamp (local clock)                           │
+│  detectors: DetectorBitmap                                      │
+│  source_tile: TileId                                            │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ DetectorBitmap (Value Object)                           │   │
+│  │  bits: [u64; N]  // Packed detector values              │   │
+│  │  detector_count: usize                                  │   │
+│  │                                                         │   │
+│  │  fn fired_count(&self) -> usize                         │   │
+│  │  fn get(&self, idx: usize) -> bool                      │   │
+│  │  fn iter_fired(&self) -> impl Iterator<Item = usize>    │   │
+│  └─────────────────────────────────────────────────────────┘   │
+├─────────────────────────────────────────────────────────────────┤
+│  Invariants:                                                    │
+│  - round_id unique per tile                                     │
+│  - timestamp monotonically increasing per tile                  │
+│  - detector_count matches configured detector map               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### SyndromeBuffer (Aggregate)
+
+Ring buffer holding recent syndrome history.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     SYNDROME BUFFER                             │
+│                    (Aggregate Root)                             │
+├─────────────────────────────────────────────────────────────────┤
+│  buffer_id: BufferId                                            │
+│  tile_id: TileId                                                │
+│  capacity: usize (typically 1024 rounds)                        │
+│  write_index: usize                                             │
+│  watermark: RoundId                                             │
+│  rounds: CircularArray<SyndromeRound>                           │
+├─────────────────────────────────────────────────────────────────┤
+│  Methods:                                                       │
+│  fn push(&mut self, round: SyndromeRound)                       │
+│  fn window(&self, size: usize) -> &[SyndromeRound]              │
+│  fn get(&self, round_id: RoundId) -> Option<&SyndromeRound>     │
+│  fn statistics(&self) -> BufferStatistics                       │
+├─────────────────────────────────────────────────────────────────┤
+│  Invariants:                                                    │
+│  - capacity fixed at creation                                   │
+│  - watermark ≤ oldest round in buffer                           │
+│  - write_index wraps at capacity                                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### DetectorMap (Aggregate)
+
+Configuration mapping detectors to physical qubits.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      DETECTOR MAP                               │
+│                    (Aggregate Root)                             │
+├─────────────────────────────────────────────────────────────────┤
+│  map_id: MapId                                                  │
+│  version: Version                                               │
+│  detector_count: usize                                          │
+│  mappings: Vec<DetectorMapping>                                 │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ DetectorMapping (Entity)                                │   │
+│  │  detector_idx: usize                                    │   │
+│  │  qubit_ids: Vec<QubitId>   // Qubits in support         │   │
+│  │  detector_type: DetectorType { X | Z | Flag }           │   │
+│  │  coordinates: Option<(f64, f64, f64)>                   │   │
+│  └─────────────────────────────────────────────────────────┘   │
+├─────────────────────────────────────────────────────────────────┤
+│  Methods:                                                       │
+│  fn qubits_for_detector(&self, idx: usize) -> &[QubitId]        │
+│  fn detectors_for_qubit(&self, qubit: QubitId) -> Vec<usize>    │
+│  fn neighbors(&self, idx: usize) -> Vec<usize>                  │
+├─────────────────────────────────────────────────────────────────┤
+│  Invariants:                                                    │
+│  - detector_idx unique                                          │
+│  - All referenced qubits exist in hardware                      │
+│  - Version increments on any change                             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Value Objects
+
+### DetectorBitmap
+
+Efficient packed representation of detector values.
+
+```rust
+struct DetectorBitmap {
+    bits: [u64; 16],  // 1024 detectors max
+    count: usize,
+}
+
+impl DetectorBitmap {
+    fn new(count: usize) -> Self;
+    fn set(&mut self, idx: usize, value: bool);
+    fn get(&self, idx: usize) -> bool;
+    fn fired_count(&self) -> usize;
+    fn iter_fired(&self) -> impl Iterator<Item = usize>;
+    fn xor(&self, other: &DetectorBitmap) -> DetectorBitmap;
+    fn popcount(&self) -> usize;
+}
+```
+
+### SyndromeDelta
+
+Change between consecutive rounds.
+
+```rust
+struct SyndromeDelta {
+    from_round: RoundId,
+    to_round: RoundId,
+    flipped: DetectorBitmap,  // XOR of consecutive rounds
+    new_firings: Vec<usize>,
+    cleared_firings: Vec<usize>,
+}
+
+impl SyndromeDelta {
+    fn is_quiet(&self) -> bool {
+        self.flipped.popcount() == 0
+    }
+
+    fn activity_level(&self) -> f64 {
+        self.flipped.popcount() as f64 / self.flipped.count as f64
+    }
+}
+```
+
+### CorrelationMatrix
+
+Pairwise detector correlations.
+
+```rust
+struct CorrelationMatrix {
+    size: usize,
+    // Packed upper triangle (symmetric)
+    correlations: Vec<f32>,
+}
+
+impl CorrelationMatrix {
+    fn get(&self, i: usize, j: usize) -> f32;
+    fn update(&mut self, i: usize, j: usize, value: f32);
+    fn significant_pairs(&self, threshold: f32) -> Vec<(usize, usize, f32)>;
+}
+```
+
+### DetectorCluster
+
+Group of correlated detectors.
+
+```rust
+struct DetectorCluster {
+    cluster_id: ClusterId,
+    detectors: Vec<usize>,
+    centroid: Option<(f64, f64, f64)>,
+    firing_rate: f64,
+}
+
+impl DetectorCluster {
+    fn size(&self) -> usize;
+    fn is_hot_spot(&self, threshold: f64) -> bool;
+    fn spatial_extent(&self) -> f64;
+}
+```
+
+---
+
+## Domain Events
+
+### Ingestion Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `RoundReceived` | New syndrome arrives | round_id, timestamp, raw_data |
+| `RoundDropped` | Buffer overflow | round_id, reason |
+| `IngestionPaused` | Backpressure | buffer_fill_level |
+| `IngestionResumed` | Buffer drains | buffer_fill_level |
+
+### Buffer Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `BufferFull` | Capacity reached | watermark, oldest_round |
+| `WatermarkAdvanced` | Old data evicted | old_watermark, new_watermark |
+| `WindowExtracted` | Analysis requested | start_round, end_round, size |
+
+### Transform Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `DeltaComputed` | Round processed | delta |
+| `ClusterDetected` | Spatial correlation | cluster |
+| `HotSpotIdentified` | Elevated activity | region, rate, duration |
+| `CorrelationUpdated` | Statistics refresh | matrix_hash |
+
+### Output Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `GraphDeltaPublished` | Transform complete | graph_delta |
+| `SyndromeEventPublished` | For gate consumption | syndrome_event |
+| `StatisticsPublished` | Periodic | statistics |
+
+---
+
+## Domain Services
+
+### SyndromeIngestionService
+
+High-throughput syndrome ingestion.
+
+```rust
+trait SyndromeIngestionService {
+    /// Receive raw syndrome packet from hardware
+    async fn receive(&self, packet: RawSyndromePacket) -> Result<RoundId, IngestError>;
+
+    /// Get current ingestion rate
+    fn throughput(&self) -> f64;
+
+    /// Apply backpressure
+    fn pause(&self);
+    fn resume(&self);
+}
+```
+
+### SyndromeBufferService
+
+Buffer management and windowing.
+
+```rust
+trait SyndromeBufferService {
+    /// Get current buffer for a tile
+    fn buffer(&self, tile: TileId) -> &SyndromeBuffer;
+
+    /// Extract window for analysis
+    fn window(&self, tile: TileId, size: usize) -> Window;
+
+    /// Get statistics
+    fn statistics(&self, tile: TileId) -> BufferStatistics;
+
+    /// Force eviction of old data
+    fn evict(&self, tile: TileId, before: RoundId);
+}
+```
+
+### SyndromeTransformService
+
+Transform syndromes to coherence signals.
+
+```rust
+trait SyndromeTransformService {
+    /// Compute delta between consecutive rounds
+    fn compute_delta(&self, from: &SyndromeRound, to: &SyndromeRound) -> SyndromeDelta;
+
+    /// Update correlation matrix with new round
+    fn update_correlations(&self, round: &SyndromeRound);
+
+    /// Detect clusters in current window
+    fn detect_clusters(&self, window: &Window) -> Vec<DetectorCluster>;
+
+    /// Generate graph delta from syndrome analysis
+    fn to_graph_delta(&self, delta: &SyndromeDelta, clusters: &[DetectorCluster]) -> GraphDelta;
+}
+```
+
+### SyndromePublishService
+
+Publish events to Coherence Gate context.
+
+```rust
+trait SyndromePublishService {
+    /// Publish syndrome event
+    async fn publish_syndrome(&self, event: SyndromeEvent);
+
+    /// Publish graph delta
+    async fn publish_graph_delta(&self, delta: GraphDelta);
+
+    /// Publish statistics
+    async fn publish_statistics(&self, stats: SyndromeStatistics);
+}
+```
+
+---
+
+## Repositories
+
+### SyndromeRoundRepository
+
+```rust
+trait SyndromeRoundRepository {
+    /// Store round (typically in ring buffer)
+    fn store(&self, round: SyndromeRound);
+
+    /// Find by round ID
+    fn find_by_id(&self, id: RoundId) -> Option<&SyndromeRound>;
+
+    /// Find rounds in range
+    fn find_in_range(&self, start: RoundId, end: RoundId) -> Vec<&SyndromeRound>;
+
+    /// Get most recent N rounds
+    fn recent(&self, n: usize) -> Vec<&SyndromeRound>;
+}
+```
+
+### DetectorMapRepository
+
+```rust
+trait DetectorMapRepository {
+    /// Get current detector map
+    fn current(&self) -> &DetectorMap;
+
+    /// Get map at specific version
+    fn at_version(&self, version: Version) -> Option<&DetectorMap>;
+
+    /// Update map
+    fn update(&self, map: DetectorMap) -> Result<(), UpdateError>;
+}
+```
+
+### CorrelationRepository
+
+```rust
+trait CorrelationRepository {
+    /// Get current correlation matrix
+    fn current(&self) -> &CorrelationMatrix;
+
+    /// Update correlation
+    fn update(&self, i: usize, j: usize, value: f32);
+
+    /// Get historical snapshot
+    fn snapshot_at(&self, round: RoundId) -> Option<&CorrelationMatrix>;
+}
+```
+
+---
+
+## Processing Pipeline
+
+### Pipeline Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         SYNDROME PROCESSING PIPELINE                        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐             │
+│  │  Receive  │──▶│  Decode   │──▶│   Store   │──▶│  Window   │             │
+│  │   (DMA)   │   │  (Unpack) │   │  (Ring)   │   │ (Extract) │             │
+│  └───────────┘   └───────────┘   └───────────┘   └───────────┘             │
+│       50ns           100ns           50ns           50ns                    │
+│                                                                             │
+│                                        │                                    │
+│                                        ▼                                    │
+│  ┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐             │
+│  │  Publish  │◀──│   Graph   │◀──│  Cluster  │◀──│   Delta   │             │
+│  │  (Event)  │   │  (Update) │   │  (Find)   │   │ (Compute) │             │
+│  └───────────┘   └───────────┘   └───────────┘   └───────────┘             │
+│       50ns           100ns          200ns           100ns                   │
+│                                                                             │
+│  Total Pipeline Latency: ~700ns                                             │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Stage Details
+
+#### Stage 1: Receive
+- DMA transfer from hardware
+- CRC validation
+- Timestamp extraction
+
+#### Stage 2: Decode
+- Unpack compressed syndrome format
+- Map to detector indices
+- Validate against detector map
+
+#### Stage 3: Store
+- Append to ring buffer
+- Handle buffer wrap
+- Evict old entries if needed
+
+#### Stage 4: Window
+- Extract sliding window
+- Compute running statistics
+- Prepare for analysis
+
+#### Stage 5: Delta
+- XOR consecutive rounds
+- Identify new/cleared firings
+- Calculate activity level
+
+#### Stage 6: Cluster
+- Spatial clustering of firings
+- Identify hot spots
+- Track cluster evolution
+
+#### Stage 7: Graph Update
+- Map clusters to graph regions
+- Compute edge weight updates
+- Compute vertex health updates
+
+#### Stage 8: Publish
+- Emit SyndromeEvent
+- Emit GraphDelta
+- Update statistics
+
+---
+
+## Memory Layout
+
+### Per-Tile Memory Budget (16 KB for Syndrome Processing)
+
+```
+0x8000 - 0xBFFF : Syndrome Ring Buffer (16 KB)
+  ├── 0x8000 - 0x800F : Buffer metadata (16 bytes)
+  │     write_index: u32
+  │     watermark: u32
+  │     capacity: u32
+  │     flags: u32
+  │
+  ├── 0x8010 - 0xBFEF : Round storage (16,352 bytes)
+  │     1024 rounds × 16 bytes per round
+  │     Each round:
+  │       round_id: u32
+  │       timestamp: u32
+  │       detector_bitmap: [u8; 8] (64 detectors per tile)
+  │
+  └── 0xBFF0 - 0xBFFF : Statistics cache (16 bytes)
+        firing_rate: f32
+        activity_mean: f32
+        activity_variance: f32
+        padding: u32
+```
+
+### Published Language (to Coherence Gate)
+
+```rust
+/// Event published to Coherence Gate context
+struct SyndromeEvent {
+    round_id: RoundId,
+    tile_id: TileId,
+    timestamp: Timestamp,
+    activity_level: f64,
+    hot_spots: Vec<HotSpot>,
+    delta_summary: DeltaSummary,
+}
+
+/// Graph update derived from syndrome analysis
+struct GraphDelta {
+    source_round: RoundId,
+    vertex_updates: Vec<VertexUpdate>,
+    edge_updates: Vec<EdgeUpdate>,
+}
+
+struct VertexUpdate {
+    vertex_id: VertexId,
+    health_delta: f64,
+}
+
+struct EdgeUpdate {
+    edge_id: EdgeId,
+    weight_delta: f64,
+}
+```
+
+---
+
+## Invariants and Business Rules
+
+### Ingestion Invariants
+
+1. **Temporal Ordering**: Rounds must arrive in timestamp order per tile
+2. **No Gaps**: Round IDs must be consecutive (gaps indicate data loss)
+3. **CRC Validity**: Invalid CRCs cause round rejection
+4. **Rate Bounded**: Ingestion rate ≤ 1M rounds/second
+
+### Buffer Invariants
+
+1. **Fixed Capacity**: Buffer size constant after creation
+2. **FIFO Ordering**: Oldest data evicted first
+3. **Watermark Monotonicity**: Watermark only advances
+4. **Window Containment**: Window must be within buffer
+
+### Transform Invariants
+
+1. **Deterministic**: Same input always produces same output
+2. **Bounded Latency**: Transform ≤ 500ns
+3. **Conservation**: Delta popcount ≤ sum of round popcounts
+
+---
+
+## Integration Patterns
+
+### Published Language
+
+The Syndrome Processing context publishes a well-defined language consumed by Coherence Gate:
+
+```rust
+// The contract between Syndrome Processing and Coherence Gate
+mod syndrome_events {
+    pub struct SyndromeEvent { /* ... */ }
+    pub struct GraphDelta { /* ... */ }
+    pub struct SyndromeStatistics { /* ... */ }
+}
+```
+
+### Conformist Pattern
+
+Syndrome Processing conforms to Coherence Gate's needs:
+
+- Event format defined by consumer
+- Latency requirements set by consumer
+- Graph delta structure matches gate's graph model
+
+### Anticorruption Layer (ACL)
+
+Between Hardware Interface and Syndrome Processing:
+
+```rust
+impl HardwareAcl {
+    /// Translate hardware-specific format to domain model
+    fn translate(&self, raw: HardwarePacket) -> Result<SyndromeRound, AclError> {
+        SyndromeRound {
+            round_id: self.extract_round_id(raw),
+            cycle: self.extract_cycle(raw),
+            timestamp: self.normalize_timestamp(raw),
+            detectors: self.unpack_detectors(raw),
+            source_tile: self.identify_tile(raw),
+        }
+    }
+}
+```
+
+---
+
+## Performance Considerations
+
+### Throughput Requirements
+
+| Metric | Target | Rationale |
+|--------|--------|-----------|
+| Ingestion rate | 1M rounds/sec | 1 MHz syndrome rate |
+| Buffer depth | 1024 rounds | 1ms history at 1MHz |
+| Transform latency | ≤ 500ns | Leave margin for gate |
+| Memory per tile | 16 KB | Fits in FPGA BRAM |
+
+### Optimization Strategies
+
+1. **SIMD for bitmap operations**: Use AVX2/NEON for XOR, popcount
+2. **Zero-copy ring buffer**: Avoid allocation on hot path
+3. **Incremental correlation**: Update only changed pairs
+4. **Lazy clustering**: Only cluster when activity exceeds threshold
+
+---
+
+## References
+
+- DDD-001: Coherence Gate Domain Model
+- ADR-001: ruQu Architecture
+- Stim: Quantum Error Correction Simulator
+- Google Cirq: Detector Annotation Format