agentic-qe 3.15.16 → 3.15.18

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/init/platform-config-generator.d.ts

@@ -23,6 +23,16 @@ export interface GeneratedConfig {
     format: string;
 }
 export declare const PLATFORM_REGISTRY: Record<PlatformId, PlatformDefinition>;
+/**
+ * Issue #1269: VS Code caches each MCP server's tool list keyed by a hash of its
+ * launch config (command/args/env) and only restarts the server when that hash
+ * changes. The `agentic-qe@latest` entry is identical across releases, so tool
+ * schemas cached from an older server (the pre-#1185 "array type must have items"
+ * ones) survived upgrades. Stamping the installing version into the Copilot
+ * entry's env changes the hash whenever `aqe init` runs after an upgrade, without
+ * pinning which server version npx launches. The server does not read it.
+ */
+export declare function getCopilotInitVersionEnv(): Record<string, string>;
 export declare class PlatformConfigGenerator {
     /**
      * Get the platform definition for a given platform ID

package/dist/init/platform-config-generator.js

@@ -4,6 +4,7 @@
  *
  * Supports: GitHub Copilot, Cursor, Cline, Kilo Code, Roo Code, OpenAI Codex, Windsurf, Continue.dev
  */
+import { createRequire } from 'module';
 // ============================================================================
 // Platform Registry
 // ============================================================================
@@ -146,6 +147,29 @@ function getMcpServerEnv(dbFree) {
         ? { AQE_MEMORY_BACKEND: 'memory', AQE_V3_MODE: 'true' }
         : { AQE_MEMORY_PATH: '.agentic-qe/memory.db', AQE_V3_MODE: 'true' };
 }
+/**
+ * Installed AQE version: the build-time define in the CLI/MCP bundles, otherwise
+ * package.json (tsc output and tests). Both src/init/ and dist/cli/ sit two levels
+ * below the package root.
+ */
+function getInstalledAqeVersion() {
+    if (typeof __CLI_VERSION__ !== 'undefined')
+        return __CLI_VERSION__;
+    const pkg = createRequire(import.meta.url)('../../package.json');
+    return pkg.version;
+}
+/**
+ * Issue #1269: VS Code caches each MCP server's tool list keyed by a hash of its
+ * launch config (command/args/env) and only restarts the server when that hash
+ * changes. The `agentic-qe@latest` entry is identical across releases, so tool
+ * schemas cached from an older server (the pre-#1185 "array type must have items"
+ * ones) survived upgrades. Stamping the installing version into the Copilot
+ * entry's env changes the hash whenever `aqe init` runs after an upgrade, without
+ * pinning which server version npx launches. The server does not read it.
+ */
+export function getCopilotInitVersionEnv() {
+    return { AQE_INIT_VERSION: getInstalledAqeVersion() };
+}
 function getMcpServerEntry(withAutoApprove, dbFree) {
     const entry = {
         command: 'npx',
@@ -164,12 +188,13 @@ function getMcpServerEntry(withAutoApprove, dbFree) {
 function generateJsonConfig(platform, dbFree) {
     const serverEntry = getMcpServerEntry(platform.supportsAutoApprove, dbFree);
     if (platform.id === 'copilot') {
-        // Copilot uses "servers" key with "type": "stdio"
+        // Copilot uses "servers" key with "type": "stdio"; env carries the init version stamp (#1269)
         const config = {
             [platform.configKey]: {
                 'agentic-qe': {
                     type: 'stdio',
                     ...serverEntry,
+                    env: { ...serverEntry.env, ...getCopilotInitVersionEnv() },
                 },
             },
         };

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

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

@@ -0,0 +1,127 @@
+/**
+ * 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 { TABLE_CONFIGS, countRows } from './brain-shared.js';
+export const RICHNESS_POLICIES = ['strict', 'checkpoint'];
+/** Smallest loss the checkpoint policy refuses, so retention can trim a small table. */
+export const CHECKPOINT_MIN_LOST_ROWS = 10;
+/** A table emptied from at least this many rows is refused even under the minimum loss. */
+export 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 const CHECKPOINT_MAX_LOSS = {
+    qe_patterns: 0.1,
+    captured_experiences: 0.1,
+};
+const CHECKPOINT_DEFAULT_MAX_LOSS = 0.5;
+/** Code-intelligence vectors are a regenerable cache, never exported (#1238). */
+export const CODE_INDEX_VECTOR_ID_PREFIX = 'code-intelligence:';
+/** Refusal to replace an existing mirror. The message starts with the code. */
+export class RvfMirrorGuardError extends Error {
+    code;
+    constructor(code, detail) {
+        super(`${code}: ${detail}`);
+        this.code = code;
+        this.name = 'RvfMirrorGuardError';
+    }
+}
+export function isRichnessPolicy(value) {
+    return typeof value === 'string' && RICHNESS_POLICIES.includes(value);
+}
+function isLoss(tableName, existing, candidate, policy) {
+    if (policy === 'strict')
+        return existing > candidate;
+    const lost = existing - candidate;
+    const maxLoss = CHECKPOINT_MAX_LOSS[tableName] ?? CHECKPOINT_DEFAULT_MAX_LOSS;
+    const emptied = candidate === 0 && existing >= CHECKPOINT_MIN_EMPTIED_ROWS;
+    return lost > existing * maxLoss && (lost >= CHECKPOINT_MIN_LOST_ROWS || emptied);
+}
+/**
+ * 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 function assertNotPoorerThanMirror(tableNames, existingCounts, candidateCounts, policy = 'strict') {
+    const missing = tableNames.filter((tableName) => !existingCounts || !Number.isSafeInteger(existingCounts[tableName]));
+    if (!existingCounts || (policy === 'strict' && missing.length > 0)) {
+        throw new RvfMirrorGuardError('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 = tableNames
+        .map((tableName) => ({
+        tableName,
+        existing: Number.isSafeInteger(existingCounts[tableName]) ? existingCounts[tableName] : 0,
+        candidate: candidateCounts[tableName] ?? 0,
+    }))
+        .filter(({ tableName, existing, candidate }) => isLoss(tableName, existing, candidate, policy));
+    if (richer.length > 0) {
+        const differences = richer
+            .map(({ tableName, existing, candidate }) => `${tableName} ${existing} -> ${candidate}`)
+            .join(', ');
+        throw new RvfMirrorGuardError('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.`);
+    }
+}
+/** Row counts of every mirrored table, counted the way the RVF export counts them. */
+export function mirroredTableCounts(db) {
+    const counts = {};
+    for (const { tableName } of TABLE_CONFIGS) {
+        counts[tableName] = tableName === 'vectors'
+            ? countRows(db, 'vectors', `(id IS NULL OR substr(id, 1, ?) != ?)`, [CODE_INDEX_VECTOR_ID_PREFIX.length, CODE_INDEX_VECTOR_ID_PREFIX])
+            : countRows(db, tableName);
+    }
+    return counts;
+}
+/** An acknowledgement is honoured for this long after the shrink. */
+export const SHRINK_ACK_MAX_AGE_MS = 24 * 3600_000;
+/** Clock skew tolerated for an acknowledgement dated in the future. */
+const SHRINK_ACK_MAX_SKEW_MS = 5 * 60_000;
+/**
+ * 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 function evaluateShrinkAck(raw, tableNames, candidateCounts, now = Date.now()) {
+    const ack = raw;
+    if (!ack || typeof ack !== 'object' || (ack.producer !== 'prune' && ack.producer !== 'dream')
+        || !ack.tableCounts || typeof ack.tableCounts !== 'object') {
+        return { honoured: false, reason: 'malformed acknowledgement' };
+    }
+    const at = Date.parse(String(ack.at));
+    if (!Number.isFinite(at) || at > now + SHRINK_ACK_MAX_SKEW_MS) {
+        return { honoured: false, reason: `invalid time ${String(ack.at)}` };
+    }
+    if (now - at > SHRINK_ACK_MAX_AGE_MS) {
+        return { honoured: false, reason: `older than 24h (${ack.producer} at ${ack.at})` };
+    }
+    try {
+        assertNotPoorerThanMirror(tableNames, ack.tableCounts, candidateCounts, 'checkpoint');
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.replace(/^RVF_MIRROR_[A-Z_]+: /, '') : String(error);
+        return { honoured: false, reason: `the brain shrank again since the ${ack.producer}: ${detail.split('.')[0]}` };
+    }
+    return { honoured: true, producer: ack.producer };
+}
+//# sourceMappingURL=brain-rvf-richness.js.map

package/dist/kernel/unified-memory-migration.js

@@ -70,8 +70,8 @@ export async function migrateToUnifiedMemory(options) {
             if (!fs.existsSync(opts.baseDir)) {
                 fs.mkdirSync(opts.baseDir, { recursive: true });
             }
+            // #1164: openDatabase() set the journal mode (retrying contention, honouring AQE_DISABLE_WAL).
             targetDb = openDatabase(memoryDbPath);
-            targetDb.pragma('journal_mode = WAL');
         }
         // Get list of tables to migrate
         const tablesToMigrate = [

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

@@ -82,6 +82,8 @@ export declare class UnifiedMemoryManager {
     private constructor();
     static getInstance(config?: Partial<UnifiedMemoryConfig>): UnifiedMemoryManager;
     static getInstanceAsync(config?: Partial<UnifiedMemoryConfig>): Promise<UnifiedMemoryManager>;
+    /** The shared instance when it is initialized; never creates one. */
+    static peekInitialized(): UnifiedMemoryManager | null;
     static resetInstance(): void;
     initialize(options?: {
         signal?: AbortSignal;
@@ -227,6 +229,12 @@ export declare class UnifiedMemoryManager {
 }
 export declare function getUnifiedMemory(config?: Partial<UnifiedMemoryConfig>): UnifiedMemoryManager;
 export declare function initializeUnifiedMemory(config?: Partial<UnifiedMemoryConfig>): Promise<UnifiedMemoryManager>;
+/**
+ * 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 declare function getOpenUnifiedMemoryDatabase(): DatabaseType | null;
 export declare function resetUnifiedMemory(): void;
 /**
  * Run a write on `db` through the shared manager's writeWhenUnlocked queue

package/dist/kernel/unified-memory.js

@@ -174,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();
@@ -1118,6 +1123,14 @@ 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();
 }