agentic-qe 3.9.30 → 3.9.32

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

package/dist/learning/qe-reasoning-bank-types.d.ts

@@ -79,6 +79,17 @@ export interface QERoutingResult {
     guidance: string[];
     /** Reasoning for the recommendation */
     reasoning: string;
+    /**
+     * ADR-095 telemetry — all optional, populated by routeTask when the
+     * exploration / Q-value path runs. Callers persist these into
+     * routing_outcomes for retrospective analysis.
+     */
+    /** True if ε-greedy promoted an alternative over the greedy winner. */
+    exploration?: boolean;
+    /** Mincut safety multiplier in effect (1.0 = full rate, 0.2 = dampened). */
+    criticality?: number;
+    /** Average qWeight across the scored agents — proxy for Q-table maturity. */
+    qWeight?: number;
 }
 /**
  * Pattern learning outcome

package/dist/learning/qe-reasoning-bank.d.ts

@@ -118,6 +118,17 @@ export declare class QEReasoningBank implements IQEReasoningBank {
      * Route a task to optimal agent
      */
     routeTask(request: QERoutingRequest): Promise<Result<QERoutingResult>>;
+    /**
+     * ADR-095: Build a per-agent Q-value lookup closure for the current
+     * routing decision. The closure executes a prepared-statement query
+     * against `rl_q_values` for each agent considered.
+     *
+     * Returns a no-op lookup when the unified memory backend is unavailable
+     * (e.g. during early boot or in tests that don't initialize SQLite).
+     * The no-op causes `calculateAgentScores` to fall back to pure-static
+     * scoring — identical to pre-ADR-095 behavior.
+     */
+    private buildQValueLookup;
     /**
      * Get guidance for a domain
      */

package/dist/learning/qe-reasoning-bank.js

@@ -25,7 +25,9 @@ import { getWitnessChain } from '../audit/witness-chain.js';
 // Import extracted modules
 import { DEFAULT_QE_REASONING_BANK_CONFIG } from './qe-reasoning-bank-types.js';
 import { PRETRAINED_PATTERNS } from './pretrained-patterns.js';
-import { AGENT_CAPABILITIES, calculateAgentScores, } from './agent-routing.js';
+import { AGENT_CAPABILITIES, calculateAgentScores, applyExplorationPolicy, resolveExplorationRate, deriveTaskType, buildRoutingStateKey, deriveComplexityBucket, } from './agent-routing.js';
+import { resolveTopologyCriticalFromSharedMincut } from './routing-topology-gate.js';
+import { getUnifiedMemory } from '../kernel/unified-memory.js';
 import { resizeEmbedding, hashEmbedding } from './embedding-utils.js';
 import { checkPatternPromotionWithCoherence, promotePattern as promotePatternFn, seedCrossDomainPatterns as seedCrossDomainPatternsFn, } from './pattern-promotion.js';
 // ============================================================================
@@ -395,8 +397,35 @@ export class QEReasoningBank {
                     agentDomainPatternCounts.set(agentType, count);
                 }
             }
-            // 4. Calculate agent scores using extracted function
-            const agentScores = calculateAgentScores(detectedDomains, request.capabilities, agentDomainPatternCounts, this.config.routingWeights);
+            // ADR-095: build the Q-value lookup closure from the task's state_key.
+            // The state_key MUST match what `updateHookRouterQValue` writes from
+            // post-task — buildRoutingStateKey enforces that.
+            const stateKey = buildRoutingStateKey({
+                taskType: deriveTaskType(request.task),
+                priority: 'normal',
+                domain: detectedDomains[0],
+                complexityBucket: deriveComplexityBucket(request.task),
+            });
+            const qValueLookup = this.buildQValueLookup(stateKey);
+            // 4. Calculate agent scores (now Q-blended when lookup available)
+            const agentScores = calculateAgentScores(detectedDomains, request.capabilities, agentDomainPatternCounts, this.config.routingWeights, AGENT_CAPABILITIES, request.context?.language, qValueLookup);
+            // ADR-095: ε-greedy exploration with mincut safety gate.
+            // The exploration is best-effort — failures fall through to greedy.
+            // Topology check uses `resolveTopologyCriticalFromSharedMincut` —
+            // see that module for the empty-graph regression context.
+            let safetyMultiplier = 1.0;
+            try {
+                const topologyCritical = resolveTopologyCriticalFromSharedMincut();
+                const rateInfo = resolveExplorationRate({
+                    envOverride: process.env.AQE_ROUTER_EXPLORATION_RATE,
+                    topologyCritical,
+                });
+                safetyMultiplier = rateInfo.safetyMultiplier;
+                applyExplorationPolicy(agentScores, rateInfo.epsilon);
+            }
+            catch {
+                // Exploration failures are non-fatal; greedy order stands.
+            }
             const recommended = agentScores[0];
             const alternatives = agentScores.slice(1, 4);
             // Generate guidance
@@ -411,6 +440,11 @@ export class QEReasoningBank {
             }
             // Update stats
             this.stats.totalRoutingConfidence += recommended.score;
