agentic-qe 3.7.21 → 3.8.0

package/dist/domains/visual-accessibility/cnn-visual-regression.js

@@ -0,0 +1,327 @@
+/**
+ * Agentic QE v3 - CNN Visual Regression Testing
+ *
+ * TypeScript spatial pooling visual regression with optional Sobel edge detection.
+ * No native CNN package exists — the spatial pooling implementation IS the
+ * production implementation.
+ *
+ * - TypeScript spatial-pooling (8x8 grid, RGB channels)
+ * - Optional Sobel edge detection for gradient/structural change sensitivity
+ * - Supports regions of interest masking to ignore dynamic areas
+ * - Contrastive threshold learning from labeled positive/negative pairs
+ *
+ * @module domains/visual-accessibility/cnn-visual-regression
+ */
+/**
+ * Compute cosine similarity between two vectors of equal length.
+ * Returns 0 if either vector has zero norm.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector length mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+/** L2-normalize a vector in place and return it. */
+function l2Normalize(vec) {
+    let norm = 0;
+    for (let i = 0; i < vec.length; i++)
+        norm += vec[i] * vec[i];
+    norm = Math.sqrt(norm);
+    if (norm > 0) {
+        for (let i = 0; i < vec.length; i++)
+            vec[i] /= norm;
+    }
+    return vec;
+}
+/**
+ * CNN-based visual regression testing using embedding comparison.
+ *
+ * Images are projected into a compact embedding space via spatial average
+ * pooling. Cosine similarity determines whether two images represent the
+ * same visual state.
+ *
+ * @example
+ * ```typescript
+ * const cnn = new CNNVisualRegression();
+ * const baseline = cnn.computeEmbedding(baselinePixels, 1024, 768);
+ * const current = cnn.computeEmbedding(currentPixels, 1024, 768);
+ * if (cnn.isRegression(baseline, current)) {
+ *   console.log('Visual regression detected!');
+ * }
+ * ```
+ */
+export class CNNVisualRegression {
+    defaultThreshold;
+    defaultGridSize;
+    tryNative;
+    useEdgeDetection;
+    nativeBackend = null;
+    nativeLoadAttempted = false;
+    constructor(config) {
+        this.defaultThreshold = config?.defaultThreshold ?? 0.95;
+        this.defaultGridSize = config?.defaultGridSize ?? 8;
+        this.tryNative = config?.tryNativeBackend ?? true;
+        this.useEdgeDetection = config?.useEdgeDetection ?? false;
+    }
+    /**
+     * Check for native CNN backend.
+     * No native package exists — always returns false.
+     * The TypeScript spatial pooling implementation is used.
+     */
+    async tryLoadNativeBackend() {
+        if (this.nativeLoadAttempted)
+            return this.nativeBackend !== null;
+        this.nativeLoadAttempted = true;
+        return false;
+    }
+    /**
+     * Compute a feature embedding for an image using spatial average pooling.
+     * When edge detection is enabled (via config or options), the embedding
+     * concatenates spatial pooling of the original pixels with spatial pooling
+     * of the Sobel edge map, then L2-normalizes the result.
+     *
+     * @param imageData Raw pixel data in RGBA format (4 bytes per pixel)
+     * @param width Image width in pixels
+     * @param height Image height in pixels
+     * @param options Configuration for grid size, masking, and edge detection
+     * @returns L2-normalized embedding vector
+     */
+    computeEmbedding(imageData, width, height, options) {
+        this.validateImageInput(imageData, width, height);
+        const gridSize = options?.gridSize ?? this.defaultGridSize;
+        const channels = options?.channels ?? 3;
+        let pixels = imageData;
+        if (options?.maskRegions && options.maskRegions.length > 0) {
+            pixels = this.applyMask(imageData, width, height, options.maskRegions);
+        }
+        const edgeEnabled = this.useEdgeDetection || (options?.useEdgeDetection === true);
+        if (edgeEnabled) {
+            const spatialEmbed = this.computeSpatialPoolingEmbedding(pixels, width, height, gridSize, channels);
+            const edgeMap = this.applySobelEdgeDetection(pixels, width, height);
+            const edgeEmbed = this.computeSpatialPoolingEmbedding(edgeMap, width, height, gridSize, channels);
+            const combined = new Float32Array(spatialEmbed.length + edgeEmbed.length);
+            combined.set(spatialEmbed, 0);
+            combined.set(edgeEmbed, spatialEmbed.length);
+            return l2Normalize(combined);
+        }
+        return this.computeSpatialPoolingEmbedding(pixels, width, height, gridSize, channels);
+    }
+    /** Compute embedding asynchronously, attempting native backend first. */
+    async computeEmbeddingAsync(imageData, width, height, options) {
+        this.validateImageInput(imageData, width, height);
+        const hasNative = await this.tryLoadNativeBackend();
+        if (hasNative && this.nativeBackend) {
+            let pixels = imageData;
+            if (options?.maskRegions && options.maskRegions.length > 0) {
+                pixels = this.applyMask(imageData, width, height, options.maskRegions);
+            }
+            return this.nativeBackend.computeEmbedding(pixels, width, height);
+        }
+        return this.computeEmbedding(imageData, width, height, options);
+    }
+    /** Compare two embeddings and produce a detailed comparison result. */
+    compare(baseline, current, threshold) {
+        const t = threshold ?? this.defaultThreshold;
+        const similarity = cosineSimilarity(baseline, current);
+        return { similarity, isMatch: similarity >= t, threshold: t };
+    }
+    /**
+     * Compare embeddings with per-region analysis. Computes per-region
+     * similarity alongside the global similarity.
+     */
+    compareWithRegions(baseline, current, regions, imageWidth, imageHeight, threshold) {
+        const t = threshold ?? this.defaultThreshold;
+        const globalSimilarity = cosineSimilarity(baseline, current);
+        const gridSize = this.defaultGridSize;
+        const channels = 3;
+        const regionSimilarities = regions.map((region, regionIndex) => ({
+            regionIndex,
+            similarity: this.computeRegionSimilarity(baseline, current, region, imageWidth, imageHeight, gridSize, channels),
+        }));
+        return { similarity: globalSimilarity, isMatch: globalSimilarity >= t, threshold: t, regionSimilarities };
+    }
+    /** Check if a visual regression has occurred (similarity below threshold). */
+    isRegression(baseline, current, threshold) {
+        return cosineSimilarity(baseline, current) < (threshold ?? this.defaultThreshold);
+    }
+    /**
+     * Learn an optimal threshold from labeled positive/negative pairs.
+     * Sweeps candidate thresholds and picks the one maximizing accuracy.
+     * @throws Error if no examples or all examples share the same label
+     */
+    learnThreshold(examples) {
+        if (examples.length === 0) {
+            throw new Error('At least one labeled pair is required');
+        }
+        if (!examples.some((e) => e.isMatch) || !examples.some((e) => !e.isMatch)) {
+            throw new Error('Examples must contain both matching and non-matching pairs');
+        }
+        const scored = examples
+            .map((ex) => ({ similarity: cosineSimilarity(ex.embedA, ex.embedB), isMatch: ex.isMatch }))
+            .sort((a, b) => a.similarity - b.similarity);
+        let bestThreshold = 0;
+        let bestAccuracy = 0;
+        for (const { similarity: candidate } of scored) {
+            let correct = 0;
+            for (const item of scored) {
+                if ((item.similarity >= candidate) === item.isMatch)
+                    correct++;
+            }
+            const accuracy = correct / scored.length;
+            if (accuracy > bestAccuracy) {
+                bestAccuracy = accuracy;
+                bestThreshold = candidate;
+            }
+        }
+        return bestThreshold;
+    }
+    computeRegionSimilarity(baseline, current, region, imageWidth, imageHeight, gridSize, channels) {
+        const cellW = imageWidth / gridSize;
+        const cellH = imageHeight / gridSize;
+        const gxStart = Math.max(0, Math.floor(region.x / cellW));
+        const gxEnd = Math.min(gridSize, Math.ceil((region.x + region.width) / cellW));
+        const gyStart = Math.max(0, Math.floor(region.y / cellH));
+        const gyEnd = Math.min(gridSize, Math.ceil((region.y + region.height) / cellH));
+        const regionBaseline = [];
+        const regionCurrent = [];
+        for (let gy = gyStart; gy < gyEnd; gy++) {
+            for (let gx = gxStart; gx < gxEnd; gx++) {
+                const base = (gy * gridSize + gx) * channels;
+                for (let c = 0; c < channels; c++) {
+                    regionBaseline.push(baseline[base + c]);
+                    regionCurrent.push(current[base + c]);
+                }
+            }
+        }
+        if (regionBaseline.length === 0)
+            return 1.0;
+        return cosineSimilarity(new Float32Array(regionBaseline), new Float32Array(regionCurrent));
+    }
+    /** Spatial average pooling: divides image into grid, averages RGB per cell, L2-normalizes. */
+    computeSpatialPoolingEmbedding(pixels, width, height, gridSize, channels) {
+        const embedding = new Float32Array(gridSize * gridSize * channels);
+        const cellW = width / gridSize;
+        const cellH = height / gridSize;
+        for (let gy = 0; gy < gridSize; gy++) {
+            for (let gx = 0; gx < gridSize; gx++) {
+                const sums = new Float64Array(channels);
+                let count = 0;
+                const yStart = Math.floor(gy * cellH);
+                const yEnd = Math.floor((gy + 1) * cellH);
+                const xStart = Math.floor(gx * cellW);
+                const xEnd = Math.floor((gx + 1) * cellW);
+                for (let y = yStart; y < yEnd; y++) {
+                    for (let x = xStart; x < xEnd; x++) {
+                        const idx = (y * width + x) * 4;
+                        for (let c = 0; c < channels; c++)
+                            sums[c] += pixels[idx + c];
+                        count++;
+                    }
+                }
+                const base = (gy * gridSize + gx) * channels;
+                for (let c = 0; c < channels; c++) {
+                    embedding[base + c] = count > 0 ? sums[c] / count / 255 : 0;
+                }
+            }
+        }
+        return l2Normalize(embedding);
+    }
+    /** Zero out pixel data in masked regions. Returns a copy. */
+    applyMask(pixels, width, height, regions) {
+        const masked = new Uint8Array(pixels);
+        for (const region of regions) {
+            const xStart = Math.max(0, Math.min(region.x, width));
+            const xEnd = Math.max(0, Math.min(region.x + region.width, width));
+            const yStart = Math.max(0, Math.min(region.y, height));
+            const yEnd = Math.max(0, Math.min(region.y + region.height, height));
+            for (let y = yStart; y < yEnd; y++) {
+                for (let x = xStart; x < xEnd; x++) {
+                    const idx = (y * width + x) * 4;
+                    masked[idx] = 0;
+                    masked[idx + 1] = 0;
+                    masked[idx + 2] = 0;
+                    masked[idx + 3] = 0;
+                }
+            }
+        }
+        return masked;
+    }
+    /**
+     * Apply Sobel edge detection to an RGBA image.
+     * Converts to grayscale, applies 3x3 Sobel kernels for horizontal and
+     * vertical gradients, computes the magnitude, and returns the result
+     * as RGBA (edge magnitude in R,G,B channels, alpha=255).
+     */
+    applySobelEdgeDetection(pixels, width, height) {
+        // Convert RGBA to grayscale
+        const gray = new Float64Array(width * height);
+        for (let i = 0; i < width * height; i++) {
+            const idx = i * 4;
+            gray[i] = 0.299 * pixels[idx] + 0.587 * pixels[idx + 1] + 0.114 * pixels[idx + 2];
+        }
+        const output = new Uint8Array(width * height * 4);
+        // Sobel kernels
+        // Gx = [[-1,0,1],[-2,0,2],[-1,0,1]]
+        // Gy = [[-1,-2,-1],[0,0,0],[1,2,1]]
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                let gx = 0;
+                let gy = 0;
+                // Apply 3x3 kernel centered at (x, y)
+                for (let ky = -1; ky <= 1; ky++) {
+                    for (let kx = -1; kx <= 1; kx++) {
+                        const sy = Math.min(Math.max(y + ky, 0), height - 1);
+                        const sx = Math.min(Math.max(x + kx, 0), width - 1);
+                        const val = gray[sy * width + sx];
+                        // Gx kernel
+                        if (kx === -1) {
+                            gx -= val * (ky === 0 ? 2 : 1);
+                        }
+                        else if (kx === 1) {
+                            gx += val * (ky === 0 ? 2 : 1);
+                        }
+                        // Gy kernel
+                        if (ky === -1) {
+                            gy -= val * (kx === 0 ? 2 : 1);
+                        }
+                        else if (ky === 1) {
+                            gy += val * (kx === 0 ? 2 : 1);
+                        }
+                    }
+                }
+                const magnitude = Math.min(Math.sqrt(gx * gx + gy * gy), 255);
+                const outIdx = (y * width + x) * 4;
+                const mag = Math.round(magnitude);
+                output[outIdx] = mag;
+                output[outIdx + 1] = mag;
+                output[outIdx + 2] = mag;
+                output[outIdx + 3] = 255;
+            }
+        }
+        return output;
+    }
+    validateImageInput(imageData, width, height) {
+        if (width <= 0 || height <= 0) {
+            throw new Error(`Invalid image dimensions: ${width}x${height}`);
+        }
+        const expectedLength = width * height * 4;
+        if (imageData.length < expectedLength) {
+            throw new Error(`Image data too small: expected at least ${expectedLength} bytes for ${width}x${height} RGBA, got ${imageData.length}`);
+        }
+    }
+    getDefaultThreshold() { return this.defaultThreshold; }
+    getEmbeddingDimension(gridSize) {
+        const base = (gridSize ?? this.defaultGridSize) ** 2 * 3;
+        return this.useEdgeDetection ? base * 2 : base;
+    }
+    isNativeBackendLoaded() { return this.nativeBackend !== null; }
+}
+//# sourceMappingURL=cnn-visual-regression.js.map

