agentic-qe 3.9.30 → 3.9.31

package/dist/learning/agent-routing.js

@@ -1,10 +1,12 @@
 /**
  * Agentic QE v3 - Agent Routing
  * ADR-021: QE ReasoningBank for Pattern Learning
+ * ADR-095: ε-greedy exploration with Q-value blending and mincut safety gate
  *
  * Static agent capability mapping and routing score calculation
  * used by QEReasoningBank.routeTask().
  */
+import { randomInt } from 'crypto';
 // ============================================================================
 // Agent Capabilities Map
 // ============================================================================
@@ -72,6 +74,159 @@ export const AGENT_CAPABILITIES = {
         performanceScore: 0.75,
     },
 };
+// ============================================================================
+// ADR-095: Q-Value Blending + ε-Greedy Exploration
+// ============================================================================
+/**
+ * Maximum Q-value influence on the final score.
+ *
+ * 0.4 means a fully-mature Q-value can move the score by up to ±0.2 (since
+ * normalizedQ ranges over (0, 1) and the static contribution clamps the
+ * upper bound). This is intentionally bounded so Q-values inform rather
+ * than override the static features.
+ *
+ * Tuning: post-deploy telemetry will tell us whether agents are actually
+ * being separated by Q-values. If the avg `q_weight` in routing_outcomes
+ * climbs but quality_score doesn't improve, this constant is too high.
+ */
+export const MAX_Q_WEIGHT = 0.4;
+/**
+ * Number of (state_key, action_key) visits at which qWeight saturates at
+ * MAX_Q_WEIGHT. Below this, qWeight ramps linearly from 0.
+ *
+ * 20 visits at the default 30-min worker tick + typical session cadence
+ * implies ~1 week of activity before a (state, agent) pair drives the
+ * decision. Adjust downward if cold-start latency proves problematic.
+ */
+export const QWEIGHT_RAMP_VISITS = 20;
+/**
+ * Sigmoid mapping R → (0, 1) for Q-value normalization before blending.
+ * A fresh row with q_value = 0 contributes 0.5 (neutral); negative q_values
+ * (after a failure, given the asymmetric -1.0 penalty from ADR-061) push
+ * the contribution toward 0, positive q_values toward 1.
+ */
+function sigmoid(x) {
+    return 1 / (1 + Math.exp(-x));
+}
+/**
+ * Blend a static score with a Q-value contribution.
+ *
+ *   effectiveScore = staticScore * (1 - qWeight) + normalizedQ * qWeight
+ *
+ * Returns { score, qWeight, qValue, qVisits } so callers can attach the
+ * telemetry fields to the ScoredAgent record.
+ */
+export function blendStaticAndQValue(staticScore, qLookup) {
+    if (!qLookup || qLookup.visits === 0) {
+        return { score: staticScore, qWeight: 0, qValue: 0, qVisits: 0 };
+    }
+    const qWeight = Math.min(qLookup.visits / QWEIGHT_RAMP_VISITS, 1) * MAX_Q_WEIGHT;
+    const normalizedQ = sigmoid(qLookup.qValue);
+    return {
+        score: staticScore * (1 - qWeight) + normalizedQ * qWeight,
+        qWeight,
+        qValue: qLookup.qValue,
+        qVisits: qLookup.visits,
+    };
+}
+/**
+ * Resolve the per-decision ε for the exploration policy.
+ *
+ * Priority order:
+ *   1. AQE_ROUTER_EXPLORATION_RATE env var (operator override, fixed)
+ *   2. Default base rate (0.05)
+ * The result is then multiplied by the mincut safety gate (caller passes
+ * `topologyCritical` derived from getSharedMinCutMonitor().isCritical()):
+ * critical topology → 0.2x dampening, healthy/unknown → 1.0x.
+ *
+ * Returns a number in [0, 1].
+ */
+export function resolveExplorationRate(opts) {
+    const envValue = opts.envOverride;
+    const parsed = envValue !== undefined ? Number.parseFloat(envValue) : NaN;
+    const baseEpsilon = Number.isFinite(parsed) && parsed >= 0 && parsed <= 1
+        ? parsed
+        : 0.05;
+    const safetyMultiplier = opts.topologyCritical ? 0.2 : 1.0;
+    const epsilon = Math.min(Math.max(baseEpsilon * safetyMultiplier, 0), 1);
+    return { epsilon, baseEpsilon, safetyMultiplier };
+}
+/**
+ * Apply the ε-greedy exploration policy to a sorted score list.
+ *
+ * With probability ε (computed from resolveExplorationRate), swaps the
+ * top-scored agent with a uniformly-random pick from positions 1..3 (or
+ * fewer if the list is shorter). Mutates `agentScores` in place. The
+ * promoted agent gets `exploration = true`.
+ *
+ * Uses `crypto.randomInt` for cryptographically-strong uniform sampling —
+ * matches the codebase convention (randomUUID is imported from 'crypto'
+ * in the same modules). Math.random() would work but breaks consistency.
+ */
+export function applyExplorationPolicy(agentScores, epsilon) {
+    if (epsilon <= 0 || agentScores.length < 2)
+        return;
+    // Compare in micro-units so randomInt can do uniform sampling without
+    // float arithmetic. ε = 0.05 → 50_000 micro-units in 1_000_000.
+    const epsilonMicro = Math.round(epsilon * 1_000_000);
+    if (epsilonMicro <= 0)
+        return;
+    if (randomInt(0, 1_000_000) >= epsilonMicro)
+        return;
+    // Pick from top alternatives (positions 1..min(3, length-1)).
+    const ceiling = Math.min(4, agentScores.length);
+    const exploreIdx = randomInt(1, ceiling);
+    const explored = agentScores[exploreIdx];
+    agentScores[exploreIdx] = agentScores[0];
+    agentScores[0] = explored;
+    agentScores[0].exploration = true;
+    agentScores[0].reasoning = [...agentScores[0].reasoning, '(exploration)'];
+}
+/**
+ * Derive a structural taskType from a free-form task description. Used to
+ * build the q-learning state_key shared with the post-task Bellman update
+ * (hooks-dream-learning.ts).
+ *
+ * Exported (rather than kept private in task-hooks) so QEReasoningBank can
+ * compute the same state_key at routing time as post-task does at outcome
+ * time — without that, the Q-table writer and reader would address
+ * different keys.
+ */
+export function deriveTaskType(description) {
+    const d = description.toLowerCase();
+    if (/\bgenerate[- ]?test|\btest[- ]?gen|\bgenerate.+spec/.test(d))
+        return 'test-generation';
+    if (/\bcoverage|\banalyze.+cover/.test(d))
+        return 'coverage-analysis';
+    if (/\bquality|\bassess|\baudit/.test(d))
+        return 'quality-assessment';
+    if (/\bsecurity|\bvulnerab|\bcompliance/.test(d))
+        return 'security-compliance';
+    if (/\bdefect|\bbug|\bdiagnos/.test(d))
+        return 'defect-intelligence';
+    if (/\brequirement|\bspec\b/.test(d))
+        return 'requirements-validation';
+    if (/\brefactor|\brewrite|\boptim/.test(d))
+        return 'refactoring';
+    if (/\btest|\brun.+test/.test(d))
+        return 'test-execution';
+    return 'unknown';
+}
+/**
+ * Build the canonical Q-learning state_key. Must match the format used by
+ * `updateHookRouterQValue` in hooks-dream-learning.ts — the writer and
+ * reader must agree on the key shape.
+ */
+export function buildRoutingStateKey(opts) {
+    return `${opts.taskType}|${opts.priority ?? 'normal'}|${opts.domain ?? 'any'}|${opts.complexityBucket}`;
+}
+/**
+ * Compute the complexity bucket [0, 10] from a task description length.
+ * Mirrors the formula in task-hooks.ts pre-task bridge.
+ */
+export function deriveComplexityBucket(description) {
+    return Math.max(0, Math.min(10, Math.round(Math.min(description.length / 200, 1) * 10)));
+}
 /**
  * Calculate agent scores for a routing request.
  *
@@ -83,7 +238,14 @@ export const AGENT_CAPABILITIES = {
  * @param requestLanguage - Optional language to boost agents with matching language expertise
  * @returns Sorted array of scored agents (highest score first)
  */
