agentic-qe 3.8.14 → 3.9.1

package/dist/persistence/rvf-migration-coordinator.d.ts

@@ -0,0 +1,115 @@
+/**
+ * RVF Migration Coordinator (ADR-072 Phase 3)
+ *
+ * Wires together RvfMigrationAdapter, RvfConsistencyValidator, and
+ * RvfStageGate into a single service that can be initialized during
+ * kernel boot and exposed via MCP tools.
+ *
+ * Lifecycle:
+ *   1. Kernel calls RvfMigrationCoordinator.initialize(db)
+ *   2. Coordinator reads stage from feature flags, attaches SQLite + RVF handles
+ *   3. MCP tools call getStatus(), runConsistencyCheck(), promote()
+ *
+ * @module persistence/rvf-migration-coordinator
+ */
+import { RvfMigrationAdapter, type MigrationStage, type MigrationMetrics } from './rvf-migration-adapter.js';
+import { type ConsistencyCheckResult } from './rvf-consistency-validator.js';
+import { type StageGateResult } from './rvf-stage-gate.js';
+export interface MigrationStatus {
+    stage: MigrationStage;
+    stageName: string;
+    metrics: MigrationMetrics;
+    consistencyHistory: {
+        totalChecks: number;
+        rollingDivergenceRate: number;
+        lastCheck: ConsistencyCheckResult | null;
+    };
+    gateEvaluation: StageGateResult;
+    engineStatus: {
+        sqliteVectorCount: number;
+        rvfAvailable: boolean;
+        rvfVectorCount: number | null;
+        rvfDeadSpaceRatio: number | null;
+    };
+}
+export interface MigrationCoordinatorConfig {
+    /** Override migration stage (otherwise reads from feature flags) */
+    stage?: MigrationStage;
+    /** RVF file path */
+    rvfPath?: string;
+    /** Vector dimensions */
+    dimensions?: number;
+}
+export declare class RvfMigrationCoordinator {
+    private adapter;
+    private validator;
+    private gate;
+    private currentStage;
+    private initialized;
+    constructor(config?: MigrationCoordinatorConfig);
+    /**
+     * Attach the real SQLite database handle (from UnifiedMemoryManager).
+     * Called during kernel boot.
+     */
+    attachSqliteDb(db: unknown): void;
+    /**
+     * Attach the shared RVF store (from shared-rvf-adapter singleton).
+     * Called during kernel boot when native bindings are available.
+     */
+    attachRvfStore(store: unknown): void;
+    /**
+     * Attach a witness chain for audit trail of stage promotions.
+     */
+    attachWitnessChain(wc: unknown): void;
+    /**
+     * Full initialization: reads handles from running system.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get comprehensive migration status.
+     * This is the primary user-facing method — shows stage, metrics,
+     * consistency history, and gate evaluation at a glance.
+     */
+    getStatus(): MigrationStatus;
+    /**
+     * Run a consistency check between SQLite and RVF.
+     * Returns the check result with divergence details.
+     */
+    runConsistencyCheck(): ConsistencyCheckResult;
+    /**
+     * Evaluate whether promotion to the next stage is allowed.
+     */
+    evaluateGate(): StageGateResult;
+    /**
+     * Attempt to promote to the next migration stage.
+     *
+     * @param force - Skip gate checks (records forced promotion in witness chain)
+     * @returns Promotion result with new stage
+     */
+    promote(force?: boolean): {
+        promoted: boolean;
+        previousStage: MigrationStage;
+        newStage: MigrationStage;
+        result: StageGateResult;
+    };
+    /**
+     * Write a vector through the migration adapter.
+     * Used to verify dual-write routing at each stage.
+     */
+    write(id: string, vector: Float32Array | number[]): import("./rvf-migration-adapter.js").WriteResult;
+    /**
+     * Search through the migration adapter.
+     * Used to verify read routing at each stage.
+     */
+    search(query: Float32Array | number[], k: number): import("./rvf-migration-adapter.js").ReadResult<{
+        id: string;
+        score: number;
+    }[]>;
+    /**
+     * Get the underlying adapter (for advanced use / testing).
+     */
+    getAdapter(): RvfMigrationAdapter;
+    static getInstance(config?: MigrationCoordinatorConfig): RvfMigrationCoordinator;
+    static resetInstance(): void;
+}
+//# sourceMappingURL=rvf-migration-coordinator.d.ts.map

