agentic-qe 3.14.0 → 3.14.2

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,6 +381,7 @@ 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'); }
 
@@ -388,7 +389,7 @@ function exportBrain() {
   if (!fs.existsSync(DB_PATH)) { log('No memory.db, skipping'); return { exported: false }; }
   try {
     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+)/);
@@ -422,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
@@ -441,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,
                         },
                     ],
@@ -453,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,
                         },
                     ],
@@ -465,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,
                         },
                     ],
@@ -477,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,
                         },
                     ],
@@ -490,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,
                         },
                     ],
@@ -501,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,
                         },
                     ],
@@ -512,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,
                         },
                     ],
@@ -527,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,
                         },
                     ],
@@ -539,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,
                         },
                     ],
@@ -549,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,
                         },
                     ],
@@ -561,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,
                         },
                     ],
@@ -575,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,
                         },
                     ],
@@ -585,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/learning/index.d.ts

@@ -46,10 +46,13 @@ export { admitLearningEvidence, countIndependentAdmissions, createLearningEviden
 export { persistLearningEvidence } from './evidence-admission-store.js';
 export type { PersistLearningEvidenceOptions, PersistedLearningEvidence, } from './evidence-admission-store.js';
 export type { LearningAdmissionResult, LearningContribution, LearningEvidenceManifest, LearningSegment, } from './learning-evidence-admission.js';
+export * from './structural-retrieval/index.js';
 export type { QEDomain, QEPatternType, QEPattern, QEPatternContext, QEPatternTemplate, QETemplateVariable, ProgrammingLanguage, TestFramework, ComplexityLevel, CreateQEPatternOptions, PatternMatchResult, } from './qe-patterns.js';
 export { QE_GUIDANCE_REGISTRY, TEST_GENERATION_GUIDANCE, COVERAGE_ANALYSIS_GUIDANCE, MUTATION_TESTING_GUIDANCE, API_TESTING_GUIDANCE, SECURITY_TESTING_GUIDANCE, VISUAL_TESTING_GUIDANCE, ACCESSIBILITY_GUIDANCE, PERFORMANCE_GUIDANCE, getGuidance, getFrameworkGuidance, getLanguageGuidance, getCombinedGuidance, checkAntiPatterns, generateGuidanceContext, } from './qe-guidance.js';
 export type { QEGuidance, AntiPattern, GuidanceExample, } from './qe-guidance.js';
 export { PatternStore, createPatternStore, DEFAULT_PATTERN_STORE_CONFIG, } from './pattern-store.js';
+export { PatternMutationError } from './pattern-mutation-error.js';
+export type { PatternMutationDisposition } from './pattern-mutation-error.js';
 export type { IPatternStore, PatternStoreConfig, PatternStoreStats, PatternSearchOptions, PatternSearchResult, } from './pattern-store.js';
 export { QE_HOOK_EVENTS, createQEHookHandlers, QEHookRegistry, createQEHookRegistry, setupQEHooks, } from './qe-hooks.js';
 export type { QEHookEvent, QEHookContext, QEHookResult, QEHookHandler, } from './qe-hooks.js';

package/dist/learning/index.js

@@ -55,6 +55,7 @@ QE_PATTERN_TYPES,
 detectQEDomain, detectQEDomains, mapQEDomainToAQE, calculateQualityScore, shouldPromotePattern, validateQEPattern, applyPatternTemplate, matchPatternContext, } from './qe-patterns.js';
 export { admitLearningEvidence, countIndependentAdmissions, createLearningEvidenceManifest, } from './learning-evidence-admission.js';
 export { persistLearningEvidence } from './evidence-admission-store.js';
+export * from './structural-retrieval/index.js';
 // ============================================================================
 // QE Guidance
 // ============================================================================
@@ -69,6 +70,7 @@ getGuidance, getFrameworkGuidance, getLanguageGuidance, getCombinedGuidance, che
 // Pattern Store
 // ============================================================================
 export { PatternStore, createPatternStore, DEFAULT_PATTERN_STORE_CONFIG, } from './pattern-store.js';
+export { PatternMutationError } from './pattern-mutation-error.js';
 // ============================================================================
 // QE Hooks
 // ============================================================================

