agentic-qe 3.8.10 → 3.8.12

package/dist/integrations/ruvector/coherence-gate-core.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Coherence Gate - Core Module (Task 3.1, ADR-083)
+ *
+ * CoherenceGate class, public API, types, and factory functions.
+ * Validates AI-generated test artifacts using heuristic coherence scoring
+ * based on word-level feature similarity.
+ *
+ * @module integrations/ruvector/coherence-gate-core
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+import type { ITransferCoherenceGate, CoherenceValidation } from './transfer-coherence-stub.js';
+import type { WitnessChain as GovernanceWitnessChain } from '../../governance/witness-chain.js';
+import type { GateType } from './cusum-detector.js';
+/**
+ * Test artifact to validate for coherence.
+ */
+export interface TestArtifact {
+    /** Assertions made by the generated test */
+    assertions: string[];
+    /** Observed behaviors from actual execution */
+    observedBehavior: string[];
+    /** Code coverage ratio (0-1) */
+    coverage: number;
+    /** Domain the test belongs to */
+    domain: string;
+    /** Confidence score of the generator (0-1) */
+    confidence: number;
+}
+/**
+ * Result of coherence energy computation.
+ */
+export interface CoherenceResult {
+    /** Coherence energy score (0-1, lower = more coherent) */
+    energy: number;
+    /** Which compute tier was used */
+    tier: 'reflex' | 'retrieval';
+    /** Breakdown of energy components */
+    components: EnergyComponents;
+    /** Computation latency in milliseconds */
+    latencyMs: number;
+}
+/**
+ * Breakdown of energy components for explainability.
+ */
+export interface EnergyComponents {
+    /** Energy from assertion-observation mismatch (0-1) */
+    assertionCoverage: number;
+    /** Energy from low code coverage (0-1) */
+    codeCoverage: number;
+    /** Energy from low confidence (0-1) */
+    confidencePenalty: number;
+    /** Energy from contradiction detection (0-1, retrieval only) */
+    contradictionScore: number;
+    /** Energy from sheaf Laplacian deviation (0-1, retrieval only) */
+    laplacianDeviation: number;
+}
+/**
+ * Result of validation against a threshold.
+ */
+export interface ValidationResult {
+    /** Whether the artifact passes coherence validation */
+    passed: boolean;
+    /** The coherence energy score */
+    energy: number;
+    /** The threshold used for validation */
+    threshold: number;
+    /** Human-readable reason if validation failed */
+    reason?: string;
+    /** The witness record for this decision */
+    witness: WitnessRecord;
+}
+/**
+ * Hash-chained witness record for audit trail.
+ */
+export interface WitnessRecord {
+    /** Unique record identifier */
+    id: string;
+    /** Timestamp of the decision */
+    timestamp: number;
+    /** Hash of the artifact that was validated */
+    artifactHash: string;
+    /** The coherence energy computed */
+    energy: number;
+    /** The threshold applied */
+    threshold: number;
+    /** Whether validation passed */
+    passed: boolean;
+    /** Hash of the previous witness record */
+    previousHash: string;
+    /** Hash of this record (chained) */
+    recordHash: string;
+}
+/**
+ * Decision log entry for observability.
+ */
+export interface CoherenceDecision {
+    /** Unique decision identifier */
+    id: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Domain of the artifact */
+    domain: string;
+    /** Computed energy */
+    energy: number;
+    /** Compute tier used */
+    tier: 'reflex' | 'retrieval';
+    /** Whether validation passed */
+    passed: boolean;
+    /** Threshold used */
+    threshold: number;
+}
+/** Default coherence threshold (Normal regime) */
+export declare const DEFAULT_COHERENCE_THRESHOLD = 0.4;
+/**
+ * Coherence gate for validating AI-generated test artifacts.
+ *
+ * Uses word-level heuristic coherence scoring to detect hallucinated or
+ * inconsistent test outputs. Implements ITransferCoherenceGate for
+ * cross-domain transfer validation compatibility.
+ *
+ * @example
+ * ```typescript
+ * const gate = new CoherenceGate();
+ * const result = gate.validate({
+ *   assertions: ['expect(result).toBe(true)'],
+ *   observedBehavior: ['result was true'],
+ *   coverage: 0.85,
+ *   domain: 'test-generation',
+ *   confidence: 0.9,
+ * });
+ * if (!result.passed) {
+ *   console.warn('Artifact may be hallucinated:', result.reason);
+ * }
+ * ```
+ */
+export declare class CoherenceGate implements ITransferCoherenceGate {
+    private readonly threshold;
+    private decisionLog;
+    private witnessChain;
+    private lastWitnessHash;
+    private nativeAvailable;
+    /** Optional governance witness chain for SQLite persistence */
+    private governanceChain;
+    constructor(threshold?: number);
+    /**
+     * Attach a governance WitnessChain (or PersistentWitnessChain) for
+     * durable persistence of coherence decisions.
+     */
+    setGovernanceChain(chain: GovernanceWitnessChain): void;
+    /**
+     * Compute coherence energy for a test artifact.
+     *
+     * Uses a two-tier compute ladder:
+     * - Reflex (<1ms): Simple heuristic checks
+     * - Retrieval (~10ms): Full sheaf Laplacian computation
+     *
+     * @param artifact - Test artifact to evaluate
+     * @param forceRetrieval - Skip reflex tier and go straight to retrieval
+     * @param gateType - Gate action type for CUSUM drift tracking (default: 'retrieve')
+     */
+    computeEnergy(artifact: TestArtifact, forceRetrieval?: boolean, gateType?: GateType): CoherenceResult;
+    /**
+     * Validate a test artifact against the coherence threshold.
+     *
+     * @param artifact - Test artifact to validate
+     * @param threshold - Optional override threshold (default: constructor threshold)
+     * @param gateType - Gate action type for CUSUM drift tracking (default: 'retrieve')
+     */
+    validate(artifact: TestArtifact, threshold?: number, gateType?: GateType): ValidationResult;
+    /** Get the decision log for observability. */
+    getDecisionLog(): CoherenceDecision[];
+    /** Get the witness chain for audit purposes. */
+    getWitnessChain(): WitnessRecord[];
+    /** Get the current threshold. */
+    getThreshold(): number;
+    /** Clear the decision log (for testing). */
+    clearDecisionLog(): void;
+    validateTransfer(pattern: {
+        id?: string;
+        domain?: string;
+        confidence?: number;
+        [key: string]: unknown;
+    }, targetDomain: string): CoherenceValidation;
+    private buildFailureReason;
+    private createWitnessRecord;
+    private hashContent;
+    private logDecision;
+    private extractAssertions;
+    private extractObservedBehavior;
+}
+/**
+ * Create a coherence gate instance.
+ */
+export declare function createCoherenceGate(threshold?: number, governanceChain?: GovernanceWitnessChain): CoherenceGate;
+/**
+ * Create a transfer coherence gate.
+ * Returns the real CoherenceGate implementation (replacing the stub).
+ */
+export declare function createRealTransferCoherenceGate(): ITransferCoherenceGate;
+//# sourceMappingURL=coherence-gate-core.d.ts.map