+            // ADR-095 telemetry: average qWeight across the scored agents — a
+            // proxy for Q-table maturity. Operators can correlate this with
+            // routing_outcomes.quality_score over time to see if learning helps.
+            const totalQWeight = agentScores.reduce((acc, a) => acc + (a.qWeight ?? 0), 0);
+            const avgQWeight = agentScores.length > 0 ? totalQWeight / agentScores.length : 0;
             const result = {
                 recommendedAgent: recommended.agent,
                 confidence: recommended.score,
@@ -419,6 +453,9 @@ export class QEReasoningBank {
                 patterns,
                 guidance,
                 reasoning: recommended.reasoning.join('; '),
+                exploration: recommended.exploration === true,
+                criticality: safetyMultiplier,
+                qWeight: avgQWeight,
             };
             return ok(result);
         }
@@ -426,6 +463,52 @@ export class QEReasoningBank {
             return err(toError(error));
         }
     }
+    /**
+     * ADR-095: Build a per-agent Q-value lookup closure for the current
+     * routing decision. The closure executes a prepared-statement query
+     * against `rl_q_values` for each agent considered.
+     *
+     * Returns a no-op lookup when the unified memory backend is unavailable
+     * (e.g. during early boot or in tests that don't initialize SQLite).
+     * The no-op causes `calculateAgentScores` to fall back to pure-static
+     * scoring — identical to pre-ADR-095 behavior.
+     */
+    buildQValueLookup(stateKey) {
+        try {
+            const um = getUnifiedMemory();
+            if (!um.isInitialized())
+                return () => undefined;
+            const db = um.getDatabase();
+            // Verify the Q-table exists; many CLI commands run without ever
+            // initializing the schema and the SELECT below would throw.
+            const tableExists = db
+                .prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='rl_q_values'")
+                .get();
+            if (!tableExists)
+                return () => undefined;
+            const stmt = db.prepare(`
+        SELECT q_value, visits FROM rl_q_values
+         WHERE algorithm = 'q-learning'
+           AND agent_id = 'aqe-hook-router'
+           AND state_key = ?
+           AND action_key = ?
+      `);
+            return (agentType) => {
+                try {
+                    const row = stmt.get(stateKey, agentType);
+                    if (!row)
+                        return undefined;
+                    return { qValue: row.q_value, visits: row.visits };
+                }
+                catch {
+                    return undefined;
+                }
+            };
+        }
+        catch {
+            return () => undefined;
+        }
+    }
     /**
      * Get guidance for a domain
      */

package/dist/learning/routing-topology-gate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Routing Topology Safety Gate (ADR-095 — CRITICAL #1 follow-up)
+ *
+ * Resolves whether the agent dependency graph is in a "critical" topology
+ * state for the purpose of dampening exploration in QEReasoningBank.routeTask.
+ *
+ * Why this lives in its own module:
+ *
+ * 1. Testability. The reasoning-bank's full init path (real embeddings,
+ *    HNSW, pretrained patterns) is OOM-heavy in test environments. Putting
+ *    the topology gate here lets us unit-test it against a fresh
+ *    SwarmGraph singleton without spinning up the kernel + bank stack.
+ *
+ * 2. The empty-graph regression. `MinCutCalculator.getMinCutValue` returns
+ *    0 on an empty graph; `MinCutHealthMonitor.isCritical()` is defined as
+ *    `minCutValue < warningThreshold`, so an empty graph reports as
+ *    critical. CLI hook routing — the only place this gate fires in
+ *    practice — sees an empty graph because Queen coordinator activity
+ *    is what populates it. Without the emptiness check, exploration is
+ *    permanently dampened in the exact deployment case ADR-095 was meant
+ *    to help.
+ *
+ * Treat empty/uninitialized graph as "no signal" (full ε rate). Only
+ * consult `isCritical()` when the graph has actual vertices.
+ */
+/**
+ * Returns true ONLY when:
+ *   1. The shared monitor + graph are both initialized
+ *   2. The graph has at least one vertex (so the mincut value is real,
+ *      not the degenerate 0 of an empty graph)
+ *   3. The monitor's `isCritical()` returns true
+ *
+ * Any other state returns false (full ε rate / no dampening).
+ *
+ * All errors are swallowed — the gate is a best-effort signal that must
+ * never block routing. Caller defaults safetyMultiplier to 1.0 when this
+ * returns false.
+ */
+export declare function resolveTopologyCriticalFromSharedMincut(): boolean;
+//# sourceMappingURL=routing-topology-gate.d.ts.map

package/dist/learning/routing-topology-gate.js

