agentic-qe 3.13.12 → 3.14.1

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

@@ -293,7 +293,7 @@ export class HooksPhase extends BasePhase {
     /**
      * Install the resilient hook shim (aqe-hook.cjs) into .claude/hooks/.
      * The generated settings.json hooks run `node .../aqe-hook.cjs <cmd>` — the
-     * shim resolves a project-local AQE bundle (or falls back to npx), strips
+     * shim resolves a project-local AQE bundle (or an installed aqe binary), strips
      * init noise from stdout, swallows stderr, and always exits 0.
      */
     installHookShim(projectRoot, context) {
@@ -321,7 +321,7 @@ export class HooksPhase extends BasePhase {
             return;
         }
         // Should not happen for a real install (the file ships in the package).
-        context.services.log('  ⚠ aqe-hook.cjs source not found — hooks will fall back to `npx agentic-qe`');
+        context.services.log('  ⚠ aqe-hook.cjs source not found — lifecycle hooks cannot run until AQE is reinstalled');
     }
     /**
      * Generate a minimal statusline-v3.cjs script as a fallback.
@@ -381,17 +381,15 @@ const AQE_DIR = path.join(PROJECT_ROOT, '.agentic-qe');
 const RVF_PATH = path.join(AQE_DIR, 'aqe.rvf');
 const DB_PATH = path.join(AQE_DIR, 'memory.db');
 const MAX_AGE_HOURS = 24;
+const AQE_BIN = process.env.AQE_HOOK_BIN || (process.platform === 'win32' ? 'aqe.cmd' : 'aqe');
 
 function log(msg) { process.stderr.write('[brain-checkpoint] ' + msg + '\\n'); }
 
 function exportBrain() {
   if (!fs.existsSync(DB_PATH)) { log('No memory.db, skipping'); return { exported: false }; }
   try {
-    if (fs.existsSync(RVF_PATH)) fs.unlinkSync(RVF_PATH);
-    const idmap = RVF_PATH + '.idmap.json';
-    if (fs.existsSync(idmap)) fs.unlinkSync(idmap);
     const result = execFileSync(
-      'npx', ['agentic-qe', 'brain', 'export', '-o', RVF_PATH, '--format', 'rvf'],
+      AQE_BIN, ['brain', 'export', '-o', RVF_PATH, '--format', 'rvf'],
       { timeout: 60000, encoding: 'utf-8' }
     );
     const m = result.match(/Patterns:\\s+(\\d+)/);
@@ -425,8 +423,8 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
     /**
      * Generate hooks configuration
      *
-     * Uses `npx agentic-qe` for portability - works without global installation.
-     * All hooks use --json output for structured data and fail silently with continueOnError.
+     * Timeout values use Claude Code's native seconds unit. The shim itself uses
+     * a smaller millisecond budget so it can record failures before the host stops it.
      */
     generateHooksConfig(_config, _projectRoot) {
         // Shell injection safety: env vars like $TOOL_INPUT_file_path are set by
@@ -444,7 +442,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" guard --file "$TOOL_INPUT_file_path" --json',
-                            timeout: 3000,
+                            timeout: 3,
                             continueOnError: true,
                         },
                     ],
@@ -456,7 +454,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" pre-edit --file "$TOOL_INPUT_file_path" --json',
-                            timeout: 5000,
+                            timeout: 5,
                             continueOnError: true,
                         },
                     ],
@@ -468,7 +466,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" pre-command --command "$TOOL_INPUT_command" --json',
-                            timeout: 3000,
+                            timeout: 3,
                             continueOnError: true,
                         },
                     ],
@@ -480,7 +478,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" pre-task --description "$TOOL_INPUT_prompt" --json',
-                            timeout: 5000,
+                            timeout: 5,
                             continueOnError: true,
                         },
                     ],
@@ -493,7 +491,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" post-edit --file "$TOOL_INPUT_file_path" --success --json',
-                            timeout: 5000,
+                            timeout: 5,
                             continueOnError: true,
                         },
                     ],
@@ -504,7 +502,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" post-command --command "$TOOL_INPUT_command" --success true --json',
-                            timeout: 5000,
+                            timeout: 5,
                             continueOnError: true,
                         },
                     ],
@@ -515,7 +513,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" post-task --task-id "$TOOL_RESULT_agent_id" --agent "$TOOL_INPUT_subagent_type" --success true --description "$TOOL_INPUT_prompt" --json',
-                            timeout: 5000,
+                            timeout: 5,
                             continueOnError: true,
                         },
                     ],
