Files
wifi-densepose/vendor/ruvector/docs/architecture/quantum-engine/quantum-engine-ddd-integration.md

33 KiB

Quantum Simulation Engine: Domain-Driven Design - Integration Patterns

Version: 0.1 Date: 2026-02-06 Status: Draft


Overview

This document defines the cross-domain integration patterns, anti-corruption layers, shared kernel, and context mapping that connect the quantum simulation engine (ruqu-core, ruqu-algorithms, ruqu-wasm) to the existing ruVector subsystems. It specifies how the simulation domain communicates with the coherence engine, agent system, graph database, and WASM platform without contaminating bounded context boundaries.


Context Map

+-------------------------------------------------------------------+
|                         CONTEXT MAP                                |
|                                                                    |
|  +--------------------+     Shared Kernel     +------------------+ |
|  |                    |<----(ruvector-math)--->|                  | |
|  |  Quantum Sim       |                       |  Coherence       | |
|  |  Engine             |                       |  Engine          | |
|  |  (ruqu-core,        |    Anti-Corruption    |  (ruvector-      | |
|  |   ruqu-algorithms)  |<----(CoherenceBridge) |   coherence)     | |
|  |                    |                       |                  | |
|  +--------+-----------+                       +------------------+ |
|           |                                          ^             |
|           | Customer-Supplier                        |             |
|           v                                          |             |
|  +--------------------+                    +---------+--------+   |
|  |                    |    Partnership     |                  |   |
|  |  Agent System      |<----------------->|  Graph Database  |   |
|  |  (claude-flow)     |                   |  (ruvector-graph)|   |
|  |                    |                   |                  |   |
|  +--------------------+                   +------------------+   |
|           |                                                       |
|           | Conformist                                            |
|           v                                                       |
|  +--------------------+     Published Language                    |
|  |                    |<----(OpenQASM 3.0)                       |
|  |  WASM Platform     |                                          |
|  |  (ruqu-wasm)       |                                          |
|  |                    |                                          |
|  +--------------------+                                          |
+-------------------------------------------------------------------+

Relationship Summary

Upstream Downstream Pattern Shared Artifact
Quantum Engine Coherence Engine Anti-Corruption Layer CoherenceBridge trait
ruvector-math Quantum Engine, Coherence Engine Shared Kernel Complex<f64>, SIMD traits
Quantum Engine Agent System Customer-Supplier SimulationContract
ruvector-graph Quantum Engine Partnership Adjacency structures
External tools Quantum Engine Published Language OpenQASM 3.0
WASM platform ruqu-wasm Conformist WASM constraints accepted

1. Anti-Corruption Layer: Coherence Bridge

The Coherence Bridge translates between the quantum simulation domain language and the ruQu coherence domain. It prevents internal types from either domain from leaking into the other.

Purpose

  • Map syndrome bitstrings produced by surface code experiments into the SyndromeFilter input format expected by the coherence engine
  • Map decoder correction outputs (Pauli operators) to gate operations the simulation can apply
  • Translate coherence scores into the CoherenceScore value object used by simulation sessions
  • Isolate the quantum simulation engine from changes in the coherence engine's internal API

Interface

/// Anti-corruption layer between quantum simulation and coherence engine.
///
/// All translation between bounded contexts passes through this trait.
/// Neither domain's internal types appear on the wrong side of this boundary.
pub trait CoherenceBridge: Send + Sync {
    /// Translate a quantum syndrome into a coherence engine filter input.
    ///
    /// The simulation produces `SyndromeBits`; the coherence engine expects
    /// `DetectorBitmap` with specific tile routing. This method handles the
    /// mapping, including stabilizer-to-detector index translation.
    fn syndrome_to_filter_input(
        &self,
        syndrome: &SyndromeBits,
        code_distance: u32,
    ) -> Result<CoherenceFilterInput, BridgeError>;

    /// Translate a coherence decoder correction into Pauli gate operations.
    ///
    /// The coherence engine's decoder outputs correction vectors in its own
    /// format. This method maps them to `PauliOp` sequences that the
    /// simulation engine can apply as gate operations.
    fn correction_to_pauli_ops(
        &self,
        correction: &CoherenceCorrectionOutput,
    ) -> Result<Vec<(QubitIndex, PauliOp)>, BridgeError>;

