agentic-qe 3.15.12 → 3.15.14

package/dist/domains/visual-accessibility/services/accessibility-tester.js

@@ -3,9 +3,10 @@
  * Implements WCAG 2.2 compliance auditing with browser mode support
  *
  * This service supports multiple modes of operation:
- * 1. Heuristic Mode (default): URL-pattern-based analysis without browser automation
- * 2. Browser Mode (agent-browser): Real DOM inspection via unified browser client
- * 3. Browser Mode (Vibium): Real DOM inspection via Vibium MCP integration
+ * 1. Browser Mode (agent-browser): Real DOM inspection via unified browser client
+ * 2. Browser Mode (Vibium): Real DOM inspection via Vibium MCP integration
+ * 3. Not measured: no browser could load the page. The report says so
+ *    (`measured: false`) and carries no findings (#1145).
  *
  * Browser mode provides more accurate results by:
  * - Running actual axe-core accessibility checks in the browser
@@ -15,7 +16,8 @@
  * Browser Client Integration:
  * - Prefers agent-browser when available (supports snapshots and axe-core injection)
  * - Falls back to Vibium if agent-browser unavailable
- * - Uses heuristic mode when no browser tool is available
+ * - Reports "not measured" when no browser tool could audit the page; it never
+ *   guesses findings from the URL (#1145)
  *
  * @module domains/visual-accessibility/services/accessibility-tester
  */
@@ -28,7 +30,7 @@ import { toError } from '../../../shared/error-utils.js';
 import { getBrowserClientForUseCase, } from '../../../integrations/browser/index.js';
 // Extracted modules
 import { WCAG_CRITERIA, getErrorMessage, auditWithBrowserClient, auditWithVibium, auditElementWithVibium, checkContrastWithVibium, checkKeyboardWithVibium, } from './accessibility-tester-browser.js';
-import { initializeRules, filterRulesByLevel, runRule, validateCriterion, analyzeContrastForElements, generateKeyboardReportWithHeuristics, hashUrl, } from './accessibility-tester-heuristics.js';
+import { initializeRules, filterRulesByLevel, runSimulatedRule, hashUrl, } from './accessibility-tester-heuristics.js';
 const DEFAULT_CONFIG = {
     defaultWCAGLevel: 'AA',
     includeWarnings: true,
@@ -109,28 +111,29 @@ export class AccessibilityTesterService {
     async audit(url, options) {
         try {
             const wcagLevel = options?.wcagLevel || this.config.defaultWCAGLevel;
+            const failures = [];
             if (this.shouldUseBrowserMode()) {
                 const browserClient = await this.getBrowserClient();
                 if (browserClient) {
                     const browserResult = await auditWithBrowserClient(browserClient, url, wcagLevel, this.config.browserConfig, options);
-                    if (browserResult.success) {
-                        await this.storeReport(browserResult.value);
-                        return browserResult;
-                    }
+                    if (browserResult.success)
+                        return await this.measuredReport(browserResult.value);
                     const errorMsg = getErrorMessage(browserResult);
+                    failures.push(errorMsg);
                     logger.warn(`Browser client audit failed: ${errorMsg}`);
                 }
                 if (this.vibiumClient && isBrowserModeEnabled() && isAxeCoreEnabled()) {
                     const vibiumResult = await auditWithVibium(this.vibiumClient, url, wcagLevel, this.config.browserConfig, options);
-                    if (vibiumResult.success) {
-                        await this.storeReport(vibiumResult.value);
-                        return vibiumResult;
-                    }
+                    if (vibiumResult.success)
+                        return await this.measuredReport(vibiumResult.value);
                     const errorMsg = getErrorMessage(vibiumResult);
-                    logger.warn(`Vibium audit failed, falling back to heuristic mode: ${errorMsg}`);
+                    failures.push(errorMsg);
+                    logger.warn(`Vibium audit failed; the page is not measured: ${errorMsg}`);
                 }
             }
-            return this.auditWithHeuristics(url, wcagLevel, options);
+            if (this.config.simulationMode)
+                return this.auditSimulated(url, wcagLevel, options);
+            return ok(this.notMeasuredReport(url, wcagLevel, this.notMeasuredReason(failures)));
         }
         catch (error) {
             return err(toError(error));
@@ -139,12 +142,10 @@ export class AccessibilityTesterService {
     async auditElement(url, selector) {
         if (this.shouldUseBrowserMode() && this.vibiumClient) {
             const browserResult = await auditElementWithVibium(this.vibiumClient, url, selector, this.config.defaultWCAGLevel, this.config.browserConfig);
-            if (browserResult.success) {
-                await this.storeReport(browserResult.value);
-                return browserResult;
-            }
+            if (browserResult.success)
+                return await this.measuredReport(browserResult.value);
             const errorMsg = getErrorMessage(browserResult);
-            logger.warn(`Browser mode element audit failed, falling back to heuristic mode: ${errorMsg}`);
+            logger.warn(`Browser mode element audit failed, falling back to a page audit: ${errorMsg}`);
         }
         return this.audit(url, {
             excludeSelectors: [],
@@ -152,9 +153,38 @@ export class AccessibilityTesterService {
         });
     }
     // ============================================================================
-    // Heuristic Audit
+    // Unmeasured Results (#1145)
     // ============================================================================
-    async auditWithHeuristics(url, wcagLevel, options) {
+    async measuredReport(report) {
+        const measured = { ...report, measured: true };
+        await this.storeReport(measured);
+        return ok(measured);
+    }
+    notMeasuredReason(failures) {
+        if (failures.length > 0)
+            return `no browser could audit the page (${failures.join('; ')})`;
+        if (!this.config.useBrowserMode)
+            return 'browser mode is disabled, and only a browser run measures a page';
+        return 'no browser is available (install agent-browser or connect Vibium) to load the page';
+    }
+    /** A report that says nothing was measured: no violations, no passes, no verdict. */
+    notMeasuredReport(url, wcagLevel, reason) {
+        return {
+            url,
+            timestamp: new Date(),
+            violations: [],
+            passes: [],
+            incomplete: filterRulesByLevel(this.rules, wcagLevel).map((rule) => ({
+                id: rule.id, description: rule.description, reason: 'Not measured: see notMeasuredReason', nodes: [],
+            })),
+            score: -1,
+            wcagLevel,
+            measured: false,
+            notMeasuredReason: reason,
+        };
+    }
+    /** Simulation mode: synthetic results, labelled unmeasured and never stored. */
+    async auditSimulated(url, wcagLevel, options) {
         try {
             const includeWarnings = options?.includeWarnings ?? this.config.includeWarnings;
             const applicableRules = includeWarnings
@@ -164,7 +194,7 @@ export class AccessibilityTesterService {
             const passes = [];
             const incomplete = [];
             for (const rule of applicableRules) {
-                const result = runRule(rule, { url }, this.config.simulationMode, this.config.enableColorContrastCheck);
+                const result = runSimulatedRule(rule, { url });
                 if (result.nodes.length > 0) {
                     violations.push({
                         id: rule.id,
@@ -192,19 +222,18 @@ export class AccessibilityTesterService {
                     });
                 }
             }
-            const totalChecks = applicableRules.length;
-            const failedChecks = violations.length;
-            const score = Math.round(((totalChecks - failedChecks) / totalChecks) * 100);
             const report = {
                 url,
                 timestamp: new Date(),
                 violations,
                 passes,
                 incomplete,
-                score,
+                // The synthetic score is not a measurement: -1, like every unmeasured score
+                score: -1,
                 wcagLevel,
+                measured: false,
+                notMeasuredReason: 'simulation mode: synthetic results, the page was not loaded',
             };
-            await this.storeReport(report);
             return ok(report);
         }
         catch (error) {
@@ -216,25 +245,19 @@ export class AccessibilityTesterService {
     // ============================================================================
     async checkContrast(url) {
         try {
-            const cacheKey = `visual-accessibility:contrast:${hashUrl(url)}`;
+            // v2 (#1145): never serve a guessed result cached by an earlier version.
+            const cacheKey = `visual-accessibility:contrast:v2:${hashUrl(url)}`;
             const cached = await this.memory.get(cacheKey);
             if (cached)
                 return ok(cached);
-            let analyses;
-            if (this.shouldUseBrowserMode() && this.vibiumClient) {
-                const browserResult = await checkContrastWithVibium(this.vibiumClient, url, this.config.defaultWCAGLevel, this.config.browserConfig);
-                if (browserResult.success) {
-                    analyses = browserResult.value;
-                }
-                else {
-                    const errorMsg = getErrorMessage(browserResult);
-                    logger.warn(`Browser mode contrast check failed, falling back to heuristic mode: ${errorMsg}`);
-                    analyses = analyzeContrastForElements(url);
-                }
+            if (!this.shouldUseBrowserMode() || !this.vibiumClient) {
+                return err(notMeasuredError('Color contrast', url, this.notMeasuredReason([])));
             }
-            else {
-                analyses = analyzeContrastForElements(url);
+            const browserResult = await checkContrastWithVibium(this.vibiumClient, url, this.config.defaultWCAGLevel, this.config.browserConfig);
+            if (!browserResult.success) {
+                return err(notMeasuredError('Color contrast', url, this.notMeasuredReason([getErrorMessage(browserResult)])));
             }
+            const analyses = browserResult.value;
             await this.memory.set(cacheKey, analyses, { namespace: 'visual-accessibility', ttl: 3600 });
             return ok(analyses);
         }
@@ -247,25 +270,23 @@ export class AccessibilityTesterService {
     // ============================================================================
     async validateWCAGLevel(url, level) {
         try {
-            const levelOrder = { A: 1, AA: 2, AAA: 3 };
-            const targetLevel = levelOrder[level];
-            const applicableCriteria = Object.values(WCAG_CRITERIA).filter((c) => levelOrder[c.level] <= targetLevel);
-            const failedCriteria = [];
-            const passedCriteria = [];
-            const urlHash = hashUrl(url);
-            const hashNum = parseInt(urlHash, 36);
-            for (const criterion of applicableCriteria) {
-                const ruleResult = validateCriterion(criterion, hashNum);
-                if (ruleResult.passed) {
-                    passedCriteria.push(criterion);
-                }
-                else {
-                    failedCriteria.push(criterion);
-                }
+            const audit = await this.audit(url, { wcagLevel: level, includeWarnings: true });
+            if (!audit.success)
+                return err(audit.error);
+            if (audit.value.measured !== true) {
+                return err(notMeasuredError(`WCAG ${level} validation`, url, audit.value.notMeasuredReason ?? 'not audited'));
             }
-            const passed = failedCriteria.length === 0;
+            const levelOrder = { A: 1, AA: 2, AAA: 3 };
+            const applicableCriteria = Object.values(WCAG_CRITERIA).filter((c) => levelOrder[c.level] <= levelOrder[level]);
+            const violated = new Set(audit.value.violations.flatMap((v) => v.wcagCriteria.map((c) => c.id)));
+            const failedCriteria = applicableCriteria.filter((c) => violated.has(c.id));
+            const passedCriteria = applicableCriteria.filter((c) => !violated.has(c.id));
             const score = Math.round((passedCriteria.length / applicableCriteria.length) * 100);
-            return ok({ level, passed, failedCriteria, passedCriteria, score });
+            return ok({
+                level, passed: failedCriteria.length === 0, failedCriteria, passedCriteria, score, measured: true,
+                limitations: ['A passed criterion means no automated axe-core check failed for it; ' +
+                        'keyboard operation, focus order and similar criteria still need manual review.'],
+            });
         }
         catch (error) {
             return err(toError(error));
@@ -276,25 +297,20 @@ export class AccessibilityTesterService {
     // ============================================================================
     async checkKeyboardNavigation(url) {
         try {
-            const cacheKey = `visual-accessibility:keyboard:${hashUrl(url)}`;
+            const cacheKey = `visual-accessibility:keyboard:v2:${hashUrl(url)}`;
             const cached = await this.memory.get(cacheKey);
             if (cached)
                 return ok(cached);
-            let report;
-            if (this.shouldUseBrowserMode() && this.config.enableKeyboardCheck && this.vibiumClient) {
-                const browserResult = await checkKeyboardWithVibium(this.vibiumClient, url, this.config.defaultWCAGLevel, this.config.browserConfig);
-                if (browserResult.success) {
-                    report = browserResult.value;
-                }
-                else {
-                    const errorMsg = getErrorMessage(browserResult);
-                    logger.warn(`Browser mode keyboard check failed, falling back to heuristic mode: ${errorMsg}`);
-                    report = generateKeyboardReportWithHeuristics(url);
-                }
+            if (!this.shouldUseBrowserMode() || !this.config.enableKeyboardCheck || !this.vibiumClient) {
+                const reason = this.config.enableKeyboardCheck
+                    ? this.notMeasuredReason([]) : 'the keyboard check is disabled';
+                return err(notMeasuredError('Keyboard navigation', url, reason));
             }
-            else {
-                report = generateKeyboardReportWithHeuristics(url);
+            const browserResult = await checkKeyboardWithVibium(this.vibiumClient, url, this.config.defaultWCAGLevel, this.config.browserConfig);
+            if (!browserResult.success) {
+                return err(notMeasuredError('Keyboard navigation', url, this.notMeasuredReason([getErrorMessage(browserResult)])));
             }
+            const report = browserResult.value;
             await this.memory.set(cacheKey, report, { namespace: 'visual-accessibility', ttl: 3600 });
             return ok(report);
         }
@@ -322,6 +338,9 @@ export class AccessibilityTesterService {
             if (!wcagResult.success) {
                 return err(new Error(`WCAG audit failed: ${wcagResult.error.message}`));
             }
+            if (wcagResult.value.measured !== true) {
+                return err(notMeasuredError('EU compliance', url, wcagResult.value.notMeasuredReason ?? 'not audited'));
+            }
             const euResult = await this.euComplianceService.validateCompliance(wcagResult.value, options);
             return euResult;
         }
@@ -348,4 +367,8 @@ export class AccessibilityTesterService {
         }
     }
 }
+/** #1145: an unmeasured check is an error with its reason, never an empty pass. */
+function notMeasuredError(check, url, reason) {
+    return new Error(`${check} NOT MEASURED for ${url}: ${reason}. No findings or verdict were produced.`);
+}
 //# sourceMappingURL=accessibility-tester.js.map

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

@@ -394,6 +394,7 @@ console.log(\`\\x1b[1m\\x1b[35m▊ Agentic QE v3\\x1b[0m\${branchStr}\${patStr}\
  *   node brain-checkpoint.cjs verify   # Verify aqe.rvf exists (session-start)
  */
 const { execFileSync } = require('child_process');
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
@@ -402,6 +403,11 @@ 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;
+// #1238: after a too-large export, skip the Stop-hook export for a while
+// unless a newer aqe.rvf shows that an export has succeeded since.
+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;
 // 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() {
@@ -422,32 +428,110 @@ function aqeInvocation() {
 
 function log(msg) { process.stderr.write('[brain-checkpoint] ' + msg + '\\n'); }
 
+function activeSkip() {
+  let st; try { st = fs.lstatSync(SKIP_PATH); } catch { return null; }
+  let skip = null;
+  if (st.isFile()) { try { skip = JSON.parse(fs.readFileSync(SKIP_PATH, 'utf8')); } catch { /* unreadable */ } }
+  const at = skip ? Date.parse(skip.at) : NaN;
+  let rvfMtime = 0; try { rvfMtime = fs.lstatSync(RVF_PATH).mtimeMs; } catch { /* absent */ }
+  if (!Number.isFinite(at) || Date.now() >= at + TOO_LARGE_RETRY_HOURS * 3600000 || rvfMtime > at) {
+    try { fs.unlinkSync(SKIP_PATH); } catch { /* best-effort */ }
+    return null;
+  }
+  return skip;
+}
+
+function writeSkip(reason) {
+  const at = new Date();
+  const skip = { reason, at: at.toISOString(), retryAfter: new Date(at.getTime() + TOO_LARGE_RETRY_HOURS * 3600000).toISOString() };
+  // 'wx' after unlink: never write through a planted symlink (#970).
+  try { try { fs.unlinkSync(SKIP_PATH); } catch { /* absent */ } fs.writeFileSync(SKIP_PATH, JSON.stringify(skip) + '\\n', { flag: 'wx' }); } catch { /* best-effort */ }
+  return skip;
+}
+
+// Export to a temp store next to aqe.rvf; rename it over aqe.rvf only on
+// success, so a failed, too-large or killed export keeps the last checkpoint.
+const RVF_SIDECARS = ['.idmap.json', '.manifest.json'];
+const TMP_PREFIX = path.basename(RVF_PATH) + '.tmp-';
+function removeEntry(p) { try { fs.unlinkSync(p); } catch (e) { if (!e || e.code !== 'ENOENT') throw e; } }
+function isPidAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return !!e && e.code === 'EPERM'; } }
+function removeByPrefix(prefix, keep) {
+  let entries = []; try { entries = fs.readdirSync(AQE_DIR); } catch { return; }
+  for (const entry of entries) {
+    if (!entry.startsWith(prefix) || (keep && keep(entry))) continue;
+    try { removeEntry(path.join(AQE_DIR, entry)); } catch { /* best-effort */ }
+  }
+}
+function sweepStaleTmp() {
+  removeByPrefix(TMP_PREFIX, (entry) => {
+    const pid = Number.parseInt(entry.slice(TMP_PREFIX.length).split('-')[0], 10);
+    return !Number.isInteger(pid) || pid <= 0 || isPidAlive(pid);
+  });
+}
+function lexists(p) { try { fs.lstatSync(p); return true; } catch { return false; } }
+// rename() replaces a planted symlink without writing through it (#970). The
+// store goes first: if that fails nothing changed. If a sidecar rename fails
+// afterwards, the stale sidecar is removed, so the new store is never read
+// with the previous export's idmap.
+function promote(tmp) {
+  fs.renameSync(tmp, RVF_PATH);
+  for (const suffix of RVF_SIDECARS) {
+    try {
+      if (lexists(tmp + suffix)) fs.renameSync(tmp + suffix, RVF_PATH + suffix);
+      else removeEntry(RVF_PATH + suffix);
+    } catch { try { removeEntry(RVF_PATH + suffix); } catch { /* best-effort */ } }
+  }
+}
+
 function exportBrain() {
   if (!fs.existsSync(DB_PATH)) { log('No memory.db, skipping'); return { exported: false }; }
   const aqe = aqeInvocation();
   if (!aqe.cmd) { log('Export skipped: ' + aqe.reason); return { exported: false, reason: aqe.reason }; }
-  // Never write through a committed symlink: .agentic-qe must be a real dir, and
-  // unlink (not existsSync) drops a planted aqe.rvf link, even a dangling one.
+  // 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 }; }
-  for (const f of [RVF_PATH, RVF_PATH + '.idmap.json']) { try { fs.unlinkSync(f); } catch { /* absent */ } }
+  const skip = activeSkip();
+  if (skip) {
+    log('Export skipped until ' + skip.retryAfter + ': ' + skip.reason);
+    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 result = execFileSync(
-      aqe.cmd, [...aqe.args, 'brain', 'export', '-o', RVF_PATH, '--format', 'rvf'],
-      { timeout: 60000, encoding: 'utf-8', windowsHide: true }
+      aqe.cmd, [...aqe.args, 'brain', 'export', '-o', tmp, '--format', 'rvf'],
+      { timeout: 60000, encoding: 'utf-8', windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] }
     );
+    // A zero exit without a store is a failure, not an empty checkpoint.
+    if (!lexists(tmp)) throw new Error('brain export exited 0 but wrote no store');
+    promote(tmp);
     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) };
   } catch (e) {
-    log('Export failed: ' + e.message);
+    const tooLarge = (String(e.stderr || '') + String(e.stdout || '')).match(/RVF_KERNEL_TOO_LARGE:[^\\n]*/);
+    if (tooLarge) {
+      const skip = writeSkip(tooLarge[0].trim());
+      log('Export failed: ' + skip.reason);
+      log('Skipping the checkpoint export until ' + skip.retryAfter + ' (AQE_BRAIN_CHECKPOINT_RETRY_HOURS sets the wait).');
+      return { exported: false, tooLarge: true, reason: skip.reason, retryAfter: skip.retryAfter };
+    }
+    log('Export failed: ' + e.message + ' (previous aqe.rvf kept)');
     return { exported: false, reason: e.message };
+  } finally {
+    removeByPrefix(path.basename(tmp));
   }
 }
 
 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');
     return { valid: false, reason: 'missing' };
   }

package/dist/integrations/embeddings/index/HNSWIndex.js

@@ -10,6 +10,10 @@
  * @module integrations/embeddings/index/HNSWIndex
  */
 import { createRequire } from 'node:module';
+// Static import so the bundlers inline the adapter. A runtime
+// require('../../../kernel/hnsw-adapter.js') resolves against the bundle
+// file instead and fails, which silently capped the index at 10,000 (#1237).
+import { HnswAdapter } from '../../../kernel/hnsw-adapter.js';
 const require = createRequire(import.meta.url);
 let cachedHnswlibCtor = null;
 function loadHnswlibConstructor() {
@@ -70,8 +74,6 @@ export class HNSWEmbeddingIndex {
         // ADR-071: Route through unified HnswAdapter when flag is enabled
         if (this.useUnified && this.unifiedAdapters) {
             try {
-                // eslint-disable-next-line @typescript-eslint/no-require-imports
-                const { HnswAdapter } = require('../../../kernel/hnsw-adapter.js');
                 const adapter = new HnswAdapter(`embedding-${namespace}`, {
                     dimensions: this.config.dimension,
                     M: this.config.M,
@@ -84,8 +86,10 @@ export class HNSWEmbeddingIndex {
                 this.nextId.set(namespace, 0);
                 return;
             }
-            catch {
-                // Fall through to hnswlib-node
+            catch (error) {
+                // Fall through to hnswlib-node, which holds at most 10,000 entries.
+                console.warn(`[HNSWEmbeddingIndex] Unified HNSW adapter unavailable for '${namespace}', ` +
+                    `using the legacy index (max 10000 entries): ${error instanceof Error ? error.message : String(error)}`);
             }
         }
         // Legacy path: hnswlib-node

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

@@ -19,6 +19,8 @@ export interface RvfBrainManifest {
         readonly totalRecords?: number;
         /** Per-table row counts used by the recovery-mirror richness guard. */
         readonly tableCounts?: Readonly<Record<string, number>>;
+        /** Regenerable cache rows left out of the kernel, per table (#1238). */
+        readonly skippedCacheRows?: Readonly<Record<string, number>>;
     };
     readonly domains: readonly string[];
     readonly checksum: string;
@@ -48,6 +50,8 @@ export interface RvfBrainExportOptions {
     readonly signerKeyId?: string;
     /** Explicit operator acknowledgement that a richer existing mirror may be replaced. */
     readonly allowOverwriteRicher?: boolean;
+    /** Kernel size ceiling in bytes. Defaults to RVF_MAX_KERNEL_BYTES; lowered only by tests. */
+    readonly maxKernelBytes?: number;
 }
 export interface RvfBrainImportOptions {
     readonly mergeStrategy: MergeStrategy;
@@ -59,6 +63,27 @@ export interface RvfBrainImportResult {
     readonly conflicts: number;
     readonly embeddingsRestored: number;
 }
+/**
+ * Largest kernel image @ruvector/rvf-node accepts. One byte more and
+ * `embedKernel` fails with a misleading `RVF error 0x0303: FsyncFailed`
+ * (#1238; measured 134,217,728 B ok, 134,217,729 B fails).
+ */
+export declare const RVF_MAX_KERNEL_BYTES: number;
+/**
+ * Vector ids written by the code-intelligence domain (KG nodes, semantic code
+ * 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:";
+/** Thrown before any native call when the kernel would exceed the RVF limit. */
+export declare class RvfKernelTooLargeError extends Error {
+    readonly kernelBytes: number;
+    readonly limitBytes: number;
+    readonly tableBytes: Readonly<Record<string, number>>;
+    readonly complete: boolean;
+    readonly code = "RVF_KERNEL_TOO_LARGE";
+    constructor(kernelBytes: number, limitBytes: number, tableBytes: Readonly<Record<string, number>>, complete: boolean);
+}
 /** Export brain state to a single `.rvf` file with vector embeddings + kernel. */
 export declare function exportBrainToRvf(db: Database.Database, options: RvfBrainExportOptions, sourceDbLabel?: string): RvfBrainManifest;
 /** Import brain state from a `.rvf` file into a SQLite database. */