@@ -530,7 +528,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                             // var, so we let the CLI read stdin directly.
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" route --json',
-                            timeout: 5000,
+                            timeout: 5,
                             continueOnError: true,
                         },
                     ],
@@ -542,7 +540,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" session-start --session-id "$SESSION_ID" --json',
-                            timeout: 10000,
+                            timeout: 10,
                             continueOnError: true,
                         },
                     ],
@@ -552,7 +550,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'sh -c \'exec node "${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/brain-checkpoint.cjs" verify --json\'',
-                            timeout: 5000,
+                            timeout: 5,
                             continueOnError: true,
                         },
                     ],
@@ -564,7 +562,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" session-end --save-state --json',
-                            timeout: 5000,
+                            timeout: 5,
                             continueOnError: true,
                         },
                     ],
@@ -578,7 +576,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                             // rows forever in direct-work sessions (no Task/Agent spawned).
                             type: 'command',
                             command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" post-route --success true --json',
-                            timeout: 5000,
+                            timeout: 5,
                             continueOnError: true,
                         },
                     ],
@@ -588,7 +586,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                         {
                             type: 'command',
                             command: 'sh -c \'exec node "${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/brain-checkpoint.cjs" export --json\'',
-                            timeout: 60000,
+                            timeout: 60,
                             continueOnError: true,
                         },
                     ],

package/dist/init/phases/09-assets.d.ts

@@ -16,6 +16,10 @@ export interface AssetsResult {
     kiroHooks: number;
     platformsConfigured: string[];
     browserEngine?: BrowserEngineInstallResult;
+    codexGuidance?: {
+        policy: 'full' | 'compact' | 'none';
+        ownedBytes: number;
+    };
 }
 /**
  * Assets phase - installs skills and agents

package/dist/init/phases/09-assets.js

@@ -8,7 +8,7 @@ import { BasePhase, } from './phase-interface.js';
 import { createSkillsInstaller } from '../skills-installer.js';
 import { createAgentsInstaller } from '../agents-installer.js';
 import { createN8nInstaller } from '../n8n-installer.js';
-import { installBrowserEngine, DEFAULT_VIBIUM_SPEC, } from '../browser-engine-installer.js';
+import { installBrowserEngine, detectBrowserEngine, diagnosePlatform, DEFAULT_VIBIUM_SPEC, } from '../browser-engine-installer.js';
 import { initializeOverlays } from '../../routing/qe-agent-registry.js';
 /**
  * Assets phase - installs skills and agents
@@ -36,6 +36,7 @@ export class AssetsPhase extends BasePhase {
         let kiroAgents = 0;
         let kiroSkills = 0;
         let kiroHooks = 0;
+        let codexGuidance;
         if (options.upgrade) {
             context.services.log(`  Upgrade mode: overwriting existing files`);
         }
@@ -93,15 +94,14 @@ export class AssetsPhase extends BasePhase {
             try {
                 // Pre-flight check: if vibium is already on PATH, skip the loud
                 // banner so we don't scare users on the common path.
-                const alreadyHere = installBrowserEngine({
-                    skip: false,
-                    // Use a tiny timeout for the pre-flight detect-only call. The
-                    // installer will short-circuit on already-installed without
-                    // ever invoking npm.
-                    timeoutMs: 5_000,
-                });
-                if (alreadyHere.status === 'already-installed') {
-                    browserEngine = alreadyHere;
+                const detected = detectBrowserEngine();
+                if (detected.status === 'ready') {
+                    browserEngine = {
+                        status: 'already-installed',
+                        version: detected.version,
+                        packageSpec: DEFAULT_VIBIUM_SPEC,
+                        platformHint: diagnosePlatform(),
+                    };
                     context.services.log(`  Browser engine: vibium ${browserEngine.version} (already installed)`);
                 }
                 else {
@@ -298,9 +298,11 @@ export class AssetsPhase extends BasePhase {
                 overwrite: shouldOverwrite,
                 installMcp: !options.noMcp,
                 includeRuflo: options.withRuflo,
+                guidancePolicy: options.codexGuidance,
                 memoryBackend: options.memoryBackend === 'memory' ? 'memory' : undefined,
             });
             const res = await installer.install();
+            codexGuidance = { policy: res.guidancePolicy, ownedBytes: res.ownedGuidanceBytes };
             if (res.mcpConfigured)
                 platformsConfigured.push('codex');
             if (res.errors.length > 0)
@@ -358,6 +360,7 @@ export class AssetsPhase extends BasePhase {
             kiroHooks,
             platformsConfigured,
             browserEngine,
+            codexGuidance,
         };
     }
     /**

package/dist/init/phases/phase-interface.d.ts

@@ -123,6 +123,8 @@ export interface InitOptions {
     withCodex?: boolean;
     /** Include optional Ruflo guidance and Codex lifecycle integration */
     withRuflo?: boolean;