    /// Query the current coherence score for a simulation region.
    ///
    /// Returns a domain-native `CoherenceScore` value object, hiding
    /// the coherence engine's internal energy representation.
    fn query_coherence_score(
        &self,
        region_id: &str,
    ) -> Result<CoherenceScore, BridgeError>;

    /// Submit simulation metrics to the coherence monitoring system.
    ///
    /// Translates `SimulationMetrics` into the coherence engine's
    /// signal ingestion format without exposing internal types.
    fn report_simulation_metrics(
        &self,
        session_id: &str,
        metrics: &SimulationMetrics,
    ) -> Result<(), BridgeError>;
}

/// Opaque input type for the coherence filter (ACL boundary type).
pub struct CoherenceFilterInput {
    pub detector_bitmap: Vec<u64>,
    pub tile_id: u8,
    pub round_id: u64,
}

/// Opaque output type from the coherence decoder (ACL boundary type).
pub struct CoherenceCorrectionOutput {
    pub corrections: Vec<(u32, u8)>,  // (qubit_index, pauli_code)
    pub confidence: f64,
}

/// Errors specific to the bridge translation layer.
#[derive(Debug, thiserror::Error)]
pub enum BridgeError {
    #[error("syndrome dimension mismatch: expected {expected}, got {actual}")]
    SyndromeDimensionMismatch { expected: usize, actual: usize },

    #[error("unknown correction code: {0}")]
    UnknownCorrectionCode(u8),

    #[error("coherence engine unavailable: {0}")]
    CoherenceUnavailable(String),

    #[error("tile routing failed for code distance {0}")]
    TileRoutingFailed(u32),
}

Implementation Sketch

/// Production implementation backed by the ruQu coherence engine.
pub struct RuQuCoherenceBridge {
    /// Reference to the coherence engine's filter pipeline.
    filter_pipeline: Arc<dyn FilterPipelineAccess>,
    /// Stabilizer-to-detector mapping, precomputed per code distance.
    detector_maps: HashMap<u32, StabilizerDetectorMap>,
}

impl CoherenceBridge for RuQuCoherenceBridge {
    fn syndrome_to_filter_input(
        &self,
        syndrome: &SyndromeBits,
        code_distance: u32,
    ) -> Result<CoherenceFilterInput, BridgeError> {
        let map = self.detector_maps.get(&code_distance)
            .ok_or(BridgeError::TileRoutingFailed(code_distance))?;

        let mut bitmap = vec![0u64; (map.detector_count + 63) / 64];
        for (stab_idx, &fired) in syndrome.0.iter().enumerate() {
            if fired {
                let det_idx = map.stabilizer_to_detector(stab_idx);
                bitmap[det_idx / 64] |= 1u64 << (det_idx % 64);
            }
        }

        Ok(CoherenceFilterInput {
            detector_bitmap: bitmap,
            tile_id: map.tile_for_distance(code_distance),
            round_id: 0, // Filled by caller
        })
    }

    fn correction_to_pauli_ops(
        &self,
        correction: &CoherenceCorrectionOutput,
    ) -> Result<Vec<(QubitIndex, PauliOp)>, BridgeError> {
        correction.corrections.iter()
            .map(|(qubit, code)| {
                let op = match code {
                    0 => PauliOp::I,
                    1 => PauliOp::X,
                    2 => PauliOp::Y,
                    3 => PauliOp::Z,
                    other => return Err(BridgeError::UnknownCorrectionCode(*other)),
                };
                Ok((QubitIndex(*qubit), op))
            })
            .collect()
    }

    fn query_coherence_score(
        &self,
        region_id: &str,
    ) -> Result<CoherenceScore, BridgeError> {
        let energy = self.filter_pipeline.current_energy(region_id)
            .map_err(|e| BridgeError::CoherenceUnavailable(e.to_string()))?;
        // Invert: high energy = low coherence
        Ok(CoherenceScore(1.0 / (1.0 + energy as f64)))
    }

