agentic-qe 3.8.11 → 3.8.13

package/dist/integrations/ruvector/delta-tracker.d.ts

@@ -0,0 +1,122 @@
+/**
+ * R3: Delta Event Sourcing for Pattern History
+ *
+ * Tracks pattern version history as a sequence of delta events.
+ * Enables rollback to any previous state and incremental sync between agents.
+ * Uses SQLite for persistence via the existing database layer.
+ *
+ * @module integrations/ruvector/delta-tracker
+ */
+import { type Database as DatabaseType } from 'better-sqlite3';
+/**
+ * RFC 6902 JSON Patch operation
+ */
+export interface JsonPatch {
+    op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+    path: string;
+    value?: unknown;
+    from?: string;
+}
+/**
+ * A single delta event representing a change to a pattern
+ */
+export interface DeltaEvent {
+    /** Unique delta ID (UUID) */
+    id: string;
+    /** Pattern being tracked */
+    patternId: string;
+    /** Sequential version number (0 = genesis) */
+    version: number;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Event type */
+    type: 'genesis' | 'update' | 'rollback';
+    /** RFC 6902 JSON Patch operations (forward) */
+    patch: JsonPatch[];
+    /** RFC 6902 JSON Patch operations (reverse, for undo) */
+    reversePatch: JsonPatch[];
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for the DeltaTracker
+ */
+export interface DeltaTrackerConfig {
+    /** Maximum versions to retain per pattern. Default: 100 */
+    maxVersionsPerPattern?: number;
+    /** Reserved for future LZ4 compression support. Default: false */
+    compressDeltas?: boolean;
+}
+/**
+ * DDL for the pattern_deltas table
+ */
+export declare const PATTERN_DELTAS_SCHEMA = "\n  CREATE TABLE IF NOT EXISTS pattern_deltas (\n    id TEXT PRIMARY KEY,\n    pattern_id TEXT NOT NULL,\n    version INTEGER NOT NULL,\n    timestamp INTEGER NOT NULL,\n    type TEXT NOT NULL CHECK (type IN ('genesis', 'update', 'rollback')),\n    patch TEXT NOT NULL DEFAULT '[]',\n    reverse_patch TEXT NOT NULL DEFAULT '[]',\n    metadata TEXT\n  );\n  CREATE INDEX IF NOT EXISTS idx_pattern_deltas_pid_version\n    ON pattern_deltas (pattern_id, version);\n  CREATE INDEX IF NOT EXISTS idx_pattern_deltas_timestamp\n    ON pattern_deltas (timestamp);\n";
+/**
+ * Tracks pattern version history as delta events with rollback support.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new DeltaTracker(db);
+ * tracker.initialize();
+ *
+ * tracker.createGenesis('pat-1', { name: 'Login test', confidence: 0.5 });
+ * tracker.recordDelta('pat-1', { name: 'Login test', confidence: 0.5 }, { name: 'Login test', confidence: 0.9 });
+ *
+ * const state = tracker.rollback('pat-1', 0); // back to genesis
+ * ```
+ */
+export declare class DeltaTracker {
+    private readonly db;
+    private readonly config;
+    private prepared;
+    private initialized;
+    constructor(db: DatabaseType, config?: DeltaTrackerConfig);
+    /**
+     * Create the pattern_deltas table and indexes if they do not exist.
+     */
+    initialize(): void;
+    private prepareStatements;
+    private ensureInitialized;
+    /**
+     * Create a genesis snapshot for a pattern (version 0).
+     * The full object is stored in metadata.snapshot; patches are empty.
+     */
+    createGenesis(patternId: string, snapshot: object, metadata?: Record<string, unknown>): DeltaEvent;
+    /**
+     * Record a delta between two states of a pattern.
+     * Computes forward and reverse patches automatically.
+     */
+    recordDelta(patternId: string, before: object, after: object, metadata?: Record<string, unknown>): DeltaEvent;
+    /**
+     * Rollback a pattern to a specific version by applying reverse patches
+     * from the current version back to the target version.
+     *
+     * Returns the reconstructed object at the target version.
+     */
+    rollback(patternId: string, toVersion: number): object;
+    /**
+     * Get the full delta history for a pattern, ordered by version ascending.
+     */
+    getHistory(patternId: string): DeltaEvent[];
+    /**
+     * Get all delta events created after a given timestamp (for incremental sync).
+     */
+    incrementalSync(since: number): DeltaEvent[];
+    /**
+     * Get the current (highest) version number for a pattern.
+     * Returns -1 if no events exist for the pattern.
+     */
+    getCurrentVersion(patternId: string): number;
+    private insertEvent;
+    /**
+     * Reconstruct pattern state at a given version by replaying patches
+     * from genesis forward.
+     */
+    private reconstructState;
+    /**
+     * Enforce maxVersionsPerPattern retention by deleting oldest deltas.
+     * Always keeps the genesis event (version 0).
+     */
+    private enforceRetention;
+}
+//# sourceMappingURL=delta-tracker.d.ts.map

package/dist/integrations/ruvector/delta-tracker.js

@@ -0,0 +1,311 @@
+/**
+ * R3: Delta Event Sourcing for Pattern History
+ *
+ * Tracks pattern version history as a sequence of delta events.
+ * Enables rollback to any previous state and incremental sync between agents.
+ * Uses SQLite for persistence via the existing database layer.
+ *
+ * @module integrations/ruvector/delta-tracker
+ */
+import { v4 as uuidv4 } from 'uuid';
+import * as fastJsonPatch from 'fast-json-patch';
+// ============================================================================
+// Schema
+// ============================================================================
+/**
+ * DDL for the pattern_deltas table
+ */
+export const PATTERN_DELTAS_SCHEMA = `
+  CREATE TABLE IF NOT EXISTS pattern_deltas (
+    id TEXT PRIMARY KEY,
+    pattern_id TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    timestamp INTEGER NOT NULL,
+    type TEXT NOT NULL CHECK (type IN ('genesis', 'update', 'rollback')),
+    patch TEXT NOT NULL DEFAULT '[]',
+    reverse_patch TEXT NOT NULL DEFAULT '[]',
+    metadata TEXT
+  );
+  CREATE INDEX IF NOT EXISTS idx_pattern_deltas_pid_version
+    ON pattern_deltas (pattern_id, version);
+  CREATE INDEX IF NOT EXISTS idx_pattern_deltas_timestamp
+    ON pattern_deltas (timestamp);
+`;
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/**
+ * Compute forward and reverse RFC 6902 patches between two objects.
+ * Uses fast-json-patch for reliable diff generation.
+ */
+function computePatches(before, after) {
+    const forward = fastJsonPatch.compare(before, after);
+    const reverse = fastJsonPatch.compare(after, before);
+    return { forward, reverse };
+}
+/**
+ * Apply a sequence of JSON Patch operations to an object (immutable).
+ * Returns a deep clone with patches applied.
+ */
+function applyPatches(obj, patches) {
+    const cloned = JSON.parse(JSON.stringify(obj));
+    const result = fastJsonPatch.applyPatch(cloned, patches);
+    return result.newDocument;
+}
+function rowToEvent(row) {
+    return {
+        id: row.id,
+        patternId: row.pattern_id,
+        version: row.version,
+        timestamp: row.timestamp,
+        type: row.type,
+        patch: JSON.parse(row.patch),
+        reversePatch: JSON.parse(row.reverse_patch),
+        metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+    };
+}
+// ============================================================================
+// DeltaTracker
+// ============================================================================
+/**
+ * Tracks pattern version history as delta events with rollback support.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new DeltaTracker(db);
+ * tracker.initialize();
+ *
+ * tracker.createGenesis('pat-1', { name: 'Login test', confidence: 0.5 });
+ * tracker.recordDelta('pat-1', { name: 'Login test', confidence: 0.5 }, { name: 'Login test', confidence: 0.9 });
+ *
+ * const state = tracker.rollback('pat-1', 0); // back to genesis
+ * ```
+ */
+export class DeltaTracker {
+    db;
+    config;
+    prepared = new Map();
+    initialized = false;
+    constructor(db, config) {
+        this.db = db;
+        this.config = {
+            maxVersionsPerPattern: config?.maxVersionsPerPattern ?? 100,
+            compressDeltas: config?.compressDeltas ?? false,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Initialization
+    // --------------------------------------------------------------------------
+    /**
+     * Create the pattern_deltas table and indexes if they do not exist.
+     */
+    initialize() {
+        if (this.initialized)
+            return;
+        this.db.exec(PATTERN_DELTAS_SCHEMA);
+        this.prepareStatements();
+        this.initialized = true;
+    }
+    prepareStatements() {
+        this.prepared.set('insert', this.db.prepare(`
+        INSERT INTO pattern_deltas (id, pattern_id, version, timestamp, type, patch, reverse_patch, metadata)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `));
+        this.prepared.set('getHistory', this.db.prepare(`
+        SELECT * FROM pattern_deltas
+        WHERE pattern_id = ?
+        ORDER BY version ASC
+      `));
+        this.prepared.set('currentVersion', this.db.prepare(`
+        SELECT MAX(version) as max_version FROM pattern_deltas
+        WHERE pattern_id = ?
+      `));
+        this.prepared.set('incrementalSync', this.db.prepare(`
+        SELECT * FROM pattern_deltas
+        WHERE timestamp > ?
+        ORDER BY timestamp ASC
+      `));
+        this.prepared.set('countForPattern', this.db.prepare(`
+        SELECT COUNT(*) as cnt FROM pattern_deltas
+        WHERE pattern_id = ?
+      `));
+        this.prepared.set('deleteOldest', this.db.prepare(`
+        DELETE FROM pattern_deltas
+        WHERE pattern_id = ? AND version IN (
+          SELECT version FROM pattern_deltas
+          WHERE pattern_id = ?
+          ORDER BY version ASC
+          LIMIT ?
+        )
+      `));
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('DeltaTracker not initialized. Call initialize() first.');
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Public API
+    // --------------------------------------------------------------------------
+    /**
+     * Create a genesis snapshot for a pattern (version 0).
+     * The full object is stored in metadata.snapshot; patches are empty.
+     */
+    createGenesis(patternId, snapshot, metadata) {
+        this.ensureInitialized();
+        const existing = this.getCurrentVersion(patternId);
+        if (existing >= 0) {
+            throw new Error(`Genesis already exists for pattern ${patternId} (current version: ${existing})`);
+        }
+        const event = {
+            id: uuidv4(),
+            patternId,
+            version: 0,
+            timestamp: Date.now(),
+            type: 'genesis',
+            patch: [],
+            reversePatch: [],
+            metadata: { ...metadata, snapshot },
+        };
+        this.insertEvent(event);
+        return event;
+    }
+    /**
+     * Record a delta between two states of a pattern.
+     * Computes forward and reverse patches automatically.
+     */
+    recordDelta(patternId, before, after, metadata) {
+        this.ensureInitialized();
+        const currentVersion = this.getCurrentVersion(patternId);
+        if (currentVersion < 0) {
+            throw new Error(`No genesis found for pattern ${patternId}. Call createGenesis() first.`);
+        }
+        const { forward, reverse } = computePatches(before, after);
+        const event = {
+            id: uuidv4(),
+            patternId,
+            version: currentVersion + 1,
+            timestamp: Date.now(),
+            type: 'update',
+            patch: forward,
+            reversePatch: reverse,
+            metadata,
+        };
+        this.insertEvent(event);
+        this.enforceRetention(patternId);
+        return event;
+    }
+    /**
+     * Rollback a pattern to a specific version by applying reverse patches
+     * from the current version back to the target version.
+     *
+     * Returns the reconstructed object at the target version.
+     */
+    rollback(patternId, toVersion) {
+        this.ensureInitialized();
+        const history = this.getHistory(patternId);
+        if (history.length === 0) {
+            throw new Error(`No history found for pattern ${patternId}`);
+        }
+        const currentVersion = history[history.length - 1].version;
+        if (toVersion < 0 || toVersion > currentVersion) {
+            throw new Error(`Invalid rollback version ${toVersion}. Valid range: 0-${currentVersion}`);
+        }
+        if (toVersion === currentVersion) {
+            // Already at target; reconstruct current state
+            return this.reconstructState(history, currentVersion);
+        }
+        // Reconstruct the state at the target version
+        const targetState = this.reconstructState(history, toVersion);
+        // Record a rollback event from current to target
+        const currentState = this.reconstructState(history, currentVersion);
+        const { forward, reverse } = computePatches(currentState, targetState);
+        const rollbackEvent = {
+            id: uuidv4(),
+            patternId,
+            version: currentVersion + 1,
+            timestamp: Date.now(),
+            type: 'rollback',
+            patch: forward,
+            reversePatch: reverse,
+            metadata: { rolledBackTo: toVersion },
+        };
+        this.insertEvent(rollbackEvent);
+        this.enforceRetention(patternId);
+        return targetState;
+    }
+    /**
+     * Get the full delta history for a pattern, ordered by version ascending.
+     */
+    getHistory(patternId) {
+        this.ensureInitialized();
+        const rows = this.prepared.get('getHistory').all(patternId);
+        return rows.map(rowToEvent);
+    }
+    /**
+     * Get all delta events created after a given timestamp (for incremental sync).
+     */
+    incrementalSync(since) {
+        this.ensureInitialized();
+        const rows = this.prepared.get('incrementalSync').all(since);
+        return rows.map(rowToEvent);
+    }
+    /**
+     * Get the current (highest) version number for a pattern.
+     * Returns -1 if no events exist for the pattern.
+     */
+    getCurrentVersion(patternId) {
+        this.ensureInitialized();
+        const row = this.prepared.get('currentVersion').get(patternId);
+        return row.max_version ?? -1;
+    }
+    // --------------------------------------------------------------------------
+    // Internal helpers
+    // --------------------------------------------------------------------------
+    insertEvent(event) {
+        this.prepared.get('insert').run(event.id, event.patternId, event.version, event.timestamp, event.type, JSON.stringify(event.patch), JSON.stringify(event.reversePatch), event.metadata ? JSON.stringify(event.metadata) : null);
+    }
+    /**
+     * Reconstruct pattern state at a given version by replaying patches
+     * from genesis forward.
+     */
+    reconstructState(history, targetVersion) {
+        const genesis = history.find((e) => e.type === 'genesis');
+        if (!genesis || !genesis.metadata?.snapshot) {
+            throw new Error('Cannot reconstruct state: no genesis snapshot found');
+        }
+        let state = JSON.parse(JSON.stringify(genesis.metadata.snapshot));
+        // Apply forward patches from version 1 up to targetVersion
+        for (const event of history) {
+            if (event.version === 0)
+                continue;
+            if (event.version > targetVersion)
+                break;
+            state = applyPatches(state, event.patch);
+        }
+        return state;
+    }
+    /**
+     * Enforce maxVersionsPerPattern retention by deleting oldest deltas.
+     * Always keeps the genesis event (version 0).
+     */
+    enforceRetention(patternId) {
+        const { maxVersionsPerPattern } = this.config;
+        const row = this.prepared.get('countForPattern').get(patternId);
+        const count = row.cnt;
+        if (count > maxVersionsPerPattern) {
+            const excess = count - maxVersionsPerPattern;
+            // Delete oldest non-genesis events
+            this.db
+                .prepare(`DELETE FROM pattern_deltas
+           WHERE pattern_id = ? AND version != 0 AND id IN (
+             SELECT id FROM pattern_deltas
+             WHERE pattern_id = ? AND version != 0
+             ORDER BY version ASC
+             LIMIT ?
+           )`)
+                .run(patternId, patternId, excess);
+        }
+    }
+}
+//# sourceMappingURL=delta-tracker.js.map

package/dist/integrations/ruvector/domain-transfer.d.ts

@@ -3,7 +3,8 @@
  *
  * Enables knowledge transfer between QE domains using Thompson Sampling
  * with Beta priors, sqrt-dampening, transfer verification gates, domain
- * pair affinity scoring, and coherence gate integration.
+ * pair affinity scoring, coherence gate integration, and R7 meta-learning
+ * enhancements (DecayingBeta, PlateauDetector, ParetoFront, CuriosityBonus).
  *
  * @module integrations/ruvector/domain-transfer
  */
@@ -59,9 +60,70 @@ export interface DomainTransferConfig {
     verification: Partial<TransferVerificationConfig>;
     /** Maximum transfer records to retain in history */
     maxHistorySize: number;
+    /** Enable R7 meta-learning enhancements (ADR-087, Milestone 3) */
+    useMetaLearningEnhancements: boolean;
 }
 /** Default domain transfer configuration */
 export declare const DEFAULT_DOMAIN_TRANSFER_CONFIG: DomainTransferConfig;
+/** Point on the Pareto front, tracking multi-objective performance */
+export interface ParetoPoint {
+    pairKey: string;
+    successRate: number;
+    speed: number;
+    confidence: number;
+}
+/** Applies time-based decay to Thompson Sampler exploration variance. */
+export declare class DecayingBeta {
+    private readonly decayThreshold;
+    constructor(decayThreshold?: number);
+    /** Decay multiplier: 0.5^(successCount/threshold). 1.0 when count=0, 0.5 at threshold. */
+    getDecayMultiplier(successCount: number): number;
+    /** Shrink sampled value toward mean by the decay multiplier. */
+    applyDecay(sampled: number, mean: number, successCount: number): number;
+}
+/**
+ * Detects when transfer success rate has plateaued using CUSUM (R2).
+ *
+ * Feeds a running success rate into a CusumDetector on the 'learn' gate.
+ * Plateau is detected when CUSUM does NOT fire — i.e., the rate is
+ * stationary (no drift in either direction) for enough samples.
+ * CUSUM firing means the rate is changing, so NOT plateaued.
+ */
+export declare class PlateauDetector {
+    private readonly cusum;
+    private readonly outcomes;
+    private readonly windowSize;
+    constructor(windowSize?: number);
+    record(success: boolean): void;
+    /**
+     * Plateau = we have enough data AND CUSUM has not detected drift.
+     * No drift means the rate is stationary — learning has stalled.
+     */
+    isPlateaued(): boolean;
+    getCurrentRate(): number;
+    getOutcomeCount(): number;
+    /** Expose CUSUM state for observability */
+    getCusumState(): import("./cusum-detector.js").CusumResult;
+}
+/** Tracks Pareto-optimal transfer candidates across multiple objectives. */
+export declare class ParetoFront {
+    private readonly front;
+    dominates(a: ParetoPoint, b: ParetoPoint): boolean;
+    add(point: ParetoPoint): void;
+    getFront(): ParetoPoint[];
+    isNonDominated(point: ParetoPoint): boolean;
+}
+/** Curiosity bonus for novel/untried source-target domain pairs. */
+export declare class CuriosityBonus {
+    private readonly bonusScale;
+    private readonly triedPairs;
+    constructor(bonusScale?: number);
+    markTried(pairKey: string): void;
+    isTried(pairKey: string): boolean;
+    getBonus(pairKey: string): number;
+    apply(sampledProbability: number, pairKey: string): number;
+    getTriedCount(): number;
+}
 /**
  * Cross-domain transfer learning engine. Moves learned patterns between QE
  * domains using Thompson Sampling, sqrt-dampening, and a double verification gate.
@@ -76,10 +138,15 @@ export declare class DomainTransferEngine {
     private performanceProvider;
     private transferExecutor;
     private nativeModule;
+    private readonly decayingBeta;
+    private readonly plateauDetector;
+    private readonly paretoFront;
+    private readonly curiosityBonus;
     constructor(config?: Partial<DomainTransferConfig>);
     /**
      * Evaluate whether a transfer between two domains should be attempted.
      * Uses Thompson Sampling to balance exploration and exploitation.
+     * When meta-learning is enabled, applies DecayingBeta and CuriosityBonus.
      */
     evaluateTransfer(sourceDomain: string, targetDomain: string): TransferCandidate;
     /**
@@ -104,7 +171,18 @@ export declare class DomainTransferEngine {
     getSampler(): ThompsonSampler;
     /** Get the coherence gate (for testing). */
     getCoherenceGate(): ITransferCoherenceGate;
+    /** Get the DecayingBeta component (for testing). */
+    getDecayingBeta(): DecayingBeta;
+    /** Get the PlateauDetector component (for testing). */
+    getPlateauDetector(): PlateauDetector;
+    /** Get the ParetoFront component (for testing). */
+    getParetoFront(): ParetoFront;
+    /** Get the CuriosityBonus component (for testing). */
+    getCuriosityBonus(): CuriosityBonus;
+    /** Check if learning has plateaued */
+    isLearningPlateaued(): boolean;
     private isEnabled;
+    private isMetaLearningEnabled;
     private makePairKey;
     /**
      * Sqrt-dampening: sqrt(observations / (observations + warmup)).