agentic-qe 3.15.17 → 3.15.18

package/dist/domains/learning-optimization/pattern-merge.js

@@ -0,0 +1,127 @@
+/**
+ * Agentic QE v3 - Committing one pattern merge (#1106, #1149)
+ *
+ * `LearningCoordinatorService.consolidatePatterns` builds the consolidated
+ * pattern; this module moves the sources out of the active set:
+ *
+ * 1. Every source pattern's archive copy is written and verified.
+ * 2. The consolidated pattern is stored and read back in full.
+ * 3. The sources are removed one by one with compare-and-delete.
+ *
+ * A failure in steps 1-2, or before the first source is removed, rolls the
+ * merge back: the consolidated pattern and the archive copies are deleted and
+ * every source stays active. A failure after a source was removed keeps the
+ * consolidated pattern (it now holds that source's data) and reports each
+ * source's real state. Callers run this under `withPatternMoveLock`.
+ */
+import { err, ok } from '../../shared/types/index.js';
+import { toError } from '../../shared/error-utils.js';
+import { LEARNING_NS, LEARNING_PATTERN_KEY_PREFIX } from './active-patterns.js';
+import { canonicalJson, copyPatternToArchive, discardArchiveCopy, removeArchivedPattern, } from './pattern-archive.js';
+const LEFT_ACTIVE = 'nothing was merged and every source pattern was left active';
+const REMOVE_REASONS = {
+    changed: 'changed after its archive copy',
+    failed: 'archive copy no longer verifies',
+};
+/**
+ * Archive `sources`, store `consolidated` with `store`, then remove the
+ * sources. Returns the consolidated pattern only when every source left the
+ * active set.
+ */
+export async function commitPatternMerge(memory, sources, consolidated, store, archivedAt = new Date()) {
+    const copied = [];
+    let storeAttempted = false;
+    const rollBack = async (reason) => {
+        const problems = await undoMerge(memory, copied, storeAttempted ? consolidated : undefined);
+        return err(new Error(`${reason}; ${LEFT_ACTIVE}${problems.length ? ` (rollback incomplete: ${problems.join('; ')})` : ''}`));
+    };
+    try {
+        let notCopied = 0;
+        for (const source of sources) {
+            if ((await copyPatternToArchive(memory, source, archivedAt)) === 'copied')
+                copied.push(source);
+            else
+                notCopied++;
+        }
+        if (notCopied > 0) {
+            return rollBack(`${notCopied} of ${sources.length} source patterns could not be archived (archive copy not verified)`);
+        }
+        storeAttempted = true;
+        await store(consolidated);
+        const stored = await memory.get(`${LEARNING_PATTERN_KEY_PREFIX}${consolidated.id}`, LEARNING_NS);
+        if (!stored || canonicalJson(stored) !== canonicalJson(consolidated)) {
+            return rollBack('Consolidated pattern could not be read back');
+        }
+    }
+    catch (error) {
+        return rollBack(`Merge failed before any source pattern was removed: ${toError(error).message}`);
+    }
+    const removed = [];
+    for (let i = 0; i < sources.length; i++) {
+        let reason;
+        try {
+            const outcome = await removeArchivedPattern(memory, sources[i]);
+            if (outcome === 'removed' || outcome === 'missing') {
+                removed.push(outcome === 'missing' ? `${sources[i].id} (already gone)` : sources[i].id);
+                continue;
+            }
+            reason = REMOVE_REASONS[outcome];
+        }
+        catch (error) {
+            // A delete can fail after it took effect: report what is stored.
+            if (await isGone(memory, sources[i])) {
+                removed.push(sources[i].id);
+                continue;
+            }
+            reason = `delete failed: ${toError(error).message}`;
+        }
+        if (removed.length === 0)
+            return rollBack(`Source pattern ${sources[i].id} was not removed (${reason})`);
+        const leftActive = sources.slice(i);
+        const problems = [];
+        for (const source of leftActive) {
+            try {
+                await discardArchiveCopy(memory, source);
+            }
+            catch (error) {
+                problems.push(`archive copy of ${source.id} not removed: ${toError(error).message}`);
+            }
+        }
+        const states = leftActive.map((s, j) => `${s.id} (${j === 0 ? reason : 'not attempted'})`);
+        return err(new Error(`Merge partially applied: consolidated pattern ${consolidated.id} is active; ` +
+            `removed: ${removed.join(', ')}; left active: ${states.join(', ')}` +
+            (problems.length ? `; ${problems.join('; ')}` : '')));
+    }
+    return ok(consolidated);
+}
+/** True only when the source's active key is confirmed absent. */
+async function isGone(memory, source) {
+    try {
+        return !(await memory.get(`${LEARNING_PATTERN_KEY_PREFIX}${source.id}`, LEARNING_NS));
+    }
+    catch {
+        return false;
+    }
+}
+/** Delete the consolidated pattern and the archive copies of sources that are still active. */
+async function undoMerge(memory, copied, consolidated) {
+    const problems = [];
+    if (consolidated) {
+        try {
+            await memory.delete(`${LEARNING_PATTERN_KEY_PREFIX}${consolidated.id}`, LEARNING_NS);
+        }
+        catch (error) {
+            problems.push(`consolidated pattern ${consolidated.id} not removed: ${toError(error).message}`);
+        }
+    }
+    for (const source of copied) {
+        try {
+            await discardArchiveCopy(memory, source);
+        }
+        catch (error) {
+            problems.push(`archive copy of ${source.id} not removed: ${toError(error).message}`);
+        }
+    }
+    return problems;
+}
+//# sourceMappingURL=pattern-merge.js.map

