agentic-qe 3.7.21 → 3.8.0

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

@@ -0,0 +1,309 @@
+/**
+ * Coherence Gate (Task 3.1, ADR-083)
+ *
+ * Validates AI-generated test artifacts using heuristic coherence scoring
+ * based on word-level feature similarity. Detects hallucinated or inconsistent
+ * test outputs by measuring the energy deviation from expected pattern consistency.
+ *
+ * Compute ladder:
+ *   - Reflex (<1ms): Simple heuristic checks (assertion count, coverage overlap)
+ *   - Retrieval (~10ms): Full word-frequency coherence computation
+ *
+ * Implements ITransferCoherenceGate for cross-domain transfer validation.
+ * Uses Blake3 hash-chained witness records for audit trail.
+ *
+ * @module integrations/ruvector/coherence-gate
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+import type { ITransferCoherenceGate, CoherenceValidation } from './transfer-coherence-stub.js';
+/**
+ * Reset the CohomologyEngine loader state (for testing).
+ */
+export declare function resetCohomologyEngineLoader(): void;
+/**
+ * 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;
+    constructor(threshold?: number);
+    /**
+     * 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 - The test artifact to evaluate
+     * @param forceRetrieval - If true, skip reflex and go straight to retrieval
+     * @returns Coherence result with energy score and component breakdown
+     */
+    computeEnergy(artifact: TestArtifact, forceRetrieval?: boolean): CoherenceResult;
+    /**
+     * Validate a test artifact against the coherence threshold.
+     *
+     * @param artifact - The test artifact to validate
+     * @param threshold - Optional override for the default threshold
+     * @returns Validation result with witness record
+     */
+    validate(artifact: TestArtifact, threshold?: number): 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;
+    /**
+     * Validate whether a pattern can be transferred to a target domain
+     * without introducing coherence violations.
+     *
+     * Converts the pattern into a TestArtifact and runs coherence validation.
+     */
+    validateTransfer(pattern: {
+        id?: string;
+        domain?: string;
+        confidence?: number;
+        [key: string]: unknown;
+    }, targetDomain: string): CoherenceValidation;
+    /**
+     * Reflex-tier energy computation using simple heuristics.
+     * Must complete in <1ms.
+     */
+    private computeReflexEnergy;
+    /**
+     * Retrieval-tier energy computation using sheaf Laplacian.
+     * Includes contradiction detection and Laplacian deviation.
+     */
+    private computeRetrievalEnergy;
+    /**
+     * Compute assertion coverage energy.
+     * High energy when assertions far exceed observed behavior (hallucination signal).
+     */
+    private computeAssertionCoverageEnergy;
+    /**
+     * Compute code coverage energy.
+     * Higher energy for lower coverage.
+     */
+    private computeCodeCoverageEnergy;
+    /**
+     * Compute confidence penalty.
+     * Higher energy for lower confidence.
+     */
+    private computeConfidencePenalty;
+    /**
+     * Detect contradictions between assertions and observed behavior.
+     *
+     * Simple heuristic: look for negation patterns and semantic opposites
+     * in the assertion/behavior pairing.
+     */
+    private detectContradictions;
+    /**
+     * 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.
+     */
+    private computeLaplacianDeviation;
+    /**
+     * 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.
+     */
+    private computeNativeLaplacianDeviation;
+    /**
+     * Fallback: compute pairwise word-frequency cosine consistency score.
+     */
+    private computeFallbackLaplacianDeviation;
+    /**
+     * Hash a word to a bucket index 0-63 using FNV-1a.
+     */
+    private hashWord;
+    /**
+     * Convert text to a 64-dim word-level feature vector using feature hashing.
+     *
+     * Tokenizes on whitespace and punctuation, hashes each word to one of 64
+     * buckets via FNV-1a, builds a term-frequency vector, and L2-normalizes it.
+     */
+    private textToWordFeatureVector;
+    /**
+     * Compute cosine similarity between two vectors.
+     */
+    private cosineSimilarity;
+    /**
+     * Build a human-readable failure reason from coherence results.
+     */
+    private buildFailureReason;
+    /**
+     * Create a Blake3-style hash-chained witness record.
+     * Falls back to SHA-256 when Blake3 is unavailable.
+     */
+    private createWitnessRecord;
+    /**
+     * Hash content using SHA-256 (Blake3 fallback).
+     */
+    private hashContent;
+    /**
+     * Log a coherence decision for observability.
+     */
+    private logDecision;
+    /**
+     * Extract assertions from a transfer pattern object.
+     */
+    private extractAssertions;
+    /**
+     * Extract observed behaviors from a transfer pattern object.
+     */
+    private extractObservedBehavior;
+}
+/**
+ * Create a coherence gate instance.
+ *
+ * @param threshold - Coherence energy threshold (default: 0.4)
+ * @returns A new CoherenceGate instance
+ */
+export declare function createCoherenceGate(threshold?: number): CoherenceGate;
+/**
+ * Create a transfer coherence gate.
+ *
+ * Returns the real CoherenceGate implementation (replacing the stub).
+ * The CoherenceGate implements ITransferCoherenceGate.
+ */
+export declare function createRealTransferCoherenceGate(): ITransferCoherenceGate;
+//# sourceMappingURL=coherence-gate.d.ts.map