agentic-qe 3.7.21 → 3.8.0

package/dist/governance/witness-chain.js

@@ -0,0 +1,509 @@
+/**
+ * Witness Chain - Hash-Linked Audit Trail for Quality Gate Decisions
+ *
+ * Implements an append-only, hash-linked witness log for quality gate decisions.
+ * Each receipt is cryptographically chained to its predecessor using SHA-256,
+ * creating a tamper-evident audit trail.
+ *
+ * Features:
+ * - Append-only witness log with SHA-256 hash linking
+ * - Chain integrity verification with tamper detection
+ * - SPRT (Sequential Probability Ratio Test) evidence accumulation
+ * - Export/import for brain transfer
+ * - Feature-flag gated via useWitnessChain
+ *
+ * @module governance/witness-chain
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+import { createHash, randomUUID } from 'crypto';
+import { LoggerFactory } from '../logging/index.js';
+import { getRuVectorFeatureFlags } from '../integrations/ruvector/feature-flags.js';
+const logger = LoggerFactory.create('witness-chain');
+// ============================================================================
+// SPRT Accumulator
+// ============================================================================
+/**
+ * Sequential Probability Ratio Test accumulator for Pass/Fail decisions.
+ *
+ * Simplified sequential decision rule with configurable evidence strength.
+ * For production use, strength should reflect log-likelihood ratio of the
+ * observation under the alternative vs null hypothesis.
+ *
+ * Accumulates evidence over a sequence of observations to decide between
+ * two hypotheses (Pass vs Fail) with controlled error rates.
+ *
+ * Boundaries:
+ * - Upper bound (accept H1 / PASS): ln(1/alpha)
+ * - Lower bound (accept H0 / FAIL): ln(beta)
+ *
+ * Default evidence step: +0.5 for positive, -0.5 for negative.
+ * Use addWeightedEvidence() for variable-strength observations.
+ */
+export class SPRTAccumulator {
+    logLikelihoodRatio = 0;
+    upperBound;
+    lowerBound;
+    observations = 0;
+    /**
+     * @param alpha - Type I error rate (false positive). Default: 0.05
+     * @param beta - Type II error rate (false negative). Default: 0.05
+     */
+    constructor(alpha = 0.05, beta = 0.05) {
+        this.upperBound = Math.log(1 / alpha);
+        this.lowerBound = Math.log(beta);
+    }
+    /**
+     * Add a weighted observation and return the current decision.
+     *
+     * The strength parameter controls the log-likelihood step size.
+     * For production use, strength should reflect the log-likelihood ratio
+     * of the observation under the alternative vs null hypothesis.
+     *
+     * @param positive - Whether this observation is positive evidence
+     * @param strength - Evidence strength (step size). Default 0.5 for backward compat.
+     * @returns Current decision: PASS, FAIL, or INCONCLUSIVE
+     */
+    addWeightedEvidence(positive, strength) {
+        this.logLikelihoodRatio += positive ? strength : -strength;
+        this.observations++;
+        if (this.logLikelihoodRatio >= this.upperBound)
+            return 'PASS';
+        if (this.logLikelihoodRatio <= this.lowerBound)
+            return 'FAIL';
+        return 'INCONCLUSIVE';
+    }
+    /**
+     * Add an observation with default strength (0.5) and return the current decision.
+     *
+     * @param positive - Whether this observation is positive evidence
+     * @returns Current decision: PASS, FAIL, or INCONCLUSIVE
+     */
+    addEvidence(positive) {
+        return this.addWeightedEvidence(positive, 0.5);
+    }
+    /**
+     * Get the current log-likelihood ratio.
+     */
+    getRatio() {
+        return this.logLikelihoodRatio;
+    }
+    /**
+     * Get the total number of observations.
+     */
+    getObservations() {
+        return this.observations;
+    }
+    /**
+     * Get the SPRT boundaries.
+     */
+    getBounds() {
+        return { upper: this.upperBound, lower: this.lowerBound };
+    }
+    /**
+     * Reset the accumulator to its initial state.
+     */
+    reset() {
+        this.logLikelihoodRatio = 0;
+        this.observations = 0;
+    }
+}
+// ============================================================================
+// Witness Chain
+// ============================================================================
+/** Genesis hash: 64 hex zeros */
+const GENESIS_HASH = '0'.repeat(64);
+/**
+ * Append-only, hash-linked witness chain for quality gate decisions.
+ *
+ * Maintains an ordered sequence of witness receipts where each receipt
+ * references the hash of its predecessor, forming a tamper-evident chain.
+ *
+ * @example
+ * ```typescript
+ * const chain = new WitnessChain();
+ * const receipt = chain.appendWitness({
+ *   type: 'coherence-gate',
+ *   decision: 'PASS',
+ *   context: { energy: 0.23, threshold: 0.4 },
+ * });
+ * const result = chain.verifyChain();
+ * console.log(result.valid); // true
+ * ```
+ */
+export class WitnessChain {
+    receipts = [];
+    lastHash = GENESIS_HASH;
+    sprtAccumulators = new Map();
+    /**
+     * Append a witness decision to the chain.
+     *
+     * Creates a new receipt hash-linked to the previous receipt and appends
+     * it to the chain. Optionally updates the SPRT accumulator for the
+     * decision type.
+     *
+     * @param decision - The decision to witness
+     * @returns The new witness receipt with its chain hash
+     */
+    appendWitness(decision) {
+        const id = randomUUID();
+        const timestamp = Date.now();
+        const chainIndex = this.receipts.length;
+        // Compute receipt hash: SHA-256(previousHash + JSON(decision) + timestamp)
+        const hashPayload = this.lastHash + JSON.stringify(decision) + timestamp;
+        const hash = createHash('sha256').update(hashPayload).digest('hex');
+        const receipt = {
+            id,
+            timestamp,
+            previousHash: this.lastHash,
+            hash,
+            decision,
+            chainIndex,
+        };
+        this.receipts.push(receipt);
+        this.lastHash = hash;
+        // Update SPRT accumulator for this decision type
+        this.updateSPRT(decision);
+        logger.debug('Witness appended', {
+            chainIndex,
+            type: decision.type,
+            decision: decision.decision,
+            hash: hash.slice(0, 16) + '...',
+        });
+        return receipt;
+    }
+    /**
+     * Verify the integrity of the entire witness chain.
+     *
+     * Walks the chain from genesis to tip, recomputing each receipt's hash
+     * and checking it against the stored value. Reports the first breakage.
+     *
+     * @returns Verification result with validity, length, and break point
+     */
+    verifyChain() {
+        if (this.receipts.length === 0) {
+            return {
+                valid: true,
+                length: 0,
+                brokenAt: -1,
+                message: 'Chain is empty (valid)',
+                lastHash: GENESIS_HASH,
+            };
+        }
+        let expectedPrevHash = GENESIS_HASH;
+        for (let i = 0; i < this.receipts.length; i++) {
+            const receipt = this.receipts[i];
+            // Check previousHash link
+            if (receipt.previousHash !== expectedPrevHash) {
+                return {
+                    valid: false,
+                    length: this.receipts.length,
+                    brokenAt: i,
+                    message: `Chain broken at index ${i}: previousHash mismatch`,
+                    lastHash: this.lastHash,
+                };
+            }
+            // Recompute hash
+            const hashPayload = receipt.previousHash + JSON.stringify(receipt.decision) + receipt.timestamp;
+            const expectedHash = createHash('sha256').update(hashPayload).digest('hex');
+            if (receipt.hash !== expectedHash) {
+                return {
+                    valid: false,
+                    length: this.receipts.length,
+                    brokenAt: i,
+                    message: `Chain broken at index ${i}: hash mismatch (tamper detected)`,
+                    lastHash: this.lastHash,
+                };
+            }
+            expectedPrevHash = receipt.hash;
+        }
+        return {
+            valid: true,
+            length: this.receipts.length,
+            brokenAt: -1,
+            message: `Chain valid (${this.receipts.length} receipts)`,
+            lastHash: this.lastHash,
+        };
+    }
+    /**
+     * Get receipts from the chain.
+     *
+     * @param limit - Maximum number of receipts to return (from most recent).
+     *                If omitted, returns the entire chain.
+     * @returns Array of witness receipts
+     */
+    getChain(limit) {
+        if (limit !== undefined && limit > 0) {
+            return [...this.receipts.slice(-limit)];
+        }
+        return [...this.receipts];
+    }
+    /**
+     * Get the total number of receipts in the chain.
+     */
+    getChainLength() {
+        return this.receipts.length;
+    }
+    /**
+     * Get the hash of the most recent receipt (chain tip).
+     */
+    getLastHash() {
+        return this.lastHash;
+    }
+    /**
+     * Export the chain as a JSON string for brain transfer.
+     *
+     * @returns JSON string containing the full chain
+     */
+    exportChain() {
+        const data = {
+            version: '1.0.0',
+            exportedAt: Date.now(),
+            length: this.receipts.length,
+            receipts: this.receipts,
+        };
+        return JSON.stringify(data, null, 2);
+    }
+    /**
+     * Import a chain from a JSON string.
+     *
+     * Validates the imported chain integrity before accepting it.
+     * Replaces the current chain if valid.
+     *
+     * @param data - JSON string from exportChain()
+     * @returns true if import was successful, false if data was invalid
+     */
+    importChain(data) {
+        try {
+            const parsed = JSON.parse(data);
+            // Validate structure
+            if (!parsed || parsed.version !== '1.0.0' || !Array.isArray(parsed.receipts)) {
+                logger.warn('Import failed: invalid format');
+                return false;
+            }
+            // Validate chain integrity before accepting
+            const savedReceipts = this.receipts;
+            const savedLastHash = this.lastHash;
+            this.receipts = parsed.receipts;
+            this.lastHash =
+                parsed.receipts.length > 0
+                    ? parsed.receipts[parsed.receipts.length - 1].hash
+                    : GENESIS_HASH;
+            const verification = this.verifyChain();
+            if (!verification.valid) {
+                // Rollback
+                this.receipts = savedReceipts;
+                this.lastHash = savedLastHash;
+                logger.warn('Import failed: chain integrity check failed', {
+                    message: verification.message,
+                });
+                return false;
+            }
+            logger.info('Chain imported successfully', { length: parsed.receipts.length });
+            return true;
+        }
+        catch (error) {
+            logger.warn('Import failed: parse error', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Get or create an SPRT accumulator for a decision type.
+     *
+     * @param type - The decision type (e.g., 'coherence-gate')
+     * @param alpha - Type I error rate (default: 0.05)
+     * @param beta - Type II error rate (default: 0.05)
+     * @returns The SPRT accumulator for the given type
+     */
+    getSPRT(type, alpha, beta) {
+        if (!this.sprtAccumulators.has(type)) {
+            this.sprtAccumulators.set(type, new SPRTAccumulator(alpha, beta));
+        }
+        return this.sprtAccumulators.get(type);
+    }
+    /**
+     * Get a receipt by chain index.
+     *
+     * @param index - The chain index (0-based)
+     * @returns The receipt at the given index, or undefined if out of range
+     */
+    getReceipt(index) {
+        return this.receipts[index];
+    }
+    // ==========================================================================
+    // Private Methods
+    // ==========================================================================
+    /**
+     * Update the SPRT accumulator based on the decision.
+     */
+    updateSPRT(decision) {
+        const positive = decision.decision === 'PASS' || decision.decision === 'PERMIT';
+        const accumulator = this.getSPRT(decision.type);
+        accumulator.addEvidence(positive);
+    }
+}
+/**
+ * SQLite-backed WitnessChain that persists receipts to the unified database.
+ *
+ * Extends WitnessChain with optional SQLite persistence. When a persistence
+ * backend is provided, each witness receipt is written to SQLite on append,
+ * and the chain can be restored from SQLite on startup.
+ *
+ * @example
+ * ```typescript
+ * const persistence = createWitnessChainSQLitePersistence(db);
+ * const chain = createPersistentWitnessChain(persistence);
+ * // Chain is automatically loaded from SQLite on creation
+ * ```
+ */
+export class PersistentWitnessChain extends WitnessChain {
+    persistence;
+    constructor(persistence) {
+        super();
+        this.persistence = persistence;
+        // Restore chain from SQLite
+        const storedReceipts = persistence.loadAllReceipts();
+        if (storedReceipts.length > 0) {
+            const exported = {
+                version: '1.0.0',
+                exportedAt: Date.now(),
+                length: storedReceipts.length,
+                receipts: storedReceipts,
+            };
+            const imported = this.importChain(JSON.stringify(exported));
+            if (imported) {
+                logger.info('Witness chain restored from SQLite', {
+                    receipts: storedReceipts.length,
+                });
+            }
+            else {
+                logger.warn('Failed to restore witness chain from SQLite — starting fresh');
+            }
+        }
+    }
+    /**
+     * Append a witness and persist it to SQLite.
+     */
+    appendWitness(decision) {
+        const receipt = super.appendWitness(decision);
+        try {
+            this.persistence.insertReceipt(receipt);
+        }
+        catch (err) {
+            logger.warn('Failed to persist witness receipt to SQLite', {
+                chainIndex: receipt.chainIndex,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return receipt;
+    }
+}
+/**
+ * Create a SQLite persistence backend using better-sqlite3.
+ *
+ * Creates the `witness_chain_receipts` table if it doesn't exist
+ * and provides insert/load methods.
+ *
+ * @param db - better-sqlite3 Database instance (from unified persistence)
+ * @returns IWitnessChainPersistence implementation
+ */
+export function createWitnessChainSQLitePersistence(db) {
+    // Create table if not exists
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS witness_chain_receipts (
+      id TEXT PRIMARY KEY,
+      chain_index INTEGER NOT NULL,
+      timestamp INTEGER NOT NULL,
+      previous_hash TEXT NOT NULL,
+      hash TEXT NOT NULL,
+      decision_type TEXT NOT NULL,
+      decision_outcome TEXT NOT NULL,
+      decision_context TEXT NOT NULL,
+      decision_evidence REAL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+    db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_witness_chain_index
+    ON witness_chain_receipts(chain_index)
+  `);
+    const insertStmt = db.prepare(`
+    INSERT OR REPLACE INTO witness_chain_receipts
+    (id, chain_index, timestamp, previous_hash, hash,
+     decision_type, decision_outcome, decision_context, decision_evidence)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    const loadAllStmt = db.prepare(`
+    SELECT * FROM witness_chain_receipts ORDER BY chain_index ASC
+  `);
+    const countStmt = db.prepare(`
+    SELECT COUNT(*) as cnt FROM witness_chain_receipts
+  `);
+    return {
+        insertReceipt(receipt) {
+            insertStmt.run(receipt.id, receipt.chainIndex, receipt.timestamp, receipt.previousHash, receipt.hash, receipt.decision.type, receipt.decision.decision, JSON.stringify(receipt.decision.context), receipt.decision.evidence ?? null);
+        },
+        loadAllReceipts() {
+            const rows = loadAllStmt.all();
+            return rows.map(row => {
+                let context = {};
+                try {
+                    context = JSON.parse(row.decision_context);
+                }
+                catch {
+                    logger.warn('Corrupt decision_context in witness receipt, using empty object', {
+                        receiptId: row.id,
+                        chainIndex: row.chain_index,
+                    });
+                }
+                return {
+                    id: row.id,
+                    chainIndex: row.chain_index,
+                    timestamp: row.timestamp,
+                    previousHash: row.previous_hash,
+                    hash: row.hash,
+                    decision: {
+                        type: row.decision_type,
+                        decision: row.decision_outcome,
+                        context,
+                        evidence: row.decision_evidence ?? undefined,
+                    },
+                };
+            });
+        },
+        getReceiptCount() {
+            const row = countStmt.get();
+            return row.cnt;
+        },
+    };
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a new WitnessChain instance (in-memory).
+ *
+ * @returns A new empty WitnessChain
+ */
+export function createWitnessChain() {
+    return new WitnessChain();
+}
+/**
+ * Create a SQLite-backed WitnessChain that persists receipts.
+ *
+ * @param persistence - SQLite persistence backend
+ * @returns A PersistentWitnessChain loaded from SQLite
+ */
+export function createPersistentWitnessChain(persistence) {
+    return new PersistentWitnessChain(persistence);
+}
+/**
+ * Check if the witness chain feature is enabled.
+ *
+ * @returns true if the useWitnessChain feature flag is on
+ */
+export function isWitnessChainFeatureEnabled() {
+    return getRuVectorFeatureFlags().useWitnessChain;
+}
+//# sourceMappingURL=witness-chain.js.map

package/dist/init/index.d.ts

@@ -41,6 +41,4 @@ export type { WindsurfInstallerOptions, WindsurfInstallResult } from './windsurf
 export { WindsurfInstaller, createWindsurfInstaller } from './windsurf-installer.js';
 export type { ContinueDevInstallerOptions, ContinueDevInstallResult } from './continuedev-installer.js';
 export { ContinueDevInstaller, createContinueDevInstaller } from './continuedev-installer.js';
-export type { V2DetectionInfo, MigrationResult, } from './migration/index.js';
-export { V2Detector, createV2Detector, V2DataMigrator, createV2DataMigrator, V2ConfigMigrator, createV2ConfigMigrator, } from './migration/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/init/index.js

@@ -24,5 +24,4 @@ export { RooCodeInstaller, createRooCodeInstaller } from './roocode-installer.js
 export { CodexInstaller, createCodexInstaller } from './codex-installer.js';
 export { WindsurfInstaller, createWindsurfInstaller } from './windsurf-installer.js';
 export { ContinueDevInstaller, createContinueDevInstaller } from './continuedev-installer.js';
-export { V2Detector, createV2Detector, V2DataMigrator, createV2DataMigrator, V2ConfigMigrator, createV2ConfigMigrator, } from './migration/index.js';
 //# sourceMappingURL=index.js.map

package/dist/init/init-wizard-steps.d.ts

@@ -6,6 +6,16 @@
  * Extracted from init-wizard.ts.
  */
 import type { AQEInitConfig, PretrainedLibrary } from './types.js';
+/**
+ * Read AQE version directly from memory.db without full initialization.
+ * Returns undefined if no version is stored.
+ */
+export declare function readVersionFromDb(dbPath: string): string | undefined;
+/**
+ * Write AQE version to memory.db in _system namespace.
+ * Used by init wizard to mark installation version.
+ */
+export declare function writeVersionToDb(projectRoot: string, version: string): Promise<boolean>;
 /**
  * Initialize the persistence database (REQUIRED).
  * Creates the SQLite database file with proper schema.

package/dist/init/init-wizard-steps.js

@@ -6,12 +6,98 @@
  * Extracted from init-wizard.ts.
  */
 import { existsSync, mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { join, dirname } from 'path';
 import { createSkillsInstaller } from './skills-installer.js';
 import { createAgentsInstaller } from './agents-installer.js';
 import { createN8nInstaller } from './n8n-installer.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { openDatabase } from '../shared/safe-db.js';
+import { safeJsonParse } from '../shared/safe-json.js';
+// ============================================================================
+// Version Management
+// ============================================================================
+/**
+ * Read AQE version directly from memory.db without full initialization.
+ * Returns undefined if no version is stored.
+ */
+export function readVersionFromDb(dbPath) {
+    try {
+        const db = openDatabase(dbPath, { readonly: true, fileMustExist: true });
+        try {
+            const tableExists = db.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type='table' AND name='kv_store'
+      `).get();
+            if (!tableExists) {
+                db.close();
+                return undefined;
+            }
+            const row = db.prepare(`
+        SELECT value FROM kv_store
+        WHERE key = 'aqe_version' AND namespace = '_system'
+      `).get();
+            db.close();
+            if (row) {
+                return safeJsonParse(row.value);
+            }
+            return undefined;
+        }
+        catch {
+            db.close();
+            return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Write AQE version to memory.db in _system namespace.
+ * Used by init wizard to mark installation version.
+ */
+export async function writeVersionToDb(projectRoot, version) {
+    const memoryDbPath = join(projectRoot, '.agentic-qe', 'memory.db');
+    try {
+        const dir = dirname(memoryDbPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const db = openDatabase(memoryDbPath);
+        try {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS kv_store (
+          key TEXT NOT NULL,
+          namespace TEXT NOT NULL,
+          value TEXT NOT NULL,
+          expires_at INTEGER,
+          created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),
+          PRIMARY KEY (namespace, key)
+        );
+      `);
+            const now = Date.now();
+            db.prepare(`
+        INSERT OR REPLACE INTO kv_store (key, namespace, value, created_at)
+        VALUES (?, '_system', ?, ?)
+      `).run('aqe_version', JSON.stringify(version), now);
+            db.prepare(`
+        INSERT OR REPLACE INTO kv_store (key, namespace, value, created_at)
+        VALUES (?, '_system', ?, ?)
+      `).run('init_timestamp', JSON.stringify(new Date().toISOString()), now);
+            db.close();
+            console.log(`  ✓ Version ${version} written to memory.db`);
+            return true;
+        }
+        catch (err) {
+            db.close();
+            console.warn(`  ⚠ Could not write version: ${toErrorMessage(err)}`);
+            return false;
+        }
+    }
+    catch (err) {
+        console.warn(`  ⚠ Could not open memory.db: ${toErrorMessage(err)}`);
+        return false;
+    }
+}
 // ============================================================================
 // Persistence Database
 // ============================================================================

package/dist/init/init-wizard.d.ts

@@ -6,11 +6,9 @@
  *
  * This is a facade module. Implementation details are extracted to:
  * - init-wizard-hooks.ts     (hook configuration, MCP, CLAUDE.md generation)
- * - init-wizard-migration.ts (V2 detection, migration, config conversion)
- * - init-wizard-steps.ts     (persistence, learning, workers, skills, agents, config)
+ * - init-wizard-steps.ts     (persistence, learning, workers, skills, agents, config, version)
  */
 import type { InitResult, WizardStep, PretrainedLibrary } from './types.js';
-export type { V2DetectionResult } from './init-wizard-migration.js';
 export interface InitOrchestratorOptions {
     /** Project root directory */
     projectRoot: string;
@@ -31,8 +29,6 @@ export interface InitOrchestratorOptions {
         baseUrl?: string;
         apiKey?: string;
     };
-    /** Automatically migrate from v2 if detected */
-    autoMigrate?: boolean;
 }
 export declare class InitOrchestrator {
     private projectRoot;
@@ -49,10 +45,6 @@ export declare class InitOrchestrator {
      * Get wizard steps
      */
     getWizardSteps(): WizardStep[];
-    /**
-     * Handle V2 detection - returns early result if migration not auto, null otherwise.
-     */
-    private handleV2Detection;
     /**
      * Run a single initialization step with timing and status tracking
      */