package/dist/domains/learning-optimization/services/learning-coordinator.js

@@ -9,7 +9,8 @@ import { rehydrateDates } from '../../../shared/utils/kv-date-rehydrate.js';
 import { toError } from '../../../shared/error-utils.js';
 import { readActivePatterns } from '../active-patterns.js';
 import { isMeasuredPattern, partitionByRewardSource, patternEvidenceOf } from '../reward-source.js';
-import { copyPatternToArchive, removeArchivedPattern } from '../pattern-archive.js';
+import { withPatternMoveLock } from '../pattern-archive.js';
+import { commitPatternMerge } from '../pattern-merge.js';
 import { buildConsolidatedPattern } from '../pattern-consolidation.js';
 import { createQEFlashAttention, } from '../../../integrations/ruvector/wrappers.js';
 import { getClaudeModelForTier } from '../../../shared/llm/model-registry.js';
@@ -346,41 +347,26 @@ Provide:
             if (patternIds.length < 2) {
                 return err(new Error('Need at least 2 patterns to consolidate'));
             }
-            const patterns = [];
-            for (const id of patternIds) {
-                const pattern = await this.memory.get(`learning:pattern:${id}`, LEARNING_NS);
-                if (pattern) {
-                    patterns.push(pattern);
+            // #1149: one move at a time per backend. A second merge of the same ids
+            // reads its sources after the first has removed them, and stops.
+            return await withPatternMoveLock(this.memory, async () => {
+                const patterns = [];
+                for (const id of patternIds) {
+                    const pattern = await this.memory.get(`learning:pattern:${id}`, LEARNING_NS);
+                    if (pattern) {
+                        patterns.push(pattern);
+                    }
                 }
-            }
-            if (patterns.length < 2) {
-                return err(new Error('Not enough valid patterns found'));
-            }
-            // Merge patterns - take best template, combine contexts
-            const consolidatedPattern = buildConsolidatedPattern(patterns, uuidv4());
-            // #1106: all or nothing. Every source pattern's archive copy is written
-            // and read back first; then the consolidated pattern is stored and read
-            // back; only then are the source patterns removed from the active set.
-            // If any step fails, no source pattern is deleted.
-            const archivedAt = new Date();
-            let notCopied = 0;
-            for (const pattern of patterns) {
-                if (await copyPatternToArchive(this.memory, pattern, archivedAt) !== 'copied')
-                    notCopied++;
-            }
-            if (notCopied > 0) {
-                return err(new Error(`${notCopied} of ${patterns.length} source patterns could not be archived (archive copy not verified); ` +
-                    'nothing was merged and every source pattern was left active'));
-            }
-            await this.storePattern(consolidatedPattern);
-            const stored = await this.memory.get(`learning:pattern:${consolidatedPattern.id}`, LEARNING_NS);
-            if (!stored || stored.id !== consolidatedPattern.id) {
-                return err(new Error('Consolidated pattern could not be read back; nothing was merged and every source pattern was left active'));
-            }
-            for (const pattern of patterns) {
-                await removeArchivedPattern(this.memory, pattern);
-            }
-            return ok(consolidatedPattern);
+                if (patterns.length < 2) {
+                    return err(new Error('Not enough valid patterns found'));
+                }
+                // Merge patterns - take best template, combine contexts
+                const consolidatedPattern = buildConsolidatedPattern(patterns, uuidv4());
+                // #1106/#1149: every source is archived and verified, then the
+                // consolidated pattern is stored and verified, then the sources are
+                // removed with compare-and-delete; failures roll back (pattern-merge.ts).
+                return commitPatternMerge(this.memory, patterns, consolidatedPattern, (p) => this.storePattern(p));
+            });
         }
         catch (error) {
             return err(toError(error));

package/dist/domains/test-execution/services/test-executor.js

@@ -11,7 +11,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { v4 as uuidv4 } from 'uuid';
 import { ok, err } from '../../../shared/types/index.js';
 import { TEST_EXECUTION_CONSTANTS, LLM_ANALYSIS_CONSTANTS } from '../../constants.js';
-import { toErrorMessage, toError } from '../../../shared/error-utils.js';
+import { CallerInputError, isCallerInputError, toErrorMessage, toError } from '../../../shared/error-utils.js';
 import { safeJsonParse } from '../../../shared/safe-json.js';
 import { secureRandom, secureRandomInt } from '../../../shared/utils/crypto-random.js';
 import { writeTestRunEvidence } from '../../quality-assessment/quality-evidence.js';
@@ -442,6 +442,10 @@ Provide:
             // Runner/suite errors have no trustworthy assertion receipt to aggregate.
             if (result.error instanceof TestRunnerExecutionError)
                 throw result.error;
+            // #1147: the caller's input (a test file that does not exist) is not a
+            // failed test, so it is never counted as a measured failure.
+            if (isCallerInputError(result.error))
+                throw result.error;
             // Return as a failed test rather than throwing — allows other files to still run
             return {
                 total: files.length,
@@ -467,7 +471,7 @@ Provide:
         // Verify test file exists
         const missingFile = files.find(file => !existsSync(file));
         if (missingFile) {
-            return err(new Error(`Test file not found: ${missingFile}`));
+            return err(new CallerInputError(`Test file not found: ${missingFile}`));
         }
         // Build command based on framework
         const { command, args, report, coverageDirectory } = this.buildTestCommand(files, framework);

package/dist/init/init-wizard-steps.js

@@ -13,6 +13,7 @@ import { createN8nInstaller } from './n8n-installer.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { isNativeModuleLoadFailure, withNativeModuleRemedy } from '../shared/native-module-errors.js';
 import { openDatabase } from '../shared/safe-db.js';
+import { setJournalModeWithRetry } from '../shared/sqlite-journal-mode.js';
 import { safeJsonParse } from '../shared/safe-json.js';
 // ============================================================================
 // Version Management
@@ -128,8 +129,9 @@ export async function initializePersistenceDatabase(projectRoot) {
     const dbPath = join(dataDir, 'memory.db');
     try {
         const db = new Database(dbPath);
-        db.pragma('journal_mode = WAL');
+        // busy_timeout first; the WAL switch retries within it (#1164).
         db.pragma('busy_timeout = 5000');
+        setJournalModeWithRetry(db, 'WAL', 5000);
         db.exec(`
       CREATE TABLE IF NOT EXISTS kv_store (
         key TEXT NOT NULL,

package/dist/init/phases/07-hooks.js

@@ -408,6 +408,15 @@ const MAX_AGE_HOURS = 24;
 const SKIP_PATH = path.join(AQE_DIR, 'brain-checkpoint.skip.json');
 const RETRY_ENV = Number.parseFloat(process.env.AQE_BRAIN_CHECKPOINT_RETRY_HOURS || '');
 const TOO_LARGE_RETRY_HOURS = Number.isFinite(RETRY_ENV) && RETRY_ENV >= 0 ? RETRY_ENV : 6;
+// #1251: refuse an export in which a table collapsed; a deliberate shrink
+// (aqe learning prune --apply, dream retention) leaves this acknowledgement,
+// which the CLI honours once, within 24h, while the brain holds its counts.
+const SHRINK_ACK_PATH = path.join(AQE_DIR, 'brain-checkpoint.accept-shrink.json');
+const SHRINK_ACK_MAX_AGE_HOURS = 24;
+const MIRROR_REFUSAL = /RVF_MIRROR_(?:RICHER|INSPECTION_AMBIGUOUS):[^\\n]*/;
+const SHRINK_ACK_VERDICT = /SHRINK_ACK_(HONOURED|IGNORED): ([^\\n]*)/;
+// An older global aqe rejects the #1251 flags: back off rather than fail every turn.
+const OUTDATED_CLI = /unknown option '(--(?:compare-with|richness-policy|accept-shrink))'/;
 // Windows (#872): never execFile aqe.cmd (EINVAL without a shell); reuse the
 // hook shim's resolver, which runs the AQE bundle via node instead.
 function aqeInvocation() {
@@ -441,6 +450,42 @@ function activeSkip() {
   return skip;
 }
 
+function dropShrinkAck(why) {
+  try { fs.unlinkSync(SHRINK_ACK_PATH); } catch { /* best-effort */ }
+  log('Ignored the shrink acknowledgement (' + why + '); the normal checkpoint policy applies.');
+}
+// The deliberate-shrink acknowledgement, or null; drops one that is unreadable,
+// over 24h old or older than aqe.rvf. The CLI checks its counts (--accept-shrink).
+function pendingShrinkAck() {
+  let st; try { st = fs.lstatSync(SHRINK_ACK_PATH); } catch { return null; }
+  let ack = null;
+  if (st.isFile()) { try { ack = JSON.parse(fs.readFileSync(SHRINK_ACK_PATH, 'utf8')); } catch { /* unreadable */ } }
+  const at = ack ? Date.parse(ack.at) : NaN;
+  let rvfMtime = 0; try { rvfMtime = fs.lstatSync(RVF_PATH).mtimeMs; } catch { /* absent */ }
+  let why = null;
+  if (!Number.isFinite(at)) why = 'unreadable';
+  else if (Date.now() - at > SHRINK_ACK_MAX_AGE_HOURS * 3600000) why = 'older than 24h';
+  else if (rvfMtime > at) why = 'already checkpointed';
+  if (why) { dropShrinkAck(why); return null; }
+  return { at, producer: String(ack.producer) };
+}
+// The CLI's verdict on the acknowledgement: its producer when honoured. No
+// verdict (the export failed first) keeps it for the next turn.
+function settleShrinkAck(output) {
+  const verdict = String(output || '').match(SHRINK_ACK_VERDICT);
+  if (!verdict) return null;
+  if (verdict[1] === 'IGNORED') { dropShrinkAck(verdict[2].trim()); return null; }
+  return verdict[2].trim();
+}
+function resumeHint(skip) {
+  return MIRROR_REFUSAL.test(skip.reason)
+    ? 'To resume now, back up aqe.rvf and run \`aqe brain export -o .agentic-qe/aqe.rvf --force-overwrite-richer\`, '
+      + 'or delete .agentic-qe/brain-checkpoint.skip.json to retry.'
+    : skip.reason.includes('upgrade to enable the checkpoint guard')
+      ? 'Upgrade the global aqe (npm i -g agentic-qe), then delete .agentic-qe/brain-checkpoint.skip.json.'
+      : 'To retry now, delete .agentic-qe/brain-checkpoint.skip.json.';
+}
+
 function writeSkip(reason) {
   const at = new Date();
   const skip = { reason, at: at.toISOString(), retryAfter: new Date(at.getTime() + TOO_LARGE_RETRY_HOURS * 3600000).toISOString() };
@@ -483,6 +528,17 @@ function promote(tmp) {
   }
 }
 
+// Version of the installed aqe, for the outdated-CLI back-off.
+function aqeVersion(aqe) {
+  try {
+    const out = execFileSync(aqe.cmd, [...aqe.args, '--version'],
+      { timeout: 10000, encoding: 'utf-8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+    return out.trim().split(/\\s+/).pop() || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
 function exportBrain() {
   if (!fs.existsSync(DB_PATH)) { log('No memory.db, skipping'); return { exported: false }; }
   const aqe = aqeInvocation();
@@ -490,17 +546,22 @@ function exportBrain() {
   // Never write through a committed symlink: .agentic-qe must be a real dir.
   let st; try { st = fs.lstatSync(AQE_DIR); } catch { /* missing */ }
   if (!st || !st.isDirectory()) { log('Export skipped: .agentic-qe is a symlink'); return { exported: false }; }
+  const ack = pendingShrinkAck();
   const skip = activeSkip();
-  if (skip) {
-    log('Export skipped until ' + skip.retryAfter + ': ' + skip.reason);
+  // A shrink acknowledged after the back-off began is the answer to it.
+  if (skip && !(ack && ack.at > Date.parse(skip.at))) {
+    // Logged once, when the back-off began; session-start verify reports it.
     return { exported: false, skipped: true, reason: skip.reason, retryAfter: skip.retryAfter };
   }
   sweepStaleTmp();
   const tmp = path.join(AQE_DIR, TMP_PREFIX + process.pid + '-' + crypto.randomBytes(4).toString('hex'));
   try {
     for (const suffix of ['', ...RVF_SIDECARS]) removeEntry(tmp + suffix);
+    const args = [...aqe.args, 'brain', 'export', '-o', tmp, '--format', 'rvf'];
+    if (lexists(RVF_PATH)) args.push('--compare-with', RVF_PATH, '--richness-policy', 'checkpoint');
+    if (ack) args.push('--accept-shrink', SHRINK_ACK_PATH);
     const result = execFileSync(
-      aqe.cmd, [...aqe.args, 'brain', 'export', '-o', tmp, '--format', 'rvf'],
+      aqe.cmd, args,
       { timeout: 60000, encoding: 'utf-8', windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] }
     );
     // A zero exit without a store is a failure, not an empty checkpoint.
@@ -509,9 +570,30 @@ function exportBrain() {
     const m = result.match(/Patterns:\\s+(\\d+)/);
     const p = m ? m[1] : '0';
     log('Exported ' + p + ' patterns to aqe.rvf');
-    return { exported: true, patterns: parseInt(p) };
+    const accepted = ack ? settleShrinkAck(result) : null;
+    if (!accepted) return { exported: true, patterns: parseInt(p) };
+    try { removeEntry(SHRINK_ACK_PATH); removeEntry(SKIP_PATH); } catch { /* spent: older than aqe.rvf now */ }
+    log('Accepted the smaller brain (' + accepted + ')');
+    return { exported: true, patterns: parseInt(p), acceptedShrink: accepted };
   } catch (e) {
-    const tooLarge = (String(e.stderr || '') + String(e.stdout || '')).match(/RVF_KERNEL_TOO_LARGE:[^\\n]*/);
+    const output = String(e.stderr || '') + String(e.stdout || '');
+    if (ack) settleShrinkAck(e.stdout);
+    const outdated = output.match(OUTDATED_CLI);
+    if (outdated) {
+      const skip = writeSkip('installed aqe ' + aqeVersion(aqe) + ' lacks ' + outdated[1] + '; upgrade to enable the checkpoint guard');
+      log('Export skipped, previous aqe.rvf kept: ' + skip.reason);
+      log('Skipping the checkpoint export until ' + skip.retryAfter + ' (logged once).');
+      return { exported: false, outdatedCli: true, reason: skip.reason, retryAfter: skip.retryAfter };
+    }
+    const refused = output.match(MIRROR_REFUSAL);
+    if (refused) {
+      const skip = writeSkip(refused[0].trim());
+      log('Export refused, previous aqe.rvf kept: ' + skip.reason);
+      log('Skipping the checkpoint export until ' + skip.retryAfter + ' (logged once). If the smaller brain is '
+        + 'intended, back up aqe.rvf and run: aqe brain export -o .agentic-qe/aqe.rvf --force-overwrite-richer');
+      return { exported: false, richer: true, reason: skip.reason, retryAfter: skip.retryAfter };
+    }
+    const tooLarge = output.match(/RVF_KERNEL_TOO_LARGE:[^\\n]*/);
     if (tooLarge) {
       const skip = writeSkip(tooLarge[0].trim());
       log('Export failed: ' + skip.reason);
@@ -529,18 +611,23 @@ function verifyBrain() {
   if (!fs.existsSync(RVF_PATH)) {
     const skip = activeSkip();
     if (skip) {
-      log('No aqe.rvf found; checkpoint export paused until ' + skip.retryAfter + ': ' + skip.reason);
-      return { valid: false, reason: 'missing', skippedUntil: skip.retryAfter };
+      log('No aqe.rvf found; checkpoint export paused until ' + skip.retryAfter + ': ' + skip.reason + ' ' + resumeHint(skip));
+      return { valid: false, reason: 'missing', skippedUntil: skip.retryAfter, resumeHint: resumeHint(skip) };
     }
     log('No aqe.rvf found');
     return { valid: false, reason: 'missing' };
   }
   const stat = fs.statSync(RVF_PATH);
+  const paused = activeSkip();
+  if (paused) log('Checkpoint export paused until ' + paused.retryAfter + ': ' + paused.reason + ' ' + resumeHint(paused));
+  const pause = paused
+    ? { pausedUntil: paused.retryAfter, pauseReason: paused.reason, resumeHint: resumeHint(paused) }
+    : {};
   const ageH = (Date.now() - stat.mtimeMs) / 3600000;
-  if (stat.size < 1024) { log('aqe.rvf too small'); return { valid: false, reason: 'too-small' }; }
-  if (ageH > MAX_AGE_HOURS) { log('aqe.rvf is ' + ageH.toFixed(1) + 'h old'); return { valid: true, stale: true }; }
+  if (stat.size < 1024) { log('aqe.rvf too small'); return { valid: false, reason: 'too-small', ...pause }; }
+  if (ageH > MAX_AGE_HOURS) { log('aqe.rvf is ' + ageH.toFixed(1) + 'h old'); return { valid: true, stale: true, ...pause }; }
   log('aqe.rvf OK (' + (stat.size/1048576).toFixed(1) + ' MB)');
-  return { valid: true, stale: false };
+  return { valid: true, stale: false, ...pause };
 }
 
 const cmd = process.argv[2] || 'verify';

package/dist/integrations/embeddings/cache/EmbeddingCache.js

@@ -89,8 +89,8 @@ export class EmbeddingCache {
                 if (!existsSync(dir)) {
                     mkdirSync(dir, { recursive: true });
                 }
+                // #1164: openDatabase() set the journal mode (retrying contention, honouring AQE_DISABLE_WAL).
                 this.db = openDatabase(this.storagePath);
-                this.db.pragma('journal_mode = WAL');
                 this.db.pragma('synchronous = NORMAL');
                 // Create table if not exists (only for legacy mode)
                 this.db.exec(`

package/dist/integrations/ruvector/brain-rvf-exporter.d.ts

@@ -5,6 +5,7 @@
  */
 import Database from 'better-sqlite3';
 import { type MergeStrategy } from './brain-shared.js';
+import { CODE_INDEX_VECTOR_ID_PREFIX, type RichnessPolicy, type ShrinkAckVerdict } from './brain-rvf-richness.js';
 export interface RvfBrainManifest {
     readonly version: '2.0' | '3.0';
     readonly format: 'rvf';
@@ -50,6 +51,20 @@ export interface RvfBrainExportOptions {
     readonly signerKeyId?: string;
     /** Explicit operator acknowledgement that a richer existing mirror may be replaced. */
     readonly allowOverwriteRicher?: boolean;
+    /**
+     * The mirror to compare richness against, when it is not `outputPath`
+     * (#1251: the checkpoint hook exports to a temp path, then renames).
+     */
+    readonly compareWithPath?: string;
+    /** How much shrinkage the richness guard tolerates. Defaults to 'strict'. */
+    readonly richnessPolicy?: RichnessPolicy;
+    /**
+     * A deliberate-shrink acknowledgement (parsed JSON, #1251). When it still
+     * vouches for this export, it replaces the mirror comparison.
+     */
+    readonly shrinkAck?: unknown;
+    /** Told whether `shrinkAck` was honoured, before the mirror comparison runs. */
+    readonly onShrinkAck?: (verdict: ShrinkAckVerdict) => void;
     /** Kernel size ceiling in bytes. Defaults to RVF_MAX_KERNEL_BYTES; lowered only by tests. */
     readonly maxKernelBytes?: number;
 }
@@ -74,7 +89,7 @@ export declare const RVF_MAX_KERNEL_BYTES: number;
  * index, C4 diagrams). They are derived from source code and rebuilt by
  * `aqe code index`, so they stay out of the brain kernel (#1238).
  */
-export declare const CODE_INDEX_VECTOR_ID_PREFIX = "code-intelligence:";
+export { CODE_INDEX_VECTOR_ID_PREFIX };
 /** Thrown before any native call when the kernel would exceed the RVF limit. */
 export declare class RvfKernelTooLargeError extends Error {
     readonly kernelBytes: number;

package/dist/integrations/ruvector/brain-rvf-exporter.js

@@ -8,6 +8,7 @@ import { basename, dirname, join, resolve } from 'path';
 import { createRvfStore, openRvfStore, openRvfStoreReadonly, isRvfNativeAvailable, } from './rvf-native-adapter.js';
 import { sha256, tableExists, queryAll, domainFilterForColumn, runImportTransaction, mergeGenericRow, remapPatternReferences, mergeAppendOnlyRow, TABLE_CONFIGS, TABLE_BLOB_COLUMNS, PK_COLUMNS, CONFIDENCE_COLUMNS, TIMESTAMP_COLUMNS, serializeRowBlobs, deserializeRowBlobs, } from './brain-shared.js';
 import { appendBrainImportWitness } from './brain-import-audit.js';
+import { assertNotPoorerThanMirror, CODE_INDEX_VECTOR_ID_PREFIX, evaluateShrinkAck, RvfMirrorGuardError, } from './brain-rvf-richness.js';
 // --- Export ---
 /**
  * Largest kernel image @ruvector/rvf-node accepts. One byte more and
@@ -20,7 +21,7 @@ export const RVF_MAX_KERNEL_BYTES = 128 * 1024 * 1024;
  * index, C4 diagrams). They are derived from source code and rebuilt by
  * `aqe code index`, so they stay out of the brain kernel (#1238).
  */
-export const CODE_INDEX_VECTOR_ID_PREFIX = 'code-intelligence:';
+export { CODE_INDEX_VECTOR_ID_PREFIX };
 const CODE_INDEX_VECTOR_MATCH = `substr(id, 1, ${CODE_INDEX_VECTOR_ID_PREFIX.length}) = ?`;
 function isCodeIndexVectorRow(tableName, row) {
     if (tableName !== 'vectors')
@@ -319,47 +320,32 @@ export function exportBrainToRvf(db, options, sourceDbLabel = 'memory.db') {
         // promotion. Inspection is fail-closed when the RVF itself remains readable
         // but its kernel cannot yield a complete table inventory. A genuinely
         // unreadable/corrupt RVF remains replaceable to preserve #563 recovery.
-        if (existsSync(outPath) && !options.allowOverwriteRicher) {
+        // #1251: the Stop-hook checkpoint writes to a temp path and names the
+        // published checkpoint in `compareWithPath`, so it is compared here too.
+        const comparePath = options.compareWithPath ? resolve(options.compareWithPath) : outPath;
+        let allowOverwriteRicher = options.allowOverwriteRicher === true;
+        if (options.shrinkAck !== undefined && !allowOverwriteRicher) {
+            const verdict = evaluateShrinkAck(options.shrinkAck, TABLE_CONFIGS.map(({ tableName }) => tableName), manifest.stats.tableCounts);
+            options.onShrinkAck?.(verdict);
+            allowOverwriteRicher = verdict.honoured;
+        }
+        if (existsSync(comparePath) && !allowOverwriteRicher) {
             let existing;
             try {
                 // Code-index vectors are no longer exported (#1238), so an older mirror
                 // that still holds them is compared on the rows both exports carry.
-                existing = readBrainInfo(outPath, true);
+                existing = readBrainInfo(comparePath, true);
             }
             catch (error) {
-                if (hasReadableBrainKernel(outPath) || !isKnownUnusableRvfError(error)) {
+                if (hasReadableBrainKernel(comparePath) || !isKnownUnusableRvfError(error)) {
                     const detail = error instanceof Error ? error.message : String(error);
-                    throw new Error(`RVF_MIRROR_INSPECTION_AMBIGUOUS: the existing mirror is readable but its ` +
-                        `richness could not be established (${detail}). Preserve/import it before retrying, ` +
-                        `or repeat with --force-overwrite-richer after preserving a backup.`);
+                    throw new RvfMirrorGuardError('RVF_MIRROR_INSPECTION_AMBIGUOUS', `the existing mirror is readable but its richness could not be established ` +
+                        `(${detail}). Preserve/import it before retrying, or repeat with ` +
+                        `--force-overwrite-richer after preserving a backup.`);
                 }
             }
             if (existing) {
-                const existingCounts = existing.stats.tableCounts;
-                const candidateCounts = manifest.stats.tableCounts;
-                const missing = TABLE_CONFIGS
-                    .map(({ tableName }) => tableName)
-                    .filter((tableName) => !existingCounts || !Number.isSafeInteger(existingCounts[tableName]));
-                if (missing.length > 0) {
-                    throw new Error(`RVF_MIRROR_INSPECTION_AMBIGUOUS: existing mirror lacks trustworthy counts for ` +
-                        `${missing.join(', ')}. Preserve/import it before retrying, or repeat with ` +
-                        `--force-overwrite-richer after preserving a backup.`);
-                }
-                const richer = TABLE_CONFIGS
-                    .map(({ tableName }) => ({
-                    tableName,
-                    existing: existingCounts[tableName],
-                    candidate: candidateCounts[tableName],
-                }))
-                    .filter(({ existing: existingCount, candidate }) => existingCount > candidate);
-                if (richer.length > 0) {
-                    const differences = richer
-                        .map(({ tableName, existing: existingCount, candidate }) => `${tableName} ${existingCount} -> ${candidate}`)
-                        .join(', ');
-                    throw new Error(`RVF_MIRROR_RICHER: refusing to replace richer mirrored tables: ${differences}. ` +
-                        `Restore/import the mirror first, or repeat with --force-overwrite-richer after ` +
-                        `preserving a backup.`);
-                }
+                assertNotPoorerThanMirror(TABLE_CONFIGS.map(({ tableName }) => tableName), existing.stats.tableCounts, manifest.stats.tableCounts, options.richnessPolicy);
             }
         }
         // Promote tmp → final. The store itself goes last: until it lands, the

package/dist/integrations/ruvector/brain-rvf-richness.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Richness comparison between an existing RVF mirror and a new export
+ * (#629, ADR-128; #1251 for the checkpoint policy).
+ *
+ * - `strict` (default, manual `aqe brain export`): any mirrored table with
+ *   fewer rows than the existing mirror refuses the export.
+ * - `checkpoint` (the Stop-hook checkpoint): routine retention trims rows
+ *   between turns (routing outcomes, concept edges, q-values, trajectories),
+ *   so only a collapse refuses: a table that lost more than its share in
+ *   CHECKPOINT_MAX_LOSS (half by default), and either at least
+ *   CHECKPOINT_MIN_LOST_ROWS rows or every row of a table that had at least
+ *   CHECKPOINT_MIN_EMPTIED_ROWS. A database recreated from seed data loses
+ *   that much; a retention pass does not. A table the existing mirror does
+ *   not have (added in a later release) held no rows to lose.
+ *
+ * A deliberate shrink (`aqe learning prune --apply`, dream retention) records
+ * a CheckpointShrinkAck. The checkpoint honours it in place of the mirror
+ * comparison only while it is fresh and the export still holds the counts the
+ * shrink left, so it cannot approve a later, unrelated drop.
+ */
+import type Database from 'better-sqlite3';
+export type RichnessPolicy = 'strict' | 'checkpoint';
+export declare const RICHNESS_POLICIES: readonly RichnessPolicy[];
+/** Smallest loss the checkpoint policy refuses, so retention can trim a small table. */
+export declare const CHECKPOINT_MIN_LOST_ROWS = 10;
+/** A table emptied from at least this many rows is refused even under the minimum loss. */
+export declare const CHECKPOINT_MIN_EMPTIED_ROWS = 3;
+/**
+ * Largest share of a table the checkpoint policy lets go. Learned patterns
+ * are deduplicated at most 10% at a time (SQLitePatternStore), and captured
+ * experiences are never deleted (v3.9.22), so they get the 10% bound.
+ */
+export declare const CHECKPOINT_MAX_LOSS: Readonly<Record<string, number>>;
+/** Code-intelligence vectors are a regenerable cache, never exported (#1238). */
+export declare const CODE_INDEX_VECTOR_ID_PREFIX = "code-intelligence:";
+export type RvfMirrorGuardCode = 'RVF_MIRROR_RICHER' | 'RVF_MIRROR_INSPECTION_AMBIGUOUS';
+/** Refusal to replace an existing mirror. The message starts with the code. */
+export declare class RvfMirrorGuardError extends Error {
+    readonly code: RvfMirrorGuardCode;
+    constructor(code: RvfMirrorGuardCode, detail: string);
+}
+export declare function isRichnessPolicy(value: unknown): value is RichnessPolicy;
+/**
+ * Throw when replacing a mirror with `existingCounts` by a candidate with
+ * `candidateCounts` would lose rows under `policy`. `existingCounts` is
+ * undefined when the mirror has no table inventory at all: that is ambiguous
+ * under every policy.
+ */
+export declare function assertNotPoorerThanMirror(tableNames: readonly string[], existingCounts: Readonly<Record<string, number>> | undefined, candidateCounts: Readonly<Record<string, number>>, policy?: RichnessPolicy): void;
+/** Row counts of every mirrored table, counted the way the RVF export counts them. */
+export declare function mirroredTableCounts(db: Database.Database): Record<string, number>;
+export type ShrinkProducer = 'prune' | 'dream';
+/** What a deliberate shrink records for the checkpoint hook. */
+export interface CheckpointShrinkAck {
+    readonly at: string;
+    readonly producer: ShrinkProducer;
+    /** mirroredTableCounts() right after the shrink. */
+    readonly tableCounts: Readonly<Record<string, number>>;
+}
+/** An acknowledgement is honoured for this long after the shrink. */
+export declare const SHRINK_ACK_MAX_AGE_MS: number;
+export type ShrinkAckVerdict = {
+    readonly honoured: true;
+    readonly producer: ShrinkProducer;
+} | {
+    readonly honoured: false;
+    readonly reason: string;
+};
+/**
+ * Whether the acknowledgement `raw` (parsed JSON, or anything else) still
+ * vouches for an export with `candidateCounts`: under 24h old, and no table
+ * collapsed since the shrink, under the checkpoint policy. Growth is fine.
+ */
+export declare function evaluateShrinkAck(raw: unknown, tableNames: readonly string[], candidateCounts: Readonly<Record<string, number>>, now?: number): ShrinkAckVerdict;
+//# sourceMappingURL=brain-rvf-richness.d.ts.map