ruvnet--ruflo/v3/docs/ddd/coherence-engine/integration-points.md

Coherence Engine Integration Points

Overview

This document describes how the Coherence Engine domain integrates with Claude Flow V3 modules, including the Memory, Security, Coordination, and Hive-Mind domains.

Integration Architecture

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              Claude Flow V3                                      │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  ┌────────────┐ │
│  │ Memory Domain   │  │ Security Domain │  │ Coordination    │  │ Hive-Mind  │ │
│  │                 │  │                 │  │ Domain          │  │ Domain     │ │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  └─────┬──────┘ │
│           │                    │                    │                  │        │
│           │                    │                    │                  │        │
│  ┌────────▼────────────────────▼────────────────────▼──────────────────▼──────┐ │
│  │                    Coherence Engine Plugin                                  │ │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │ │
│  │  │ Coherence    │  │ Input        │  │ Consensus    │  │ Swarm        │   │ │
│  │  │ Gate         │  │ Validator    │  │ Verifier     │  │ Analyzer     │   │ │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘   │ │
│  └───────────────────────────────────────────────────────────────────────────┘ │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

Memory Domain Integration

Integration Type: Shared Kernel

The Coherence Engine shares a kernel with the Memory domain for pre-storage validation.

Hook: pre-memory-store

Purpose: Validate memory entries for contradiction before storage.

Trigger: Called before any entry is stored in memory.

Implementation:

// Hook registration
{
  name: 'pr/pre-memory-store',
  event: 'pre-memory-store',
  priority: HookPriority.HIGH,
  handler: async (context, payload) => {
    const gate = context.get<CoherenceGate>('pr.coherenceGate');
    const memoryService = context.get('memory');

    // Get existing context from same namespace
    const existingEntries = await memoryService.search({
      namespace: payload.namespace,
      limit: 10,
      embedding: payload.embedding
    });

    const validation = await gate.validate(payload, existingEntries);

    if (validation.action === 'reject') {
      throw new CoherenceViolationError(
        validation.coherenceResult.energy,
        validation.coherenceResult.violations
      );
    }

    // Add coherence metadata
    if (validation.action === 'warn') {
      payload.metadata = {
        ...payload.metadata,
        coherenceWarning: true,
        coherenceEnergy: validation.coherenceResult.energy
      };
    }

    return payload;
  }
}

Extended Service: CoherentMemoryService

Purpose: Provides memory operations with built-in coherence validation.

Methods:

Method	Description	Coherence Integration
storeWithCoherence()	Store with validation	Pre-store coherence check
searchCoherent()	Search with filtering	Post-search coherence filter
validateNamespace()	Validate namespace	Batch coherence analysis

Usage Example:

// Initialize coherent memory service
const coherentMemory = new CoherentMemoryService(memoryService, coherenceGate);

// Store with coherence validation
const result = await coherentMemory.storeWithCoherence({
  namespace: 'agents/decisions',
  key: 'decision-123',
  content: 'Agent decided to proceed with option A',
  embedding: embeddingVector
});

if (!result.stored) {
  console.warn(`Entry rejected: energy=${result.coherenceResult.energy}`);
}

// Search with coherence filtering
const coherentResults = await coherentMemory.searchCoherent(
  queryEmbedding,
  10,
  { namespace: 'agents/decisions', minCoherence: 0.8 }
);

Memory Namespaces Used

Namespace	Purpose
pr/coherence-checks	Stores coherence check history
pr/stability-metrics	Stores stability analysis results
pr/thresholds	Stores configured thresholds

Security Domain Integration

Integration Type: Conformist

The Coherence Engine conforms to the Security domain's patterns for input validation.

Hook: pre-rag-retrieval

Purpose: Prevent hallucinations by validating retrieved context coherence.

Trigger: Called before RAG retrieval results are used.

Implementation:

{
  name: 'pr/pre-rag-retrieval',
  event: 'pre-rag-retrieval',
  priority: HookPriority.HIGH,
  handler: async (context, payload) => {
    const bridge = context.get<PrimeRadiantBridge>('pr.bridge');

    const vectors = payload.retrievedDocs.map(d => new Float32Array(d.embedding));

    if (vectors.length < 2) return payload;

    const coherence = await bridge.checkCoherence(vectors);

    if (coherence.energy > 0.5) {
      // Filter contradictory documents
      console.warn(`RAG coherence warning: ${coherence.violations.join(', ')}`);

      return {
        ...payload,
        retrievedDocs: filterMostCoherent(payload.retrievedDocs, vectors),
        coherenceFiltered: true,
        originalCoherenceEnergy: coherence.energy
      };
    }

    return payload;
  }
}

AIDefence Integration

Purpose: Extend threat detection with coherence-based analysis.

Integration Points:

AIDefence Feature	Coherence Enhancement
Input validation	Coherence-based content validation
Threat detection	Causal analysis of attack patterns
Pattern matching	Spectral analysis of threat signatures

Usage Example:

// Extend AIDefence with coherence checking
const enhancedScan = async (input: string, embedding: Float32Array) => {
  // Standard AIDefence scan
  const aidefenceResult = await aidefence.scan(input);

  // Coherence enhancement
  const coherenceResult = await coherenceGate.validate(
    { embedding },
    await getRecentInputEmbeddings()
  );

  return {
    ...aidefenceResult,
    coherenceScore: coherenceResult.coherenceResult.confidence,
    coherenceWarnings: coherenceResult.coherenceResult.violations
  };
};

Coordination Domain Integration

Integration Type: Shared Kernel

The Coherence Engine shares a kernel with Coordination for swarm stability analysis.

Hook: post-swarm-task

Purpose: Analyze swarm stability after task completion.

Trigger: Called after a swarm task completes.

Implementation:

{
  name: 'pr/post-swarm-task',
  event: 'post-task',
  priority: HookPriority.NORMAL,
  handler: async (context, payload) => {
    if (!payload.isSwarmTask) return payload;

    const bridge = context.get<PrimeRadiantBridge>('pr.bridge');
    const coordination = context.get('coordination');

    // Get agent communication patterns
    const agentStates = await coordination.getAgentStates();
    const adj = buildCommunicationMatrix(agentStates);

    // Analyze spectral stability
    const spectral = await bridge.analyzeSpectral(adj);

    // Store metrics
    await context.get('memory').store({
      namespace: 'pr/stability-metrics',
      key: `task-${payload.taskId}`,
      content: JSON.stringify({
        stable: spectral.stable,
        spectralGap: spectral.spectralGap,
        timestamp: Date.now()
      })
    });

    return {
      ...payload,
      stabilityMetrics: spectral
    };
  }
}

Swarm Health Monitoring

MCP Tool: pr/swarm-health

Purpose: Continuous swarm health monitoring using spectral analysis.

Metrics Provided:

Metric	Description	Healthy Range
spectralGap	Gap between top eigenvalues	> 0.1
stabilityIndex	Aggregate stability measure	> 0.5
clusteringCoefficient	Agent clustering tendency	0.3 - 0.7
connectivityScore	Overall swarm connectivity	> 0.8

Usage Example:

// Monitor swarm health
const health = await primeRadiantPlugin.tools.swarmHealth({
  swarmId: 'main-swarm',
  includeHistory: true
});

if (!health.stable) {
  console.warn('Swarm instability detected:', health.recommendations);
}

Hive-Mind Domain Integration

Integration Type: Shared Kernel

The Coherence Engine shares a kernel with Hive-Mind for consensus verification.

Hook: pre-consensus

Purpose: Mathematically validate consensus proposals before voting.

Trigger: Called before a consensus vote is accepted.

Implementation:

{
  name: 'pr/pre-consensus',
  event: 'pre-consensus',
  priority: HookPriority.HIGH,
  handler: async (context, payload) => {
    const bridge = context.get<PrimeRadiantBridge>('pr.bridge');

    // Check proposal coherence against existing decisions
    const vectors = [
      new Float32Array(payload.proposalEmbedding),
      ...payload.existingDecisions.map(d => new Float32Array(d.embedding))
    ];

    const coherence = await bridge.checkCoherence(vectors);

    if (coherence.energy > 0.7) {
      return {
        ...payload,
        rejected: true,
        rejectionReason: `Proposal contradicts existing decisions (energy: ${coherence.energy.toFixed(3)})`
      };
    }

    return {
      ...payload,
      coherenceEnergy: coherence.energy,
      coherenceConfidence: coherence.confidence
    };
  }
}

Extended Service: CoherentHiveMind

Purpose: Provides hive-mind operations with mathematical verification.

Methods:

Method	Description	Coherence Integration
verifyConsensus()	Verify consensus mathematically	Coherence + spectral check
analyzeSwarmHealth()	Analyze swarm health	Spectral stability analysis
proposeWithValidation()	Propose with pre-validation	Pre-proposal coherence gate

Usage Example:

// Initialize coherent hive-mind
const coherentHive = new CoherentHiveMind(hiveMind, primeRadiantBridge);

// Verify consensus mathematically
const verification = await coherentHive.verifyConsensus('proposal-123');

if (!verification.verified) {
  console.warn('Consensus not verified:', {
    coherenceEnergy: verification.coherenceEnergy.getValue(),
    spectralStability: verification.spectralStability,
    agreementRatio: verification.agreementRatio
  });
}

// Analyze swarm health
const health = await coherentHive.analyzeSwarmHealth();
if (!health.healthy) {
  for (const rec of health.recommendations) {
    console.warn('Health recommendation:', rec);
  }
}

Byzantine Fault Tolerance Enhancement

Purpose: Enhance BFT with mathematical coherence checking.

Integration:

// BFT with coherence verification
async function bftWithCoherence<T>(
  operation: () => Promise<T>,
  replicaCount: number = 3
): Promise<T> {
  const results: T[] = [];
  const embeddings: Float32Array[] = [];

  // Execute on replicas
  for (let i = 0; i < replicaCount; i++) {
    const result = await operation();
    results.push(result);
    embeddings.push(await embed(result));
  }

  // Check coherence of results
  const coherence = await bridge.checkCoherence(embeddings);

  if (coherence.energy > 0.5) {
    throw new Error('BFT results are incoherent - potential Byzantine failure');
  }

  // Return majority result
  return selectMajority(results);
}

Embeddings Domain Integration

Integration Type: Customer-Supplier

The Coherence Engine is a customer of the Embeddings domain.

Embedding Generation

Purpose: Generate embeddings for coherence checking.

Integration:

// Use embeddings service for coherence input
const embeddingsService = context.get<EmbeddingsService>('embeddings');

async function prepareForCoherence(content: string): Promise<Float32Array> {
  const embedding = await embeddingsService.generate(content);
  return new Float32Array(embedding);
}

// Batch embedding for multiple entries
async function prepareMultiple(contents: string[]): Promise<Float32Array[]> {
  const embeddings = await embeddingsService.batchGenerate(contents);
  return embeddings.map(e => new Float32Array(e));
}

Hyperbolic Embedding Support

Purpose: Enhanced coherence checking with hyperbolic embeddings.

Integration:

// Use hyperbolic embeddings for hierarchical coherence
const hyperbolicEmbedding = await embeddingsService.generate(content, {
  hyperbolic: true,
  curvature: -1
});

// Coherence in Poincare ball
const coherence = await bridge.checkCoherenceHyperbolic(
  hyperbolicEmbeddings,
  { curvature: -1 }
);

MCP Tool Registration

Tools Provided