    fn report_simulation_metrics(
        &self,
        _session_id: &str,
        _metrics: &SimulationMetrics,
    ) -> Result<(), BridgeError> {
        // Translate to coherence signal format and submit
        Ok(())
    }
}

2. Shared Kernel: ruvector-math

Both the quantum simulation engine and the coherence engine depend on a shared mathematical foundation. Changes to ruvector-math must be validated against both domains before release.

Shared Types

// ruvector-math provides these types used by both domains:

/// Complex number with f64 components (re, im).
/// Used by quantum state vectors AND coherence restriction maps.
pub struct Complex<T> {
    pub re: T,
    pub im: T,
}

/// Cache-line-aligned vector for SIMD operations.
/// Used by both state vector operations and residual computation.
#[repr(align(64))]
pub struct AlignedVec<T> {
    data: Vec<T>,
}

/// SIMD dispatch trait: implementations select AVX2, NEON, or scalar
/// at runtime depending on platform capabilities.
pub trait SimdOps {
    fn dot_product_f64(a: &[f64], b: &[f64]) -> f64;
    fn complex_multiply(a: &[Complex<f64>], b: &[Complex<f64>], out: &mut [Complex<f64>]);
    fn norm_squared(v: &[Complex<f64>]) -> f64;
    fn axpy(alpha: f64, x: &[f64], y: &mut [f64]);
}

Change Coordination Protocol

  1. Any proposed change to ruvector-math must include tests for both the quantum engine use case and the coherence engine use case.
  2. The CI pipeline runs cargo test -p ruqu-core and cargo test -p ruvector-coherence after any change to ruvector-math.
  3. Breaking changes require a version bump and simultaneous updates to both downstream crates.
  4. Performance regressions in SIMD operations must be caught by benchmarks in both domains.

Boundary

Only the types and functions listed above cross the shared kernel boundary. Internal implementation details of ruvector-math (e.g., specific SIMD intrinsics, platform detection) are not shared.


3. Customer-Supplier: Agent System Integration

The ruVector agent system (powered by claude-flow) acts as the customer, invoking the quantum simulation engine as a supplier. The contract defines what the agent can request and what it receives in return.

Contract

/// Contract for agent system access to the quantum simulation engine.
///
/// The agent system (customer) invokes these operations.
/// The quantum engine (supplier) fulfills them.
pub trait SimulationContract: Send + Sync {
    /// Build a circuit from a high-level description.
    fn build_circuit(&self, spec: CircuitSpec) -> Result<CircuitHandle, ContractError>;

    /// Run a simulation and return results.
    fn run_simulation(&self, circuit: CircuitHandle, config: RunConfig)
        -> Result<SimulationOutput, ContractError>;

    /// Run a VQE optimization and return the ground state energy.
    fn run_vqe(&self, spec: VQESpec) -> Result<VQEOutput, ContractError>;

    /// Query resource requirements before committing to a run.
    fn estimate_resources(&self, circuit: CircuitHandle) -> Result<ResourceEstimate, ContractError>;
}

/// High-level circuit specification from the agent.
pub struct CircuitSpec {
    pub qubit_count: u32,
    pub gate_sequence: Vec<GateSpec>,
    pub parameters: HashMap<String, f64>,
}

/// Agent-facing gate specification (simplified from internal Gate).
pub struct GateSpec {
    pub gate_type: String,
    pub target: u32,
    pub control: Option<u32>,
    pub angle: Option<f64>,
}

/// Configuration limits the agent can set.
pub struct RunConfig {
    pub max_shots: u32,
    pub max_memory_mb: u32,
    pub timeout_seconds: u32,
    pub backend_preference: Option<String>,
}

/// Results returned to the agent.
pub struct SimulationOutput {
    pub measurement_counts: HashMap<String, u32>,
    pub expectation_values: Vec<(String, f64)>,
    pub metrics: SimulationMetrics,
}

/// VQE-specific results.
pub struct VQEOutput {
    pub ground_state_energy: f64,
    pub optimal_parameters: Vec<f64>,
    pub iterations: u32,
    pub converged: bool,
}

/// Resource estimate before execution.
pub struct ResourceEstimate {
    pub memory_bytes: usize,
    pub estimated_time_ms: f64,
    pub qubit_count: u32,
    pub gate_count: u32,
}