package/dist/learning/pattern-mutation-error.d.ts

@@ -0,0 +1,9 @@
+export type PatternMutationDisposition = 'FAILED' | 'COMMITTED_PENDING_INDEX';
+/** Error evidence that distinguishes an uncommitted write from index lag. */
+export declare class PatternMutationError extends Error {
+    readonly patternId: string;
+    readonly disposition: PatternMutationDisposition;
+    readonly cause: unknown;
+    constructor(patternId: string, disposition: PatternMutationDisposition, cause: unknown);
+}
+//# sourceMappingURL=pattern-mutation-error.d.ts.map

package/dist/learning/pattern-mutation-error.js

@@ -0,0 +1,14 @@
+/** Error evidence that distinguishes an uncommitted write from index lag. */
+export class PatternMutationError extends Error {
+    patternId;
+    disposition;
+    cause;
+    constructor(patternId, disposition, cause) {
+        super(`${disposition}: pattern ${patternId}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = 'PatternMutationError';
+        this.patternId = patternId;
+        this.disposition = disposition;
+        this.cause = cause;
+    }
+}
+//# sourceMappingURL=pattern-mutation-error.js.map

package/dist/learning/pattern-store.js

@@ -31,6 +31,7 @@ import { createHopfieldMemory } from '../integrations/ruvector/hopfield-memory.j
 import { createHyperbolicPatternIndex, } from './hyperbolic-pattern-index.js';
 import { PatternNullStore } from './pattern-null-store.js';
 import { getActiveEmbeddingSpaceIdentity } from './real-embeddings.js';
+import { PatternMutationError } from './pattern-mutation-error.js';
 // ============================================================================
 // R1: HDC Fingerprint Singleton (lazy-initialized)
 // ============================================================================
@@ -443,6 +444,10 @@ export class PatternStore {
         if (pattern.confidence < this.config.minConfidence) {
             return err(new Error(`Pattern confidence ${pattern.confidence} below threshold ${this.config.minConfidence}`));
         }
+        const persistentBackend = (process.env.AQE_MEMORY_BACKEND ?? 'memory') !== 'memory';
+        if (persistentBackend && !this.sqliteStore) {
+            return err(new PatternMutationError(pattern.id, 'FAILED', new Error('authoritative SQLite pattern store is unavailable')));
+        }
         const activeSpaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? this.config.embeddingSpaceId;
         if (pattern.embedding && !activeSpaceId) {
             return err(new Error('VECTOR_SPACE_UNVERIFIED: refusing to persist or index an embedding without runtime provenance'));
@@ -455,6 +460,12 @@ export class PatternStore {
         }
         // R3b: Capture pre-existing pattern for VectorDeltaTracker before overwrite
         const existingPattern = this.patternCache.get(pattern.id) ?? null;
+        let authoritativeCommitted = false;
+        const rollbackUncommittedCache = () => {
+            this.unindexPattern(pattern);
+            if (existingPattern)
+                this.indexPattern(existingPattern);
+        };
         // Index in memory cache
         this.indexPattern(pattern);
         // Persist to SQLite (pattern + embedding atomically)
@@ -472,14 +483,23 @@ export class PatternStore {
                     pattern.id = actualId;
                     this.indexPattern(pattern);
                 }
+                authoritativeCommitted = true;
             }
             catch (error) {
-                console.warn(`[PatternStore] SQLite persist failed for ${pattern.id}:`, toErrorMessage(error));
+                rollbackUncommittedCache();
+                return err(new PatternMutationError(pattern.id, 'FAILED', error));
             }
         }
         // Add to HNSW if embedding is available (lazy-load HNSW only when needed)
         if (pattern.embedding) {
             const hnsw = await this.ensureHNSW();
+            if (!hnsw && authoritativeCommitted) {
+                return err(new PatternMutationError(pattern.id, 'COMMITTED_PENDING_INDEX', new Error('HNSW unavailable after authoritative pattern commit')));
+            }
+            if (!hnsw && persistentBackend) {
+                rollbackUncommittedCache();
+                return err(new PatternMutationError(pattern.id, 'FAILED', new Error('HNSW unavailable before an authoritative pattern commit')));
+            }
             if (hnsw) {
                 try {
                     // Cast pattern metadata to CoverageVectorMetadata for HNSW storage
@@ -498,7 +518,9 @@ export class PatternStore {
                     });
                 }
                 catch (error) {
-                    console.warn(`[PatternStore] Failed to index embedding for ${pattern.id}:`, error);
+                    if (!authoritativeCommitted)
+                        rollbackUncommittedCache();
+                    return err(new PatternMutationError(pattern.id, authoritativeCommitted ? 'COMMITTED_PENDING_INDEX' : 'FAILED', error));
                 }
             }
         }

package/dist/learning/qe-reasoning-bank.js

@@ -23,6 +23,7 @@ import { createPatternStore, } from './pattern-store.js';
 import { createSQLitePatternStore, } from './sqlite-persistence.js';
 import { getWitnessChain } from '../audit/witness-chain.js';
 import { getActiveEmbeddingSpaceIdentity } from './real-embeddings.js';
+import { PatternMutationError } from './pattern-mutation-error.js';
 // Import extracted modules
 import { DEFAULT_QE_REASONING_BANK_CONFIG } from './qe-reasoning-bank-types.js';
 import { PRETRAINED_PATTERNS } from './pretrained-patterns.js';
@@ -281,16 +282,34 @@ export class QEReasoningBank {
             options = { ...options, embedding };
         }
         const result = await this.patternStore.create(options);
+        // A pending-index error still proves the authoritative SQLite mutation
+        // committed. Resolve that committed row for witness and replication side
+        // effects, while returning the original typed partial disposition.
+        let committedPattern = result.success ? result.value : null;
+        if (!result.success &&
+            result.error instanceof PatternMutationError &&
+            result.error.disposition === 'COMMITTED_PENDING_INDEX') {
+            try {
+                committedPattern = await this.patternStore.get(result.error.patternId);
+            }
+            catch (error) {
+                logger.warn('Committed pattern lookup failed', {
+                    patternId: result.error.patternId,
+                    error: toErrorMessage(error),
+                });
+            }
+        }
         // ADR-070: Record pattern creation in witness chain
-        if (result.success) {
-            getWitnessChain().then(wc => wc.append('PATTERN_CREATE', { patternId: result.value.id, domain: result.value.qeDomain, confidence: result.value.confidence, name: result.value.name }, 'reasoning-bank')).catch((e) => { logger.warn('Witness chain PATTERN_CREATE failed', { error: toErrorMessage(e) }); });
+        if (committedPattern) {
+            const sideEffectPattern = committedPattern;
+            getWitnessChain().then(wc => wc.append('PATTERN_CREATE', { patternId: sideEffectPattern.id, domain: sideEffectPattern.qeDomain, confidence: sideEffectPattern.confidence, name: sideEffectPattern.name }, 'reasoning-bank')).catch((e) => { logger.warn('Witness chain PATTERN_CREATE failed', { error: toErrorMessage(e) }); });
             // Phase 3: Best-effort RVF dual-write for vector replication
-            if (this.rvfDualWriter && result.value.embedding && result.value.embedding.length > 0) {
+            if (this.rvfDualWriter && sideEffectPattern.embedding && sideEffectPattern.embedding.length > 0) {
                 try {
-                    this.rvfDualWriter.writePattern(result.value.id, result.value.embedding);
+                    this.rvfDualWriter.writePattern(sideEffectPattern.id, sideEffectPattern.embedding);
                 }
                 catch (rvfErr) {
-                    logger.warn('RVF dual-write failed (non-fatal)', { patternId: result.value.id, error: toErrorMessage(rvfErr) });
+                    logger.warn('RVF dual-write failed (non-fatal)', { patternId: sideEffectPattern.id, error: toErrorMessage(rvfErr) });
                 }
             }
         }

package/dist/learning/rvf-pattern-store.js

@@ -18,6 +18,7 @@ import { calculateQualityScore, validateQEPattern, mapQEDomainToAQE, PROMOTION_T
 import { DEFAULT_PATTERN_STORE_CONFIG } from './pattern-store.js';
 import { getActiveEmbeddingSpaceIdentity } from './real-embeddings.js';
 import { verifyOrCreateEmbeddingSpaceManifest } from './embedding-space.js';
+import { PatternMutationError } from './pattern-mutation-error.js';
 // ============================================================================
 // RVF Pattern Store Implementation
 // ============================================================================
@@ -63,9 +64,11 @@ export class RvfPatternStore {
     async initialize() {
         if (this.initialized)
             return;
+        this.rvfInitError = null;
         // Database-free mode (#534): never create an on-disk patterns.rvf (+ .idmap/.lock).
-        // Run adapter-less — the store degrades to metadata-only (the same graceful
-        // path used when the RVF native binding is unavailable), writing nothing.
+        // Run adapter-less and write nothing. The factory normally selects the
+        // in-memory PatternStore in this mode; a directly constructed RVF store
+        // remains fail-closed unless an authoritative SQLite delegate is attached.
         if (process.env.AQE_MEMORY_BACKEND === 'memory') {
             this.adapter = null;
             this.initialized = true;
@@ -172,10 +175,18 @@ export class RvfPatternStore {
         if (pattern.confidence < this.config.minConfidence) {
             return err(new Error(`Pattern confidence ${pattern.confidence} below threshold ${this.config.minConfidence}`));
         }
+        // RVF is a derived persistent index. A write is observable only through its
+        // authoritative SQLite metadata row, regardless of the process-wide memory
+        // setting. The factory routes memory mode to PatternStore, so a directly
+        // constructed RVF store without SQLite must fail before vector ingestion.
+        if (!this.sqliteStore) {
+            return err(new PatternMutationError(pattern.id, 'FAILED', new Error('authoritative SQLite pattern store is unavailable')));
+        }
         const activeSpaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? this.embeddingSpaceId;
         if (pattern.embedding && !activeSpaceId) {
             return err(new Error('VECTOR_SPACE_UNVERIFIED: refusing to persist or index an embedding without runtime provenance'));
         }
+        let authoritativeCommitted = false;
         // Persist metadata to SQLite. #447: capture the returned id — ON CONFLICT
         // on (name, qe_domain, pattern_type) preserves the existing row's id, so
         // we must align pattern.id with what's actually stored before ingesting
@@ -190,21 +201,28 @@ export class RvfPatternStore {
                     // before HNSW ingest (otherwise the index keys diverge from SQLite).
                     pattern.id = actualId;
                 }
+                authoritativeCommitted = true;
             }
             catch (error) {
-                console.warn(`[RvfPatternStore] SQLite persist failed for ${pattern.id}:`, toErrorMessage(error));
+                return err(new PatternMutationError(pattern.id, 'FAILED', error));
             }
         }
+        if (pattern.embedding && !this.adapter && this.rvfInitError) {
+            return err(new PatternMutationError(pattern.id, authoritativeCommitted ? 'COMMITTED_PENDING_INDEX' : 'FAILED', new Error(`RVF unavailable ${authoritativeCommitted ? 'after' : 'before'} authoritative pattern commit: ${this.rvfInitError}`)));
+        }
         // Ingest vector into RVF
         if (pattern.embedding && this.adapter) {
             try {
                 const vec = pattern.embedding instanceof Float32Array
                     ? pattern.embedding
                     : new Float32Array(pattern.embedding);
-                this.adapter.ingest([{ id: pattern.id, vector: vec }]);
+                const ingest = this.adapter.ingest([{ id: pattern.id, vector: vec }]);
+                if (ingest.accepted !== 1 || ingest.rejected !== 0) {
+                    throw new Error(`RVF rejected pattern vector (accepted=${ingest.accepted}, rejected=${ingest.rejected})`);
+                }
             }
             catch (error) {
-                console.warn(`[RvfPatternStore] RVF ingest failed for ${pattern.id}:`, toErrorMessage(error));
+                return err(new PatternMutationError(pattern.id, authoritativeCommitted ? 'COMMITTED_PENDING_INDEX' : 'FAILED', error));
             }
         }
         return ok(pattern.id);

package/dist/learning/structural-retrieval/corpus.d.ts

@@ -0,0 +1,5 @@
+import type { StructuralRetrievalCorpus, StructuralTransformation } from './types.js';
+export declare function createStructuralRetrievalCorpus(): StructuralRetrievalCorpus;
+export declare const STRUCTURAL_RETRIEVAL_TRANSFORMATIONS: readonly StructuralTransformation[];
+export declare function verifyStructuralRetrievalCorpus(corpus: StructuralRetrievalCorpus): boolean;
+//# sourceMappingURL=corpus.d.ts.map

package/dist/learning/structural-retrieval/corpus.js

@@ -0,0 +1,97 @@
+import { createHash } from 'node:crypto';
+const REVISION = 'aqe-structural-transfer-2026-09-06';
+const TRANSFORMATIONS = [
+    'rename', 'framework-transfer', 'reordered-steps',
+    'distractor-terminology', 'cross-domain-transfer',
+];
+const SEEDS = [
+    ['async-race', 'observe completion before assertion', 'await the operation', 'increase the timeout', 'completion probe', 'unit', 'vitest'],
+    ['stale-cache', 'invalidate on every state mutation', 'invalidate the cache', 'retry the read', 'freshness assertion', 'integration', 'redis'],
+    ['transaction-leak', 'rollback isolates each test', 'rollback the transaction', 'truncate a shared table', 'row-count check', 'database', 'postgres'],
+    ['clock-skew', 'compare times in one clock domain', 'inject a monotonic clock', 'widen the time window', 'clock boundary check', 'unit', 'node'],
+    ['event-loss', 'subscribe before publishing', 'register the listener first', 'publish twice', 'delivery assertion', 'events', 'eventemitter'],
+    ['resource-leak', 'release resources on every exit', 'close in a finally block', 'raise the pool limit', 'handle-count check', 'integration', 'playwright'],
+    ['eventual-consistency', 'poll the observable state', 'poll with a bounded deadline', 'sleep for a fixed delay', 'state convergence', 'distributed', 'kubernetes'],
+    ['identity-confusion', 'compare canonical identities', 'normalize the identifier', 'use display names', 'identity equality', 'security', 'oauth'],
+    ['partial-write', 'publish only complete state', 'commit through an atomic swap', 'ignore missing fields', 'atomicity check', 'filesystem', 'node'],
+    ['order-dependence', 'tests start from isolated state', 'reset state in setup', 'force alphabetical order', 'shuffle repeat', 'unit', 'jest'],
+    ['schema-drift', 'validate at the boundary', 'reject the incompatible schema', 'cast the payload', 'schema validator', 'api', 'zod'],
+    ['backpressure-loss', 'producer respects consumer capacity', 'await the drain signal', 'increase buffer memory', 'loss counter', 'performance', 'streams'],
+    ['retry-duplication', 'retries preserve idempotency', 'attach an idempotency key', 'disable all retries', 'duplicate detector', 'api', 'fetch'],
+    ['permission-bypass', 'authorization precedes mutation', 'check permission before write', 'hide the user interface', 'denial assertion', 'security', 'express'],
+    ['encoding-mismatch', 'encode and decode with one charset', 'set UTF-8 explicitly', 'strip non-ASCII text', 'round-trip equality', 'api', 'json'],
+    ['pagination-gap', 'cursor advances from the last item', 'use the returned cursor', 'increase page size', 'set equality', 'api', 'graphql'],
+    ['cancellation-leak', 'cancellation propagates to children', 'forward the abort signal', 'wait for natural completion', 'abort observation', 'integration', 'abortcontroller'],
+    ['floating-point-boundary', 'compare numeric results by tolerance', 'use an error bound', 'round every input', 'relative-error check', 'unit', 'vitest'],
+    ['locale-dependence', 'format under an explicit locale', 'pass the locale explicitly', 'update the snapshot locally', 'multi-locale check', 'ui', 'intl'],
+    ['lock-starvation', 'lock acquisition remains fair', 'queue lock waiters', 'raise retry count', 'bounded-wait check', 'concurrency', 'mutex'],
+].map(([mechanism, invariant, action, wrongAction, oracle, domain, framework]) => ({
+    mechanism, invariant, action, wrongAction, oracle, domain, framework,
+}));
+function splitFor(index) {
+    if (index < 12)
+        return 'train';
+    if (index < 16)
+        return 'calibration';
+    return 'audit';
+}
+function stableHash(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+function queryText(seed, transformation, index) {
+    const object = `component-${index + 41}`;
+    switch (transformation) {
+        case 'rename': return `${object} intermittently fails; ensure ${seed.invariant} by applying: ${seed.action}`;
+        case 'framework-transfer': return `In an alternative runtime, ${seed.mechanism} appears. Preserve this rule: ${seed.invariant}`;
+        case 'reordered-steps': return `Verify with ${seed.oracle}; first arrange the fixture, then ${seed.action}; fault: ${seed.mechanism}`;
+        case 'distractor-terminology': return `${seed.wrongAction} is tempting for ${seed.mechanism}, but the required invariant is ${seed.invariant}`;
+        case 'cross-domain-transfer': return `A ${seed.domain} workflow moved to service-${index}; reuse the mechanism ${seed.mechanism} and ${seed.action}`;
+    }
+}
+export function createStructuralRetrievalCorpus() {
+    const patterns = [];
+    const queries = [];
+    SEEDS.forEach((seed, index) => {
+        const familyId = `family-${String(index + 1).padStart(2, '0')}`;
+        const correctId = `${familyId}-structural`;
+        const distractorId = `${familyId}-surface-distractor`;
+        const counterexampleId = `${familyId}-counterexample`;
+        patterns.push({ id: correctId, familyId, framework: seed.framework, domain: seed.domain,
+            failureMechanism: seed.mechanism, invariant: seed.invariant, actions: [seed.action], oracle: seed.oracle,
+            text: `${seed.framework} ${seed.domain} ${seed.mechanism}: ${seed.action}; verify ${seed.oracle}` }, { id: distractorId, familyId, framework: seed.framework, domain: seed.domain,
+            failureMechanism: `symptom resembling ${seed.mechanism}`, invariant: 'mask the observed symptom',
+            actions: [seed.wrongAction], oracle: 'single rerun',
+            text: `${seed.framework} ${seed.domain} ${seed.mechanism}: ${seed.wrongAction}; quick ${seed.oracle}` }, { id: counterexampleId, familyId, framework: seed.framework, domain: seed.domain,
+            failureMechanism: seed.mechanism, invariant: `environment forbids ${seed.action}`,
+            actions: [`escalate instead of ${seed.action}`], oracle: 'environment constraint check',
+            text: `${seed.mechanism} ${seed.action} ${seed.framework}, but environment forbids the action` });
+        TRANSFORMATIONS.forEach((transformation) => queries.push({
+            id: `${familyId}-${transformation}`,
+            familyId,
+            split: splitFor(index),
+            transformation,
+            text: queryText(seed, transformation, index),
+            relevantPatternIds: [correctId],
+            mustNotRankAbove: [
+                { lowerPatternId: distractorId, higherPatternId: correctId },
+                { lowerPatternId: counterexampleId, higherPatternId: correctId },
+            ],
+        }));
+    });
+    const payload = { schemaVersion: 'aqe-structural-retrieval/v1', corpusRevision: REVISION, patterns, queries };
+    return deepFreeze({ ...payload, lineageHash: stableHash(payload) });
+}
+export const STRUCTURAL_RETRIEVAL_TRANSFORMATIONS = Object.freeze([...TRANSFORMATIONS]);
+export function verifyStructuralRetrievalCorpus(corpus) {
+    const { lineageHash: _lineageHash, ...payload } = corpus;
+    return stableHash(payload) === corpus.lineageHash;
+}
+//# sourceMappingURL=corpus.js.map

package/dist/learning/structural-retrieval/evaluate.d.ts

@@ -0,0 +1,7 @@
+import type { QueryRetrievalResult, RetrievalDiagnostic, StructuralRetrievalCorpus, StructuralRetrievalQuery, StructuralRetrievalReport } from './types.js';
+export declare function diagnoseRetrieval(query: StructuralRetrievalQuery, result: QueryRetrievalResult, k: number): RetrievalDiagnostic;
+export declare function evaluateStructuralRetrieval(corpus: StructuralRetrievalCorpus, results: QueryRetrievalResult[], options: {
+    rankerVersion: string;
+    k?: number;
+}): StructuralRetrievalReport;
+//# sourceMappingURL=evaluate.d.ts.map