-export function calculateAgentScores(detectedDomains, requestCapabilities, agentDomainPatternCounts, routingWeights, agentCapabilities = AGENT_CAPABILITIES, requestLanguage) {
+export function calculateAgentScores(detectedDomains, requestCapabilities, agentDomainPatternCounts, routingWeights, agentCapabilities = AGENT_CAPABILITIES, requestLanguage, 
+/**
+ * ADR-095: optional per-agent Q-value lookup. When provided, the static
+ * score is blended with the Q-value contribution via blendStaticAndQValue.
+ * When omitted (or returning undefined for every agent), behavior is
+ * identical to the pre-ADR-095 deterministic scoring.
+ */
+qValueLookup) {
     const agentScores = [];
     for (const [agentType, profile] of Object.entries(agentCapabilities)) {
         let score = 0;
@@ -128,7 +290,28 @@ export function calculateAgentScores(detectedDomains, requestCapabilities, agent
             score += patternBoost;
             reasoning.push(`Pattern matches: ${patternCount}`);
         }
-        agentScores.push({ agent: agentType, score, reasoning });
+        // ADR-095: blend Q-value if a lookup is provided
+        const staticScore = score;
+        if (qValueLookup) {
+            const q = qValueLookup(agentType);
+            const blended = blendStaticAndQValue(staticScore, q);
+            score = blended.score;
+            if (blended.qWeight > 0) {
+                reasoning.push(`Q-bonus (w=${blended.qWeight.toFixed(2)}, v=${blended.qVisits})`);
+            }
+            agentScores.push({
+                agent: agentType,
+                score,
+                reasoning,
+                staticScore,
+                qWeight: blended.qWeight,
+                qValue: blended.qValue,
+                qVisits: blended.qVisits,
+            });
+        }
+        else {
+            agentScores.push({ agent: agentType, score, reasoning, staticScore });
+        }
     }
     // Sort by score descending
     agentScores.sort((a, b) => b.score - a.score);

package/dist/learning/dream/dream-insights-pruner.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Dream Insights Pruner (#488 C.2)
+ *
+ * Periodic retention sweep for the `dream_insights` table.
+ *
+ * dream_insights accumulate forever in default deployments — the schema has
+ * `created_at` but no `expires_at`, no foreign-key cascade that fires on
+ * regular cycle delete (cycles aren't routinely purged either), and no
+ * equivalent of `pattern-lifecycle.ts`'s decay/deprecation pass.
+ *
+ * Observed in state-rich shops (per #488 reporter): 120+ rows accumulated
+ * over ~30h of activity, with most at `applied = 0`. Without pruning, this
+ * grows linearly with hook activity. Over months the table becomes a slow
+ * `getPendingInsights` target and vector embeddings (if attached) grow
+ * unbounded.
+ *
+ * Strategy: delete only insights that:
+ *   - have never been applied (`applied = 0`), AND
+ *   - are older than the retention window (default 30 days)
+ *
+ * Applied insights stay forever — they're part of the audit trail for
+ * pattern changes. Recently-created insights stay regardless of applied
+ * state — they might still be picked up by a future `applyInsight` pass.
+ *
+ * Called from `LearningConsolidationWorker.runContinuousLearningLoop` on
+ * the 30-min worker tick. Failures are non-fatal — the worker continues
+ * with the rest of its lifecycle work.
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+export interface PruneStaleDreamInsightsOptions {
+    /**
+     * How many days old an `applied = 0` insight must be before it's
+     * eligible for deletion. Defaults to 30 days — matches the
+     * `staleDaysThreshold` used by `pattern-lifecycle.ts` for consistency.
+     */
+    retentionDays?: number;
+}
+export interface PruneResult {
+    /** Number of rows deleted. Zero if the table is empty or no rows qualify. */
+    pruned: number;
+}
+/**
+ * Delete stale unapplied insights. Idempotent — safe to call on every tick.
+ *
+ * Returns `{ pruned: 0 }` if the table doesn't exist (init hasn't created
+ * the dream schema yet) or if no rows qualify.
+ */
+export declare function pruneStaleDreamInsights(db: DatabaseType, options?: PruneStaleDreamInsightsOptions): PruneResult;
+//# sourceMappingURL=dream-insights-pruner.d.ts.map

package/dist/learning/dream/dream-insights-pruner.js

@@ -0,0 +1,53 @@
+/**
+ * Dream Insights Pruner (#488 C.2)
+ *
+ * Periodic retention sweep for the `dream_insights` table.
+ *
+ * dream_insights accumulate forever in default deployments — the schema has
+ * `created_at` but no `expires_at`, no foreign-key cascade that fires on
+ * regular cycle delete (cycles aren't routinely purged either), and no
+ * equivalent of `pattern-lifecycle.ts`'s decay/deprecation pass.
+ *
+ * Observed in state-rich shops (per #488 reporter): 120+ rows accumulated
+ * over ~30h of activity, with most at `applied = 0`. Without pruning, this
+ * grows linearly with hook activity. Over months the table becomes a slow
+ * `getPendingInsights` target and vector embeddings (if attached) grow
+ * unbounded.
+ *
+ * Strategy: delete only insights that:
+ *   - have never been applied (`applied = 0`), AND
+ *   - are older than the retention window (default 30 days)
+ *
+ * Applied insights stay forever — they're part of the audit trail for
+ * pattern changes. Recently-created insights stay regardless of applied
+ * state — they might still be picked up by a future `applyInsight` pass.
+ *
+ * Called from `LearningConsolidationWorker.runContinuousLearningLoop` on
+ * the 30-min worker tick. Failures are non-fatal — the worker continues
+ * with the rest of its lifecycle work.
+ */
+const DEFAULT_RETENTION_DAYS = 30;
+/**
+ * Delete stale unapplied insights. Idempotent — safe to call on every tick.
+ *
+ * Returns `{ pruned: 0 }` if the table doesn't exist (init hasn't created
+ * the dream schema yet) or if no rows qualify.
+ */
+export function pruneStaleDreamInsights(db, options = {}) {
+    const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
+    // Guard against the table not existing yet — a freshly-init'd shop may
+    // have started the worker before the dream schema was applied.
+    const tableExists = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='dream_insights'")
+        .get();
+    if (!tableExists) {
+        return { pruned: 0 };
+    }
+    const result = db
+        .prepare(`DELETE FROM dream_insights
+         WHERE applied = 0
+           AND created_at < datetime('now', ?)`)
+        .run(`-${retentionDays} days`);
+    return { pruned: result.changes };
+}
+//# sourceMappingURL=dream-insights-pruner.js.map

package/dist/learning/dream/dream-scheduler.js

@@ -17,6 +17,9 @@ import { LoggerFactory } from '../../logging/index.js';
 // ADR-062: Meta-learning integration
 import { MetaLearningEngine, DEFAULT_META_LEARNING_CONFIG, } from '../aqe-learning-engine.js';
 import { LearningMetricsTracker, } from '../metrics-tracker.js';
+// ADR-094 / #488 B.2: record per-tick liveness so `aqe learning loop-health`
+// surfaces the kernel-side dream loop as live.
+import { recordLoopHealth } from '../loop-health.js';
 const logger = LoggerFactory.create('DreamScheduler');
 /**
  * Default DreamScheduler configuration
@@ -333,6 +336,7 @@ export class DreamScheduler {
         }
         this.dreaming = true;
         logger.info('Starting dream cycle', { durationMs });
+        let dreamError;
         try {
             // Ensure concepts are loaded before dreaming
             const loaded = await this.dreamEngine.ensureConceptsLoaded();
@@ -372,8 +376,21 @@ export class DreamScheduler {
             logger.info('Dream completed', { insightsGenerated: result.insights.length });
             return result;
         }
+        catch (err) {
+            dreamError = err instanceof Error ? err : new Error(String(err));
+            throw err;
+        }
         finally {
             this.dreaming = false;
+            // ADR-094 / #488 B.2: record liveness so `aqe learning loop-health`
+            // can show the kernel-side dream scheduler as live. Best-effort —
+            // recordLoopHealth itself never throws.
+            if (this.memoryBackend) {
+                await recordLoopHealth(this.memoryBackend, 'dreamScheduler', {
+                    success: !dreamError,
+                    error: dreamError,
+                });
+            }
         }
     }
     /**

package/dist/learning/loop-health.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Self-Learning Loop Health (#488 B.2)
+ *
+ * Records per-component liveness signals for the AQE self-learning loop:
+ *
+ *   captured_experiences (SQLite)
+ *     → CapturedExperienceBridge.drain        (component: 'bridge')
+ *       → learning:experience:* kv
+ *         → LearningConsolidationWorker.tick  (component: 'learningWorker')
+ *           → learning:pattern:* kv
+ *             → DreamScheduler.tick           (component: 'dreamScheduler')
+ *               → dream_insights / qe_patterns
+ *
+ * Each tick records `{ success: true }` so operators can answer "is the
+ * loop closing end-to-end?" without DB-mining `dream_cycles`, `kv_store`,
+ * and `routing_outcomes` separately. Cumulative counters in `aqe learning
+ * stats` are not enough: they grow forever and can't distinguish "healthy
+ * loop" from "loop wedged 3 hours ago with stale totals".
+ *
+ * Persists as a single JSON value under `learning:loop-health` in the
+ * unified memory. Cheap to write (~200 bytes), cheap to read.
+ */
+import type { MemoryBackend } from '../kernel/interfaces.js';
+export declare const LOOP_HEALTH_KEY = "learning:loop-health";
+export type LoopComponent = 'bridge' | 'dreamScheduler' | 'learningWorker';
+export interface ComponentHealth {
+    /** ISO timestamp of the most recent successful tick. Empty string when never succeeded. */
+    lastSuccessAt: string;
+    /** Total ticks attempted since this loop-health record was created. */
+    ticksSinceBoot: number;
+    /** Total successful ticks since this loop-health record was created. */
+    successesSinceBoot: number;
+    /** Most recent error captured during a failed tick. Cleared on next success. */
+    lastError?: {
+        message: string;
+        at: string;
+    };
+}
+export interface LoopHealth {
+    /** Max(lastSuccessAt across components). Empty string when nothing has succeeded yet. */
+    overallLastSuccess: string;
+    /** ISO timestamp when this record was first written. */
+    bootedAt: string;
+    /** Per-component status. Components are added on first tick — absence means never invoked. */
+    components: {
+        bridge?: ComponentHealth;
+        dreamScheduler?: ComponentHealth;
+        learningWorker?: ComponentHealth;
+    };
+}
+/**
+ * Minimal memory interface this module needs. Both `MemoryBackend` (kernel)
+ * and `WorkerMemory` (worker context) satisfy this — the helper stays
+ * transport-agnostic so writers can call it without knowing which they hold.
+ */
+export interface LoopHealthMemory {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+}
+/**
+ * Record one tick of a component. Always best-effort: a write failure here
+ * MUST NOT propagate to the calling component (the bridge / worker should
+ * keep running even if the health key can't be persisted).
+ */
+export declare function recordLoopHealth(memory: LoopHealthMemory | MemoryBackend, component: LoopComponent, result: {
+    success: boolean;
+    error?: Error | string;
+}): Promise<void>;
+/**
+ * Read the current loop-health record. Returns undefined if no tick has
+ * ever fired — operators reading via `aqe learning loop-health` should
+ * interpret undefined as "the loop hasn't started yet (or workers aren't
+ * running)" rather than "the loop is healthy".
+ */
+export declare function getLoopHealth(memory: LoopHealthMemory | MemoryBackend): Promise<LoopHealth | undefined>;
+/**
+ * Compute a staleness verdict per component given a "stale after" threshold.
+ * Caller chooses the threshold based on the component's expected cadence:
+ *   - bridge: 5s poll → stale after ~30s
+ *   - learningWorker: 30 min tick → stale after ~2h
+ *   - dreamScheduler: variable → caller's call
+ */
+export declare function isComponentStale(health: ComponentHealth | undefined, staleAfterMs: number, now?: Date): boolean;
+//# sourceMappingURL=loop-health.d.ts.map

package/dist/learning/loop-health.js

@@ -0,0 +1,91 @@
+/**
+ * Self-Learning Loop Health (#488 B.2)
+ *
+ * Records per-component liveness signals for the AQE self-learning loop:
+ *
+ *   captured_experiences (SQLite)
+ *     → CapturedExperienceBridge.drain        (component: 'bridge')
+ *       → learning:experience:* kv
+ *         → LearningConsolidationWorker.tick  (component: 'learningWorker')
+ *           → learning:pattern:* kv
+ *             → DreamScheduler.tick           (component: 'dreamScheduler')
+ *               → dream_insights / qe_patterns
+ *
+ * Each tick records `{ success: true }` so operators can answer "is the
+ * loop closing end-to-end?" without DB-mining `dream_cycles`, `kv_store`,
+ * and `routing_outcomes` separately. Cumulative counters in `aqe learning
+ * stats` are not enough: they grow forever and can't distinguish "healthy
+ * loop" from "loop wedged 3 hours ago with stale totals".
+ *
+ * Persists as a single JSON value under `learning:loop-health` in the
+ * unified memory. Cheap to write (~200 bytes), cheap to read.
+ */
+export const LOOP_HEALTH_KEY = 'learning:loop-health';
+/**
+ * Record one tick of a component. Always best-effort: a write failure here
+ * MUST NOT propagate to the calling component (the bridge / worker should
+ * keep running even if the health key can't be persisted).
+ */
+export async function recordLoopHealth(memory, component, result) {
+    try {
+        const now = new Date().toISOString();
+        const state = (await memory.get(LOOP_HEALTH_KEY)) ?? {
+            overallLastSuccess: '',
+            bootedAt: now,
+            components: {},
+        };
+        const existing = state.components[component] ?? {
+            lastSuccessAt: '',
+            ticksSinceBoot: 0,
+            successesSinceBoot: 0,
+        };
+        existing.ticksSinceBoot += 1;
+        if (result.success) {
+            existing.lastSuccessAt = now;
+            existing.successesSinceBoot += 1;
+            delete existing.lastError;
+        }
+        else if (result.error) {
+            const message = result.error instanceof Error ? result.error.message : String(result.error);
+            existing.lastError = { message, at: now };
+        }
+        state.components[component] = existing;
+        // Recompute overallLastSuccess as max(component.lastSuccessAt). ISO 8601
+        // strings sort lexicographically the same as chronologically.
+        const successTimes = Object.values(state.components)
+            .map((c) => c?.lastSuccessAt ?? '')
+            .filter((t) => t !== '');
+        state.overallLastSuccess = successTimes.length > 0 ? successTimes.sort().pop() : '';
+        await memory.set(LOOP_HEALTH_KEY, state);
+    }
+    catch {
+        // Loop-health is itself best-effort observability. Never throw.
+    }
+}
+/**
+ * Read the current loop-health record. Returns undefined if no tick has
+ * ever fired — operators reading via `aqe learning loop-health` should
+ * interpret undefined as "the loop hasn't started yet (or workers aren't
+ * running)" rather than "the loop is healthy".
+ */
+export async function getLoopHealth(memory) {
+    try {
+        return await memory.get(LOOP_HEALTH_KEY);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Compute a staleness verdict per component given a "stale after" threshold.
+ * Caller chooses the threshold based on the component's expected cadence:
+ *   - bridge: 5s poll → stale after ~30s
+ *   - learningWorker: 30 min tick → stale after ~2h
+ *   - dreamScheduler: variable → caller's call
+ */
+export function isComponentStale(health, staleAfterMs, now = new Date()) {
+    if (!health || !health.lastSuccessAt)
+        return true;
+    return now.getTime() - new Date(health.lastSuccessAt).getTime() > staleAfterMs;
+}
+//# sourceMappingURL=loop-health.js.map

package/dist/learning/pattern-usage-recorder.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pattern Usage Recorder
+ * ADR-021: QE ReasoningBank for Pattern Learning (single-writer extension)
+ *
+ * Single source of truth for "pattern was used in a task" accounting:
+ *
+ *   - INSERTs a row into qe_pattern_usage (per-use audit trail)
+ *   - UPDATEs qe_patterns.{usage_count, successful_uses, success_rate,
+ *     quality_score, last_used_at, updated_at}
+ *
+ * Both writes happen inside ONE transaction so the audit trail and the
+ * aggregate columns never disagree on count.
+ *
+ * Before this helper, two parallel writers existed (#486 Gap B):
+ *   - SQLitePatternStore.recordUsage — did BOTH INSERT and UPDATE atomically
+ *   - hooks-dream-learning.ts inline UPDATE — did UPDATE only, skipping the
+ *     audit INSERT. Hook-driven usage stayed invisible in qe_pattern_usage
+ *     even as qe_patterns.usage_count incremented.
+ *
+ * Quality formula (mirrors pattern-lifecycle.ts and the legacy inline hook):
+ *   quality_score = confidence * 0.3 + min(usage_count/100, 1) * 0.2 + success_rate * 0.5
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+export interface PatternUsageRecord {
+    patternId: string;
+    success: boolean;
+    metrics?: Record<string, unknown>;
+    feedback?: string;
+}
+export interface PatternUsageResult {
+    /**
+     * Whether the helper found and updated the pattern row.
+     * False (no throw) if patternId doesn't exist, since hook subprocesses
+     * iterate over selectedPatternIds that may include stale UUIDs from
+     * the routing kv. Callers who want strict semantics should check this
+     * flag and throw themselves.
+     */
+    updated: boolean;
+    /** Post-update usage_count. Undefined if !updated. */
+    usageCount?: number;
+    /** Post-update successful_uses. Undefined if !updated. */
+    successfulUses?: number;
+    /** Post-update success_rate. Undefined if !updated. */
+    successRate?: number;
+    /** Post-update quality_score. Undefined if !updated. */
+    qualityScore?: number;
+}
+/**
+ * Record one use of a pattern atomically across qe_pattern_usage and qe_patterns.
+ *
+ * Idempotency: each call inserts ONE audit row and increments usage_count by ONE.
+ * The transaction makes the two writes atomic — if either fails, neither lands.
+ *
+ * Concurrency: better-sqlite3 transactions are serialized at the connection
+ * level. Multiple concurrent callers on the same connection will queue.
+ */
+export declare function recordPatternUsage(db: DatabaseType, record: PatternUsageRecord): PatternUsageResult;
+//# sourceMappingURL=pattern-usage-recorder.d.ts.map

package/dist/learning/pattern-usage-recorder.js

@@ -0,0 +1,72 @@
+/**
+ * Pattern Usage Recorder
+ * ADR-021: QE ReasoningBank for Pattern Learning (single-writer extension)
+ *
+ * Single source of truth for "pattern was used in a task" accounting:
+ *
+ *   - INSERTs a row into qe_pattern_usage (per-use audit trail)
+ *   - UPDATEs qe_patterns.{usage_count, successful_uses, success_rate,
+ *     quality_score, last_used_at, updated_at}
+ *
+ * Both writes happen inside ONE transaction so the audit trail and the
+ * aggregate columns never disagree on count.
+ *
+ * Before this helper, two parallel writers existed (#486 Gap B):
+ *   - SQLitePatternStore.recordUsage — did BOTH INSERT and UPDATE atomically
+ *   - hooks-dream-learning.ts inline UPDATE — did UPDATE only, skipping the
+ *     audit INSERT. Hook-driven usage stayed invisible in qe_pattern_usage
+ *     even as qe_patterns.usage_count incremented.
+ *
+ * Quality formula (mirrors pattern-lifecycle.ts and the legacy inline hook):
+ *   quality_score = confidence * 0.3 + min(usage_count/100, 1) * 0.2 + success_rate * 0.5
+ */
+/**
+ * Record one use of a pattern atomically across qe_pattern_usage and qe_patterns.
+ *
+ * Idempotency: each call inserts ONE audit row and increments usage_count by ONE.
+ * The transaction makes the two writes atomic — if either fails, neither lands.
+ *
+ * Concurrency: better-sqlite3 transactions are serialized at the connection
+ * level. Multiple concurrent callers on the same connection will queue.
+ */
+export function recordPatternUsage(db, record) {
+    const pattern = db
+        .prepare(`SELECT confidence, usage_count, successful_uses FROM qe_patterns WHERE id = ?`)
+        .get(record.patternId);
+    if (!pattern) {
+        return { updated: false };
+    }
+    const successInc = record.success ? 1 : 0;
+    const newUsageCount = pattern.usage_count + 1;
+    const newSuccessfulUses = pattern.successful_uses + successInc;
+    const newSuccessRate = newSuccessfulUses / newUsageCount;
+    const usageScore = Math.min(1, newUsageCount / 100);
+    const newQualityScore = pattern.confidence * 0.3 + usageScore * 0.2 + newSuccessRate * 0.5;
+    const insertUsage = db.prepare(`
+    INSERT INTO qe_pattern_usage (pattern_id, success, metrics_json, feedback)
+    VALUES (?, ?, ?, ?)
+  `);
+    const updatePattern = db.prepare(`
+    UPDATE qe_patterns SET
+      usage_count = ?,
+      successful_uses = ?,
+      success_rate = ?,
+      quality_score = ?,
+      last_used_at = datetime('now'),
+      updated_at = datetime('now')
+    WHERE id = ?
+  `);
+    const txn = db.transaction(() => {
+        insertUsage.run(record.patternId, successInc, record.metrics ? JSON.stringify(record.metrics) : null, record.feedback ?? null);
+        updatePattern.run(newUsageCount, newSuccessfulUses, newSuccessRate, newQualityScore, record.patternId);
+    });
+    txn();
+    return {
+        updated: true,
+        usageCount: newUsageCount,
+        successfulUses: newSuccessfulUses,
+        successRate: newSuccessRate,
+        qualityScore: newQualityScore,
+    };
+}
+//# sourceMappingURL=pattern-usage-recorder.js.map