Agent Integration Flow

Agent Context         Quantum Engine            Result
    |                      |                      |
    | 1. build_circuit()   |                      |
    |--------------------->|                      |
    |   CircuitHandle      |                      |
    |<---------------------|                      |
    |                      |                      |
    | 2. estimate_resources|                      |
    |--------------------->|                      |
    |   ResourceEstimate   |                      |
    |<---------------------|                      |
    |                      |                      |
    | 3. run_simulation()  |                      |
    |--------------------->|                      |
    |                      | [executes internally]|
    |                      |---+                  |
    |                      |   | circuit -> state |
    |                      |   | gates -> measure |
    |                      |<--+                  |
    |   SimulationOutput   |                      |
    |<---------------------|                      |
    |                      |                      |
    | 4. Agent acts on     |                      |
    |    results           |                      |
    v                      v                      v

Resource Limits

The supplier enforces resource limits set by the customer:

  • Memory: Capped at max_memory_mb; returns error if state vector exceeds budget
  • Time: Monitored per-step; simulation aborted if timeout_seconds exceeded
  • Qubits: Platform limit (30 for state vector, higher for tensor network) communicated via estimate_resources

4. Published Language: OpenQASM Compatibility

A future integration point for importing and exporting circuits in the OpenQASM 3.0 standard, enabling interoperability with IBM Qiskit, Google Cirq, and other quantum frameworks.

Translation Layer

/// Trait for OpenQASM import/export.
pub trait OpenQASMTranslator {
    /// Parse an OpenQASM 3.0 string into the internal circuit representation.
    fn import(&self, qasm: &str) -> Result<QuantumCircuit, TranslationError>;

    /// Export an internal circuit to OpenQASM 3.0 format.
    fn export(&self, circuit: &QuantumCircuit) -> Result<String, TranslationError>;
}

#[derive(Debug, thiserror::Error)]
pub enum TranslationError {
    #[error("unsupported gate in OpenQASM: {0}")]
    UnsupportedGate(String),

    #[error("parse error at line {line}: {message}")]
    ParseError { line: u32, message: String },

    #[error("circuit uses features not supported by OpenQASM 3.0: {0}")]
    UnsupportedFeature(String),
}

Scope

  • Phase 1: Import basic gate circuits (H, CNOT, Rz, measure)
  • Phase 2: Export circuits with parameter bindings
  • Phase 3: Support custom gate definitions and classical control flow

5. Conformist: WASM Platform

The ruqu-wasm crate conforms to WASM platform constraints without attempting to work around them. Limitations are accepted as-is, with graceful degradation where capabilities are reduced.

Accepted Constraints

Constraint Impact Mitigation
No native threads Single-threaded execution Sequential gate application; no rayon
4GB memory limit Max ~25 qubits (state vector) Tensor network backend for larger circuits
No filesystem Cannot persist results Return all data via JS callbacks
No system clock Timing metrics unavailable Use performance.now() via JS bridge
No SIMD (some runtimes) Slower math Feature-gated SIMD; scalar fallback

WASM API Surface

/// Public API exposed to JavaScript via wasm-bindgen.
///
/// This is the conformist boundary: we accept WASM constraints
/// and expose only what the platform allows.
#[cfg(target_arch = "wasm32")]
pub mod wasm_api {
    use wasm_bindgen::prelude::*;

    #[wasm_bindgen]
    pub struct WasmSimulator {
        session: SimulationSession,
    }

    #[wasm_bindgen]
    impl WasmSimulator {
        /// Create a new simulator for the given qubit count.
        #[wasm_bindgen(constructor)]
        pub fn new(qubit_count: u32) -> Result<WasmSimulator, JsValue> {
            // Enforce WASM-specific qubit limit
            if qubit_count > 25 {
                return Err(JsValue::from_str(
                    "WASM platform supports at most 25 qubits in state vector mode"
                ));
            }
            // ... construction
            Ok(WasmSimulator { session: todo!() })
        }

        /// Add a gate to the circuit.
        pub fn add_gate(&mut self, gate_type: &str, target: u32, control: Option<u32>)
            -> Result<(), JsValue> { Ok(()) }