+    /** Codex AGENTS.md guidance policy. */
+    codexGuidance?: 'full' | 'compact' | 'none';
     /** Install Windsurf MCP config and rules */
     withWindsurf?: boolean;
     /** Install Continue.dev MCP config and rules */

package/dist/init/types.d.ts

@@ -223,6 +223,10 @@ export interface InitResult {
             agents: number;
             skills: number;
         };
+        codexGuidance?: {
+            policy: 'full' | 'compact' | 'none';
+            ownedBytes: number;
+        };
     };
     totalDurationMs: number;
     timestamp: Date;

package/dist/integrations/embeddings/base/EmbeddingGenerator.js

@@ -68,9 +68,11 @@ export class EmbeddingGenerator {
             }
             catch (err) {
                 throw new Error('Local (in-process) embeddings require the optional dependency ' +
-                    '"@huggingface/transformers", which is not installed. Either run ' +
-                    '`npm install @huggingface/transformers`, or configure an embedding ' +
+                    '"@huggingface/transformers", which is not installed. Configure an embedding ' +
                     'endpoint (e.g. Cognitum /v1/embeddings) so the local backend is not needed. ' +
+                    'Installing @huggingface/transformers@4.2.0 is an explicit security opt-in: ' +
+                    'its compatible dependency chain currently has unresolved HIGH advisories ' +
+                    'GHSA-xcpc-8h2w-3j85 and GHSA-f88m-g3jw-g9cj. ' +
                     `Underlying import error: ${err instanceof Error ? err.message : String(err)}`);
             }
             this.model = await pipeline('feature-extraction', this.config.model, {

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

@@ -1,7 +1,7 @@
 /**
  * QE Brain Export/Import System
  *
- * Exports learning state (25 tables) into a portable directory format
+ * Exports learning state (31 tables) into a portable directory format
  * that can be imported by another AQE instance.
  *
  * Export format (.aqe-brain directory):

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

@@ -1,7 +1,7 @@
 /**
  * QE Brain Export/Import System
  *
- * Exports learning state (25 tables) into a portable directory format
+ * Exports learning state (31 tables) into a portable directory format
  * that can be imported by another AQE instance.
  *
  * Export format (.aqe-brain directory):
@@ -51,9 +51,21 @@ function exportTableRows(db, config, options, outDir) {
         writeJsonl(join(outDir, config.fileName), []);
         return { count: 0, rows: [] };
     }
-    const [where, params] = config.domainColumn
+    let [where, params] = config.domainColumn
         ? domainFilterForColumn(options.domains, config.domainColumn)
         : [undefined, []];
+    if (options.domains && options.domains.length > 0 && !config.domainColumn) {
+        const placeholders = options.domains.map(() => '?').join(',');
+        const manifestFilter = `manifest_id IN (SELECT id FROM learning_evidence_manifests WHERE task_family IN (${placeholders}))`;
+        if (['learning_evidence_segments', 'learning_segment_edges', 'learning_evidence_admissions'].includes(config.tableName)) {
+            where = manifestFilter;
+            params = [...options.domains];
+        }
+        else if (['pattern_manifest_lineage', 'pattern_segment_lineage'].includes(config.tableName)) {
+            where = `${manifestFilter} AND pattern_id IN (SELECT id FROM qe_patterns WHERE qe_domain IN (${placeholders}))`;
+            params = [...options.domains, ...options.domains];
+        }
+    }
     const rowCount = countRows(db, config.tableName, where, params);
     // For large tables, stream to avoid OOM
     if (rowCount >= STREAMING_THRESHOLD) {
@@ -232,7 +244,7 @@ export function importBrain(db, containerPath, options) {
                 let result;
                 if (config.dedupColumns && config.dedupColumns.length > 0) {
                     // Append-only tables (witness_chain, qe_pattern_usage)
-                    result = mergeAppendOnlyRow(db, config.tableName, row, config.dedupColumns);
+                    result = mergeAppendOnlyRow(db, config.tableName, row, config.dedupColumns, config.preserveId);
                 }
                 else {
                     // Tables with TEXT PK

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

@@ -17,6 +17,8 @@ export interface RvfBrainManifest {
         readonly dreamInsightCount: number;
         readonly witnessChainLength: number;
         readonly totalRecords?: number;
+        /** Per-table row counts used by the recovery-mirror richness guard. */
+        readonly tableCounts?: Readonly<Record<string, number>>;
     };
     readonly domains: readonly string[];
     readonly checksum: string;
@@ -44,6 +46,8 @@ export interface RvfBrainExportOptions {
     readonly sign?: boolean;
     /** Key identifier to record in manifest when signing */
     readonly signerKeyId?: string;
+    /** Explicit operator acknowledgement that a richer existing mirror may be replaced. */
+    readonly allowOverwriteRicher?: boolean;
 }
 export interface RvfBrainImportOptions {
     readonly mergeStrategy: MergeStrategy;

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

@@ -110,6 +110,25 @@ export function exportBrainToRvf(db, options, sourceDbLabel = 'memory.db') {
                 ? domainFilterForColumn(options.domains, config.domainColumn)
                 : [undefined, []];
             let rows = queryAll(db, config.tableName, where, params);
+            if (options.domains && options.domains.length > 0) {
+                const manifestIds = new Set((allTableData.learning_evidence_manifests ?? []).map(row => row.id));
+                const patternIds = new Set((allTableData.qe_patterns ?? []).map(row => row.id));
+                if (['learning_evidence_segments', 'learning_segment_edges', 'learning_evidence_admissions'].includes(config.tableName)) {
+                    rows = rows.filter(row => manifestIds.has(row.manifest_id));
+                }
+                else if (config.tableName === 'pattern_manifest_lineage') {
+                    rows = rows.filter(row => {
+                        const lineage = row;
+                        return manifestIds.has(lineage.manifest_id) && patternIds.has(lineage.pattern_id);
+                    });
+                }
+                else if (config.tableName === 'pattern_segment_lineage') {
+                    rows = rows.filter(row => {
+                        const lineage = row;
+                        return manifestIds.has(lineage.manifest_id) && patternIds.has(lineage.pattern_id);
+                    });
+                }
+            }
             if (config.tableName === 'qe_patterns') {
                 for (const p of rows) {
                     if (p.qe_domain)
@@ -128,50 +147,28 @@ export function exportBrainToRvf(db, options, sourceDbLabel = 'memory.db') {
         let embeddingCount = 0;
         const embeddingEntries = [];
         if (tableExists(db, 'qe_pattern_embeddings')) {
-            const rows = db.prepare('SELECT pattern_id, embedding, dimension FROM qe_pattern_embeddings').all();
+            const hasSpaceId = db.prepare("PRAGMA table_info('qe_pattern_embeddings')").all()
+                .some((column) => column.name === 'space_id');
+            const rows = db.prepare(`SELECT pattern_id, embedding, dimension, ${hasSpaceId ? 'space_id' : 'NULL'} AS space_id
+           FROM qe_pattern_embeddings`).all();
             for (const row of rows) {
-                if (row.embedding && row.dimension === dimension) {
+                // Legacy vectors without executable provenance remain in the embedded
+                // SQLite kernel for re-embedding, but must never enter the portable ANN
+                // index where their space would be indistinguishable from query vectors.
+                if (row.embedding && row.dimension === dimension && row.space_id) {
                     embeddingEntries.push({
                         id: `pe:${row.pattern_id}`,
                         vector: new Float32Array(row.embedding.buffer, row.embedding.byteOffset, dimension),
-                        metadata: { tableName: 'qe_pattern_embeddings' },
-                    });
-                }
-            }
-        }
-        if (tableExists(db, 'captured_experiences')) {
-            const rows = db.prepare('SELECT id, embedding, embedding_dimension, domain, quality FROM captured_experiences WHERE embedding IS NOT NULL').all();
-            for (const row of rows) {
-                if (row.embedding_dimension === dimension) {
-                    embeddingEntries.push({
-                        id: `exp:${row.id}`,
-                        vector: new Float32Array(row.embedding.buffer, row.embedding.byteOffset, dimension),
-                        metadata: {
-                            tableName: 'captured_experiences',
-                            domain: row.domain,
-                            confidence: row.quality,
-                        },
-                    });
-                }
-            }
-        }
-        if (tableExists(db, 'sona_patterns')) {
-            const rows = db.prepare('SELECT id, state_embedding, domain, confidence FROM sona_patterns WHERE state_embedding IS NOT NULL').all();
-            for (const row of rows) {
-                const dim = row.state_embedding.byteLength / 4;
-                if (dim === dimension) {
-                    embeddingEntries.push({
-                        id: `sona:${row.id}`,
-                        vector: new Float32Array(row.state_embedding.buffer, row.state_embedding.byteOffset, dimension),
-                        metadata: {
-                            tableName: 'sona_patterns',
-                            domain: row.domain,
-                            confidence: row.confidence,
-                        },
+                        metadata: { tableName: 'qe_pattern_embeddings', spaceId: row.space_id },
                     });
                 }
             }
         }
+        // captured_experiences and sona_patterns are still included in the kernel
+        // below, but their schemas do not yet carry embedding-space provenance.
+        // Mixing them into this ANN index would violate #633 even when dimensions
+        // and model labels happen to match, so they are intentionally excluded
+        // until their own write paths persist a space_id.
         if (embeddingEntries.length > 0) {
             const result = rvf.ingest(embeddingEntries);
             embeddingCount = result.accepted;
@@ -210,6 +207,7 @@ export function exportBrainToRvf(db, options, sourceDbLabel = 'memory.db') {
                 dreamInsightCount: (allTableData['dream_insights'] || []).length,
                 witnessChainLength: (allTableData['witness_chain'] || []).length,
                 totalRecords,
+                tableCounts: Object.fromEntries(TABLE_CONFIGS.map(({ tableName }) => [tableName, allTableData[tableName]?.length ?? 0])),
             },
             domains: brainData.domains,
             checksum,
@@ -235,6 +233,53 @@ export function exportBrainToRvf(db, options, sourceDbLabel = 'memory.db') {
         // sidecar, so renaming any earlier would publish an incomplete store.
         rvf.close();
         closed = true;
+        // Issue #629: a stage-2 mirror must not be destroyed when SQLite has just
+        // been recreated from seed data. Compare every mirrored table in the fully
+        // materialized candidate with the still-published store immediately before
+        // 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) {
+            let existing;
+            try {
+                existing = brainInfoFromRvf(outPath);
+            }
+            catch (error) {
+                if (hasReadableBrainKernel(outPath) || !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.`);
+                }
+            }
+            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.`);
+                }
+            }
+        }
         // Promote tmp → final. The store itself goes last: until it lands, the
         // previous store (if any) is still the one on disk, and a crash mid-promote
         // leaves the old store readable rather than a half-written new one.
@@ -263,6 +308,36 @@ export function exportBrainToRvf(db, options, sourceDbLabel = 'memory.db') {
         throw err;
     }
 }
+/**
+ * Distinguish a corrupt/unopenable store (#563, replaceable) from a readable
+ * store whose richness inspection failed (ambiguous, therefore protected).
+ */
+function hasReadableBrainKernel(rvfPath) {
+    let rvf;
+    try {
+        rvf = openRvfStoreReadonly(resolve(rvfPath));
+        const kernel = rvf.extractKernel();
+        return Boolean(kernel?.image);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            rvf?.close();
+        }
+        catch { /* best-effort probe cleanup */ }
+    }
+}
+/**
+ * Only known structural corruption is replaceable without an operator
+ * override. Permission, locking, I/O, and programmer errors are ambiguous and
+ * must fail closed instead of being mistaken for disposable corruption.
+ */
+function isKnownUnusableRvfError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /ManifestNotFound|InvalidMagic|ChecksumMismatch|CorruptStore/i.test(message);
+}
 /** Legacy field-to-table mapping for older RVF exports. */
 const LEGACY_FIELD_MAP = {
     patterns: 'qe_patterns',
@@ -359,7 +434,7 @@ export function importBrainFromRvf(db, rvfPath, options) {
                 for (const row of rows) {
                     let result;
                     if (config.dedupColumns && config.dedupColumns.length > 0) {
-                        result = mergeAppendOnlyRow(db, config.tableName, row, config.dedupColumns);
+                        result = mergeAppendOnlyRow(db, config.tableName, row, config.dedupColumns, config.preserveId);
                     }
                     else {
                         const idCol = PK_COLUMNS[config.tableName] || 'id';
@@ -418,6 +493,11 @@ export function brainInfoFromRvf(rvfPath) {
         const qValueCount = t ? (t['rl_q_values']?.length ?? 0) : (brainData.qValues?.length ?? 0);
         const dreamInsightCount = t ? (t['dream_insights']?.length ?? 0) : (brainData.dreamInsights?.length ?? 0);
         const witnessChainLength = t ? (t['witness_chain']?.length ?? 0) : (brainData.witnessChain?.length ?? 0);
+        const tableCounts = t && typeof t === 'object' && !Array.isArray(t)
+            ? Object.fromEntries(Object.entries(t)
+                .filter((entry) => Array.isArray(entry[1]))
+                .map(([tableName, rows]) => [tableName, rows.length]))
+            : undefined;
         return {
             version: '3.0',
             format: 'rvf',
@@ -429,6 +509,7 @@ export function brainInfoFromRvf(rvfPath) {
                 qValueCount,
                 dreamInsightCount,
                 witnessChainLength,
+                ...(tableCounts ? { tableCounts } : {}),
             },
             domains: brainData.domains ?? [],
             checksum: sha256(brainJson),

package/dist/integrations/ruvector/brain-search.d.ts

@@ -4,7 +4,7 @@
  * Offline, read-only filtered search over a JSONL brain export directory.
  * Useful for exploring what a snapshot contains without importing it.
  *
- * Defaults to searching qe_patterns but can target any of the 25 exported
+ * Defaults to searching qe_patterns but can target any of the 31 exported
  * tables via the `table` option. Supports filters by domain, pattern_type,
  * date range, and a substring query that matches `name` + `description`.
  *

package/dist/integrations/ruvector/brain-search.js

@@ -4,7 +4,7 @@
  * Offline, read-only filtered search over a JSONL brain export directory.
  * Useful for exploring what a snapshot contains without importing it.
  *
- * Defaults to searching qe_patterns but can target any of the 25 exported
+ * Defaults to searching qe_patterns but can target any of the 31 exported
  * tables via the `table` option. Supports filters by domain, pattern_type,
  * date range, and a substring query that matches `name` + `description`.
  *

package/dist/integrations/ruvector/brain-shared.d.ts

@@ -7,7 +7,7 @@
  * This module owns:
  *   - Row type interfaces (PatternRow, QValueRow, DreamInsightRow, WitnessRow)
  *   - Merge result type and merge strategy type
- *   - TABLE_CONFIGS: data-driven list of all 25 exportable tables
+ *   - TABLE_CONFIGS: data-driven list of all 31 exportable tables
  *   - All 4 legacy merge functions + generic mergeGenericRow / mergeAppendOnlyRow
  *   - All SQL insert/update helpers
  *   - Utility functions (sha256, tableExists, queryAll, domainFilter, countRows)
@@ -94,6 +94,8 @@ export interface TableExportConfig {
     readonly blobColumns?: readonly string[];
     /** For tables with AUTOINCREMENT PK, specify dedup columns. */
     readonly dedupColumns?: readonly string[];
+    /** Preserve an `id` column when a deduplicated table does not use AUTOINCREMENT. */
+    readonly preserveId?: boolean;
 }
 /** PK column for tables with non-standard PK names. Default is 'id'. */
 export declare const PK_COLUMNS: Record<string, string>;
@@ -138,7 +140,7 @@ export declare function mergeGenericRow(db: Database.Database, tableName: string
  * Merge for append-only tables (AUTOINCREMENT PK).
  * Deduplicates by checking composite columns; inserts if no match found.
  */
-export declare function mergeAppendOnlyRow(db: Database.Database, tableName: string, row: Record<string, unknown>, dedupColumns: readonly string[]): MergeResult;
+export declare function mergeAppendOnlyRow(db: Database.Database, tableName: string, row: Record<string, unknown>, dedupColumns: readonly string[], preserveId?: boolean): MergeResult;
 export declare function mergePattern(db: Database.Database, pattern: PatternRow, strategy: MergeStrategy): MergeResult;
 export declare function mergeQValue(db: Database.Database, qv: QValueRow, strategy: MergeStrategy): MergeResult;
 export declare function mergeDreamInsight(db: Database.Database, insight: DreamInsightRow, strategy: MergeStrategy): MergeResult;