agentic-qe 3.15.15 → 3.15.17

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');
@@ -168,6 +174,11 @@ export class UnifiedMemoryManager {
         }
         return UnifiedMemoryManager.instancePromise;
     }
+    /** The shared instance when it is initialized; never creates one. */
+    static peekInitialized() {
+        const instance = UnifiedMemoryManager.instance;
+        return instance?.initialized ? instance : null;
+    }
     static resetInstance() {
         if (UnifiedMemoryManager.instance) {
             UnifiedMemoryManager.instance.close();
@@ -307,6 +318,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 +571,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 +619,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 +662,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 +765,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 +785,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 +1086,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;
@@ -1073,9 +1123,27 @@ export async function initializeUnifiedMemory(config) {
     await manager.initialize();
     return manager;
 }
+/**
+ * The shared memory.db connection when UnifiedMemory is already initialized,
+ * else null. Never opens it: callers that run before it keep their
+ * no-database behavior (#1298).
+ */
+export function getOpenUnifiedMemoryDatabase() {
+    return UnifiedMemoryManager.peekInitialized()?.getDatabase() ?? null;
+}
 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

@@ -15,6 +15,8 @@
  *   - Bearer auth from env only; URL userinfo stripped + warned on construct.
  *   - Probe + identity fingerprint required before `embed()`; breaker recovery
  *     invalidates identity so re-probe runs against a fresh endpoint.
+ *   - The first identity is bound for the client's lifetime: a re-probe that
+ *     finds another model is refused, never adopted (#1282).
  *   - True TCP connect timeout via socket-level setTimeout (not req.setTimeout).
  *   - TLS knobs (ca / cert / key / rejectUnauthorized / servername) for self-hosted.
  */
@@ -64,6 +66,8 @@ export interface EmbedderEndpointClientOptions {
     /** TLS overrides for https transport. Ignored for http/unix. */
     tlsOptions?: EmbedderTlsOptions;
 }
+/** The text every probe embeds; its vector is the endpoint's identity evidence. */
+export declare const ENDPOINT_IDENTITY_CANARY = "AQE embedder endpoint identity canary v1";
 /**
  * Parsed endpoint — either an HTTP(S) URL or a Unix socket path.
  */
@@ -82,6 +86,27 @@ 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);
+}
+/**
+ * #1282: a probe found a different endpoint identity than the one the client
+ * bound to. Vectors from the new identity are not comparable with stored ones,
+ * so the client refuses to embed until the endpoint serves the bound identity
+ * again or the process restarts.
+ */
+export declare class EmbedderEndpointIdentityChangedError extends Error {
+    readonly bound: EndpointIdentity;
+    readonly current: EndpointIdentity;
+    constructor(bound: EndpointIdentity, current: EndpointIdentity);
+}
 /**
  * OpenAI-compatible embeddings client with keep-alive, circuit breaker, and identity probe.
  */
@@ -91,9 +116,39 @@ export declare class EmbedderEndpointClient {
     private readonly breaker;
     private readonly opts;
     private cachedIdentity;
+    /**
+     * #1282: the first identity a probe found. Every embedding this client
+     * returns belongs to it; later probes must find it again.
+     */
+    private boundIdentity;
+    /** #1282: the canary vector behind `boundIdentity`. */
+    private boundCanary;
+    /** #1282: set while the endpoint serves an identity other than the bound one. */
+    private identityChange;
     /** 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;
     /**
@@ -115,7 +170,28 @@ export declare class EmbedderEndpointClient {
     probe(): Promise<EndpointIdentity>;
     private ensureProbed;
     private doProbe;
+    /**
+     * #1282: true when a re-probe found the bound model. The int16 fingerprint
+     * flips on noise of about 3e-5 per component, which the same model restarted
+     * on other hardware or kernels can produce, so a changed hash alone is not a
+     * changed model: the canary must also have moved below the ADR-097
+     * round-trip cosine.
+     */
+    private isBoundModel;
+    /**
+     * #1282: the endpoint answers, but as a different model than the one this
+     * client bound to (an endpoint restarted with another model of the same
+     * dimension, typically seen when the breaker recovers). Treat it as down:
+     * open the breaker so every caller fast-fails with this error, and retry
+     * as a half-open trial after each window, in case the bound model returns.
+     * Reported once per new identity.
+     */
+    private refuseIdentityChange;
     getCachedIdentity(): EndpointIdentity | null;
+    /** #1282: the identity every vector from this client belongs to. */
+    getBoundIdentity(): EndpointIdentity | null;
+    /** #1298: the canary vector behind the bound identity (ENDPOINT_IDENTITY_CANARY). */
+    getBoundCanary(): readonly number[] | null;
     getBreakerState(): {
         open: boolean;
         failures: number;