@@ -0,0 +1,55 @@
+/**
+ * Routing Topology Safety Gate (ADR-095 — CRITICAL #1 follow-up)
+ *
+ * Resolves whether the agent dependency graph is in a "critical" topology
+ * state for the purpose of dampening exploration in QEReasoningBank.routeTask.
+ *
+ * Why this lives in its own module:
+ *
+ * 1. Testability. The reasoning-bank's full init path (real embeddings,
+ *    HNSW, pretrained patterns) is OOM-heavy in test environments. Putting
+ *    the topology gate here lets us unit-test it against a fresh
+ *    SwarmGraph singleton without spinning up the kernel + bank stack.
+ *
+ * 2. The empty-graph regression. `MinCutCalculator.getMinCutValue` returns
+ *    0 on an empty graph; `MinCutHealthMonitor.isCritical()` is defined as
+ *    `minCutValue < warningThreshold`, so an empty graph reports as
+ *    critical. CLI hook routing — the only place this gate fires in
+ *    practice — sees an empty graph because Queen coordinator activity
+ *    is what populates it. Without the emptiness check, exploration is
+ *    permanently dampened in the exact deployment case ADR-095 was meant
+ *    to help.
+ *
+ * Treat empty/uninitialized graph as "no signal" (full ε rate). Only
+ * consult `isCritical()` when the graph has actual vertices.
+ */
+import { getSharedMinCutGraph, getSharedMinCutMonitor, isSharedMinCutGraphInitialized, isSharedMinCutMonitorInitialized, } from '../coordination/mincut/shared-singleton.js';
+/**
+ * Returns true ONLY when:
+ *   1. The shared monitor + graph are both initialized
+ *   2. The graph has at least one vertex (so the mincut value is real,
+ *      not the degenerate 0 of an empty graph)
+ *   3. The monitor's `isCritical()` returns true
+ *
+ * Any other state returns false (full ε rate / no dampening).
+ *
+ * All errors are swallowed — the gate is a best-effort signal that must
+ * never block routing. Caller defaults safetyMultiplier to 1.0 when this
+ * returns false.
+ */
+export function resolveTopologyCriticalFromSharedMincut() {
+    try {
+        if (!isSharedMinCutMonitorInitialized())
+            return false;
+        if (!isSharedMinCutGraphInitialized())
+            return false;
+        const graph = getSharedMinCutGraph();
+        if (graph.isEmpty())
+            return false;
+        return getSharedMinCutMonitor().isCritical();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=routing-topology-gate.js.map

package/dist/learning/sqlite-persistence.d.ts

@@ -115,7 +115,12 @@ export declare class SQLitePatternStore {
         embedding: number[];
     }>;
     /**
-     * Record pattern usage
+     * Record pattern usage.
+     *
+     * Delegates to {@link recordPatternUsage} so the hook path
+     * (hooks-dream-learning.ts) and the canonical pattern-store path share a
+     * single writer — #486 Gap B. Preserves the previous throw-on-missing
+     * contract by checking the helper's `updated` flag.
      */
     recordUsage(patternId: string, success: boolean, metrics?: Record<string, unknown>, feedback?: string): void;
     /**

package/dist/learning/sqlite-persistence.js

@@ -17,6 +17,7 @@ import { safeJsonParse } from '../shared/safe-json.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { getUnifiedMemory } from '../kernel/unified-memory.js';
 import { computeBatchEmbeddings, getEmbeddingDimension } from './real-embeddings.js';
+import { recordPatternUsage } from './pattern-usage-recorder.js';
 export const DEFAULT_SQLITE_CONFIG = {
     // LEGACY: Ignored when useUnified=true (the default). All data goes to memory.db
     dbPath: '.agentic-qe/memory.db',
@@ -518,32 +519,25 @@ export class SQLitePatternStore {
         }));
     }
     /**
-     * Record pattern usage
+     * Record pattern usage.
+     *
+     * Delegates to {@link recordPatternUsage} so the hook path
+     * (hooks-dream-learning.ts) and the canonical pattern-store path share a
+     * single writer — #486 Gap B. Preserves the previous throw-on-missing
+     * contract by checking the helper's `updated` flag.
      */
     recordUsage(patternId, success, metrics, feedback) {
         if (!this.db)
             throw new Error('Database not initialized');
-        const insertUsage = this.prepared.get('insertUsage');
-        const updatePattern = this.prepared.get('updatePattern');
-        if (!insertUsage || !updatePattern) {
-            throw new Error('Prepared statements not ready');
-        }
-        // Get current pattern for quality score calculation
-        const pattern = this.getPattern(patternId);
-        if (!pattern) {
+        const result = recordPatternUsage(this.db, {
+            patternId,
+            success,
+            metrics,
+            feedback,
+        });
+        if (!result.updated) {
             throw new Error(`Pattern not found: ${patternId}`);
         }
-        const newUsageCount = pattern.usageCount + 1;
-        const newSuccessfulUses = pattern.successfulUses + (success ? 1 : 0);
-        const newSuccessRate = newSuccessfulUses / newUsageCount;
-        // Quality score: confidence * 0.3 + usage * 0.2 + success_rate * 0.5
-        const usageScore = Math.min(1, newUsageCount / 100);
-        const qualityScore = pattern.confidence * 0.3 + usageScore * 0.2 + newSuccessRate * 0.5;
-        const transaction = this.db.transaction(() => {
-            insertUsage.run(patternId, success ? 1 : 0, metrics ? JSON.stringify(metrics) : null, feedback || null);
-            updatePattern.run(success ? 1 : 0, success ? 1 : 0, qualityScore, patternId);
-        });
-        transaction();
     }
     /**
      * Delete a pattern and its related data (embedding, usage history)