package/dist/integrations/ruvector/coherence-gate-core.js

@@ -0,0 +1,294 @@
+/**
+ * Coherence Gate - Core Module (Task 3.1, ADR-083)
+ *
+ * CoherenceGate class, public API, types, and factory functions.
+ * Validates AI-generated test artifacts using heuristic coherence scoring
+ * based on word-level feature similarity.
+ *
+ * @module integrations/ruvector/coherence-gate-core
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+import { createHash, randomUUID } from 'crypto';
+import { LoggerFactory } from '../../logging/index.js';
+import { getRuVectorFeatureFlags } from './feature-flags.js';
+import { computeReflexEnergy, computeRetrievalEnergy, REFLEX_LATENCY_BUDGET_MS, } from './coherence-gate-energy.js';
+const logger = LoggerFactory.create('coherence-gate');
+/** Default coherence threshold (Normal regime) */
+export const DEFAULT_COHERENCE_THRESHOLD = 0.4;
+// ============================================================================
+// Coherence Gate Implementation
+// ============================================================================
+/**
+ * Coherence gate for validating AI-generated test artifacts.
+ *
+ * Uses word-level heuristic coherence scoring to detect hallucinated or
+ * inconsistent test outputs. Implements ITransferCoherenceGate for
+ * cross-domain transfer validation compatibility.
+ *
+ * @example
+ * ```typescript
+ * const gate = new CoherenceGate();
+ * const result = gate.validate({
+ *   assertions: ['expect(result).toBe(true)'],
+ *   observedBehavior: ['result was true'],
+ *   coverage: 0.85,
+ *   domain: 'test-generation',
+ *   confidence: 0.9,
+ * });
+ * if (!result.passed) {
+ *   console.warn('Artifact may be hallucinated:', result.reason);
+ * }
+ * ```
+ */
+export class CoherenceGate {
+    threshold;
+    decisionLog = [];
+    witnessChain = [];
+    lastWitnessHash = '0'.repeat(64);
+    nativeAvailable = null;
+    /** Optional governance witness chain for SQLite persistence */
+    governanceChain = null;
+    constructor(threshold = DEFAULT_COHERENCE_THRESHOLD) {
+        this.threshold = threshold;
+    }
+    /**
+     * Attach a governance WitnessChain (or PersistentWitnessChain) for
+     * durable persistence of coherence decisions.
+     */
+    setGovernanceChain(chain) {
+        this.governanceChain = chain;
+    }
+    // ==========================================================================
+    // Core API
+    // ==========================================================================
+    /**
+     * Compute coherence energy for a test artifact.
+     *
+     * Uses a two-tier compute ladder:
+     * - Reflex (<1ms): Simple heuristic checks
+     * - Retrieval (~10ms): Full sheaf Laplacian computation
+     *
+     * @param artifact - Test artifact to evaluate
+     * @param forceRetrieval - Skip reflex tier and go straight to retrieval
+     * @param gateType - Gate action type for CUSUM drift tracking (default: 'retrieve')
+     */
+    computeEnergy(artifact, forceRetrieval = false, gateType = 'retrieve') {
+        const startTime = performance.now();
+        // Tier 1: Reflex check
+        if (!forceRetrieval) {
+            const reflexResult = computeReflexEnergy(artifact, gateType);
+            const reflexLatency = performance.now() - startTime;
+            if (reflexLatency <= REFLEX_LATENCY_BUDGET_MS) {
+                return {
+                    energy: reflexResult.energy,
+                    tier: 'reflex',
+                    components: reflexResult.components,
+                    latencyMs: reflexLatency,
+                };
+            }
+        }
+        // Tier 2: Full retrieval computation
+        const retrievalResult = computeRetrievalEnergy(artifact, gateType);
+        const latencyMs = performance.now() - startTime;
+        return {
+            energy: retrievalResult.energy,
+            tier: 'retrieval',
+            components: retrievalResult.components,
+            latencyMs,
+        };
+    }
+    /**
+     * Validate a test artifact against the coherence threshold.
+     *
+     * @param artifact - Test artifact to validate
+     * @param threshold - Optional override threshold (default: constructor threshold)
+     * @param gateType - Gate action type for CUSUM drift tracking (default: 'retrieve')
+     */
+    validate(artifact, threshold, gateType = 'retrieve') {
+        const effectiveThreshold = threshold ?? this.threshold;
+        const coherenceResult = this.computeEnergy(artifact, false, gateType);
+        const passed = coherenceResult.energy <= effectiveThreshold;
+        // Build reason for failure
+        let reason;
+        if (!passed) {
+            reason = this.buildFailureReason(coherenceResult, effectiveThreshold);
+        }
+        // Create witness record
+        const witness = this.createWitnessRecord(artifact, coherenceResult.energy, effectiveThreshold, passed);
+        // Log decision
+        this.logDecision({
+            id: witness.id,
+            timestamp: witness.timestamp,
+            domain: artifact.domain,
+            energy: coherenceResult.energy,
+            tier: coherenceResult.tier,
+            passed,
+            threshold: effectiveThreshold,
+        });
+        return {
+            passed,
+            energy: coherenceResult.energy,
+            threshold: effectiveThreshold,
+            reason,
+            witness,
+        };
+    }
+    /** Get the decision log for observability. */
+    getDecisionLog() {
+        return [...this.decisionLog];
+    }
+    /** Get the witness chain for audit purposes. */
+    getWitnessChain() {
+        return [...this.witnessChain];
+    }
+    /** Get the current threshold. */
+    getThreshold() {
+        return this.threshold;
+    }
+    /** Clear the decision log (for testing). */
+    clearDecisionLog() {
+        this.decisionLog = [];
+    }
+    // ==========================================================================
+    // ITransferCoherenceGate Implementation
+    // ==========================================================================
+    validateTransfer(pattern, targetDomain) {
+        const flags = getRuVectorFeatureFlags();
+        if (!flags.useCoherenceGate) {
+            return { approved: true };
+        }
+        const artifact = {
+            assertions: this.extractAssertions(pattern),
+            observedBehavior: this.extractObservedBehavior(pattern),
+            coverage: typeof pattern.coverage === 'number' ? pattern.coverage : 0.5,
+            domain: targetDomain,
+            confidence: pattern.confidence ?? 0.5,
+        };
+        // Transfer validation uses 'write' gate type for CUSUM tracking
+        const result = this.validate(artifact, undefined, 'write');
+        return {
+            approved: result.passed,
+            energy: result.energy,
+            rejectionReason: result.reason,
+        };
+    }
+    // ==========================================================================
+    // Private Helpers
+    // ==========================================================================
+    buildFailureReason(result, threshold) {
+        const parts = [];
+        parts.push(`Coherence energy ${result.energy.toFixed(3)} exceeds threshold ${threshold.toFixed(3)}.`);
+        const c = result.components;
+        if (c.assertionCoverage > 0.5) {
+            parts.push('High assertion-observation mismatch (possible hallucination).');
+        }
+        if (c.codeCoverage > 0.5) {
+            parts.push('Low code coverage.');
+        }
+        if (c.confidencePenalty > 0.5) {
+            parts.push('Low generator confidence.');
+        }
+        if (c.contradictionScore > 0.3) {
+            parts.push('Contradictions detected between assertions and observed behavior.');
+        }
+        if (c.laplacianDeviation > 0.5) {
+            parts.push('Inconsistent assertion structure (high Laplacian deviation).');
+        }
+        return parts.join(' ');
+    }
+    createWitnessRecord(artifact, energy, threshold, passed) {
+        const id = randomUUID();
+        const timestamp = Date.now();
+        const artifactHash = this.hashContent(JSON.stringify(artifact));
+        const record = {
+            id,
+            timestamp,
+            artifactHash,
+            energy,
+            threshold,
+            passed,
+            previousHash: this.lastWitnessHash,
+            recordHash: '',
+        };
+        // Compute record hash (chain link)
+        const hashPayload = `${id}|${timestamp}|${artifactHash}|${energy}|${threshold}|${passed}|${this.lastWitnessHash}`;
+        record.recordHash = this.hashContent(hashPayload);
+        // Update chain
+        const flags = getRuVectorFeatureFlags();
+        if (flags.useWitnessChain) {
+            this.witnessChain.push(record);
+            this.lastWitnessHash = record.recordHash;
+            // Persist to governance chain if attached
+            if (this.governanceChain) {
+                try {
+                    const governanceDecision = {
+                        type: 'coherence-gate',
+                        decision: passed ? 'PASS' : 'FAIL',
+                        context: { energy, threshold, artifactHash: record.artifactHash },
+                    };
+                    this.governanceChain.appendWitness(governanceDecision);
+                }
+                catch (err) {
+                    logger.debug('Failed to persist to governance chain', { error: String(err) });
+                }
+            }
+        }
+        return record;
+    }
+    hashContent(content) {
+        return createHash('sha256').update(content).digest('hex');
+    }
+    logDecision(decision) {
+        this.decisionLog.push(decision);
+        // Keep bounded
+        const maxLog = 1000;
+        if (this.decisionLog.length > maxLog) {
+            this.decisionLog = this.decisionLog.slice(-maxLog);
+        }
+        logger.debug('Coherence decision', {
+            domain: decision.domain,
+            energy: decision.energy,
+            tier: decision.tier,
+            passed: decision.passed,
+        });
+    }
+    extractAssertions(pattern) {
+        if (Array.isArray(pattern.assertions)) {
+            return pattern.assertions.map(String);
+        }
+        if (typeof pattern.description === 'string') {
+            return [pattern.description];
+        }
+        return ['transfer-pattern'];
+    }
+    extractObservedBehavior(pattern) {
+        if (Array.isArray(pattern.observedBehavior)) {
+            return pattern.observedBehavior.map(String);
+        }
+        if (typeof pattern.evidence === 'string') {
+            return [pattern.evidence];
+        }
+        return ['observed'];
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a coherence gate instance.
+ */
+export function createCoherenceGate(threshold, governanceChain) {
+    const gate = new CoherenceGate(threshold);
+    if (governanceChain) {
+        gate.setGovernanceChain(governanceChain);
+    }
+    return gate;
+}
+/**
+ * Create a transfer coherence gate.
+ * Returns the real CoherenceGate implementation (replacing the stub).
+ */
+export function createRealTransferCoherenceGate() {
+    return new CoherenceGate();
+}
+//# sourceMappingURL=coherence-gate-core.js.map

package/dist/integrations/ruvector/coherence-gate-energy.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Coherence Gate - Energy Computation
+ *
+ * Two-tier compute ladder for coherence energy:
+ *   - Reflex (<1ms): Simple heuristic checks (assertion count, coverage overlap)
+ *   - Retrieval (~10ms): Full word-frequency coherence computation with
+ *     contradiction detection and sheaf Laplacian deviation
+ *
+ * @module integrations/ruvector/coherence-gate-energy
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+import { type ICohomologyEngine } from './coherence-gate-cohomology.js';
+import { CusumDetector, type CusumResult, type GateType } from './cusum-detector.js';
+import type { TestArtifact, EnergyComponents } from './coherence-gate-core.js';
+/** Payload emitted when CUSUM drift is detected */
+export interface DriftDetectedPayload {
+    gateType: GateType;
+    energy: number;
+    cusumResult: CusumResult;
+    timestamp: number;
+}
+/** Callback type for drift detection events */
+export type DriftDetectedListener = (payload: DriftDetectedPayload) => void;
+/**
+ * Get the module-level CUSUM detector.
+ * Auto-creates if the feature flag is enabled.
+ */
+export declare function getCusumDetector(): CusumDetector | null;
+/**
+ * Enable CUSUM drift monitoring on energy computations.
+ * Once enabled, every energy computation feeds the
+ * CUSUM detector and may emit 'drift-detected' events.
+ *
+ * Note: With useCusumDriftDetection feature flag enabled, the detector
+ * is auto-created on first use. This function allows manual creation
+ * with custom config when the flag is off.
+ */
+export declare function enableCusumMonitoring(config?: Partial<{
+    threshold: number;
+    slack: number;
+    resetOnAlarm: boolean;
+    warmupSamples: number;
+}>): CusumDetector;
+/**
+ * Disable CUSUM drift monitoring and clear all listeners.
+ */
+export declare function disableCusumMonitoring(): void;
+/**
+ * Register a listener for 'drift-detected' events.
+ * Returns an unsubscribe function.
+ */
+export declare function onDriftDetected(listener: DriftDetectedListener): () => void;
+/**
+ * Get and drain recent drift events (for EventBus polling integration).
+ * Returns all accumulated drift events and clears the buffer.
+ * Consumers (e.g. coordinators) can poll this in their tick loop and
+ * forward to EventBus.emit('cusum:drift-detected', event).
+ */
+export declare function drainDriftEvents(): DriftDetectedPayload[];
+/** Weights for energy component computation */
+export declare const ENERGY_WEIGHTS: {
+    readonly assertionCoverage: 0.4;
+    readonly codeCoverage: 0.3;
+    readonly confidencePenalty: 0.3;
+    readonly contradictionWeight: 0.2;
+    readonly laplacianWeight: 0.15;
+};
+/** Reflex tier latency cutoff in ms */
+export declare const REFLEX_LATENCY_BUDGET_MS = 1;
+/**
+ * Compute assertion coverage energy.
+ * High energy when assertions far exceed observed behavior (hallucination signal).
+ */
+export declare function computeAssertionCoverageEnergy(artifact: TestArtifact): number;
+/**
+ * Compute code coverage energy.
+ * Higher energy for lower coverage.
+ */
+export declare function computeCodeCoverageEnergy(artifact: TestArtifact): number;
+/**
+ * Compute confidence penalty.
+ * Higher energy for lower confidence.
+ */
+export declare function computeConfidencePenalty(artifact: TestArtifact): number;
+/**
+ * Detect contradictions between assertions and observed behavior.
+ *
+ * Simple heuristic: look for negation patterns and semantic opposites
+ * in the assertion/behavior pairing.
+ */
+export declare function detectContradictions(artifact: TestArtifact): number;
+/**
+ * Compute Laplacian deviation using the native CohomologyEngine.
+ * Builds a sheaf graph where each assertion is a node and related
+ * assertion pairs form edges with identity restriction maps.
+ */
+export declare function computeNativeLaplacianDeviation(engine: ICohomologyEngine, artifact: TestArtifact, vectors: number[][]): number;
+/**
+ * Fallback: compute pairwise word-frequency cosine consistency score.
+ */
+export declare function computeFallbackLaplacianDeviation(vectors: number[][]): number;
+/**
+ * Compute coherence deviation using sheaf Laplacian energy.
+ *
+ * When `prime-radiant-advanced-wasm` CohomologyEngine is available,
+ * builds a sheaf graph from assertion vectors and computes real sheaf
+ * Laplacian consistency energy. Falls back to pairwise word-frequency
+ * cosine similarity when the WASM module is unavailable.
+ *
+ * Uses 64-dim word-level feature hashing with FNV-1a for bucket assignment
+ * and L2-normalized term-frequency vectors.
+ */
+export declare function computeLaplacianDeviation(artifact: TestArtifact): number;
+/**
+ * Reflex-tier energy computation using simple heuristics.
+ * Must complete in <1ms.
+ *
+ * @param artifact - Test artifact to compute energy for
+ * @param gateType - Gate action type for CUSUM tracking (default: 'act')
+ */
+export declare function computeReflexEnergy(artifact: TestArtifact, gateType?: GateType): {
+    energy: number;
+    components: EnergyComponents;
+};
+/**
+ * Retrieval-tier energy computation using sheaf Laplacian.
+ * Includes contradiction detection and Laplacian deviation.
+ *
+ * @param artifact - Test artifact to compute energy for
+ * @param gateType - Gate action type for CUSUM tracking (default: 'retrieve')
+ */
+export declare function computeRetrievalEnergy(artifact: TestArtifact, gateType?: GateType): {
+    energy: number;
+    components: EnergyComponents;
+};
+//# sourceMappingURL=coherence-gate-energy.d.ts.map