agentic-qe 3.15.15 → 3.15.16

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

@@ -0,0 +1,137 @@
+/**
+ * Agentic QE v3 - Contrast and keyboard checks through the unified browser client (#1228)
+ *
+ * The page audit runs through agent-browser (the default browser for audits);
+ * these checks use the same client, so they are measured whenever the audit is.
+ * Each runs axe-core in the loaded page and reports only what it returned.
+ */
+import { ok, err } from '../../../shared/types/index.js';
+import { toError } from '../../../shared/error-utils.js';
+import { safeJsonParse } from '../../../shared/safe-json.js';
+import { AXE_LOADER_JS, KEYBOARD_NOT_MEASURED, getElementType, mapKeyboardIssueType } from './accessibility-tester-browser.js';
+import { AXE_CONTRAST_DATA_JS, contrastValues, toContrastAnalysis } from './accessibility-contrast.js';
+/** axe-core rules that concern keyboard operation and focus order. */
+const KEYBOARD_RULES = ['bypass', 'tabindex', 'scrollable-region-focusable', 'accesskeys', 'frame-focusable-content'];
+/** Browser-side helper that builds a CSS selector for an element. */
+const CSS_PATH_JS = `function (el) {
+  if (el.id) return '#' + CSS.escape(el.id);
+  var parts = [];
+  while (el && el.nodeType === 1 && el !== document.documentElement) {
+    var part = el.tagName.toLowerCase();
+    var parent = el.parentElement;
+    if (parent) {
+      var same = Array.prototype.filter.call(parent.children, function (c) { return c.tagName === el.tagName; });
+      if (same.length > 1) part += ':nth-of-type(' + (same.indexOf(el) + 1) + ')';
+    }
+    parts.unshift(part);
+    el = parent;
+  }
+  return parts.join(' > ');
+}`;
+/**
+ * Check colour contrast with axe-core's contrast rule. Lists every element the
+ * rule checked, failing and passing, with the colours and ratio it measured.
+ */
+export async function checkContrastWithBrowserClient(client, url, wcagLevel, browserConfig) {
+    const rule = wcagLevel === 'AAA' ? 'color-contrast-enhanced' : 'color-contrast';
+    const script = `
+    (async function() {
+      ${AXE_LOADER_JS}
+      const contrastOf = ${AXE_CONTRAST_DATA_JS};
+      const results = await axe.run(document, { runOnly: { type: 'rule', values: ['${rule}'] } });
+      const nodesOf = (rules) => rules.flatMap(r => r.nodes.map(n => ({
+        selector: n.target.join(' > '),
+        failureSummary: n.failureSummary,
+        contrast: contrastOf(n)
+      })));
+      return JSON.stringify({ violations: nodesOf(results.violations), passes: nodesOf(results.passes) });
+    })();
+  `;
+    const result = await withLoadedPage(client, url, browserConfig, () => evaluateJson(client, script, 'contrast check'));
+    if (!result.success)
+        return result;
+    return ok([
+        ...result.value.violations.map((n) => toContrastAnalysis(n.selector, contrastValues(n.contrast, n.failureSummary), false, wcagLevel)),
+        ...result.value.passes.map((n) => toContrastAnalysis(n.selector, contrastValues(n.contrast, n.failureSummary), true, wcagLevel)),
+    ]);
+}
+/**
+ * Check keyboard navigation: the focusable elements in document order and
+ * axe-core's keyboard rules. Focus indicators and traps are not measured.
+ */
+export async function checkKeyboardWithBrowserClient(client, url, browserConfig) {
+    const script = `
+    (async function() {
+      ${AXE_LOADER_JS}
+      const cssPath = ${CSS_PATH_JS};
+      const candidates = document.querySelectorAll('a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])');
+      const focusable = Array.from(candidates)
+        .filter(el => !el.disabled && el.getClientRects().length > 0)
+        .map(el => ({ selector: cssPath(el), tagName: el.tagName }));
+      const results = await axe.run(document, { runOnly: { type: 'rule', values: ${JSON.stringify(KEYBOARD_RULES)} } });
+      return JSON.stringify({
+        focusable,
+        violations: results.violations.map(v => ({
+          id: v.id,
+          nodes: v.nodes.map(n => ({ selector: n.target.join(' > '), failureSummary: n.failureSummary }))
+        }))
+      });
+    })();
+  `;
+    const result = await withLoadedPage(client, url, browserConfig, () => evaluateJson(client, script, 'keyboard check'));
+    if (!result.success)
+        return result;
+    const tabOrder = result.value.focusable.map((el, index) => ({
+        index,
+        selector: el.selector,
+        elementType: getElementType(el.tagName),
+        hasVisibleFocus: null,
+    }));
+    const issues = result.value.violations.flatMap((v) => v.nodes.map((n) => ({
+        type: mapKeyboardIssueType(v.id),
+        selector: n.selector,
+        description: n.failureSummary ?? v.id,
+    })));
+    return ok({
+        url,
+        focusableElements: tabOrder.length,
+        tabOrder,
+        issues,
+        traps: [],
+        notMeasured: [...KEYBOARD_NOT_MEASURED],
+    });
+}
+async function withLoadedPage(client, url, browserConfig, run) {
+    try {
+        const launchResult = await client.launch({ headless: browserConfig.headless });
+        if (!launchResult.success) {
+            return err(new Error(`Failed to launch browser: ${launchResult.error?.message ?? 'Unknown error'}`));
+        }
+        try {
+            const navResult = await client.navigate(url);
+            if (!navResult.success) {
+                return err(new Error(`Failed to navigate to ${url}: ${navResult.error?.message ?? 'Unknown error'}`));
+            }
+            return await run();
+        }
+        finally {
+            await client.quit();
+        }
+    }
+    catch (error) {
+        return err(toError(error));
+    }
+}
+async function evaluateJson(client, script, label) {
+    const evalResult = await client.evaluate(script);
+    if (!evalResult.success) {
+        return err(new Error(`Failed to run the ${label}: ${evalResult.error?.message ?? 'Unknown error'}`));
+    }
+    try {
+        return ok(safeJsonParse(evalResult.value));
+    }
+    catch (parseError) {
+        return err(new Error(`Failed to parse the ${label} results: ${parseError}`));
+    }
+}
+//# sourceMappingURL=accessibility-tester-checks.js.map