        /// Run the simulation and return measurement counts as JSON.
        pub fn run(&mut self, shots: u32) -> Result<String, JsValue> {
            Ok("{}".to_string())
        }

        /// Get memory usage estimate in bytes.
        pub fn memory_estimate(&self) -> usize { 0 }
    }
}

6. Partnership: Graph Database Integration

The ruvector-graph crate and the quantum simulation engine have a bidirectional partnership around graph-structured problems, particularly QAOA and MaxCut.

Data Flow

/// Graph data provided by ruvector-graph for quantum optimization.
pub struct GraphProblem {
    pub vertex_count: u32,
    pub edges: Vec<(u32, u32, f64)>,  // (source, target, weight)
    pub problem_type: GraphProblemType,
}

#[derive(Debug, Clone, Copy)]
pub enum GraphProblemType { MaxCut, GraphColoring, TSP }

/// Results returned to ruvector-graph for annotation.
pub struct QuantumGraphResult {
    pub objective_value: CutValue,
    pub partition: Vec<bool>,
    pub confidence: f64,
    pub circuit_depth: CircuitDepth,
}

/// Partnership interface: both sides contribute and consume.
pub trait GraphQuantumPartnership {
    /// Graph -> Quantum: convert graph problem to QAOA circuit.
    fn graph_to_qaoa_circuit(
        &self,
        problem: &GraphProblem,
        layers: u32,
    ) -> Result<QuantumCircuit, DomainError>;

    /// Quantum -> Graph: feed optimization results back as graph annotations.
    fn annotate_graph_with_result(
        &self,
        problem: &GraphProblem,
        result: &QuantumGraphResult,
    ) -> Result<GraphAnnotation, DomainError>;

    /// Shared interest: partition graph using ruvector-mincut for subproblem decomposition.
    fn decompose_problem(
        &self,
        problem: &GraphProblem,
        max_subproblem_qubits: u32,
    ) -> Result<Vec<GraphProblem>, DomainError>;
}

/// Annotation written back to the graph database.
pub struct GraphAnnotation {
    pub vertex_labels: HashMap<u32, String>,
    pub edge_labels: HashMap<(u32, u32), String>,
    pub metadata: HashMap<String, String>,
}

Cross-Cutting Concerns

Error Handling Across Boundaries

Each bounded context defines its own error type. At integration boundaries, errors are translated through the ACL rather than propagated directly.

