agentic-qe 3.10.5 → 3.10.6

package/dist/kernel/unified-memory-schemas.d.ts

@@ -5,8 +5,9 @@
  * Extracted from unified-memory.ts for maintainability.
  */
 import { HYPERGRAPH_SCHEMA } from '../migrations/20260120_add_hypergraph_tables.js';
-export { HYPERGRAPH_SCHEMA };
-export declare const SCHEMA_VERSION = 9;
+import { PATTERN_NULLS_SCHEMA } from '../migrations/20260611_add_pattern_nulls_table.js';
+export { HYPERGRAPH_SCHEMA, PATTERN_NULLS_SCHEMA };
+export declare const SCHEMA_VERSION = 10;
 export declare const SCHEMA_VERSION_TABLE = "\n  CREATE TABLE IF NOT EXISTS schema_version (\n    id INTEGER PRIMARY KEY CHECK (id = 1),\n    version INTEGER NOT NULL,\n    migrated_at TEXT DEFAULT (datetime('now'))\n  );\n";
 export declare const KV_STORE_SCHEMA = "\n  -- Key-Value Store (v2 compatible - same schema as HybridBackend)\n  CREATE TABLE IF NOT EXISTS kv_store (\n    key TEXT NOT NULL,\n    namespace TEXT NOT NULL,\n    value TEXT NOT NULL,\n    expires_at INTEGER,\n    created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),\n    PRIMARY KEY (namespace, key)\n  );\n  CREATE INDEX IF NOT EXISTS idx_kv_namespace ON kv_store(namespace);\n  CREATE INDEX IF NOT EXISTS idx_kv_expires ON kv_store(expires_at) WHERE expires_at IS NOT NULL;\n";
 export declare const VECTORS_SCHEMA = "\n  -- Vector Embeddings (new in v3 - replaces in-memory AgentDB)\n  CREATE TABLE IF NOT EXISTS vectors (\n    id TEXT PRIMARY KEY,\n    namespace TEXT NOT NULL DEFAULT 'default',\n    embedding BLOB NOT NULL,\n    dimensions INTEGER NOT NULL,\n    metadata TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    updated_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_vectors_namespace ON vectors(namespace);\n  CREATE INDEX IF NOT EXISTS idx_vectors_dimensions ON vectors(dimensions);\n";

package/dist/kernel/unified-memory-schemas.js

@@ -5,12 +5,13 @@
  * Extracted from unified-memory.ts for maintainability.
  */
 import { HYPERGRAPH_SCHEMA } from '../migrations/20260120_add_hypergraph_tables.js';
+import { PATTERN_NULLS_SCHEMA } from '../migrations/20260611_add_pattern_nulls_table.js';
 // Re-export for convenience
-export { HYPERGRAPH_SCHEMA };
+export { HYPERGRAPH_SCHEMA, PATTERN_NULLS_SCHEMA };
 // ============================================================================
 // Schema Version for Migrations
 // ============================================================================
-export const SCHEMA_VERSION = 9; // v9: adds FTS5 full-text search for qe_patterns (hybrid vector/text search)
+export const SCHEMA_VERSION = 10; // v10: adds qe_pattern_nulls — kept negative pattern records (ADR-110)
 export const SCHEMA_VERSION_TABLE = `
   CREATE TABLE IF NOT EXISTS schema_version (
     id INTEGER PRIMARY KEY CHECK (id = 1),

package/dist/kernel/unified-memory.js

@@ -40,7 +40,7 @@ export { BinaryHeap, UnifiedHnswIndex, createHnswIndex } from './unified-memory-
 // parity tests or benchmarks only.
 import { UnifiedHnswIndex } from './unified-memory-hnsw.js';
 // Import schemas
-import { SCHEMA_VERSION, SCHEMA_VERSION_TABLE, KV_STORE_SCHEMA, VECTORS_SCHEMA, RL_QVALUES_SCHEMA, GOAP_SCHEMA, DREAM_SCHEMA, QE_PATTERNS_SCHEMA, MINCUT_SCHEMA, SONA_PATTERNS_SCHEMA, FEEDBACK_SCHEMA, HYPERGRAPH_SCHEMA, STATS_TABLES, } from './unified-memory-schemas.js';
+import { SCHEMA_VERSION, SCHEMA_VERSION_TABLE, KV_STORE_SCHEMA, VECTORS_SCHEMA, RL_QVALUES_SCHEMA, GOAP_SCHEMA, DREAM_SCHEMA, QE_PATTERNS_SCHEMA, MINCUT_SCHEMA, SONA_PATTERNS_SCHEMA, FEEDBACK_SCHEMA, HYPERGRAPH_SCHEMA, PATTERN_NULLS_SCHEMA, STATS_TABLES, } from './unified-memory-schemas.js';
 // CRDT imports for distributed state synchronization
 import { createCRDTStore, } from '../memory/crdt/index.js';
 // ============================================================================
@@ -452,6 +452,8 @@ export class UnifiedMemoryManager {
             SELECT rowid, name, description, pattern_type, qe_domain FROM qe_patterns;
           `);
                 }