package/dist/domains/visual-accessibility/services/accessibility-tester.d.ts

@@ -65,6 +65,11 @@ export declare class AccessibilityTesterService implements IAccessibilityAuditin
     /** Simulation mode: synthetic results, labelled unmeasured and never stored. */
     private auditSimulated;
     checkContrast(url: string): Promise<Result<ContrastAnalysis[], Error>>;
+    /**
+     * Run a check with the browser client the page audit uses (agent-browser),
+     * then Vibium (#1228). The error is the not-measured reason when neither ran.
+     */
+    private runBrowserCheck;
     validateWCAGLevel(url: string, level: 'A' | 'AA' | 'AAA'): Promise<Result<WCAGValidationResult, Error>>;
     checkKeyboardNavigation(url: string): Promise<Result<KeyboardNavigationReport, Error>>;
     private storeReport;

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

@@ -30,6 +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 { checkContrastWithBrowserClient, checkKeyboardWithBrowserClient, } from './accessibility-tester-checks.js';
 import { initializeRules, filterRulesByLevel, runSimulatedRule, hashUrl, } from './accessibility-tester-heuristics.js';
 const DEFAULT_CONFIG = {
     defaultWCAGLevel: 'AA',
@@ -245,26 +246,47 @@ export class AccessibilityTesterService {
     // ============================================================================
     async checkContrast(url) {
         try {
-            // v2 (#1145): never serve a guessed result cached by an earlier version.
-            const cacheKey = `visual-accessibility:contrast:v2:${hashUrl(url)}`;
+            // v3 (#1145, #1228): never serve a guessed result cached by an earlier version.
+            const cacheKey = `visual-accessibility:contrast:v3:${hashUrl(url)}`;
             const cached = await this.memory.get(cacheKey);
             if (cached)
                 return ok(cached);
-            if (!this.shouldUseBrowserMode() || !this.vibiumClient) {
-                return err(notMeasuredError('Color contrast', url, this.notMeasuredReason([])));
-            }
-            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);
+            const level = this.config.defaultWCAGLevel;
+            const result = await this.runBrowserCheck((client) => checkContrastWithBrowserClient(client, url, level, this.config.browserConfig), (vibium) => checkContrastWithVibium(vibium, url, level, this.config.browserConfig));
+            if (!result.success)
+                return err(notMeasuredError('Color contrast', url, result.error.message));
+            await this.memory.set(cacheKey, result.value, { namespace: 'visual-accessibility', ttl: 3600 });
+            return ok(result.value);
         }
         catch (error) {
             return err(toError(error));
         }
     }
+    /**
+     * Run a check with the browser client the page audit uses (agent-browser),
+     * then Vibium (#1228). The error is the not-measured reason when neither ran.
+     */
+    async runBrowserCheck(withClient, withVibium) {
+        const failures = [];
+        if (this.shouldUseBrowserMode()) {
+            const browserClient = await this.getBrowserClient();
+            if (browserClient) {
+                const result = await withClient(browserClient);
+                if (result.success)
+                    return result;
+                failures.push(getErrorMessage(result));
+                logger.warn(`Browser client check failed: ${getErrorMessage(result)}`);
+            }
+            if (this.vibiumClient) {
+                const result = await withVibium(this.vibiumClient);
+                if (result.success)
+                    return result;
+                failures.push(getErrorMessage(result));
+                logger.warn(`Vibium check failed: ${getErrorMessage(result)}`);
+            }
+        }
+        return err(new Error(this.notMeasuredReason(failures)));
+    }
     // ============================================================================
     // WCAG Validation
     // ============================================================================
@@ -297,22 +319,19 @@ export class AccessibilityTesterService {
     // ============================================================================
     async checkKeyboardNavigation(url) {
         try {
-            const cacheKey = `visual-accessibility:keyboard:v2:${hashUrl(url)}`;
+            // v3 (#1228): earlier versions cached hasVisibleFocus: true without measuring it.
+            const cacheKey = `visual-accessibility:keyboard:v3:${hashUrl(url)}`;
             const cached = await this.memory.get(cacheKey);
             if (cached)
                 return ok(cached);
-            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));
+            if (!this.config.enableKeyboardCheck) {
+                return err(notMeasuredError('Keyboard navigation', url, 'the keyboard check is disabled'));
             }
-            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);
+            const result = await this.runBrowserCheck((client) => checkKeyboardWithBrowserClient(client, url, this.config.browserConfig), (vibium) => checkKeyboardWithVibium(vibium, url, this.config.defaultWCAGLevel, this.config.browserConfig));
+            if (!result.success)
+                return err(notMeasuredError('Keyboard navigation', url, result.error.message));
+            await this.memory.set(cacheKey, result.value, { namespace: 'visual-accessibility', ttl: 3600 });
+            return ok(result.value);
         }
         catch (error) {
             return err(toError(error));

package/dist/domains/visual-accessibility/services/browser-swarm-coordinator.d.ts

@@ -178,9 +178,8 @@ export declare class BrowserSwarmCoordinator {
     /**
      * Run accessibility audit across all viewports
      *
-     * Navigates to the URL and runs accessibility audits in each viewport.
-     * Note: This is a placeholder implementation. Real accessibility auditing
-     * would require integration with axe-core or similar tools.
+     * Navigates to the URL and runs axe-core in each viewport. A viewport whose
+     * audit did not run is listed under failures, never as a clean report (#1228).
      *
      * @param url - URL to audit
      * @returns Accessibility audit results by viewport

package/dist/domains/visual-accessibility/services/browser-swarm-coordinator.js

@@ -24,6 +24,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { ok, err } from '../../../shared/types/index.js';
 import { FilePath } from '../../../shared/value-objects/index.js';
 import { toError } from '../../../shared/error-utils.js';
+import { runAxeCore, mapAxeResultToReport } from './accessibility-tester-browser.js';
 import { getBrowserClientForUseCase, } from '../../../integrations/browser/index.js';
 /**
  * Standard viewport configurations for common devices
@@ -304,9 +305,8 @@ export class BrowserSwarmCoordinator {
     /**
      * Run accessibility audit across all viewports
      *
-     * Navigates to the URL and runs accessibility audits in each viewport.
-     * Note: This is a placeholder implementation. Real accessibility auditing
-     * would require integration with axe-core or similar tools.
+     * Navigates to the URL and runs axe-core in each viewport. A viewport whose
+     * audit did not run is listed under failures, never as a clean report (#1228).
      *
      * @param url - URL to audit
      * @returns Accessibility audit results by viewport
@@ -326,17 +326,11 @@ export class BrowserSwarmCoordinator {
                 if (this.isAgentBrowserClient(session.client)) {
                     await session.client.setViewport(viewport.width, viewport.height);
                 }
-                // TODO: Integrate with axe-core or similar accessibility testing tool
-                // For now, return a placeholder report
-                const report = {
-                    url,
-                    timestamp: new Date(),
-                    violations: [],
-                    passes: [],
-                    incomplete: [],
-                    score: 100,
-                    wcagLevel: 'AA',
-                };
+                const axeResult = await runAxeCore(session.client, 'AA');
+                if (!axeResult.success) {
+                    throw new Error(`Accessibility NOT MEASURED in this viewport: ${axeResult.error.message}`);
+                }
+                const report = { ...mapAxeResultToReport(url, axeResult.value, 'AA'), measured: true };
                 return report;
             });
             // Process results

package/dist/feedback/coverage-learner.js

@@ -171,12 +171,15 @@ export class CoverageLearner {
     /**
      * Persist a coverage session to the database
      */
-    persistSession(session) {
+    async persistSession(session) {
         if (!this.db)
             return;
         try {
-            const database = this.db.getDatabase();
-            database.prepare(`
+            const memory = this.db;
+            const database = memory.getDatabase();
+            // #1283: queued, so a locked memory.db does not freeze the MCP server's
+            // event loop while the tool call that recorded this coverage session waits.
+            await memory.writeWhenUnlocked(() => database.prepare(`
         INSERT OR REPLACE INTO coverage_sessions (
           id, target_path, agent_id, technique,
           before_lines, before_branches, before_functions,
@@ -184,10 +187,10 @@ export class CoverageLearner {
           tests_generated, tests_passed, gaps_json,
           duration_ms, started_at, completed_at, context_json
         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(session.id, session.targetPath, session.agentId, session.technique, session.beforeCoverage.lines, session.beforeCoverage.branches, session.beforeCoverage.functions, session.afterCoverage.lines, session.afterCoverage.branches, session.afterCoverage.functions, session.testsGenerated, session.testsPassed, JSON.stringify(session.gapsTargeted), session.durationMs, session.startedAt instanceof Date ? session.startedAt.toISOString() : session.startedAt, session.completedAt instanceof Date ? session.completedAt.toISOString() : session.completedAt, session.context ? JSON.stringify(session.context) : null);
+      `).run(session.id, session.targetPath, session.agentId, session.technique, session.beforeCoverage.lines, session.beforeCoverage.branches, session.beforeCoverage.functions, session.afterCoverage.lines, session.afterCoverage.branches, session.afterCoverage.functions, session.testsGenerated, session.testsPassed, JSON.stringify(session.gapsTargeted), session.durationMs, session.startedAt instanceof Date ? session.startedAt.toISOString() : session.startedAt, session.completedAt instanceof Date ? session.completedAt.toISOString() : session.completedAt, session.context ? JSON.stringify(session.context) : null));
             this.persistCount++;
             if (this.persistCount % CoverageLearner.RETENTION_CLEANUP_INTERVAL === 0) {
-                this.enforceRetention(database);
+                await this.enforceRetention(memory);
             }
         }
         catch (error) {
@@ -197,14 +200,15 @@ export class CoverageLearner {
     /**
      * Delete oldest rows beyond retention limit
      */
-    enforceRetention(database) {
+    async enforceRetention(memory) {
         try {
+            const database = memory.getDatabase();
             const maxRows = this.config.maxOutcomesInMemory * 2;
-            database.prepare(`
+            await memory.writeWhenUnlocked(() => database.prepare(`
         DELETE FROM coverage_sessions WHERE id NOT IN (
           SELECT id FROM coverage_sessions ORDER BY created_at DESC LIMIT ?
         )
-      `).run(maxRows);
+      `).run(maxRows));
         }
         catch (error) {
             console.warn('[CoverageLearner] Retention cleanup failed:', toErrorMessage(error));
@@ -216,7 +220,7 @@ export class CoverageLearner {
     async learnFromSession(session) {
         // Store session
         this.sessionStore.add(session);
-        this.persistSession(session);
+        await this.persistSession(session);
         // Calculate improvement
         const improvement = this.calculateOverallImprovement(session);
         // Only learn from significant improvements

package/dist/feedback/test-outcome-tracker.js

@@ -142,12 +142,15 @@ export class TestOutcomeTracker {
     /**
      * Persist a single outcome to DB (write-through)
      */
-    persistOutcome(outcome) {
+    async persistOutcome(outcome) {
         if (!this.db)
             return;
         try {
-            const database = this.db.getDatabase();
-            database.prepare(`
+            const memory = this.db;
+            const database = memory.getDatabase();
+            // #1283: queued, so a locked memory.db does not freeze the MCP server's
+            // event loop while the tool call that recorded this test outcome waits.
+            await memory.writeWhenUnlocked(() => database.prepare(`
         INSERT OR REPLACE INTO test_outcomes (
           id, test_id, test_name, generated_by, pattern_id,
           framework, language, domain, passed, error_message,
@@ -156,10 +159,10 @@ export class TestOutcomeTracker {
           maintainability_score, complexity, lines_of_code,
           assertion_count, file_path, source_file_path, metadata_json
         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(outcome.id, outcome.testId, outcome.testName, outcome.generatedBy, outcome.patternId || null, outcome.framework, outcome.language, outcome.domain, outcome.passed ? 1 : 0, outcome.errorMessage || null, outcome.coverage.lines, outcome.coverage.branches, outcome.coverage.functions, outcome.mutationScore ?? null, outcome.executionTimeMs, outcome.flaky ? 1 : 0, outcome.flakinessScore ?? null, outcome.maintainabilityScore, outcome.complexity ?? null, outcome.linesOfCode ?? null, outcome.assertionCount ?? null, outcome.filePath || null, outcome.sourceFilePath || null, outcome.metadata ? JSON.stringify(outcome.metadata) : null);
+      `).run(outcome.id, outcome.testId, outcome.testName, outcome.generatedBy, outcome.patternId || null, outcome.framework, outcome.language, outcome.domain, outcome.passed ? 1 : 0, outcome.errorMessage || null, outcome.coverage.lines, outcome.coverage.branches, outcome.coverage.functions, outcome.mutationScore ?? null, outcome.executionTimeMs, outcome.flaky ? 1 : 0, outcome.flakinessScore ?? null, outcome.maintainabilityScore, outcome.complexity ?? null, outcome.linesOfCode ?? null, outcome.assertionCount ?? null, outcome.filePath || null, outcome.sourceFilePath || null, outcome.metadata ? JSON.stringify(outcome.metadata) : null));
             this.persistCount++;
             if (this.persistCount % TestOutcomeTracker.RETENTION_CLEANUP_INTERVAL === 0) {
-                this.enforceRetention(database);
+                await this.enforceRetention(memory);
             }
         }
         catch (error) {
@@ -169,14 +172,15 @@ export class TestOutcomeTracker {
     /**
      * Delete oldest rows beyond retention limit
      */
-    enforceRetention(database) {
+    async enforceRetention(memory) {
         try {
+            const database = memory.getDatabase();
             const maxRows = this.config.maxOutcomesInMemory * 2; // Keep 2x in-memory limit in DB
-            database.prepare(`
+            await memory.writeWhenUnlocked(() => database.prepare(`
         DELETE FROM test_outcomes WHERE id NOT IN (
           SELECT id FROM test_outcomes ORDER BY created_at DESC LIMIT ?
         )
-      `).run(maxRows);
+      `).run(maxRows));
         }
         catch (error) {
             console.warn('[TestOutcomeTracker] Retention cleanup failed:', toErrorMessage(error));
@@ -188,7 +192,7 @@ export class TestOutcomeTracker {
     async track(outcome) {
         // 1. Store outcome
         this.store.add(outcome);
-        this.persistOutcome(outcome);
+        await this.persistOutcome(outcome);
         // 2. Update pattern metrics if pattern was used
         if (outcome.patternId) {
             this.updatePatternMetrics(outcome);

package/dist/governance/witness-chain.d.ts

@@ -245,6 +245,11 @@ export declare class WitnessChain {
 export interface IWitnessChainPersistence {
     /** Store a receipt in SQLite. Called after each appendWitness(). */
     insertReceipt(receipt: WitnessReceipt): void;
+    /**
+     * Store a receipt without blocking on a locked database (#1283). When
+     * present, appendWitness() uses it instead of insertReceipt().
+     */
+    insertReceiptWhenUnlocked?(receipt: WitnessReceipt): Promise<void>;
     /** Load all receipts from SQLite, ordered by chainIndex. */
     loadAllReceipts(): WitnessReceipt[];
     /** Get the total count of persisted receipts. */

package/dist/governance/witness-chain.js

@@ -18,6 +18,7 @@
 import { createHash, randomUUID } from 'crypto';
 import { LoggerFactory } from '../logging/index.js';
 import { getRuVectorFeatureFlags } from '../integrations/ruvector/feature-flags.js';
+import { writeWhenUnlockedOn } from '../shared/sqlite-write-queue.js';
 const logger = LoggerFactory.create('witness-chain');
 // ============================================================================
 // SPRT Accumulator
@@ -387,14 +388,25 @@ export class PersistentWitnessChain extends WitnessChain {
      */
     appendWitness(decision) {
         const receipt = super.appendWitness(decision);
-        try {
-            this.persistence.insertReceipt(receipt);
-        }
-        catch (err) {
+        const warn = (err) => {
             logger.warn('Failed to persist witness receipt to SQLite', {
                 chainIndex: receipt.chainIndex,
                 error: err instanceof Error ? err.message : String(err),
             });
+        };
+        try {
+            // #1283: queue the insert when the backend can, so a locked memory.db
+            // does not freeze the MCP server's event loop. The receipt is already in
+            // the in-memory chain, which is what callers read.
+            if (this.persistence.insertReceiptWhenUnlocked) {
+                this.persistence.insertReceiptWhenUnlocked(receipt).catch(warn);
+            }
+            else {
+                this.persistence.insertReceipt(receipt);
+            }
+        }
+        catch (err) {
+            warn(err);
         }
         return receipt;
     }
@@ -440,9 +452,13 @@ export function createWitnessChainSQLitePersistence(db) {
     const countStmt = db.prepare(`
     SELECT COUNT(*) as cnt FROM witness_chain_receipts
   `);
+    const insertReceipt = (receipt) => {
+        insertStmt.run(receipt.id, receipt.chainIndex, receipt.timestamp, receipt.previousHash, receipt.hash, receipt.decision.type, receipt.decision.decision, JSON.stringify(receipt.decision.context), receipt.decision.evidence ?? null);
+    };
     return {
-        insertReceipt(receipt) {
-            insertStmt.run(receipt.id, receipt.chainIndex, receipt.timestamp, receipt.previousHash, receipt.hash, receipt.decision.type, receipt.decision.decision, JSON.stringify(receipt.decision.context), receipt.decision.evidence ?? null);
+        insertReceipt,
+        insertReceiptWhenUnlocked(receipt) {
+            return writeWhenUnlockedOn(db, () => insertReceipt(receipt));
         },
         loadAllReceipts() {
             const rows = loadAllStmt.all();

package/dist/integrations/agentic-flow/reasoning-bank/experience-replay.d.ts

@@ -41,6 +41,11 @@ export interface Experience {
     readonly avgTokenSavings: number;
     /** Embedding for similarity search */
     readonly embedding?: number[];
+    /**
+     * #1217: embedding-space identity (ADR-097 spaceId) the embedding was
+     * computed in. Only vectors from the active space are compared.
+     */
+    readonly embeddingSpaceId?: string;
     /** Creation timestamp */
     readonly createdAt: Date;
     /** Last applied timestamp */
@@ -135,6 +140,12 @@ export declare class ExperienceReplay {
     private idToExperienceId;
     private experienceIdToHnswId;
     private nextHnswId;
+    /**
+     * #1217: embedding space the HNSW index holds vectors of. The index only
+     * holds vectors of one space, so a similarity is never measured across
+     * spaces. Null until the embedder's space is known.
+     */
+    private indexSpaceId;
     private recentExperiences;
     private reservoirBuffer;
     private stats;
@@ -157,6 +168,10 @@ export declare class ExperienceReplay {
     /**
      * Load embeddings into HNSW index for O(log n) similarity search
      * Performance: 150x-12,500x faster than linear scan
+     *
+     * #1217: loads only vectors of the given embedding space, as the pattern
+     * banks do (ADR-097). Vectors of another space, or without provenance, are
+     * not comparable with a query embedded in this one.
      */
     private loadEmbeddingIndex;
     /**
@@ -245,6 +260,13 @@ export declare class ExperienceReplay {
     dispose(): Promise<void>;
     private ensureInitialized;
     private rowToExperience;
+    /**
+     * #1217: add a stored vector to the HNSW index. A vector of another
+     * embedding space re-binds the index to that space (the active one, since
+     * the vector was just computed): the rows of that space are reloaded,
+     * including this one.
+     */
+    private indexExperience;
     private floatArrayToBuffer;
     private bufferToFloatArray;
 }