package/dist/domains/visual-accessibility/index.d.ts

@@ -12,6 +12,7 @@ export { ResponsiveTesterService, DEVICE_VIEWPORTS, type IResponsiveTestingServi
 export { ViewportCaptureService, createViewportCaptureService, VIEWPORT_PRESETS, DEFAULT_BREAKPOINTS, type IViewportCaptureService, type ViewportPreset, type ViewportCaptureResult, type MultiViewportCaptureResult, type ResponsiveAnalysis as ViewportResponsiveAnalysis, type DetectedBreakpoint, type LayoutShift, type ScreenshotComparisonResult, type ViewportCaptureConfig, type CaptureAllOptions, type BreakpointCaptureOptions, type SingleCaptureOptions, } from './services/viewport-capture.js';
 export { VisualRegressionService, createVisualRegressionService, type VisualRegressionConfig, type BaselineMetadata, type VisualRegressionResult, type VisualRegressionTestOptions, type IVisualRegressionService, } from './services/visual-regression.js';
 export { EUComplianceService, EN_301_549_WEB_CLAUSES, EAA_WEB_REQUIREMENTS, WCAG_TO_EN301549_MAP, getWCAGLevel, type EUComplianceServiceConfig, } from './services/eu-compliance.js';
+export { CNNVisualRegression, cosineSimilarity, type ComparisonResult, type LabeledPair, type RegionOfInterest, type EmbeddingOptions, type CNNVisualRegressionConfig, } from './cnn-visual-regression.js';
 export type { Screenshot, Viewport, ScreenshotMetadata, VisualDiff, DiffRegion, DiffStatus, CaptureOptions, IVisualTestingService, AccessibilityViolation, WCAGCriterion, ViolationNode, ContrastAnalysis, AccessibilityReport, PassedRule, IncompleteCheck, WCAGValidationResult, KeyboardNavigationReport, TabOrderItem, KeyboardIssue, FocusTrap, AuditOptions, IAccessibilityAuditingService, IScreenshotDiffService, AIComparisonResult, DetectedChange, VisualTestReport, VisualTestResult, AccessibilityAuditReport, TopAccessibilityIssue, RemediationPlan, ViolationRemediation, VisualTestingStatus, IVisualAccessibilityCoordinator, IScreenshotRepository, IVisualDiffRepository, IAccessibilityReportRepository, VisualRegressionDetectedEvent, AccessibilityAuditCompletedEvent, BaselineUpdatedEvent, ContrastFailureEvent, EN301549Clause, EAARequirement, EAAProductCategory, EUComplianceResult, EN301549ClauseResult, WCAGtoEN301549Mapping, EUComplianceRecommendation, EUComplianceReport, EAAComplianceResult, EAARequirementResult, EAAExemption, EUComplianceOptions, } from './interfaces.js';
 export { injectAxeCore, runAxeAudit, parseAxeResults, runCompleteAxeAudit, AxeCoreInjectionError, AxeCoreAuditError, WCAG_TAG_MAP, WCAG_CRITERIA_MAP, FIX_SUGGESTIONS, AXE_CORE_CDN_URL, DEFAULT_AXE_CONFIG, type AxeOptions, type AxeResults, type AxeViolation, type AxePass, type AxeIncomplete, type AxeInapplicable, type AxeNode, type AxeCheck, type AxeRelatedNode, type AxeTestEnvironment, type AxeTestRunner, type AxeToolOptions, type AxeCoreConfig, } from './services/axe-core-integration.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/domains/visual-accessibility/index.js

@@ -22,6 +22,10 @@ export { ViewportCaptureService, createViewportCaptureService, VIEWPORT_PRESETS,
 export { VisualRegressionService, createVisualRegressionService, } from './services/visual-regression.js';
 export { EUComplianceService, EN_301_549_WEB_CLAUSES, EAA_WEB_REQUIREMENTS, WCAG_TO_EN301549_MAP, getWCAGLevel, } from './services/eu-compliance.js';
 // ============================================================================
+// CNN Visual Regression (Task 4.3)
+// ============================================================================
+export { CNNVisualRegression, cosineSimilarity, } from './cnn-visual-regression.js';
+// ============================================================================
 // axe-core Integration
 // ============================================================================
 export { 

package/dist/governance/coherence-validator.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Coherence Validator - Governance Pipeline for Test Artifact Validation
+ *
+ * Provides a validation pipeline that uses CoherenceGate to validate
+ * AI-generated test artifacts. Operates in two modes:
+ *
+ * - **Advisory mode** (default): Logs coherence violations but does not block.
+ *   The artifact is always approved with a warning attached.
+ *
+ * - **Blocking mode**: Rejects artifacts that exceed the coherence threshold.
+ *   Must be explicitly enabled via configuration.
+ *
+ * @module governance/coherence-validator
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+import { CoherenceGate, type TestArtifact, type ValidationResult, type CoherenceDecision } from '../integrations/ruvector/coherence-gate.js';
+/**
+ * Configuration for the coherence validation pipeline.
+ */
+export interface CoherenceValidatorConfig {
+    /** Whether to block on coherence violations (default: false = advisory) */
+    blocking: boolean;
+    /** Coherence energy threshold (default: 0.4) */
+    threshold: number;
+    /** Whether to emit warnings to the log in advisory mode (default: true) */
+    logWarnings: boolean;
+}
+/**
+ * Result from the validation pipeline.
+ */
+export interface ValidationPipelineResult {
+    /** Whether the artifact is approved (always true in advisory mode) */
+    approved: boolean;
+    /** The mode used for this validation */
+    mode: 'advisory' | 'blocking';
+    /** The underlying coherence validation result */
+    validation: ValidationResult;
+    /** Warnings generated (populated in advisory mode when energy exceeds threshold) */
+    warnings: string[];
+    /** Whether the coherence gate feature flag was enabled */
+    featureFlagEnabled: boolean;
+}
+/** Default configuration: advisory mode */
+export declare const DEFAULT_COHERENCE_VALIDATOR_CONFIG: CoherenceValidatorConfig;
+/**
+ * Validation pipeline that uses CoherenceGate for test artifact validation.
+ *
+ * Wraps the CoherenceGate with configurable advisory/blocking behavior
+ * and integrates with the governance logging infrastructure.
+ *
+ * @example
+ * ```typescript
+ * const validator = new CoherenceValidator(); // advisory mode by default
+ * const result = validator.validateTestArtifact({
+ *   assertions: ['expect(x).toBe(1)'],
+ *   observedBehavior: ['x was 1'],
+ *   coverage: 0.9,
+ *   domain: 'test-generation',
+ *   confidence: 0.95,
+ * });
+ * if (result.warnings.length > 0) {
+ *   console.warn('Coherence warnings:', result.warnings);
+ * }
+ * ```
+ */
+export declare class CoherenceValidator {
+    private readonly config;
+    private readonly gate;
+    private validationCount;
+    private warningCount;
+    private blockCount;
+    constructor(config?: Partial<CoherenceValidatorConfig>);
+    /**
+     * Validate a test artifact through the coherence pipeline.
+     *
+     * In advisory mode (default), always approves but attaches warnings
+     * when coherence energy exceeds the threshold.
+     *
+     * In blocking mode, rejects artifacts that exceed the threshold.
+     *
+     * @param artifact - The test artifact to validate
+     * @returns Pipeline result with approval status and warnings
+     */
+    validateTestArtifact(artifact: TestArtifact): ValidationPipelineResult;
+    /**
+     * Get the decision log from the underlying coherence gate.
+     */
+    getDecisionLog(): CoherenceDecision[];
+    /**
+     * Get validation statistics.
+     */
+    getStats(): {
+        validationCount: number;
+        warningCount: number;
+        blockCount: number;
+        mode: 'advisory' | 'blocking';
+        threshold: number;
+    };
+    /**
+     * Get the underlying coherence gate (for advanced usage or testing).
+     */
+    getGate(): CoherenceGate;
+    /**
+     * Create a passthrough result when the feature flag is disabled.
+     */
+    private createPassthroughResult;
+}
+/**
+ * Create a coherence validator with the given configuration.
+ */
+export declare function createCoherenceValidator(config?: Partial<CoherenceValidatorConfig>): CoherenceValidator;
+//# sourceMappingURL=coherence-validator.d.ts.map

package/dist/governance/coherence-validator.js

@@ -0,0 +1,180 @@
+/**
+ * Coherence Validator - Governance Pipeline for Test Artifact Validation
+ *
+ * Provides a validation pipeline that uses CoherenceGate to validate
+ * AI-generated test artifacts. Operates in two modes:
+ *
+ * - **Advisory mode** (default): Logs coherence violations but does not block.
+ *   The artifact is always approved with a warning attached.
+ *
+ * - **Blocking mode**: Rejects artifacts that exceed the coherence threshold.
+ *   Must be explicitly enabled via configuration.
+ *
+ * @module governance/coherence-validator
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+import { LoggerFactory } from '../logging/index.js';
+import { createCoherenceGate, DEFAULT_COHERENCE_THRESHOLD, } from '../integrations/ruvector/coherence-gate.js';
+import { getRuVectorFeatureFlags } from '../integrations/ruvector/feature-flags.js';
+const logger = LoggerFactory.create('coherence-validator');
+/** Default configuration: advisory mode */
+export const DEFAULT_COHERENCE_VALIDATOR_CONFIG = {
+    blocking: false,
+    threshold: DEFAULT_COHERENCE_THRESHOLD,
+    logWarnings: true,
+};
+// ============================================================================
+// Coherence Validator
+// ============================================================================
+/**
+ * Validation pipeline that uses CoherenceGate for test artifact validation.
+ *
+ * Wraps the CoherenceGate with configurable advisory/blocking behavior
+ * and integrates with the governance logging infrastructure.
+ *
+ * @example
+ * ```typescript
+ * const validator = new CoherenceValidator(); // advisory mode by default
+ * const result = validator.validateTestArtifact({
+ *   assertions: ['expect(x).toBe(1)'],
+ *   observedBehavior: ['x was 1'],
+ *   coverage: 0.9,
+ *   domain: 'test-generation',
+ *   confidence: 0.95,
+ * });
+ * if (result.warnings.length > 0) {
+ *   console.warn('Coherence warnings:', result.warnings);
+ * }
+ * ```
+ */
+export class CoherenceValidator {
+    config;
+    gate;
+    validationCount = 0;
+    warningCount = 0;
+    blockCount = 0;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_COHERENCE_VALIDATOR_CONFIG, ...config };
+        this.gate = createCoherenceGate(this.config.threshold);
+    }
+    /**
+     * Validate a test artifact through the coherence pipeline.
+     *
+     * In advisory mode (default), always approves but attaches warnings
+     * when coherence energy exceeds the threshold.
+     *
+     * In blocking mode, rejects artifacts that exceed the threshold.
+     *
+     * @param artifact - The test artifact to validate
+     * @returns Pipeline result with approval status and warnings
+     */
+    validateTestArtifact(artifact) {
+        const flags = getRuVectorFeatureFlags();
+        const featureFlagEnabled = flags.useCoherenceGate;
+        // If feature flag is disabled, pass through
+        if (!featureFlagEnabled) {
+            return this.createPassthroughResult(artifact);
+        }
+        this.validationCount++;
+        const validation = this.gate.validate(artifact, this.config.threshold);
+        const warnings = [];
+        const mode = this.config.blocking ? 'blocking' : 'advisory';
+        if (!validation.passed) {
+            const warning = `Coherence validation warning for domain '${artifact.domain}': ${validation.reason}`;
+            warnings.push(warning);
+            if (this.config.logWarnings) {
+                logger.warn(warning, {
+                    energy: validation.energy,
+                    threshold: validation.threshold,
+                    domain: artifact.domain,
+                    mode,
+                });
+            }
+            if (this.config.blocking) {
+                this.blockCount++;
+                logger.info('Artifact blocked by coherence gate', {
+                    energy: validation.energy,
+                    domain: artifact.domain,
+                });
+                return {
+                    approved: false,
+                    mode: 'blocking',
+                    validation,
+                    warnings,
+                    featureFlagEnabled,
+                };
+            }
+            // Advisory mode: approve but warn
+            this.warningCount++;
+        }
+        return {
+            approved: true,
+            mode,
+            validation,
+            warnings,
+            featureFlagEnabled,
+        };
+    }
+    /**
+     * Get the decision log from the underlying coherence gate.
+     */
+    getDecisionLog() {
+        return this.gate.getDecisionLog();
+    }
+    /**
+     * Get validation statistics.
+     */
+    getStats() {
+        return {
+            validationCount: this.validationCount,
+            warningCount: this.warningCount,
+            blockCount: this.blockCount,
+            mode: this.config.blocking ? 'blocking' : 'advisory',
+            threshold: this.config.threshold,
+        };
+    }
+    /**
+     * Get the underlying coherence gate (for advanced usage or testing).
+     */
+    getGate() {
+        return this.gate;
+    }
+    /**
+     * Create a passthrough result when the feature flag is disabled.
+     */
+    createPassthroughResult(artifact) {
+        // Construct a minimal validation result for passthrough
+        const validation = {
+            passed: true,
+            energy: 0,
+            threshold: this.config.threshold,
+            witness: {
+                id: 'passthrough',
+                timestamp: Date.now(),
+                artifactHash: 'disabled',
+                energy: 0,
+                threshold: this.config.threshold,
+                passed: true,
+                previousHash: '0'.repeat(64),
+                recordHash: '0'.repeat(64),
+            },
+        };
+        return {
+            approved: true,
+            mode: this.config.blocking ? 'blocking' : 'advisory',
+            validation,
+            warnings: [],
+            featureFlagEnabled: false,
+        };
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a coherence validator with the given configuration.
+ */
+export function createCoherenceValidator(config) {
+    return new CoherenceValidator(config);
+}
+//# sourceMappingURL=coherence-validator.js.map

package/dist/governance/index.d.ts

@@ -35,4 +35,5 @@ export { ShardEmbeddingsManager, shardEmbeddingsManager, DEFAULT_SHARD_EMBEDDING
 export { AdversarialDefenseIntegration, adversarialDefenseIntegration, quickThreatAssess, isSafeInput, sanitizeUserInput, type ThreatContext, type DetectedPattern, type ThreatAssessment, type DetectionPattern, type ThreatCategory, type PatternStats, type DefenseStats, } from './adversarial-defense-integration.js';
 export { ComplianceReporter, complianceReporter, createComplianceReporter, isComplianceReporterEnabled as isComplianceReporterFeatureEnabled, DEFAULT_COMPLIANCE_REPORTER_FLAGS, type ViolationType, type ViolationSeverity, type ComplianceViolation, type ViolationFilter, type TimeWindow, type ComplianceScore, type ReportOptions, type ComplianceReport, type Alert, type ComplianceStats, type ComplianceReporterFlags, } from './compliance-reporter.js';
 export { ConstitutionalEnforcer, constitutionalEnforcer, createConstitutionalEnforcer, isConstitutionalEnforcementEnabled, isStrictEnforcementEnabled, DEFAULT_CONSTITUTIONAL_ENFORCER_FLAGS, type Invariant, type InvariantCheck, type EnforcementResult, type EnforcementStats, type ExecutionProof, type SecurityScan, type Backup, type DeleteOperation, type AgentStats as ConstitutionalAgentStats, type MemoryPattern as ConstitutionalMemoryPattern, type Verification, type ConstitutionalEnforcerFlags, } from './constitutional-enforcer.js';
+export { WitnessChain, PersistentWitnessChain, createWitnessChain, createPersistentWitnessChain, createWitnessChainSQLitePersistence, isWitnessChainFeatureEnabled, SPRTAccumulator, type IWitnessChainPersistence, type WitnessDecision, type WitnessReceipt, type ChainVerificationResult as WitnessChainVerificationResult, type WitnessChainExport, } from './witness-chain.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/governance/index.js

@@ -45,4 +45,6 @@ export { AdversarialDefenseIntegration, adversarialDefenseIntegration, quickThre
 export { ComplianceReporter, complianceReporter, createComplianceReporter, isComplianceReporterEnabled as isComplianceReporterFeatureEnabled, DEFAULT_COMPLIANCE_REPORTER_FLAGS, } from './compliance-reporter.js';
 // Constitutional Enforcer
 export { ConstitutionalEnforcer, constitutionalEnforcer, createConstitutionalEnforcer, isConstitutionalEnforcementEnabled, isStrictEnforcementEnabled, DEFAULT_CONSTITUTIONAL_ENFORCER_FLAGS, } from './constitutional-enforcer.js';
+// Witness Chain - Hash-linked audit trail
+export { WitnessChain, PersistentWitnessChain, createWitnessChain, createPersistentWitnessChain, createWitnessChainSQLitePersistence, isWitnessChainFeatureEnabled, SPRTAccumulator, } from './witness-chain.js';
 //# sourceMappingURL=index.js.map