/// Integration boundary error: wraps domain errors from either side.
#[derive(Debug, thiserror::Error)]
pub enum IntegrationError {
    #[error("quantum engine error: {0}")]
    QuantumEngine(#[from] DomainError),

    #[error("coherence bridge error: {0}")]
    CoherenceBridge(#[from] BridgeError),

    #[error("contract violation: {0}")]
    ContractViolation(String),

    #[error("resource limit exceeded: {0}")]
    ResourceLimit(String),
}

Observability

Distributed tracing spans cross crate boundaries with a shared trace context.

  • Each integration call propagates a TraceId through the ACL
  • The coherence bridge logs translation events at DEBUG level
  • Agent contract calls log at INFO with duration and resource usage
  • WASM calls use console.log via the JS bridge when tracing is enabled

Resource Management

Memory and thread resources are coordinated with the ruVector runtime.

  • State vector allocation checks the global memory budget before proceeding
  • Tensor network contractions respect thread pool limits shared with rayon
  • WASM mode has a fixed 4GB ceiling enforced at the conformist boundary
  • All resource allocation events emit MemoryAllocated / MemoryReleased domain events

Configuration Propagation

Configuration flows from the ruVector root config into the quantum engine.

/// Quantum engine configuration derived from ruVector global config.
pub struct QuantumEngineConfig {
    pub max_qubits: u32,
    pub default_backend: BackendType,
    pub memory_budget_bytes: usize,
    pub thread_count: usize,
    pub coherence_bridge_enabled: bool,
    pub wasm_mode: bool,
}

impl From<&RuVectorConfig> for QuantumEngineConfig {
    fn from(global: &RuVectorConfig) -> Self {
        Self {
            max_qubits: global.quantum.max_qubits.unwrap_or(30),
            default_backend: global.quantum.backend.parse().unwrap_or(BackendType::StateVector),
            memory_budget_bytes: global.memory.budget_bytes,
            thread_count: global.runtime.thread_count,
            coherence_bridge_enabled: global.coherence.enabled,
            wasm_mode: cfg!(target_arch = "wasm32"),
        }
    }
}

Event Flow Diagrams

1. VQE Optimization Flow

Agent              CircuitBuilder     SimSession       QuantumState      Optimizer
  |                     |                |                 |                |
  | build_circuit(spec) |                |                 |                |
  |-------------------->|                |                 |                |
  |   CircuitHandle     |                |                 |                |
  |<--------------------|                |                 |                |
  |                     |                |                 |                |
  | run_vqe(spec)       |                |                 |                |
  |-------------------------------------------------------------->|        |
  |                     |                |                 |  init(params)  |
  |                     |                |                 |<---------------|
  |                     |                |                 |                |
  |                     |          +-----|---LOOP----------|--------+       |
  |                     |          |     |                 |        |       |
  |                     |          | start()              |        |       |
  |                     |          |     |----->|          |        |       |
  |                     |          |     | apply_gates()   |        |       |
  |                     |          |     |     |---------->|        |       |
  |                     |          |     |     |  expectation_value |       |
  |                     |          |     |     |---------->|        |       |
  |                     |          |     |     |  energy   |        |       |
  |                     |          |     |<----|-----------|        |       |
  |                     |          |     |                 | update(grad)   |
  |                     |          |     |                 |------->|       |
  |                     |          |     |                 | new_params     |
  |                     |          |     |                 |<-------|       |
  |                     |          +-----|---END LOOP------|--------+       |
  |                     |                |                 |                |
  |  VQEOutput(energy, params)           |                 |                |
  |<-------------------------------------------------------------|        |
  |                     |                |                 |                |

2. Surface Code QEC with Coherence Bridge

SurfaceCodeExp     NoiseService    CoherenceBridge    ruQu Filters     Decoder
  |                    |                |                  |               |
  | run_cycle()        |                |                  |               |
  |--+                 |                |                  |               |
  |  | inject_errors() |                |                  |               |
  |  |---------------->|                |                  |               |
  |  | error_list      |                |                  |               |
  |  |<----------------|                |                  |               |
  |  |                 |                |                  |               |
  |  | extract_syndrome()               |                  |               |
  |  |--+              |                |                  |               |
  |  |  | SyndromeBits |                |                  |               |
  |  |<-+              |                |                  |               |
  |  |                 |                |                  |               |
  |  | syndrome_to_filter_input()       |                  |               |
  |  |--------------------------------->|                  |               |
  |  |                 | FilterInput    |                  |               |
  |  |                 |                |  process()       |               |
  |  |                 |                |----------------->|               |
  |  |                 |                |  Verdict         |               |
  |  |                 |                |<-----------------|               |
  |  |                 |                |                  |               |
  |  |                 | correction_to_pauli_ops()         |               |
  |  |<---------------------------------|                  |               |
  |  |                 |                |                  |               |
  |  | decode(syndrome)|                |                  |               |
  |  |------------------------------------------------------------------>|
  |  | correction      |                |                  |               |
  |  |<------------------------------------------------------------------|
  |  |                 |                |                  |               |
  |  | check_logical_error()            |                  |               |
  |  |--+              |                |                  |               |
  |  |  | bool         |                |                  |               |
  |  |<-+              |                |                  |               |
  |  |                 |                |                  |               |
  | CycleReport       |                |                  |               |
  |<-+                 |                |                  |               |

3. WASM Deployment Flow

Browser JS          ruqu-wasm (WASM)       ruqu-core           Results
  |                      |                     |                   |
  | new WasmSimulator(n) |                     |                   |
  |--------------------->|                     |                   |
  |                      | QuantumState::new(n)|                   |
  |                      |-------------------->|                   |
  |                      | state               |                   |
  |                      |<--------------------|                   |
  |  WasmSimulator       |                     |                   |
  |<---------------------|                     |                   |
  |                      |                     |                   |
  | add_gate("h", 0)     |                     |                   |
  |--------------------->|                     |                   |
  |                      | circuit.add_gate()  |                   |
  |                      |-------------------->|                   |
  |  Ok                  |                     |                   |
  |<---------------------|                     |                   |
  |                      |                     |                   |
  | add_gate("cx", 1, 0) |                     |                   |
  |--------------------->|                     |                   |
  |                      | circuit.add_gate()  |                   |
  |                      |-------------------->|                   |
  |  Ok                  |                     |                   |
  |<---------------------|                     |                   |
  |                      |                     |                   |
  | run(1000)            |                     |                   |
  |--------------------->|                     |                   |
  |                      | session.start()     |                   |
  |                      |-------------------->|                   |
  |                      | run_to_completion() |                   |
  |                      |-------------------->|                   |
  |                      |                     | [gate loop]       |
  |                      |                     |---+               |
  |                      |                     |   | apply_gate()  |
  |                      |                     |<--+               |
  |                      |                     | measure()         |
  |                      |                     |---+               |
  |                      |                     |   | outcomes      |
  |                      |                     |<--+               |
  |                      | SimulationMetrics   |                   |
  |                      |<--------------------|                   |
  |                      |                     |                   |
  |                      | JSON.serialize(counts)                  |
  |                      |---------------------------------------->|
  |  "{\"00\": 503, \"11\": 497}"              |                   |
  |<---------------------|                     |                   |
  |                      |                     |                   |
  | [JS callback with results]                 |                   |
  |                      |                     |                   |

Migration Strategy

Phase 1: Standalone ruqu-core

Goal: A self-contained crate with no external dependencies except ruvector-math.

  • Implement QuantumCircuit, QuantumState, SimulationSession aggregates
  • Implement CircuitBuilder, GateFusionService, NoiseInjectionService
  • All value objects and domain events defined
  • Unit tests and property-based tests for normalization, gate unitarity
  • No coherence bridge, no agent integration, no WASM

Dependency: ruvector-math (shared kernel only)

Phase 2: ruqu-algorithms + Coherence Integration

Goal: Add VQE, surface code experiments, and the coherence bridge.

  • Implement VQEOptimization, SurfaceCodeExperiment aggregates
  • Implement TensorNetworkState for circuits exceeding state vector limits
  • Build CoherenceBridge anti-corruption layer
  • Integrate with ruQu FilterPipeline and MWPMDecoder
  • Add PauliExpectationService, ContractionPathOptimizer
  • Integration tests: VQE convergence, surface code logical error rate vs theory

Dependencies: ruqu-core, ruvector-math, ruqu (coherence bridge target)

Phase 3: ruqu-wasm

Goal: Deploy to browser environments with graceful degradation.

  • Implement WasmSimulator conformist wrapper
  • Add wasm-bindgen API surface
  • Enforce WASM constraints (25-qubit limit, no threads, no filesystem)
  • JavaScript test harness running circuits in headless browser
  • Performance benchmarks: gate throughput in WASM vs native

Dependencies: ruqu-core, wasm-bindgen, wasm-pack

Phase 4: Full Agent System Integration

Goal: Complete customer-supplier integration with the claude-flow agent system.

  • Implement SimulationContract trait and production adapter
  • Add resource estimation and budget enforcement
  • Implement GraphQuantumPartnership for QAOA/MaxCut
  • Integration with ruvector-graph for graph problem decomposition
  • End-to-end tests: agent builds circuit, runs simulation, acts on results
  • OpenQASM import/export (published language)

Dependencies: All previous phases, ruvector-graph, claude-flow agent SDK


References

  1. Evans, E. (2003). "Domain-Driven Design: Tackling Complexity in the Heart of Software."
  2. Vernon, V. (2013). "Implementing Domain-Driven Design." Chapter 13: Integrating Bounded Contexts.
  3. Coherence Engine DDD: docs/architecture/coherence-engine-ddd.md
  4. ruQu crate: crates/ruQu/
  5. ruvector-math: shared kernel for SIMD and complex number operations
  6. OpenQASM 3.0 specification: https://openqasm.com/