Tool Name	Category	Description
pr/coherence-check	Coherence	Check vector coherence
pr/spectral-analyze	Spectral	Analyze spectral stability
pr/causal-infer	Causal	Do-calculus inference
pr/consensus-verify	Consensus	Verify multi-agent consensus
pr/quantum-topology	Topology	Compute topological features
pr/memory-gate	Memory	Pre-storage coherence gate

Tool Registration Example

// Register tools with MCP server
mcpServer.registerTools([
  {
    name: 'pr_coherence_check',
    description: 'Check coherence using Sheaf Laplacian',
    inputSchema: {
      type: 'object',
      properties: {
        vectors: { type: 'array', items: { type: 'array', items: { type: 'number' } } },
        threshold: { type: 'number', default: 0.3 }
      },
      required: ['vectors']
    },
    handler: coherenceCheckHandler
  },
  // ... other tools
]);

Event Integration

Domain Events Emitted

Event	Trigger	Consumers
CoherenceViolationDetected	Entry fails coherence	Memory, Logging
StabilityThresholdBreached	Spectral gap too low	Coordination, Alerting
ConsensusVerificationFailed	Consensus not verified	Hive-Mind, Logging

Event Handling Example

// Subscribe to coherence events
eventBus.subscribe('CoherenceViolationDetected', async (event) => {
  // Log violation
  await logger.warn('Coherence violation', {
    energy: event.energy,
    violations: event.violations,
    namespace: event.namespace
  });

  // Update metrics
  await metrics.increment('coherence.violations', {
    namespace: event.namespace,
    action: event.action
  });
});

// Subscribe to stability events
eventBus.subscribe('StabilityThresholdBreached', async (event) => {
  // Alert on critical instability
  if (event.spectralGap < 0.05) {
    await alerting.critical('Swarm stability critical', {
      sourceType: event.sourceType,
      sourceId: event.sourceId,
      recommendations: event.recommendations
    });
  }
});

Performance Considerations

Caching Strategy

// LRU cache for coherence results
const coherenceCache = new LRUCache<string, CoherenceResult>({
  max: 1000,
  ttl: 60000 // 1 minute TTL
});

// Cache key generation
function getCacheKey(vectors: Float32Array[]): string {
  const hash = crypto.createHash('sha256');
  for (const v of vectors) {
    hash.update(Buffer.from(v.buffer));
  }
  return hash.digest('hex');
}

Batch Processing

// Batch coherence validation for efficiency
async function batchValidate(
  entries: MemoryEntry[],
  batchSize: number = 10
): Promise<CoherenceValidation[]> {
  const results: CoherenceValidation[] = [];

  for (let i = 0; i < entries.length; i += batchSize) {
    const batch = entries.slice(i, i + batchSize);
    const batchResults = await Promise.all(
      batch.map(e => coherenceGate.validate(e))
    );
    results.push(...batchResults);
  }

  return results;
}

Async Processing

// Non-blocking stability analysis
async function analyzeStabilityAsync(swarmId: string): Promise<void> {
  // Queue analysis for background processing
  await queue.add('stability-analysis', {
    swarmId,
    priority: 'normal'
  });
}

// Background worker
queue.process('stability-analysis', async (job) => {
  const { swarmId } = job.data;
  const analysis = await stabilityAnalyzer.analyze(swarmId);

  // Store results
  await memory.store({
    namespace: 'pr/stability-metrics',
    key: `swarm-${swarmId}-${Date.now()}`,
    content: JSON.stringify(analysis)
  });

  // Emit event if unhealthy
  if (!analysis.isHealthy()) {
    eventBus.emit('StabilityThresholdBreached', {
      type: 'StabilityThresholdBreached',
      timestamp: new Date(),
      analysisId: analysis.id,
      sourceType: 'swarm',
      sourceId: swarmId,
      spectralGap: analysis.spectralGap.getValue(),
      recommendations: analysis.recommendations
    });
  }
});

Related Documentation

• README - Domain overview
• Domain Model - Entities and aggregates
• ADR-031: Prime Radiant Integration
• ADR-006: Unified Memory Service
• ADR-022: AIDefence Integration