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**:

```typescript
// 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**:

```typescript
// 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**:

```typescript
{
  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**:

```typescript
// 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**:

```typescript
{
  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**:

```typescript
// 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**:

```typescript
{
  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**:

```typescript
// 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**:

```typescript
// 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**:

```typescript
// 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**:

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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](./README.md) - Domain overview
- [Domain Model](./domain-model.md) - Entities and aggregates
- [ADR-031: Prime Radiant Integration](../../implementation/adrs/ADR-031-prime-radiant-integration.md)
- [ADR-006: Unified Memory Service](../../implementation/adrs/ADR-006-UNIFIED-MEMORY.md)
- [ADR-022: AIDefence Integration](../../implementation/adrs/ADR-022-aidefence-integration.md)