agentic-qe 3.15.15 → 3.15.16

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

@@ -77,6 +77,17 @@ export declare class DeltaTracker {
     initialize(): void;
     private prepareStatements;
     private ensureInitialized;
+    /**
+     * createGenesis() through the shared connection's write queue (#1283). The
+     * version check and the insert run as one queued unit.
+     */
+    createGenesisWhenUnlocked(patternId: string, snapshot: object, metadata?: Record<string, unknown>): Promise<DeltaEvent>;
+    /**
+     * recordDelta() through the shared connection's write queue (#1283). Reading
+     * the current version, the insert and retention run as one queued unit, so
+     * two deltas cannot get the same version number.
+     */
+    recordDeltaWhenUnlocked(patternId: string, before: object, after: object, metadata?: Record<string, unknown>): Promise<DeltaEvent>;
     /**
      * Create a genesis snapshot for a pattern (version 0).
      * The full object is stored in metadata.snapshot; patches are empty.

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

@@ -8,6 +8,7 @@
  * @module integrations/ruvector/delta-tracker
  */
 import { v4 as uuidv4 } from 'uuid';
+import { writeWhenUnlockedOn } from '../../shared/sqlite-write-queue.js';
 import * as fastJsonPatchNs from 'fast-json-patch';
 // fast-json-patch ships two entry points with different export shapes: its CJS
 // entry (index.js) attaches named exports directly via Object.assign(exports,
@@ -156,6 +157,21 @@ export class DeltaTracker {
     // --------------------------------------------------------------------------
     // Public API
     // --------------------------------------------------------------------------
+    /**
+     * createGenesis() through the shared connection's write queue (#1283). The
+     * version check and the insert run as one queued unit.
+     */
+    createGenesisWhenUnlocked(patternId, snapshot, metadata) {
+        return writeWhenUnlockedOn(this.db, () => this.createGenesis(patternId, snapshot, metadata));
+    }
+    /**
+     * recordDelta() through the shared connection's write queue (#1283). Reading
+     * the current version, the insert and retention run as one queued unit, so
+     * two deltas cannot get the same version number.
+     */
+    recordDeltaWhenUnlocked(patternId, before, after, metadata) {
+        return writeWhenUnlockedOn(this.db, () => this.recordDelta(patternId, before, after, metadata));
+    }
     /**
      * Create a genesis snapshot for a pattern (version 0).
      * The full object is stored in metadata.snapshot; patches are empty.

package/dist/integrations/ruvector/sona-persistence.d.ts

@@ -95,6 +95,8 @@ export declare class PersistentSONAEngine {
     private initPromise;
     private pendingSaves;
     private saveTimer;
+    /** The deferred batch currently being written, if any (#1283). */
+    private flushInFlight;
     private consecutiveSaveFailures;
     private serverClient;
     constructor(config: PersistentSONAConfig);
@@ -419,6 +421,14 @@ export declare class PersistentSONAEngine {
      * Schedule batched save
      */
     private scheduleSave;
+    /**
+     * Write the batched patterns. Each write is queued on the shared connection
+     * (#1283): in the MCP server a locked memory.db no longer freezes the event
+     * loop for the whole busy_timeout per pattern; the write retries
+     * asynchronously instead. A row that still fails stays pending and the batch
+     * is retried with backoff, as before.
+     */
+    private flushPendingSaves;
     /**
      * Update pattern usage in SQLite
      */

package/dist/integrations/ruvector/sona-persistence.js

@@ -29,6 +29,7 @@ import { getUnifiedPersistence } from '../../kernel/unified-persistence.js';
 import { toErrorMessage } from '../../shared/error-utils.js';
 import { safeJsonParse } from '../../shared/safe-json.js';
 import { LoggerFactory } from '../../logging/index.js';
+import { writeWhenUnlockedOn } from '../../shared/sqlite-write-queue.js';
 const logger = LoggerFactory.create('sona-persistence');
 // ============================================================================
 // Schema (added to unified-memory.ts as part of migration)
@@ -112,6 +113,8 @@ export class PersistentSONAEngine {
     initPromise = null;
     pendingSaves = new Map();
     saveTimer = null;
+    /** The deferred batch currently being written, if any (#1283). */
+    flushInFlight = null;
     consecutiveSaveFailures = 0;
     serverClient = null;
     constructor(config) {
@@ -801,6 +804,10 @@ export class PersistentSONAEngine {
      * Close the engine
      */
     async close() {
+        // Let a deferred batch that is already writing finish first (#1283); it
+        // may schedule a retry, which the clearTimeout below then cancels.
+        if (this.flushInFlight)
+            await this.flushInFlight;
         // Flush pending saves
         if (this.saveTimer) {
             clearTimeout(this.saveTimer);
@@ -808,9 +815,9 @@ export class PersistentSONAEngine {
         }
         if (this.pendingSaves.size > 0) {
             const failures = [];
-            for (const pattern of this.pendingSaves.values()) {
+            for (const pattern of Array.from(this.pendingSaves.values())) {
                 try {
-                    this.savePatternToDb(pattern);
+                    await writeWhenUnlockedOn(this.db, () => this.savePatternToDb(pattern));
                     this.pendingSaves.delete(pattern.id);
                 }
                 catch (error) {
@@ -1085,33 +1092,51 @@ export class PersistentSONAEngine {
         }
         this.saveTimer = setTimeout(() => {
             this.saveTimer = null;
-            const patterns = Array.from(this.pendingSaves.values());
-            for (const pattern of patterns) {
-                try {
-                    this.savePatternToDb(pattern);
-                    this.pendingSaves.delete(pattern.id);
-                }
-                catch (error) {
-                    logger.warn('Deferred SONA save failed; retaining pending pattern', {
-                        patternId: pattern.id, error: toErrorMessage(error),
-                    });
-                }
-            }
-            if (this.pendingSaves.size > 0) {
-                this.consecutiveSaveFailures++;
-                // Stop after five failed batches; close() can still flush retained rows.
-                if (this.consecutiveSaveFailures < 5 && this.db?.open) {
-                    this.scheduleSave(Math.min(60000, Math.max(1000, this.config.autoSaveInterval) * 2 ** (this.consecutiveSaveFailures - 1)));
-                }
-            }
-            else {
-                this.consecutiveSaveFailures = 0;
-            }
+            const flush = this.flushPendingSaves().finally(() => {
+                if (this.flushInFlight === flush)
+                    this.flushInFlight = null;
+            });
+            this.flushInFlight = flush;
         }, delayMs);
         // The initial batch must flush on natural exit; only failure retries are optional.
         if (this.consecutiveSaveFailures > 0)
             this.saveTimer.unref();
     }
+    /**
+     * Write the batched patterns. Each write is queued on the shared connection
+     * (#1283): in the MCP server a locked memory.db no longer freezes the event
+     * loop for the whole busy_timeout per pattern; the write retries
+     * asynchronously instead. A row that still fails stays pending and the batch
+     * is retried with backoff, as before.
+     */
+    async flushPendingSaves() {
+        const patterns = Array.from(this.pendingSaves.values());
+        let failed = 0;
+        for (const pattern of patterns) {
+            try {
+                await writeWhenUnlockedOn(this.db, () => this.savePatternToDb(pattern));
+                // A newer snapshot queued during the write stays pending.
+                if (this.pendingSaves.get(pattern.id) === pattern)
+                    this.pendingSaves.delete(pattern.id);
+            }
+            catch (error) {
+                failed++;
+                logger.warn('Deferred SONA save failed; retaining pending pattern', {
+                    patternId: pattern.id, error: toErrorMessage(error),
+                });
+            }
+        }
+        if (failed > 0) {
+            this.consecutiveSaveFailures++;
+            // Stop after five failed batches; close() can still flush retained rows.
+            if (this.consecutiveSaveFailures < 5 && this.db?.open) {
+                this.scheduleSave(Math.min(60000, Math.max(1000, this.config.autoSaveInterval) * 2 ** (this.consecutiveSaveFailures - 1)));
+            }
+        }
+        else {
+            this.consecutiveSaveFailures = 0;
+        }
+    }
     /**
      * Update pattern usage in SQLite
      */

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

@@ -69,6 +69,9 @@ export declare class UnifiedMemoryManager {
     private initialized;
     private vectorsLoaded;
     private initPromise;
+    /** Tail of the FIFO write queue and how many writes are in it (#1263). */
+    private writeQueue;
+    private queuedWrites;
     private preparedStatements;
     private vectorIndex;
     private crdtStore;
@@ -115,6 +118,19 @@ export declare class UnifiedMemoryManager {
      */
     private migrateToV11GoapExecutionSteps;
     private loadVectorIndex;
+    /**
+     * Run a write on the shared connection (#1263). Under the MCP server's lock
+     * wait cap each attempt blocks for at most the cap and the write retries
+     * asynchronously, so a locked memory.db does not freeze the event loop. The
+     * write still fails with SQLITE_BUSY once the configured busyTimeout has
+     * passed. Without a cap (CLI) this is one attempt with the full busyTimeout.
+     *
+     * Writes run one at a time in call order (FIFO), so a later write to the
+     * same key cannot land before an earlier one that is still retrying. A
+     * failed write does not hold up the next. With nothing queued the first
+     * attempt runs synchronously, as the write did before.
+     */
+    writeWhenUnlocked<T>(fn: () => T): Promise<T>;
     kvSet(key: string, value: unknown, namespace?: string, ttl?: number): Promise<void>;
     kvGet<T>(key: string, namespace?: string): Promise<T | undefined>;
     kvDelete(key: string, namespace?: string): Promise<boolean>;
@@ -212,4 +228,12 @@ export declare class UnifiedMemoryManager {
 export declare function getUnifiedMemory(config?: Partial<UnifiedMemoryConfig>): UnifiedMemoryManager;
 export declare function initializeUnifiedMemory(config?: Partial<UnifiedMemoryConfig>): Promise<UnifiedMemoryManager>;
 export declare function resetUnifiedMemory(): void;
+/**
+ * Run a write on `db` through the shared manager's writeWhenUnlocked queue
+ * when `db` is that manager's connection (#1274), for modules that hold only
+ * the raw connection. The write then neither blocks the MCP server's event
+ * loop for the whole busy_timeout nor lands before an earlier queued write.
+ * A write on any other connection runs now, as before.
+ */
+export declare function writeWhenUnlockedOn<T>(db: DatabaseType, fn: () => T): Promise<T>;
 //# sourceMappingURL=unified-memory.d.ts.map

package/dist/kernel/unified-memory.js

@@ -23,6 +23,9 @@
  */
 import { openDatabase as openSafeDatabase } from '../shared/safe-db.js';
 import { safeJsonParse } from '../shared/safe-json.js';
+import { capBusyTimeout } from '../shared/sqlite-lock-wait.js';
+import { registerWriteQueue, unregisterWriteQueue, writeWhenUnlockedOn as queueWriteOn, } from '../shared/sqlite-write-queue.js';
+import { isBusyError, retryWhileBusy, withBusyTimeout } from '../learning/dream/dream-lock-retry.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -121,6 +124,9 @@ export class UnifiedMemoryManager {
     initialized = false;
     vectorsLoaded = false;
     initPromise = null;
+    /** Tail of the FIFO write queue and how many writes are in it (#1263). */
+    writeQueue = Promise.resolve();
+    queuedWrites = 0;
     preparedStatements = new Map();
     // ADR-071 Phase 2C: Always use UnifiedHnswIndex (old implementations decommissioned)
     vectorIndex = new UnifiedHnswIndex('qe-memory');
@@ -307,6 +313,8 @@ export class UnifiedMemoryManager {
             }
             this.vectorsLoaded = false;
             this.initialized = true;
+            // #1283: modules holding only the raw connection queue their writes here.
+            registerWriteQueue(this.db, (fn) => this.writeWhenUnlocked(fn));
             console.log(`[UnifiedMemory] Initialized: ${this.config.dbPath}`);
             this.warnIfDuplicateDatabases();
         }
@@ -558,14 +566,42 @@ export class UnifiedMemoryManager {
     // ============================================================================
     // KV Store Operations (v2 compatible)
     // ============================================================================
+    /**
+     * Run a write on the shared connection (#1263). Under the MCP server's lock
+     * wait cap each attempt blocks for at most the cap and the write retries
+     * asynchronously, so a locked memory.db does not freeze the event loop. The
+     * write still fails with SQLITE_BUSY once the configured busyTimeout has
+     * passed. Without a cap (CLI) this is one attempt with the full busyTimeout.
+     *
+     * Writes run one at a time in call order (FIFO), so a later write to the
+     * same key cannot land before an earlier one that is still retrying. A
+     * failed write does not hold up the next. With nothing queued the first
+     * attempt runs synchronously, as the write did before.
+     */
+    writeWhenUnlocked(fn) {
+        const run = () => retryWhileBusy(this.db, fn, {
+            waitMs: capBusyTimeout(this.config.busyTimeout),
+            budgetMs: this.config.busyTimeout,
+        });
+        // Queued writes yield to the event loop first, so one write's last attempt
+        // and the next one's first never block back to back.
+        const result = this.queuedWrites === 0
+            ? run()
+            : this.writeQueue.then(() => new Promise((r) => setImmediate(r))).then(run);
+        this.queuedWrites++;
+        const settled = result.then(() => undefined, () => undefined);
+        this.writeQueue = settled;
+        void settled.then(() => { this.queuedWrites--; });
+        return result;
+    }
     async kvSet(key, value, namespace = 'default', ttl) {
         this.ensureInitialized();
         const expiresAt = ttl ? Date.now() + ttl * 1000 : null;
         const serialized = JSON.stringify(value);
-        this.db.prepare(`
+        await this.writeWhenUnlocked(() => this.db.prepare(`
       INSERT OR REPLACE INTO kv_store (key, namespace, value, expires_at)
       VALUES (?, ?, ?, ?)
-    `).run(key, namespace, serialized, expiresAt);
+    `).run(key, namespace, serialized, expiresAt));
         // ADR-194: tamper-evident audit (no-op unless the proof-gate is enabled).
         this.auditWrite('kvSet', namespace, key, serialized);
     }
@@ -578,14 +614,22 @@ export class UnifiedMemoryManager {
         if (!row)
             return undefined;
         if (row.expires_at && Date.now() > row.expires_at) {
-            this.db.prepare('DELETE FROM kv_store WHERE key = ? AND namespace = ?').run(key, namespace);
+            try {
+                withBusyTimeout(this.db, capBusyTimeout(this.config.busyTimeout), () => this.db.prepare('DELETE FROM kv_store WHERE key = ? AND namespace = ?').run(key, namespace));
+            }
+            catch (error) {
+                // #1263: a read must not wait on a locked DB to tidy up; the row stays
+                // expired (filtered here) and kvCleanupExpired removes it later.
+                if (!isBusyError(error))
+                    throw error;
+            }
             return undefined;
         }
         return safeJsonParse(row.value);
     }
     async kvDelete(key, namespace = 'default') {
         this.ensureInitialized();
-        const result = this.db.prepare('DELETE FROM kv_store WHERE key = ? AND namespace = ?').run(key, namespace);
+        const result = await this.writeWhenUnlocked(() => this.db.prepare('DELETE FROM kv_store WHERE key = ? AND namespace = ?').run(key, namespace));
         // ADR-194: audit deletes too (no-op unless the proof-gate is enabled).
         if (result.changes > 0)
             this.auditWrite('kvDelete', namespace, key, '');
@@ -613,7 +657,7 @@ export class UnifiedMemoryManager {
     }
     async kvCleanupExpired() {
         this.ensureInitialized();
-        const result = this.db.prepare('DELETE FROM kv_store WHERE expires_at IS NOT NULL AND expires_at < ?').run(Date.now());
+        const result = await this.writeWhenUnlocked(() => this.db.prepare('DELETE FROM kv_store WHERE expires_at IS NOT NULL AND expires_at < ?').run(Date.now()));
         return result.changes;
     }
     // ============================================================================
@@ -716,10 +760,10 @@ export class UnifiedMemoryManager {
         this.ensureInitialized();
         const buffer = this.floatArrayToBuffer(embedding);
         const metadataJson = metadata ? JSON.stringify(metadata) : null;
-        this.db.prepare(`
+        await this.writeWhenUnlocked(() => this.db.prepare(`
       INSERT OR REPLACE INTO vectors (id, namespace, embedding, dimensions, metadata, updated_at)
       VALUES (?, ?, ?, ?, ?, datetime('now'))
-    `).run(id, namespace, buffer, embedding.length, metadataJson);
+    `).run(id, namespace, buffer, embedding.length, metadataJson));
         this.vectorIndex.add(id, embedding);
     }
     async vectorGet(id) {
@@ -736,7 +780,7 @@ export class UnifiedMemoryManager {
     }
     async vectorDelete(id) {
         this.ensureInitialized();
-        const result = this.db.prepare('DELETE FROM vectors WHERE id = ?').run(id);
+        const result = await this.writeWhenUnlocked(() => this.db.prepare('DELETE FROM vectors WHERE id = ?').run(id));
         this.vectorIndex.remove(id);
         return result.changes > 0;
     }
@@ -1037,6 +1081,7 @@ export class UnifiedMemoryManager {
             // hnswlib-node has none of those constraints; multiple instances
             // coexist freely.
             this.vectorIndex.clear();
+            unregisterWriteQueue(this.db);
             this.db.close();
             this.db = null;
             this.initialized = false;
@@ -1076,6 +1121,16 @@ export async function initializeUnifiedMemory(config) {
 export function resetUnifiedMemory() {
     UnifiedMemoryManager.resetInstance();
 }
+/**
+ * Run a write on `db` through the shared manager's writeWhenUnlocked queue
+ * when `db` is that manager's connection (#1274), for modules that hold only
+ * the raw connection. The write then neither blocks the MCP server's event
+ * loop for the whole busy_timeout nor lands before an earlier queued write.
+ * A write on any other connection runs now, as before.
+ */
+export function writeWhenUnlockedOn(db, fn) {
+    return queueWriteOn(db, fn);
+}
 // ============================================================================
 // Process Exit Handlers
 // ============================================================================

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

@@ -155,7 +155,7 @@ export class AQELearningEngine {
                 if (persistence.isInitialized()) {
                     const { PatternNullStore } = await import('./pattern-null-store.js');
                     const nullStore = new PatternNullStore(persistence.getDatabase());
-                    this.experienceCapture.setNullRecorder((record) => nullStore.recordNull(record));
+                    this.experienceCapture.setNullRecorder((record) => nullStore.recordNullWhenUnlocked(record));
                 }
             }
             catch (e) {

package/dist/learning/embed-and-insert-pattern.js

@@ -18,6 +18,7 @@
  * fail-soft (errors are logged at debug level and swallowed) — pattern row
  * persistence must not regress when embedding computation fails.
  */
+import { writeWhenUnlockedOn } from '../shared/sqlite-write-queue.js';
 import { computeRealEmbedding, DEFAULT_EMBEDDING_CONFIG, getActiveEmbeddingSpaceIdentity, } from './real-embeddings.js';
 /**
  * Compute an embedding for a pattern (`name + description + tags`) and persist
@@ -44,8 +45,9 @@ export async function ensurePatternEmbedding(db, patternId, name, description, t
         const spaceId = getActiveEmbeddingSpaceIdentity()?.spaceId;
         if (!spaceId)
             throw new Error('VECTOR_SPACE_UNVERIFIED: embedder has no runtime provenance');
-        db.prepare(`INSERT OR REPLACE INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, space_id)
-       VALUES (?, ?, ?, ?, ?)`).run(patternId, buffer, embedding.length, fullConfig.modelName, spaceId);
+        // #1283: queued on the shared connection so a locked memory.db does not freeze the MCP server.
+        await writeWhenUnlockedOn(db, () => db.prepare(`INSERT OR REPLACE INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, space_id)
+       VALUES (?, ?, ?, ?, ?)`).run(patternId, buffer, embedding.length, fullConfig.modelName, spaceId));
     }
     catch (error) {
         // Non-fatal: pattern row already persisted; embedding can be backfilled later.

package/dist/learning/embedder-endpoint-client.d.ts

@@ -82,6 +82,16 @@ interface ParsedEndpoint {
  */
 export declare function redactEndpoint(endpoint: string): string;
 export declare function parseEndpoint(endpoint: string): ParsedEndpoint;
+/**
+ * #1216: a connect or request timeout. The host did not answer within the
+ * budget, so the breaker opens on the first one instead of counting it as one
+ * failure of `failureThreshold`.
+ */
+export declare class EmbedderEndpointTimeoutError extends Error {
+    readonly phase: 'connect' | 'request';
+    readonly limitMs: number;
+    constructor(phase: 'connect' | 'request', limitMs: number);
+}
 /**
  * OpenAI-compatible embeddings client with keep-alive, circuit breaker, and identity probe.
  */
@@ -93,7 +103,28 @@ export declare class EmbedderEndpointClient {
     private cachedIdentity;
     /** True while a probe is in flight — prevents the embed() lazy-probe race. */
     private probeInFlight;
+    /**
+     * #1216: set when the breaker window elapsed and no probe has succeeded
+     * since. The next probe is the breaker's half-open trial; it runs in the
+     * background so no caller waits on a host that may still not answer.
+     */
+    private trialPending;
+    /** #1216: requests waiting on the host, abandoned when the breaker opens. */
+    private readonly inFlight;
     constructor(options: EmbedderEndpointClientOptions);
+    /**
+     * #1216: the breaker opened, so the host is treated as down. Requests that
+     * are still waiting on it fail now rather than each waiting out its own
+     * timeout.
+     */
+    private abandonInFlight;
+    /**
+     * #1216: true while the endpoint is not known to work: the breaker is open,
+     * or its window elapsed and the trial probe has not succeeded yet.
+     */
+    needsTrial(): boolean;
+    /** Start the half-open trial probe in the background (one at a time). */
+    private startTrialProbe;
     /** Public, redacted endpoint URL for logs/metrics. */
     getSafeEndpoint(): string;
     /**