+                if (currentVersion < 10)
+                    this.db.exec(PATTERN_NULLS_SCHEMA);
                 this.db.prepare(`
           INSERT OR REPLACE INTO schema_version (id, version, migrated_at)
           VALUES (1, ?, datetime('now'))

package/dist/learning/aqe-learning-engine.js

@@ -147,6 +147,20 @@ export class AQELearningEngine {
                 if (process.env.DEBUG)
                     console.debug('[AQELearningEngine] Witness chain wiring skipped:', e instanceof Error ? e.message : e);
             }
+            // Wire ADR-110 kept-nulls recorder (fail-soft, mirrors witness wiring)
+            try {
+                const { getUnifiedPersistence } = await import('../kernel/unified-persistence.js');
+                const persistence = getUnifiedPersistence();
+                if (persistence.isInitialized()) {
+                    const { PatternNullStore } = await import('./pattern-null-store.js');
+                    const nullStore = new PatternNullStore(persistence.getDatabase());
+                    this.experienceCapture.setNullRecorder((record) => nullStore.recordNull(record));
+                }
+            }
+            catch (e) {
+                if (process.env.DEBUG)
+                    console.debug('[AQELearningEngine] Null recorder wiring skipped:', e instanceof Error ? e.message : e);
+            }
         }
         // Wire cross-domain transfer with real performance provider (Y-2 fix)
         try {
@@ -316,10 +330,12 @@ export class AQELearningEngine {
             return err(new Error('Engine not initialized'));
         }
         // Search for similar patterns before routing (Phase 5.1 & 5.3)
+        // ADR-110: pass context so previously-failed patterns are discounted here too
         const patternSearchResult = await this.searchPatternsForTask(request.task, {
             limit: 5,
             minConfidence: 0.4,
             domain: request.domain,
+            contextFingerprint: request.domain ? `${request.domain}:router` : undefined,
         });
         // Track pattern usage for found patterns (Phase 5.4)
         if (patternSearchResult.success && patternSearchResult.value.length > 0) {
@@ -363,6 +379,7 @@ export class AQELearningEngine {
                 limit: options.limit || 5,
                 minConfidence: options.minConfidence || 0.4,
                 domain: options.domain,
+                contextFingerprint: options.contextFingerprint,
                 useVectorSearch: true,
             });
         }
@@ -555,6 +572,20 @@ export class AQELearningEngine {
                 // Fall through to local tracking
             }
         }
+        // ADR-110: retrieve the patterns that will GUIDE this task so a failure
+        // can be attributed to them as kept nulls. Fail-soft — guidance is
+        // best-effort and must never block task start.
+        const contextFingerprint = `${domain ?? 'unknown'}:${agent ?? 'unknown'}`;
+        let appliedPatterns;
+        try {
+            const guiding = await this.searchPatternsForTask(task, { domain, contextFingerprint });
+            if (guiding.success && guiding.value.length > 0) {
+                appliedPatterns = guiding.value.map(r => r.pattern.id);
+            }
+        }
+        catch {
+            // guidance retrieval is non-critical; proceed without it
+        }
         // Start experience capture (linked to trajectory if available)
         let experienceId;
         if (this.experienceCapture) {
@@ -562,6 +593,7 @@ export class AQELearningEngine {
                 agent,
                 domain,
                 trajectoryId: trajectoryId !== id ? trajectoryId : undefined,
+                appliedPatterns,
             });
         }
         // Local tracking

package/dist/learning/experience-capture.d.ts

@@ -75,6 +75,8 @@ export interface TaskExperience {
     feedback?: string;
     /** Extracted patterns (if any) */
     patterns?: string[];
+    /** Patterns that GUIDED this task (retrieved before execution) — null-capture targets on failure (ADR-110) */
+    appliedPatterns?: string[];
     /** Claude Flow trajectory ID (if available) */
     trajectoryId?: string;
     /** Additional metadata */
@@ -169,12 +171,16 @@ export declare class ExperienceCaptureService {
     private sessionCaptureCount;
     /** Optional witness chain for attaching audit receipts to experiences */
     private witnessChain?;
+    /** Optional ADR-110 null recorder — wired by the composition root to PatternNullStore.recordNull */
+    private nullRecorder?;
     constructor(memory: MemoryBackend, patternStore?: IPatternStore | undefined, eventBus?: EventBus | undefined, config?: Partial<ExperienceCaptureConfig>);
     /**
      * Set the witness chain for attaching audit receipts to captured experiences.
      * Only creates witness records when the useWitnessChain feature flag is enabled.
      */
     setWitnessChain(chain: WitnessChain): void;
+    /** Wire the ADR-110 kept-nulls recorder (typically PatternNullStore.recordNull). */
+    setNullRecorder(recorder: NonNullable<typeof this.nullRecorder>): void;
     /**
      * Initialize the experience capture service
      */
@@ -188,6 +194,8 @@ export declare class ExperienceCaptureService {
         model?: 'haiku' | 'sonnet' | 'opus';
         trajectoryId?: string;
         metadata?: Record<string, unknown>;
+        /** Pattern ids retrieved to guide this task — enables ADR-110 null capture on failure */
+        appliedPatterns?: string[];
     }): string;
     /**
      * Record a step in the experience

package/dist/learning/experience-capture.js

@@ -94,6 +94,8 @@ export class ExperienceCaptureService {
     sessionCaptureCount = 0;
     /** Optional witness chain for attaching audit receipts to experiences */
     witnessChain;
+    /** Optional ADR-110 null recorder — wired by the composition root to PatternNullStore.recordNull */
+    nullRecorder;
     constructor(memory, patternStore, eventBus, config = {}) {
         this.memory = memory;
         this.patternStore = patternStore;
@@ -107,6 +109,10 @@ export class ExperienceCaptureService {
     setWitnessChain(chain) {
         this.witnessChain = chain;
     }
+    /** Wire the ADR-110 kept-nulls recorder (typically PatternNullStore.recordNull). */
+    setNullRecorder(recorder) {
+        this.nullRecorder = recorder;
+    }
     /**
      * Initialize the experience capture service
      */
@@ -141,6 +147,7 @@ export class ExperienceCaptureService {
             quality: 0,
             trajectoryId: options?.trajectoryId,
             metadata: options?.metadata,
+            appliedPatterns: options?.appliedPatterns,
         };
         this.activeExperiences.set(id, experience);
         return id;
@@ -216,6 +223,29 @@ export class ExperienceCaptureService {
         await this.storeExperience(experience);
         // Update stats
         this.updateStats(experience);
+        // ADR-110: a pattern-guided failure is a kept null, not a discarded run.
+        // Failure = negative reward when a reward signal exists, else !success.
+        const failed = experience.reward !== undefined ? experience.reward < 0 : !experience.success;
+        if (this.nullRecorder && failed && experience.appliedPatterns?.length) {
+            const contextFingerprint = `${experience.domain ?? 'unknown'}:${experience.agent ?? 'unknown'}`;
+            for (const patternId of experience.appliedPatterns) {
+                try {
+                    this.nullRecorder({
+                        patternId,
+                        contextFingerprint,
+                        failureMode: experience.testOutcome ?? experience.feedback ?? 'task-failure',
+                        trajectoryRef: experience.trajectoryId,
+                        evidenceClass: 'EXECUTED',
+                    });
+                }
+                catch (nullError) {
+                    logger.warn('Failed to record pattern null', {
+                        patternId,
+                        error: nullError instanceof Error ? nullError.message : String(nullError),
+                    });
+                }
+            }
+        }
         // Extract patterns: require positive reward (or no reward signal) AND quality threshold
         // Zero or negative reward blocks extraction — only learn from genuinely positive outcomes
         const rewardAllowsExtraction = experience.reward === undefined || experience.reward > 0;

package/dist/learning/pattern-null-store.d.ts

@@ -0,0 +1,32 @@
+import type { Database as DatabaseType } from 'better-sqlite3';
+export type NullEvidenceClass = 'EXECUTED' | 'STATIC' | 'INFERRED' | 'CONJECTURE';
+export interface PatternNullRecord {
+    patternId: string;
+    contextFingerprint: string;
+    failureMode: string;
+    trajectoryRef?: string;
+    /** What evidence backs this failure record (ADR-105). Verdict-pipeline failures are EXECUTED. */
+    evidenceClass?: NullEvidenceClass;
+}
+export interface NullSummary {
+    patternId: string;
+    /** Total consolidated failure count across all contexts */
+    totalFailures: number;
+    /** Per-context consolidated counts */
+    byContext: Record<string, number>;
+}
+export declare class PatternNullStore {
+    private readonly db;
+    constructor(db: DatabaseType);
+    /** Record a failure; consolidates on repeat (pattern, context) pairs. */
+    recordNull(record: PatternNullRecord): void;
+    /** Batch summaries for retrieval-time surfacing. Missing patterns simply have no entry. */
+    getNullSummaries(patternIds: string[]): Map<string, NullSummary>;
+    /**
+     * Pure ranking-discount helper (no DB) so retrieval code can apply it
+     * without coupling. A null in the caller's own context discounts hardest;
+     * remote nulls discount mildly; the floor keeps patterns retrievable.
+     */
+    static applyNullDiscount(score: number, summary: NullSummary | undefined, contextFingerprint?: string): number;
+}
+//# sourceMappingURL=pattern-null-store.d.ts.map

package/dist/learning/pattern-null-store.js

@@ -0,0 +1,77 @@
+/**
+ * Pattern Null Store (ADR-110, issue #522)
+ *
+ * First-class negative pattern records: when an applied pattern fails in a
+ * context, the failure is kept — consolidated per (pattern, context) — and
+ * surfaced at retrieval time so ranking can discount by context-matched null
+ * density. Nulls are information, not tombstones: a pattern that fails in one
+ * context may be right in another, and a deleted failure is unauditable (the
+ * Pattern Space v2.1 lesson).
+ *
+ * Persistence: qe_pattern_nulls (schema v10, migration
+ * 20260611_add_pattern_nulls_table). Obtain the handle via
+ * SQLitePatternStore.getDatabase().
+ */
+import { v4 as uuidv4 } from 'uuid';
+import { applyMigration } from '../migrations/20260611_add_pattern_nulls_table.js';
+/** Weight of a context-matched null vs a null from elsewhere (ADR-110: local nulls outweigh remote successes). */
+const CONTEXT_MATCHED_WEIGHT = 0.15;
+const UNMATCHED_WEIGHT = 0.03;
+/** Floor so heavily-nulled patterns remain retrievable (nulls inform, never erase). */
+const DISCOUNT_FLOOR = 0.25;
+export class PatternNullStore {
+    db;
+    constructor(db) {
+        this.db = db;
+        // Additive, idempotent — safe on DBs that predate schema v10.
+        applyMigration(db);
+    }
+    /** Record a failure; consolidates on repeat (pattern, context) pairs. */
+    recordNull(record) {
+        this.db.prepare(`
+      INSERT INTO qe_pattern_nulls (id, pattern_id, context_fingerprint, failure_mode, trajectory_ref, evidence_class)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(pattern_id, context_fingerprint) DO UPDATE SET
+        consolidated_count = consolidated_count + 1,
+        failure_mode = excluded.failure_mode,
+        trajectory_ref = COALESCE(excluded.trajectory_ref, trajectory_ref),
+        updated_at = datetime('now')
+    `).run(uuidv4(), record.patternId, record.contextFingerprint, record.failureMode, record.trajectoryRef ?? null, record.evidenceClass ?? 'EXECUTED');
+    }
+    /** Batch summaries for retrieval-time surfacing. Missing patterns simply have no entry. */
+    getNullSummaries(patternIds) {
+        const out = new Map();
+        if (patternIds.length === 0)
+            return out;
+        const placeholders = patternIds.map(() => '?').join(',');
+        const rows = this.db.prepare(`
+      SELECT pattern_id, context_fingerprint, consolidated_count
+      FROM qe_pattern_nulls
+      WHERE pattern_id IN (${placeholders})
+    `).all(...patternIds);
+        for (const row of rows) {
+            let summary = out.get(row.pattern_id);
+            if (!summary) {
+                summary = { patternId: row.pattern_id, totalFailures: 0, byContext: {} };
+                out.set(row.pattern_id, summary);
+            }
+            summary.totalFailures += row.consolidated_count;
+            summary.byContext[row.context_fingerprint] = row.consolidated_count;
+        }
+        return out;
+    }
+    /**
+     * Pure ranking-discount helper (no DB) so retrieval code can apply it
+     * without coupling. A null in the caller's own context discounts hardest;
+     * remote nulls discount mildly; the floor keeps patterns retrievable.
+     */
+    static applyNullDiscount(score, summary, contextFingerprint) {
+        if (!summary || summary.totalFailures === 0)
+            return score;
+        const matched = contextFingerprint ? (summary.byContext[contextFingerprint] ?? 0) : 0;
+        const unmatched = summary.totalFailures - matched;
+        const factor = Math.max(DISCOUNT_FLOOR, 1 - matched * CONTEXT_MATCHED_WEIGHT - unmatched * UNMATCHED_WEIGHT);
+        return score * factor;
+    }
+}
+//# sourceMappingURL=pattern-null-store.js.map

package/dist/learning/pattern-store.d.ts

@@ -9,6 +9,7 @@ import type { MemoryBackend } from '../kernel/interfaces.js';
 import type { Result } from '../shared/types/index.js';
 import { QEPattern, QEPatternContext, QEPatternType, QEDomain, CreateQEPatternOptions } from './qe-patterns.js';
 import type { FilterExpression } from '../integrations/ruvector/interfaces.js';
+import { type NullSummary } from './pattern-null-store.js';
 /**
  * Token tracking configuration (ADR-042)
  */
@@ -130,6 +131,11 @@ export interface PatternSearchOptions {
      * When undefined, no additional filtering is applied (backward compatible).
      */
     filter?: FilterExpression;
+    /**
+     * Caller's context fingerprint (domain:agent) for ADR-110 null discounting.
+     * Nulls recorded in this context discount matching patterns hardest.
+     */
+    contextFingerprint?: string;
 }
 /**
  * Pattern search result with reuse optimization (ADR-042)
@@ -149,6 +155,8 @@ export interface PatternSearchResult {
     estimatedTokenSavings: number;
     /** Confidence level for reusing this pattern (0-1) (ADR-042) */
     reuseConfidence: number;
+    /** Kept-nulls summary when this pattern has recorded failures (ADR-110) */
+    nullSummary?: NullSummary;
 }
 /**
  * Interface for pattern store operations
@@ -196,6 +204,8 @@ export declare class PatternStore implements IPatternStore {
     private initialized;
     private cleanupTimer?;
     private sqliteStore;
+    /** Lazy ADR-110 null store over the sqlite handle */
+    private nullStore;
     private loadingPromise;
     private patternCache;
     private domainIndex;

package/dist/learning/pattern-store.js

@@ -21,6 +21,7 @@ import { DeltaTracker } from '../integrations/ruvector/delta-tracker.js';
 import { createVectorDeltaTracker, } from '../integrations/ruvector/vector-delta-tracker.js';
 import { createHopfieldMemory } from '../integrations/ruvector/hopfield-memory.js';
 import { createHyperbolicPatternIndex, } from './hyperbolic-pattern-index.js';
+import { PatternNullStore } from './pattern-null-store.js';
 // ============================================================================
 // R1: HDC Fingerprint Singleton (lazy-initialized)
 // ============================================================================
@@ -102,6 +103,8 @@ export class PatternStore {
     cleanupTimer;
     // Optional SQLite persistence delegate for delete/promote
     sqliteStore = null;
+    /** Lazy ADR-110 null store over the sqlite handle */
+    nullStore = null;
     loadingPromise = null;
     // In-memory caches for fast access
     patternCache = new Map();
@@ -767,6 +770,26 @@ export class PatternStore {
                 // while penalizing stale patterns (decayFactor is 0-1)
                 result.score = result.score * (0.7 + 0.3 * effectiveDecay);
             }
+            // ADR-110: surface kept nulls and discount scores by context-matched
+            // null density — "succeeded elsewhere" never outranks "failed here".
+            const nullDb = this.sqliteStore?.getDatabase();
+            if (nullDb && results.length > 0) {
+                try {
+                    if (!this.nullStore)
+                        this.nullStore = new PatternNullStore(nullDb);
+                    const summaries = this.nullStore.getNullSummaries(results.map(r => r.pattern.id));
+                    for (const result of results) {
+                        const summary = summaries.get(result.pattern.id);
+                        if (summary) {
+                            result.nullSummary = summary;
+                            result.score = PatternNullStore.applyNullDiscount(result.score, summary, options.contextFingerprint);
+                        }
+                    }
+                }
+                catch (error) {
+                    console.debug('[PatternStore] null discount skipped:', toErrorMessage(error));
+                }
+            }
             // Sort by score
             results.sort((a, b) => b.score - a.score);
             // Apply metadata filter BEFORE limit so we don't lose matching results (W-3 fix)