v3/docs/ddd/coherence-engine/domain-model.md
This document defines the domain model for the Coherence Engine, including entities, value objects, aggregates, and domain services that implement mathematical AI interpretability for Claude Flow V3.
Represents the Sheaf Laplacian energy measuring contradiction level.
/**
* Coherence Energy Value Object
* Immutable scalar representing contradiction level
* Range: [0, 1] where 0 = fully coherent, 1 = fully contradictory
*/
class CoherenceEnergy {
private readonly value: number;
private constructor(value: number) {
if (value < 0 || value > 1) {
throw new Error('CoherenceEnergy must be between 0 and 1');
}
this.value = value;
}
static create(value: number): CoherenceEnergy {
return new CoherenceEnergy(Math.max(0, Math.min(1, value)));
}
static coherent(): CoherenceEnergy {
return new CoherenceEnergy(0);
}
static contradictory(): CoherenceEnergy {
return new CoherenceEnergy(1);
}
getValue(): number {
return this.value;
}
isCoherent(threshold: number = 0.3): boolean {
return this.value < threshold;
}
isContradictory(threshold: number = 0.7): boolean {
return this.value >= threshold;
}
isWarning(warnThreshold: number = 0.3, rejectThreshold: number = 0.7): boolean {
return this.value >= warnThreshold && this.value < rejectThreshold;
}
getConfidence(): number {
return 1 - this.value;
}
equals(other: CoherenceEnergy): boolean {
return Math.abs(this.value - other.value) < 0.0001;
}
}
Represents the spectral gap indicating system stability.
/**
* Spectral Gap Value Object
* Difference between first and second eigenvalues
* Positive gap indicates stability
*/
class SpectralGap {
private readonly value: number;
private constructor(value: number) {
this.value = value;
}
static create(eigenvalues: number[]): SpectralGap {
if (eigenvalues.length < 2) {
return new SpectralGap(1); // Trivially stable
}
const sorted = [...eigenvalues].sort((a, b) => b - a);
return new SpectralGap(sorted[0] - sorted[1]);
}
getValue(): number {
return this.value;
}
isStable(threshold: number = 0.1): boolean {
return this.value > threshold;
}
getStabilityLevel(): 'stable' | 'marginal' | 'unstable' {
if (this.value > 0.2) return 'stable';
if (this.value > 0.05) return 'marginal';
return 'unstable';
}
equals(other: SpectralGap): boolean {
return Math.abs(this.value - other.value) < 0.0001;
}
}
Represents the estimated causal effect of an intervention.
/**
* Causal Effect Value Object
* Estimated effect of treatment on outcome
*/
class CausalEffect {
private readonly value: number;
private readonly confidence: number;
private constructor(value: number, confidence: number) {
this.value = value;
this.confidence = Math.max(0, Math.min(1, confidence));
}
static create(value: number, confidence: number): CausalEffect {
return new CausalEffect(value, confidence);
}
getValue(): number {
return this.value;
}
getConfidence(): number {
return this.confidence;
}
isSignificant(threshold: number = 0.1): boolean {
return Math.abs(this.value) > threshold && this.confidence > 0.8;
}
getDirection(): 'positive' | 'negative' | 'neutral' {
if (this.value > 0.1) return 'positive';
if (this.value < -0.1) return 'negative';
return 'neutral';
}
equals(other: CausalEffect): boolean {
return Math.abs(this.value - other.value) < 0.0001 &&
Math.abs(this.confidence - other.confidence) < 0.0001;
}
}
Represents topological invariants of a space.
/**
* Betti Numbers Value Object
* Topological invariants: b0=components, b1=loops, b2=voids
*/
class BettiNumbers {
private readonly values: number[];
private constructor(values: number[]) {
this.values = [...values];
}
static create(values: number[]): BettiNumbers {
return new BettiNumbers(values);
}
getB0(): number {
return this.values[0] ?? 0;
}
getB1(): number {
return this.values[1] ?? 0;
}
getB2(): number {
return this.values[2] ?? 0;
}
getDimension(d: number): number {
return this.values[d] ?? 0;
}
isConnected(): boolean {
return this.getB0() === 1;
}
hasLoops(): boolean {
return this.getB1() > 0;
}
hasVoids(): boolean {
return this.getB2() > 0;
}
getAll(): number[] {
return [...this.values];
}
equals(other: BettiNumbers): boolean {
if (this.values.length !== other.values.length) return false;
return this.values.every((v, i) => v === other.values[i]);
}
}
Represents a coherence validation with identity.
/**
* Coherence Check Entity
* Tracks a specific coherence validation event
*/
class CoherenceCheck {
readonly id: string;
readonly timestamp: Date;
readonly vectors: Float32Array[];
readonly energy: CoherenceEnergy;
readonly violations: string[];
readonly action: 'allow' | 'warn' | 'reject';
constructor(params: {
id: string;
vectors: Float32Array[];
energy: CoherenceEnergy;
violations: string[];
action: 'allow' | 'warn' | 'reject';
}) {
this.id = params.id;
this.timestamp = new Date();
this.vectors = params.vectors;
this.energy = params.energy;
this.violations = params.violations;
this.action = params.action;
}
static create(params: Omit<ConstructorParameters<typeof CoherenceCheck>[0], 'id'>): CoherenceCheck {
return new CoherenceCheck({
id: `coh-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
...params
});
}
wasRejected(): boolean {
return this.action === 'reject';
}
hadWarnings(): boolean {
return this.action === 'warn';
}
getViolationCount(): number {
return this.violations.length;
}
}
Represents a spectral stability analysis with identity.
/**
* Stability Analysis Entity
* Tracks spectral analysis of a system
*/
class StabilityAnalysis {
readonly id: string;
readonly timestamp: Date;
readonly sourceType: 'swarm' | 'consensus' | 'memory';
readonly sourceId: string;
readonly spectralGap: SpectralGap;
readonly eigenvalues: number[];
readonly stabilityIndex: number;
readonly recommendations: string[];
constructor(params: {
id: string;
sourceType: 'swarm' | 'consensus' | 'memory';
sourceId: string;
spectralGap: SpectralGap;
eigenvalues: number[];
stabilityIndex: number;
recommendations: string[];
}) {
this.id = params.id;
this.timestamp = new Date();
this.sourceType = params.sourceType;
this.sourceId = params.sourceId;
this.spectralGap = params.spectralGap;
this.eigenvalues = params.eigenvalues;
this.stabilityIndex = params.stabilityIndex;
this.recommendations = params.recommendations;
}
static create(params: Omit<ConstructorParameters<typeof StabilityAnalysis>[0], 'id'>): StabilityAnalysis {
return new StabilityAnalysis({
id: `stab-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
...params
});
}
isHealthy(): boolean {
return this.spectralGap.isStable() && this.stabilityIndex > 0.5;
}
needsAttention(): boolean {
return this.recommendations.length > 0;
}
}
Represents a causal inference query with identity.
/**
* Causal Query Entity
* Tracks a causal inference operation
*/
class CausalQuery {
readonly id: string;
readonly timestamp: Date;
readonly treatment: string;
readonly outcome: string;
readonly graph: CausalGraph;
readonly effect: CausalEffect;
readonly confounders: string[];
readonly backdoorPaths: string[][];
readonly interventionValid: boolean;
constructor(params: {
id: string;
treatment: string;
outcome: string;
graph: CausalGraph;
effect: CausalEffect;
confounders: string[];
backdoorPaths: string[][];
interventionValid: boolean;
}) {
this.id = params.id;
this.timestamp = new Date();
this.treatment = params.treatment;
this.outcome = params.outcome;
this.graph = params.graph;
this.effect = params.effect;
this.confounders = params.confounders;
this.backdoorPaths = params.backdoorPaths;
this.interventionValid = params.interventionValid;
}
static create(params: Omit<ConstructorParameters<typeof CausalQuery>[0], 'id'>): CausalQuery {
return new CausalQuery({
id: `causal-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
...params
});
}
hasConfounders(): boolean {
return this.confounders.length > 0;
}
hasBackdoorPaths(): boolean {
return this.backdoorPaths.length > 0;
}
isValidForIntervention(): boolean {
return this.interventionValid;
}
}
Root aggregate for coherence validation operations.
/**
* Coherence Gate Aggregate
* Manages coherence validation state and operations
*/
class CoherenceGateAggregate {
private readonly id: string;
private thresholds: CoherenceThresholds;
private recentChecks: CoherenceCheck[] = [];
private readonly maxHistory: number = 100;
constructor(id: string, thresholds?: Partial<CoherenceThresholds>) {
this.id = id;
this.thresholds = {
warn: thresholds?.warn ?? 0.3,
reject: thresholds?.reject ?? 0.7
};
}
getId(): string {
return this.id;
}
/**
* Validate vectors for coherence
*/
async validate(
vectors: Float32Array[],
engine: CohomologyEngine
): Promise<CoherenceCheck> {
const energyValue = await engine.computeSheafLaplacianEnergy(vectors);
const violations = await engine.detectContradictions(vectors);
const energy = CoherenceEnergy.create(energyValue);
let action: 'allow' | 'warn' | 'reject';
if (energy.isContradictory(this.thresholds.reject)) {
action = 'reject';
} else if (energy.isWarning(this.thresholds.warn, this.thresholds.reject)) {
action = 'warn';
} else {
action = 'allow';
}
const check = CoherenceCheck.create({
vectors,
energy,
violations,
action
});
this.addToHistory(check);
return check;
}
/**
* Update thresholds
*/
setThresholds(thresholds: Partial<CoherenceThresholds>): void {
this.thresholds = { ...this.thresholds, ...thresholds };
}
/**
* Get recent check history
*/
getRecentChecks(limit: number = 10): CoherenceCheck[] {
return this.recentChecks.slice(-limit);
}
/**
* Calculate rejection rate
*/
getRejectionRate(): number {
if (this.recentChecks.length === 0) return 0;
const rejected = this.recentChecks.filter(c => c.wasRejected()).length;
return rejected / this.recentChecks.length;
}
private addToHistory(check: CoherenceCheck): void {
this.recentChecks.push(check);
if (this.recentChecks.length > this.maxHistory) {
this.recentChecks = this.recentChecks.slice(-this.maxHistory);
}
}
}
interface CoherenceThresholds {
warn: number;
reject: number;
}
Root aggregate for spectral stability analysis.
/**
* Stability Analyzer Aggregate
* Manages stability analysis operations
*/
class StabilityAnalyzerAggregate {
private readonly id: string;
private analyses: StabilityAnalysis[] = [];
private readonly maxHistory: number = 50;
constructor(id: string) {
this.id = id;
}
getId(): string {
return this.id;
}
/**
* Analyze stability of an adjacency matrix
*/
async analyze(
adjacencyMatrix: Float32Array,
sourceType: 'swarm' | 'consensus' | 'memory',
sourceId: string,
engine: SpectralEngine
): Promise<StabilityAnalysis> {
const eigenvalues = await engine.computeEigenvalues(adjacencyMatrix);
const spectralGap = SpectralGap.create(Array.from(eigenvalues));
const stabilityIndex = await engine.computeStabilityIndex(eigenvalues);
const recommendations: string[] = [];
if (!spectralGap.isStable()) {
recommendations.push('System shows instability - consider reducing complexity');
}
if (spectralGap.getValue() < 0.1) {
recommendations.push('Low spectral gap - potential clustering/fragmentation');
}
if (stabilityIndex < 0.5) {
recommendations.push('Low stability index - coordination may be compromised');
}
const analysis = StabilityAnalysis.create({
sourceType,
sourceId,
spectralGap,
eigenvalues: Array.from(eigenvalues),
stabilityIndex,
recommendations
});
this.addToHistory(analysis);
return analysis;
}
/**
* Get recent analyses for a source
*/
getAnalysesForSource(sourceId: string): StabilityAnalysis[] {
return this.analyses.filter(a => a.sourceId === sourceId);
}
/**
* Calculate average stability
*/
getAverageStabilityIndex(): number {
if (this.analyses.length === 0) return 1;
const sum = this.analyses.reduce((acc, a) => acc + a.stabilityIndex, 0);
return sum / this.analyses.length;
}
private addToHistory(analysis: StabilityAnalysis): void {
this.analyses.push(analysis);
if (this.analyses.length > this.maxHistory) {
this.analyses = this.analyses.slice(-this.maxHistory);
}
}
}
Service for coherence validation operations.
/**
* Coherence Validation Service
* Orchestrates coherence checking across the system
*/
class CoherenceValidationService {
private readonly bridge: PrimeRadiantBridge;
private readonly gates: Map<string, CoherenceGateAggregate> = new Map();
constructor(bridge: PrimeRadiantBridge) {
this.bridge = bridge;
}
/**
* Get or create gate for namespace
*/
getGate(namespace: string): CoherenceGateAggregate {
if (!this.gates.has(namespace)) {
this.gates.set(namespace, new CoherenceGateAggregate(namespace));
}
return this.gates.get(namespace)!;
}
/**
* Validate entry against context
*/
async validateEntry(
entry: { embedding: Float32Array },
context: { embedding: Float32Array }[],
namespace: string
): Promise<CoherenceCheck> {
const vectors = [entry.embedding, ...context.map(c => c.embedding)];
const gate = this.getGate(namespace);
return gate.validate(vectors, this.bridge.getCohomologyEngine());
}
/**
* Batch validate entries
*/
async validateBatch(
entries: { embedding: Float32Array }[],
namespace: string
): Promise<CoherenceCheck[]> {
const results: CoherenceCheck[] = [];
const gate = this.getGate(namespace);
const processed: Float32Array[] = [];
for (const entry of entries) {
const vectors = [entry.embedding, ...processed];
const check = await gate.validate(vectors, this.bridge.getCohomologyEngine());
results.push(check);
if (!check.wasRejected()) {
processed.push(entry.embedding);
}
}
return results;
}
}
Service for mathematical consensus verification.
/**
* Consensus Verification Service
* Mathematically verifies multi-agent consensus
*/
class ConsensusVerificationService {
private readonly bridge: PrimeRadiantBridge;
private readonly stabilityAnalyzer: StabilityAnalyzerAggregate;
constructor(bridge: PrimeRadiantBridge) {
this.bridge = bridge;
this.stabilityAnalyzer = new StabilityAnalyzerAggregate('consensus');
}
/**
* Verify consensus mathematically
*/
async verify(
agentStates: { id: string; embedding: Float32Array; vote: boolean }[],
threshold: number = 0.8
): Promise<{
verified: boolean;
coherenceEnergy: CoherenceEnergy;
spectralStability: boolean;
agreementRatio: number;
}> {
// Check coherence of agent states
const vectors = agentStates.map(s => s.embedding);
const coherenceResult = await this.bridge.checkCoherence(vectors);
const coherenceEnergy = CoherenceEnergy.create(coherenceResult.energy);
// Build adjacency from vote agreement
const n = agentStates.length;
const adj = new Float32Array(n * n);
for (let i = 0; i < n; i++) {
for (let j = 0; j < n; j++) {
adj[i * n + j] = agentStates[i].vote === agentStates[j].vote ? 1 : 0;
}
}
// Analyze spectral stability
const stability = await this.stabilityAnalyzer.analyze(
adj,
'consensus',
`consensus-${Date.now()}`,
this.bridge.getSpectralEngine()
);
// Calculate agreement ratio
const yesVotes = agentStates.filter(s => s.vote).length;
const agreementRatio = Math.max(yesVotes, n - yesVotes) / n;
const verified = coherenceEnergy.isCoherent() &&
stability.spectralGap.isStable() &&
agreementRatio >= threshold;
return {
verified,
coherenceEnergy,
spectralStability: stability.spectralGap.isStable(),
agreementRatio
};
}
}
/**
* Domain Event: Coherence Violation Detected
*/
interface CoherenceViolationDetected {
type: 'CoherenceViolationDetected';
timestamp: Date;
checkId: string;
energy: number;
violations: string[];
namespace: string;
action: 'warn' | 'reject';
}
/**
* Domain Event: Stability Threshold Breached
*/
interface StabilityThresholdBreached {
type: 'StabilityThresholdBreached';
timestamp: Date;
analysisId: string;
sourceType: 'swarm' | 'consensus' | 'memory';
sourceId: string;
spectralGap: number;
recommendations: string[];
}
/**
* Domain Event: Consensus Verification Failed
*/
interface ConsensusVerificationFailed {
type: 'ConsensusVerificationFailed';
timestamp: Date;
proposalId: string;
coherenceEnergy: number;
agreementRatio: number;
reason: string;
}
/**
* Repository for persisting coherence checks
*/
interface CoherenceCheckRepository {
save(check: CoherenceCheck): Promise<void>;
findById(id: string): Promise<CoherenceCheck | null>;
findByNamespace(namespace: string, limit?: number): Promise<CoherenceCheck[]>;
findRejected(since: Date): Promise<CoherenceCheck[]>;
}
/**
* Repository for persisting stability analyses
*/
interface StabilityAnalysisRepository {
save(analysis: StabilityAnalysis): Promise<void>;
findById(id: string): Promise<StabilityAnalysis | null>;
findBySource(sourceType: string, sourceId: string): Promise<StabilityAnalysis[]>;
findUnhealthy(since: Date): Promise<StabilityAnalysis[]>;
}
/**
* Repository for persisting causal queries
*/
interface CausalQueryRepository {
save(query: CausalQuery): Promise<void>;
findById(id: string): Promise<CausalQuery | null>;
findByTreatment(treatment: string): Promise<CausalQuery[]>;
findInvalid(since: Date): Promise<CausalQuery[]>;
}