dearsky/wifi-densepose

Fork 0

Files

ruv cd5943df23 Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

2026-02-28 14:39:40 -05:00

22 KiB

Raw Blame History

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.

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.

enum Verdict {
    Permit,  // Action authorized
    Defer,   // Needs human review
    Deny,    // Action blocked
}

CutValue

The min-cut metric with its interpretation.

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.

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.

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.

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.

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

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

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

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

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

Three-Filter Agreement: PERMIT requires all three filters to pass
Witness on Deny: Every DENY decision must have a witness
Monotonic Sequence: Decision sequence numbers only increase
Bounded Latency: Decision must complete within 4μs budget

Token Invariants

Valid Signature: Token signature must verify with TileZero public key
Temporal Validity: Token only valid between issued_at and expires_at
Region Consistency: Token region_mask must match decision region_mask
Single Use: Token action_id must be unique (no replay)

Graph Invariants

Version Monotonicity: Graph version only increases
Edge Consistency: Edges reference valid vertices
Partition Completeness: Every vertex belongs to exactly one partition
Weight Non-Negativity: All edge weights ≥ 0

Anti-Corruption Layers

Syndrome ACL

Translates raw hardware syndromes to domain events.

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.

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.

22 KiB Raw Blame History

DDD-001: Coherence Gate Domain Model

Overview

Strategic Design

Domain Vision Statement

Core Domain

Supporting Domains

Generic Subdomains

Ubiquitous Language

Core Terms

Structural Terms

Statistical Terms

Architectural Terms

Bounded Contexts

Context Map

Coherence Gate Context (Core)

Syndrome Context (Supporting)

Calibration Context (Supporting)

Aggregates

GateDecision (Root Aggregate)

PermitToken (Aggregate)

OperationalGraph (Aggregate)

Value Objects

RegionMask

Verdict

CutValue

EvidenceAccumulator

Domain Events

Core Events

Graph Events

Filter Events

Domain Services

CoherenceGateService

FilterPipelineService

WitnessService

Repositories

GateDecisionRepository

PermitTokenRepository

OperationalGraphRepository

Factories

GateDecisionFactory

Invariants and Business Rules

Decision Invariants

Token Invariants

Graph Invariants

Anti-Corruption Layers

Syndrome ACL

Decoder ACL

Context Boundaries Summary

References

22 KiB

Raw Blame History