package/dist/persistence/rvf-migration-coordinator.js

@@ -0,0 +1,224 @@
+/**
+ * RVF Migration Coordinator (ADR-072 Phase 3)
+ *
+ * Wires together RvfMigrationAdapter, RvfConsistencyValidator, and
+ * RvfStageGate into a single service that can be initialized during
+ * kernel boot and exposed via MCP tools.
+ *
+ * Lifecycle:
+ *   1. Kernel calls RvfMigrationCoordinator.initialize(db)
+ *   2. Coordinator reads stage from feature flags, attaches SQLite + RVF handles
+ *   3. MCP tools call getStatus(), runConsistencyCheck(), promote()
+ *
+ * @module persistence/rvf-migration-coordinator
+ */
+import { RvfMigrationAdapter, STAGE_NAMES } from './rvf-migration-adapter.js';
+import { RvfConsistencyValidator } from './rvf-consistency-validator.js';
+import { RvfStageGate } from './rvf-stage-gate.js';
+// ============================================================================
+// Singleton
+// ============================================================================
+let instance = null;
+// ============================================================================
+// RvfMigrationCoordinator
+// ============================================================================
+export class RvfMigrationCoordinator {
+    adapter;
+    validator;
+    gate;
+    currentStage;
+    initialized = false;
+    constructor(config) {
+        // Stage is set synchronously from config or default.
+        // Feature flags are read asynchronously in initialize().
+        this.currentStage = config?.stage ?? 1;
+        this.adapter = new RvfMigrationAdapter({
+            stage: this.currentStage,
+            rvfPath: config?.rvfPath ?? '.agentic-qe/patterns.rvf',
+            dimensions: config?.dimensions ?? 384,
+            enableFallback: true,
+        });
+        this.validator = new RvfConsistencyValidator({
+            sampleSize: 50,
+            windowDurationMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+            compactionThreshold: 0.3,
+            scoreTolerance: 0.05,
+        });
+        this.gate = new RvfStageGate({
+            minChecksRequired: 10,
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Initialization
+    // --------------------------------------------------------------------------
+    /**
+     * Attach the real SQLite database handle (from UnifiedMemoryManager).
+     * Called during kernel boot.
+     */
+    attachSqliteDb(db) {
+        this.adapter.setSqliteDb(db);
+        this.validator.setSqliteDb(db);
+    }
+    /**
+     * Attach the shared RVF store (from shared-rvf-adapter singleton).
+     * Called during kernel boot when native bindings are available.
+     */
+    attachRvfStore(store) {
+        this.adapter.setRvfStore(store);
+        this.validator.setRvfStore(store);
+    }
+    /**
+     * Attach a witness chain for audit trail of stage promotions.
+     */
+    attachWitnessChain(wc) {
+        this.gate.setWitnessChain(wc);
+    }
+    /**
+     * Full initialization: reads handles from running system.
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        // Read stage from feature flags (async import for ESM compatibility)
+        if (this.currentStage === 1) {
+            try {
+                const { getRvfMigrationStage } = await import('../integrations/ruvector/feature-flags.js');
+                const flagStage = getRvfMigrationStage();
+                this.currentStage = flagStage;
+                this.adapter.setStage(flagStage);
+            }
+            catch {
+                // Feature flags unavailable — keep constructor default
+            }
+        }
+        // Try to get SQLite handle from UnifiedMemoryManager
+        try {
+            const { UnifiedMemoryManager } = await import('../kernel/unified-memory.js');
+            const umm = UnifiedMemoryManager.getInstance();
+            await umm.initialize();
+            const db = umm.getDatabase();
+            if (db)
+                this.attachSqliteDb(db);
+        }
+        catch {
+            // UMM unavailable — adapter works without it (read/write ops return empty)
+        }
+        // Try to get shared RVF adapter
+        try {
+            const { getSharedRvfAdapter } = await import('../integrations/ruvector/shared-rvf-adapter.js');
+            const adapter = getSharedRvfAdapter();
+            if (adapter)
+                this.attachRvfStore(adapter);
+        }
+        catch {
+            // RVF native unavailable — adapter works without it
+        }
+        // Try to attach witness chain
+        try {
+            const { WitnessChain } = await import('../audit/witness-chain.js');
+            const wc = new WitnessChain();
+            await wc.initialize();
+            this.attachWitnessChain(wc);
+        }
+        catch {
+            // Witness chain is optional
+        }
+        this.initialized = true;
+    }
+    // --------------------------------------------------------------------------
+    // User-Facing Operations
+    // --------------------------------------------------------------------------
+    /**
+     * Get comprehensive migration status.
+     * This is the primary user-facing method — shows stage, metrics,
+     * consistency history, and gate evaluation at a glance.
+     */
+    getStatus() {
+        const metrics = this.adapter.getMetrics();
+        const engineStatus = this.adapter.status();
+        const history = this.validator.getHistory();
+        const gateEvaluation = this.gate.evaluate(this.currentStage, this.validator, metrics);
+        return {
+            stage: this.currentStage,
+            stageName: STAGE_NAMES[this.currentStage],
+            metrics,
+            consistencyHistory: {
+                totalChecks: this.validator.getCheckCount(),
+                rollingDivergenceRate: this.validator.getRollingDivergenceRate(),
+                lastCheck: history.length > 0 ? history[history.length - 1] : null,
+            },
+            gateEvaluation,
+            engineStatus: {
+                sqliteVectorCount: engineStatus.sqlite.vectorCount,
+                rvfAvailable: engineStatus.rvf !== null,
+                rvfVectorCount: engineStatus.rvf?.totalVectors ?? null,
+                rvfDeadSpaceRatio: engineStatus.rvf?.deadSpaceRatio ?? null,
+            },
+        };
+    }
+    /**
+     * Run a consistency check between SQLite and RVF.
+     * Returns the check result with divergence details.
+     */
+    runConsistencyCheck() {
+        return this.validator.runCheck();
+    }
+    /**
+     * Evaluate whether promotion to the next stage is allowed.
+     */
+    evaluateGate() {
+        return this.gate.evaluate(this.currentStage, this.validator, this.adapter.getMetrics());
+    }
+    /**
+     * Attempt to promote to the next migration stage.
+     *
+     * @param force - Skip gate checks (records forced promotion in witness chain)
+     * @returns Promotion result with new stage
+     */
+    promote(force = false) {
+        const previousStage = this.currentStage;
+        const { promoted, newStage, result } = this.gate.promote(this.currentStage, this.validator, this.adapter.getMetrics(), force);
+        if (promoted) {
+            this.currentStage = newStage;
+            // Propagate to adapter so write/read routing uses the new stage
+            this.adapter.setStage(newStage);
+            // Note: The feature flag default is NOT mutated at runtime.
+            // The new stage is active for this process lifetime. To persist
+            // the promotion, update rvfMigrationStage in feature-flags.ts.
+        }
+        return { promoted, previousStage, newStage, result };
+    }
+    /**
+     * Write a vector through the migration adapter.
+     * Used to verify dual-write routing at each stage.
+     */
+    write(id, vector) {
+        return this.adapter.write(id, vector);
+    }
+    /**
+     * Search through the migration adapter.
+     * Used to verify read routing at each stage.
+     */
+    search(query, k) {
+        return this.adapter.search(query, k);
+    }
+    /**
+     * Get the underlying adapter (for advanced use / testing).
+     */
+    getAdapter() {
+        return this.adapter;
+    }
+    // --------------------------------------------------------------------------
+    // Singleton
+    // --------------------------------------------------------------------------
+    static getInstance(config) {
+        if (!instance) {
+            instance = new RvfMigrationCoordinator(config);
+        }
+        return instance;
+    }
+    static resetInstance() {
+        instance = null;
+    }
+}
+//# sourceMappingURL=rvf-migration-coordinator.js.map

package/dist/persistence/rvf-stage-gate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * RVF Stage Gate Enforcer (ADR-072)
+ *
+ * Enforces go/no-go criteria for promoting the RVF migration stage.
+ * Each stage transition has specific requirements that must be met
+ * before promotion is allowed.
+ *
+ * Stage gates (from ADR-072):
+ *   Stage 2→3: divergence <0.01% over 7 days, RVF read latency <2x SQLite
+ *   Stage 3→4: zero fallbacks over 14 days, RVF write latency <1.5x SQLite
+ *
+ * Supports manual override with witness chain recording for audit trail.
+ *
+ * @module persistence/rvf-stage-gate
+ */
+import type { MigrationStage, MigrationMetrics } from './rvf-migration-adapter.js';
+import type { RvfConsistencyValidator } from './rvf-consistency-validator.js';
+import type { WitnessChain } from '../audit/witness-chain.js';
+export interface StageGateResult {
+    /** Whether promotion is allowed */
+    canPromote: boolean;
+    /** Current stage */
+    currentStage: MigrationStage;
+    /** Target stage */
+    targetStage: MigrationStage;
+    /** Individual gate check results */
+    checks: GateCheck[];
+    /** Human-readable summary */
+    summary: string;
+}
+export interface GateCheck {
+    name: string;
+    passed: boolean;
+    actual: string;
+    threshold: string;
+}
+export interface StageGateConfig {
+    /** Max divergence rate for stage 2→3 (default: 0.0001 = 0.01%) */
+    maxDivergenceRate2to3: number;
+    /** Max RVF/SQLite read latency ratio for stage 2→3 (default: 2.0) */
+    maxReadLatencyRatio2to3: number;
+    /** Max fallbacks allowed for stage 3→4 (default: 0) */
+    maxFallbacks3to4: number;
+    /** Max RVF/SQLite write latency ratio for stage 3→4 (default: 1.5) */
+    maxWriteLatencyRatio3to4: number;
+    /** Minimum checks required in window before gate can pass (default: 10) */
+    minChecksRequired: number;
+}
+export declare class RvfStageGate {
+    private readonly config;
+    private witnessChain;
+    constructor(config?: Partial<StageGateConfig>);
+    /** Attach witness chain for audit trail of promotions */
+    setWitnessChain(wc: WitnessChain): void;
+    /**
+     * Evaluate whether promotion from currentStage to currentStage+1 is allowed.
+     */
+    evaluate(currentStage: MigrationStage, validator: RvfConsistencyValidator, metrics: MigrationMetrics): StageGateResult;
+    /**
+     * Attempt to promote to the next stage. Returns the new stage if successful.
+     * Records the promotion (or block) in the witness chain.
+     */
+    promote(currentStage: MigrationStage, validator: RvfConsistencyValidator, metrics: MigrationMetrics, force?: boolean): {
+        promoted: boolean;
+        newStage: MigrationStage;
+        result: StageGateResult;
+    };
+    private recordWitness;
+}
+//# sourceMappingURL=rvf-stage-gate.d.ts.map

package/dist/persistence/rvf-stage-gate.js

@@ -0,0 +1,163 @@
+/**
+ * RVF Stage Gate Enforcer (ADR-072)
+ *
+ * Enforces go/no-go criteria for promoting the RVF migration stage.
+ * Each stage transition has specific requirements that must be met
+ * before promotion is allowed.
+ *
+ * Stage gates (from ADR-072):
+ *   Stage 2→3: divergence <0.01% over 7 days, RVF read latency <2x SQLite
+ *   Stage 3→4: zero fallbacks over 14 days, RVF write latency <1.5x SQLite
+ *
+ * Supports manual override with witness chain recording for audit trail.
+ *
+ * @module persistence/rvf-stage-gate
+ */
+const DEFAULT_CONFIG = {
+    maxDivergenceRate2to3: 0.0001, // 0.01%
+    maxReadLatencyRatio2to3: 2.0,
+    maxFallbacks3to4: 0,
+    maxWriteLatencyRatio3to4: 1.5,
+    minChecksRequired: 10,
+};
+// ============================================================================
+// RvfStageGate
+// ============================================================================
+export class RvfStageGate {
+    config;
+    witnessChain = null;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /** Attach witness chain for audit trail of promotions */
+    setWitnessChain(wc) {
+        this.witnessChain = wc;
+    }
+    // --------------------------------------------------------------------------
+    // Gate Evaluation
+    // --------------------------------------------------------------------------
+    /**
+     * Evaluate whether promotion from currentStage to currentStage+1 is allowed.
+     */
+    evaluate(currentStage, validator, metrics) {
+        const targetStage = Math.min(currentStage + 1, 4);
+        if (currentStage >= 4) {
+            return {
+                canPromote: false,
+                currentStage,
+                targetStage: 4,
+                checks: [],
+                summary: 'Already at maximum stage (4: RVF primary)',
+            };
+        }
+        if (currentStage < 2) {
+            // Stages 0→1 and 1→2 don't have automated gates
+            return {
+                canPromote: true,
+                currentStage,
+                targetStage,
+                checks: [],
+                summary: `Stage ${currentStage}→${targetStage} has no automated gates — manual promotion allowed`,
+            };
+        }
+        const checks = [];
+        if (currentStage === 2) {
+            // Stage 2→3: divergence + read latency
+            const divergenceRate = validator.getRollingDivergenceRate();
+            const checkCount = validator.getCheckCount();
+            checks.push({
+                name: 'consistency-checks-count',
+                passed: checkCount >= this.config.minChecksRequired,
+                actual: `${checkCount} checks`,
+                threshold: `>= ${this.config.minChecksRequired} checks`,
+            });
+            checks.push({
+                name: 'divergence-rate',
+                passed: divergenceRate <= this.config.maxDivergenceRate2to3,
+                actual: `${(divergenceRate * 100).toFixed(4)}%`,
+                threshold: `<= ${(this.config.maxDivergenceRate2to3 * 100).toFixed(4)}%`,
+            });
+            const latencyRatio = metrics.sqliteReadLatencyAvgMs > 0
+                ? metrics.rvfReadLatencyAvgMs / metrics.sqliteReadLatencyAvgMs
+                : 0;
+            checks.push({
+                name: 'read-latency-ratio',
+                passed: latencyRatio <= this.config.maxReadLatencyRatio2to3 || metrics.rvfReadLatencyAvgMs === 0,
+                actual: `${latencyRatio.toFixed(2)}x`,
+                threshold: `<= ${this.config.maxReadLatencyRatio2to3}x`,
+            });
+        }
+        if (currentStage === 3) {
+            // Stage 3→4: zero fallbacks + write latency
+            checks.push({
+                name: 'fallback-count',
+                passed: metrics.fallbacksUsed <= this.config.maxFallbacks3to4,
+                actual: `${metrics.fallbacksUsed} fallbacks`,
+                threshold: `<= ${this.config.maxFallbacks3to4} fallbacks`,
+            });
+            // Use write latency metrics when available, fall back to read latency as proxy
+            const sqliteWriteAvg = metrics.sqliteWriteLatencyAvgMs ?? metrics.sqliteReadLatencyAvgMs;
+            const rvfWriteAvg = metrics.rvfWriteLatencyAvgMs ?? metrics.rvfReadLatencyAvgMs;
+            const writeLatencyRatio = sqliteWriteAvg > 0 ? rvfWriteAvg / sqliteWriteAvg : 0;
+            checks.push({
+                name: 'write-latency-ratio',
+                passed: writeLatencyRatio <= this.config.maxWriteLatencyRatio3to4 || rvfWriteAvg === 0,
+                actual: `${writeLatencyRatio.toFixed(2)}x`,
+                threshold: `<= ${this.config.maxWriteLatencyRatio3to4}x`,
+            });
+        }
+        const canPromote = checks.length > 0 && checks.every(c => c.passed);
+        const failedChecks = checks.filter(c => !c.passed).map(c => c.name);
+        return {
+            canPromote,
+            currentStage,
+            targetStage,
+            checks,
+            summary: canPromote
+                ? `All gates passed — safe to promote to stage ${targetStage}`
+                : `Blocked: ${failedChecks.join(', ')} failed`,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Promotion
+    // --------------------------------------------------------------------------
+    /**
+     * Attempt to promote to the next stage. Returns the new stage if successful.
+     * Records the promotion (or block) in the witness chain.
+     */
+    promote(currentStage, validator, metrics, force = false) {
+        const result = this.evaluate(currentStage, validator, metrics);
+        if (!result.canPromote && !force) {
+            this.recordWitness('QUALITY_GATE_FAIL', {
+                action: 'stage-promotion-blocked',
+                from: currentStage,
+                to: result.targetStage,
+                failedChecks: result.checks.filter(c => !c.passed),
+                summary: result.summary,
+            });
+            return { promoted: false, newStage: currentStage, result };
+        }
+        const newStage = result.targetStage;
+        this.recordWitness(force ? 'QUALITY_GATE_PASS' : 'QUALITY_GATE_PASS', {
+            action: force ? 'stage-promotion-forced' : 'stage-promotion-approved',
+            from: currentStage,
+            to: newStage,
+            checks: result.checks,
+            forced: force,
+            summary: result.summary,
+        });
+        return { promoted: true, newStage, result };
+    }
+    // --------------------------------------------------------------------------
+    // Private
+    // --------------------------------------------------------------------------
+    recordWitness(actionType, data) {
+        try {
+            this.witnessChain?.append(actionType, data, 'rvf-stage-gate');
+        }
+        catch {
+            // Witness recording is best-effort
+        }
+    }
+}
+//# sourceMappingURL=rvf-stage-gate.js.map

package/dist/plugins/cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Agentic QE v3 - Plugin Cache (IMP-09)
+ *
+ * Versioned immutable cache for installed plugins.
+ * Stores plugins at `.agentic-qe/plugins/{name}@{version}/`.
+ * Once cached, a version is never modified — only new versions are added.
+ */
+import type { QEPluginManifest } from './manifest';
+export interface CachedPlugin {
+    manifest: QEPluginManifest;
+    path: string;
+    cachedAt: string;
+}
+export interface PluginCacheOptions {
+    /** Base directory for the plugin cache (default: .agentic-qe/plugins) */
+    cacheDir?: string;
+    /** Number of old versions to keep per plugin (default: 2) */
+    keepVersions?: number;
+}
+export declare class PluginCache {
+    private readonly cacheDir;
+    private readonly keepVersions;
+    constructor(options?: PluginCacheOptions);
+    /** Check if a specific version is cached. */
+    has(name: string, version: string): boolean;
+    /** Get the cached path for a plugin version, or undefined if not cached. */
+    get(name: string, version: string): CachedPlugin | undefined;
+    /**
+     * Store a plugin in the cache by copying from a source directory.
+     * Returns the cache path. If already cached, returns the existing path
+     * (immutable — no overwrite).
+     */
+    store(manifest: QEPluginManifest, sourceDir: string): string;
+    /** Remove a specific cached version. */
+    remove(name: string, version: string): boolean;
+    /** List all cached versions for a plugin. */
+    listVersions(name: string): CachedPlugin[];
+    /** List all cached plugins (latest version of each). */
+    listAll(): CachedPlugin[];
+    private versionDir;
+    private pruneOldVersions;
+    private copyDir;
+}
+//# sourceMappingURL=cache.d.ts.map