agentic-qe 3.13.12 → 3.14.1

package/dist/learning/embedding-space.js

@@ -0,0 +1,128 @@
+/**
+ * Executable embedding-space provenance (#633).
+ *
+ * Model names and dimensions are declarations, not proof that two vectors are
+ * comparable.  An embedding space is therefore identified by canonical runtime
+ * configuration plus a fingerprint of a fixed canary vector.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { cosineSimilarity } from '../shared/utils/vector-math.js';
+export const EMBEDDING_SPACE_CANARY = 'aqe embedding-space compatibility canary v1';
+export const EMBEDDING_ROUND_TRIP_MIN_COSINE = 0.999;
+export class EmbeddingSpaceError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = 'EmbeddingSpaceError';
+    }
+}
+function canonicalIdentity(identity) {
+    return JSON.stringify({
+        provider: identity.provider,
+        model: identity.model,
+        dimensions: identity.dimensions,
+        pooling: identity.pooling ?? null,
+        normalized: identity.normalized,
+        preprocessingVersion: identity.preprocessingVersion ?? null,
+        implementation: identity.implementation ?? null,
+        runtimeFingerprint: identity.runtimeFingerprint,
+    });
+}
+/** Fingerprint a normalized canary vector after stable int16 quantization. */
+export function fingerprintEmbeddingRuntime(vector) {
+    const bytes = Buffer.alloc(vector.length * 2);
+    for (let i = 0; i < vector.length; i++) {
+        const quantized = Math.max(-32768, Math.min(32767, Math.round(vector[i] * 32767)));
+        bytes.writeInt16LE(quantized, i * 2);
+    }
+    return createHash('sha256').update(bytes).digest('hex').slice(0, 16);
+}
+export function deriveEmbeddingSpaceIdentity(identity) {
+    if (!identity.runtimeFingerprint) {
+        throw new Error('Embedding space identity requires executable runtime evidence');
+    }
+    const spaceId = createHash('sha256')
+        .update('aqe:embedding-space:v1\0')
+        .update(canonicalIdentity(identity))
+        .digest('hex');
+    return { ...identity, spaceId };
+}
+/** Execute the same-text write/read canary before semantic ranking is trusted. */
+export async function verifyEmbeddingRoundTrip(writeEmbed, queryEmbed, minimumCosine = EMBEDDING_ROUND_TRIP_MIN_COSINE) {
+    const [written, queried] = await Promise.all([
+        writeEmbed(EMBEDDING_SPACE_CANARY),
+        queryEmbed(EMBEDDING_SPACE_CANARY),
+    ]);
+    if (written.length !== queried.length) {
+        throw new EmbeddingSpaceError('VECTOR_SPACE_MISMATCH', `round-trip dimensions differ (${written.length} != ${queried.length})`);
+    }
+    const similarity = cosineSimilarity(written, queried);
+    if (!Number.isFinite(similarity) || similarity < minimumCosine) {
+        throw new EmbeddingSpaceError('VECTOR_SPACE_MISMATCH', `write/read canary cosine ${similarity.toFixed(6)} is below ${minimumCosine}`);
+    }
+    return similarity;
+}
+export function inspectEmbeddingSpaceRows(rows, activeSpaceId) {
+    const storedSpaceIds = [...new Set(rows.flatMap((row) => row.spaceId ? [row.spaceId] : []))].sort();
+    const unverifiedVectors = rows.filter((row) => !row.spaceId).length;
+    const verifiedVectors = activeSpaceId
+        ? rows.filter((row) => row.spaceId === activeSpaceId).length
+        : 0;
+    const mismatchedVectors = activeSpaceId
+        ? rows.filter((row) => row.spaceId !== null && row.spaceId !== activeSpaceId).length
+        : rows.length - unverifiedVectors;
+    const status = unverifiedVectors > 0 || !activeSpaceId
+        ? 'unverified'
+        : mismatchedVectors > 0 || storedSpaceIds.length > 1
+            ? 'vector_space_mismatch'
+            : 'healthy';
+    return {
+        status,
+        activeSpaceId,
+        storedSpaceIds,
+        verifiedVectors,
+        mismatchedVectors,
+        unverifiedVectors,
+    };
+}
+/** Sidecar path used to bind a persistent ANN index to one embedding space. */
+export function embeddingSpaceManifestPath(indexPath) {
+    return `${indexPath}.space.json`;
+}
+/**
+ * Bind an empty persistent index to the active space, or verify an existing
+ * binding. A populated index without a manifest is legacy/unverified and must
+ * be rebuilt rather than silently adopted by the current runtime.
+ */
+export function verifyOrCreateEmbeddingSpaceManifest(indexPath, activeSpaceId, vectorCount) {
+    if (!activeSpaceId) {
+        throw new EmbeddingSpaceError('VECTOR_SPACE_UNVERIFIED', `cannot open ANN index ${indexPath} without runtime provenance`);
+    }
+    const manifestPath = embeddingSpaceManifestPath(indexPath);
+    if (existsSync(manifestPath)) {
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        catch {
+            throw new EmbeddingSpaceError('VECTOR_SPACE_UNVERIFIED', `ANN index manifest ${manifestPath} is unreadable`);
+        }
+        if (manifest.version !== 1 || !manifest.spaceId) {
+            throw new EmbeddingSpaceError('VECTOR_SPACE_UNVERIFIED', `ANN index manifest ${manifestPath} has no verified space`);
+        }
+        if (manifest.spaceId !== activeSpaceId) {
+            throw new EmbeddingSpaceError('VECTOR_SPACE_MISMATCH', `ANN index space ${manifest.spaceId} != active space ${activeSpaceId}`);
+        }
+        return;
+    }
+    if (vectorCount > 0) {
+        throw new EmbeddingSpaceError('VECTOR_SPACE_UNVERIFIED', `populated ANN index ${indexPath} has no embedding-space manifest; rebuild required`);
+    }
+    const manifest = { version: 1, spaceId: activeSpaceId };
+    const temporaryPath = `${manifestPath}.${process.pid}.tmp`;
+    writeFileSync(temporaryPath, `${JSON.stringify(manifest)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temporaryPath, manifestPath);
+}
+//# sourceMappingURL=embedding-space.js.map

package/dist/learning/evidence-admission-store.d.ts

@@ -0,0 +1,15 @@
+import type { Database as DatabaseType } from 'better-sqlite3';
+import type { LearningAdmissionResult, LearningEvidenceManifest } from './learning-evidence-admission.js';
+export interface PersistLearningEvidenceOptions {
+    patternId?: string;
+    policyVersion?: string;
+    policyHash?: string;
+    correlationGroup?: string;
+}
+export interface PersistedLearningEvidence {
+    manifestId: string;
+    admissionId: string;
+    disposition: 'admitted' | 'rejected' | 'review-required';
+}
+export declare function persistLearningEvidence(db: DatabaseType, manifest: LearningEvidenceManifest, admission: LearningAdmissionResult, options?: PersistLearningEvidenceOptions): PersistedLearningEvidence;
+//# sourceMappingURL=evidence-admission-store.d.ts.map

package/dist/learning/evidence-admission-store.js

@@ -0,0 +1,68 @@
+import { randomUUID } from 'node:crypto';
+function evidenceClass(source) {
+    if (source === 'executed')
+        return 'EXECUTED';
+    if (source === 'static' || source === 'human-reviewed')
+        return 'STATIC';
+    return 'INFERRED';
+}
+export function persistLearningEvidence(db, manifest, admission, options = {}) {
+    if (!/^[a-f0-9]{64}$/.test(manifest.trajectoryHash)) {
+        throw new Error('trajectoryHash must be a lowercase SHA-256 digest');
+    }
+    const disposition = admission.disposition === 'admit'
+        ? 'admitted'
+        : admission.disposition === 'reject' ? 'rejected' : 'review-required';
+    const admissionId = randomUUID();
+    const persist = db.transaction(() => {
+        db.prepare(`
+      INSERT INTO learning_evidence_manifests (
+        id, trajectory_id, trajectory_hash, manifest_hash, task_family,
+        task_identity, run_identity, correlation_group, dedupe_fingerprint,
+        revision, environment, outcome, oracle_refs_json, source_kind,
+        process_signals_json, manifest_version
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1)
+    `).run(manifest.trajectoryId, manifest.trajectoryId, manifest.trajectoryHash, manifest.trajectoryHash, manifest.taskFamily, manifest.trajectoryId, manifest.trajectoryId, options.correlationGroup ?? null, manifest.trajectoryHash, manifest.revision ?? null, manifest.environment ?? null, manifest.outcome, JSON.stringify(manifest.oracleRefs), manifest.sourceKind, JSON.stringify(manifest.processSignals));
+        const insertSegment = db.prepare(`
+      INSERT INTO learning_evidence_segments (
+        id, manifest_id, segment_order, kind, contribution,
+        evidence_refs_json, admit_for_learning, reasons_json
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        manifest.segments.forEach((segment, index) => insertSegment.run(segment.id, manifest.trajectoryId, index, segment.kind, segment.contribution, JSON.stringify(segment.evidenceRefs), segment.admitForLearning ? 1 : 0, JSON.stringify(segment.reasons)));
+        const insertEdge = db.prepare(`
+      INSERT INTO learning_segment_edges (
+        manifest_id, parent_segment_id, child_segment_id, edge_kind
+      ) VALUES (?, ?, ?, 'depends-on')
+    `);
+        for (const segment of manifest.segments) {
+            for (const parentId of segment.parentIds) {
+                insertEdge.run(manifest.trajectoryId, parentId, segment.id);
+            }
+        }
+        db.prepare(`
+      INSERT INTO learning_evidence_admissions (
+        id, manifest_id, decision_seq, disposition, reason_codes_json,
+        assessor_kind, evidence_class, policy_version, policy_hash
+      ) VALUES (?, ?, 1, ?, ?, ?, ?, ?, ?)
+    `).run(admissionId, manifest.trajectoryId, disposition, JSON.stringify(admission.reasons), manifest.sourceKind, evidenceClass(manifest.sourceKind), options.policyVersion ?? null, options.policyHash ?? null);
+        if (options.patternId) {
+            db.prepare(`
+        INSERT INTO pattern_manifest_lineage (
+          pattern_id, manifest_id, use_kind
+        ) VALUES (?, ?, ?)
+      `).run(options.patternId, manifest.trajectoryId, disposition === 'admitted' ? 'promotion-support' : 'rejection');
+            const insertSegmentLineage = db.prepare(`
+        INSERT INTO pattern_segment_lineage (
+          pattern_id, manifest_id, segment_id, use_kind
+        ) VALUES (?, ?, ?, ?)
+      `);
+            for (const segmentId of admission.admittedSegmentIds) {
+                insertSegmentLineage.run(options.patternId, manifest.trajectoryId, segmentId, 'promotion-support');
+            }
+        }
+    });
+    persist();
+    return { manifestId: manifest.trajectoryId, admissionId, disposition };
+}
+//# sourceMappingURL=evidence-admission-store.js.map

package/dist/learning/index.d.ts

@@ -42,10 +42,17 @@
 export { QEReasoningBank, createQEReasoningBank, DEFAULT_QE_REASONING_BANK_CONFIG, } from './qe-reasoning-bank.js';
 export type { QEReasoningBankConfig, QERoutingRequest, QERoutingResult, LearningOutcome, IQEReasoningBank, QEReasoningBankStats, } from './qe-reasoning-bank.js';
 export { QE_DOMAINS, QE_DOMAIN_LIST, 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 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

@@ -53,6 +53,9 @@ QE_DOMAINS, QE_DOMAIN_LIST,
 QE_PATTERN_TYPES, 
 // Utility functions
 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
 // ============================================================================
@@ -67,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/learning-evidence-admission.d.ts

@@ -0,0 +1,44 @@
+export type LearningContribution = 'causal' | 'supporting' | 'irrelevant' | 'harmful' | 'unknown';
+export interface LearningSegment {
+    readonly id: string;
+    readonly parentIds: readonly string[];
+    readonly kind: 'observe' | 'decide' | 'act' | 'verify' | 'recover' | 'other';
+    readonly contribution: LearningContribution;
+    readonly evidenceRefs: readonly string[];
+    readonly admitForLearning: boolean;
+    readonly reasons: readonly string[];
+}
+export interface LearningEvidenceManifest {
+    readonly trajectoryId: string;
+    readonly trajectoryHash: string;
+    readonly taskFamily: string;
+    readonly revision?: string;
+    readonly environment?: string;
+    readonly outcome: 'verified-success' | 'verified-failure' | 'unknown';
+    readonly oracleRefs: readonly string[];
+    readonly sourceKind: 'executed' | 'static' | 'human-reviewed' | 'inferred';
+    readonly processSignals: Readonly<{
+        observedBeforeActing: boolean;
+        verificationAfterActing: boolean;
+        toolSuccessRate: number;
+        repeatedNoProgressActions: number;
+        scopeDrift: boolean;
+        leakageOrShortcut: boolean;
+        weakenedOracle: boolean;
+        unsafeSideEffect: boolean;
+    }>;
+    readonly segments: readonly LearningSegment[];
+}
+export interface LearningAdmissionResult {
+    readonly disposition: 'admit' | 'reject' | 'human-review';
+    readonly autoPromotable: boolean;
+    readonly admittedSegmentIds: readonly string[];
+    readonly rejectedSegmentIds: readonly string[];
+    readonly reasons: readonly string[];
+}
+type ManifestInput = Omit<LearningEvidenceManifest, 'trajectoryHash'>;
+export declare function createLearningEvidenceManifest(input: ManifestInput): LearningEvidenceManifest;
+export declare function admitLearningEvidence(manifest: LearningEvidenceManifest): LearningAdmissionResult;
+export declare function countIndependentAdmissions(manifests: readonly LearningEvidenceManifest[]): number;
+export {};
+//# sourceMappingURL=learning-evidence-admission.d.ts.map

package/dist/learning/learning-evidence-admission.js

@@ -0,0 +1,97 @@
+import { createHash } from 'node:crypto';
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalize).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalize(entry)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'undefined';
+}
+function freezeManifest(manifest) {
+    Object.freeze(manifest.processSignals);
+    manifest.segments.forEach(segment => {
+        Object.freeze(segment.parentIds);
+        Object.freeze(segment.evidenceRefs);
+        Object.freeze(segment.reasons);
+        Object.freeze(segment);
+    });
+    Object.freeze(manifest.oracleRefs);
+    Object.freeze(manifest.segments);
+    return Object.freeze(manifest);
+}
+export function createLearningEvidenceManifest(input) {
+    const trajectoryHash = createHash('sha256').update(canonicalize(input)).digest('hex');
+    return freezeManifest({ ...input, trajectoryHash });
+}
+function expectedTrajectoryHash(manifest) {
+    const { trajectoryHash: _claimedHash, ...input } = manifest;
+    return createHash('sha256').update(canonicalize(input)).digest('hex');
+}
+export function admitLearningEvidence(manifest) {
+    const reasons = [];
+    if (manifest.trajectoryHash !== expectedTrajectoryHash(manifest))
+        reasons.push('integrity:trajectory-hash-mismatch');
+    if (manifest.outcome !== 'verified-success')
+        reasons.push(`outcome:${manifest.outcome}`);
+    if (manifest.sourceKind === 'inferred')
+        reasons.push('source:inferred');
+    if (manifest.oracleRefs.length === 0)
+        reasons.push('oracle:missing');
+    if (!manifest.processSignals.verificationAfterActing)
+        reasons.push('verification:missing-after-action');
+    if (!manifest.processSignals.observedBeforeActing)
+        reasons.push('process:acted-before-observation');
+    if (manifest.processSignals.toolSuccessRate < 0 || manifest.processSignals.toolSuccessRate > 1) {
+        reasons.push('process:invalid-tool-success-rate');
+    }
+    else if (manifest.processSignals.toolSuccessRate < 1) {
+        reasons.push('process:tool-failure');
+    }
+    if (manifest.processSignals.repeatedNoProgressActions > 0)
+        reasons.push('process:repeated-no-progress');
+    if (manifest.processSignals.scopeDrift)
+        reasons.push('process:scope-drift');
+    if (manifest.processSignals.weakenedOracle)
+        reasons.push('oracle:weakened');
+    if (manifest.processSignals.leakageOrShortcut)
+        reasons.push('process:leakage-or-shortcut');
+    if (manifest.processSignals.unsafeSideEffect)
+        reasons.push('process:unsafe-side-effect');
+    const admittedSegmentIds = manifest.segments
+        .filter(segment => segment.admitForLearning &&
+        (segment.contribution === 'causal' || segment.contribution === 'supporting'))
+        .map(segment => segment.id);
+    const rejectedSegmentIds = manifest.segments
+        .filter(segment => !admittedSegmentIds.includes(segment.id))
+        .map(segment => segment.id);
+    if (admittedSegmentIds.length === 0)
+        reasons.push('segments:no-admitted-contribution');
+    if (manifest.segments.some(segment => admittedSegmentIds.includes(segment.id) && segment.evidenceRefs.length === 0)) {
+        reasons.push('segments:admitted-without-evidence');
+    }
+    const hardReject = reasons.some(reason => reason === 'oracle:weakened' || reason === 'process:leakage-or-shortcut' ||
+        reason === 'process:unsafe-side-effect' || reason === 'integrity:trajectory-hash-mismatch' ||
+        reason === 'process:invalid-tool-success-rate' || reason.startsWith('outcome:'));
+    const disposition = hardReject ? 'reject' : reasons.length > 0 ? 'human-review' : 'admit';
+    return Object.freeze({
+        disposition,
+        autoPromotable: disposition === 'admit',
+        admittedSegmentIds: Object.freeze(admittedSegmentIds),
+        rejectedSegmentIds: Object.freeze(rejectedSegmentIds),
+        reasons: Object.freeze(reasons),
+    });
+}
+export function countIndependentAdmissions(manifests) {
+    const identities = new Set();
+    for (const manifest of manifests) {
+        if (!admitLearningEvidence(manifest).autoPromotable)
+            continue;
+        const { trajectoryId: _runIdentity, trajectoryHash: _runHash, ...evidence } = manifest;
+        identities.add(canonicalize(evidence));
+    }
+    return identities.size;
+}
+//# sourceMappingURL=learning-evidence-admission.js.map

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.d.ts

@@ -46,6 +46,8 @@ export interface PatternStoreConfig {
     namespace: string;
     /** Dimension of embedding vectors */
     embeddingDimension: number;
+    /** Runtime-provided provenance override (primarily for injected embedders/tests). */
+    embeddingSpaceId?: string;
     /** HNSW configuration */
     hnsw: {
         M: number;
@@ -124,6 +126,8 @@ export interface PatternSearchOptions {
     context?: Partial<QEPatternContext>;
     /** Include vector similarity search */
     useVectorSearch?: boolean;
+    /** Provenance of a pre-computed query vector. Required for semantic ranking. */
+    embeddingSpaceId?: string;
     /**
      * Composable metadata filter expression (Task 1.2: ruvector-filter).
      * Applied post-search to refine results by domain, severity,
@@ -212,6 +216,7 @@ export declare class PatternStore implements IPatternStore {
     private typeIndex;
     private tierIndex;
     private hnswIndex;
+    private hnswSpaceId;
     private hnswAvailable;
     private hnswInitPromise;
     private hdcCache;

package/dist/learning/pattern-store.js

@@ -6,6 +6,8 @@
  * O(log n) approximate nearest neighbor search.
  */
 import { v4 as uuidv4 } from 'uuid';
+import { existsSync } from 'node:fs';
+import { join as joinPath } from 'node:path';
 // Issue #516: lightweight, sqlite-free project-root resolver (static import so it
 // resolves under the test runner; avoids pulling unified-memory's sqlite graph).
 import { findProjectRoot } from '../kernel/project-root.js';
@@ -28,6 +30,8 @@ import { createVectorDeltaTracker, } from '../integrations/ruvector/vector-delta
 import { createHopfieldMemory } from '../integrations/ruvector/hopfield-memory.js';
 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)
 // ============================================================================
@@ -120,6 +124,7 @@ export class PatternStore {
     // HNSW index for vector search (lazy loaded - ADR-048)
     // Using dynamic import type since HNSWIndex is lazily loaded
     hnswIndex = null;
+    hnswSpaceId = null;
     hnswAvailable = false;
     hnswInitPromise = null;
     // R1: HDC fingerprint cache (pattern ID -> fingerprint vector)
@@ -206,6 +211,11 @@ export class PatternStore {
     async ensureHNSW() {
         // Already initialized
         if (this.hnswIndex !== null) {
+            const activeSpaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? this.config.embeddingSpaceId ?? null;
+            if (this.hnswSpaceId !== activeSpaceId) {
+                console.warn('[PatternStore] VECTOR_SPACE_MISMATCH: active embedder changed; semantic index disabled');
+                return null;
+            }
             return this.hnswIndex;
         }
         // Already marked as unavailable
@@ -234,6 +244,10 @@ export class PatternStore {
      */
     async initializeHNSWInternal() {
         try {
+            this.hnswSpaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? this.config.embeddingSpaceId ?? null;
+            if (!this.hnswSpaceId) {
+                throw new Error('VECTOR_SPACE_UNVERIFIED: cannot initialize HNSW without runtime provenance');
+            }
             // ADR-071: Use unified HNSW via bridge when flag is enabled
             const unifiedFlags = getRuVectorFeatureFlags();
             if (unifiedFlags.useUnifiedHnsw) {
@@ -302,10 +316,11 @@ export class PatternStore {
             const maxBootstrap = this.config.hnsw.maxElements;
             let loaded = 0;
             let skipped = 0;
-            for (const { patternId, embedding } of embeddings) {
+            const activeSpaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? this.config.embeddingSpaceId;
+            for (const { patternId, embedding, spaceId } of embeddings) {
                 if (loaded >= maxBootstrap)
                     break;
-                if (!embedding || embedding.length !== this.config.embeddingDimension) {
+                if (!activeSpaceId || spaceId !== activeSpaceId || !embedding || embedding.length !== this.config.embeddingDimension) {
                     skipped++;
                     continue;
                 }
@@ -429,6 +444,14 @@ 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'));
+        }
         // Check domain limit
         const domainCount = this.domainIndex.get(pattern.qeDomain)?.size || 0;
         if (domainCount >= this.config.maxPatternsPerDomain) {
@@ -437,12 +460,18 @@ 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)
         if (this.sqliteStore) {
             try {
-                const actualId = this.sqliteStore.storePattern(pattern, pattern.embedding);
+                const actualId = this.sqliteStore.storePattern(pattern, pattern.embedding, activeSpaceId);
                 // #447: ON CONFLICT(name, qe_domain, pattern_type) may preserve an
                 // existing row's id instead of the one we generated — realign the
                 // in-memory indices (and pattern.id itself) or every later
@@ -454,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
@@ -480,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));
                 }
             }
         }
@@ -703,6 +743,10 @@ export class PatternStore {
             }
             // Vector search if query is embedding and HNSW available (lazy-load)
             if (Array.isArray(query) && options.useVectorSearch !== false) {
+                const activeSpaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? this.config.embeddingSpaceId;
+                if (!activeSpaceId || options.embeddingSpaceId !== activeSpaceId) {
+                    throw new Error('VECTOR_SPACE_UNVERIFIED: pre-computed query vectors require the active embeddingSpaceId');
+                }
                 const hnsw = await this.ensureHNSW();
                 if (hnsw) {
                     const hnswResults = await hnsw.search(query, limit * 2);
@@ -1410,8 +1454,6 @@ export function createPatternStore(memory, config) {
             // Only use RVF if the data directory exists (created by kernel init).
             // Issue #516: anchor to the project root so a subfolder cwd reads/writes
             // the project's own .agentic-qe/ rather than a cwd-relative stray store.
-            const { existsSync } = require('fs');
-            const { join: joinPath } = require('path');
             const projectRoot = process.env.AQE_PROJECT_ROOT ?? findProjectRoot();
             const rvfDir = joinPath(projectRoot, '.agentic-qe');
             const rvfPath = joinPath(rvfDir, 'patterns.rvf');
@@ -1431,7 +1473,12 @@ export function createPatternStore(memory, config) {
                     const shared = getSharedRvfAdapter(rvfDir, mergedConfig.embeddingDimension);
                     if (shared) {
                         useSharedAdapter = true;
-                        const store = new RvfPatternStore(() => shared, { rvfPath, base: mergedConfig, skipCloseOnDispose: true });
+                        const store = new RvfPatternStore(() => shared, {
+                            rvfPath,
+                            base: mergedConfig,
+                            skipCloseOnDispose: true,
+                            embeddingSpaceId: mergedConfig.embeddingSpaceId,
+                        });
                         console.log('[PatternStore] Using RVF-backed store (ADR-066)');
                         return store;
                     }
@@ -1487,7 +1534,11 @@ export function createPatternStore(memory, config) {
                             }
                             throw createErr;
                         }
-                    }, { rvfPath, base: mergedConfig });
+                    }, {
+                        rvfPath,
+                        base: mergedConfig,
+                        embeddingSpaceId: mergedConfig.embeddingSpaceId,
+                    });
                     console.log('[PatternStore] Using RVF-backed store (ADR-066)');
                     return store;
                 }

package/dist/learning/qe-flywheel/coupled-anchor.d.ts

@@ -21,6 +21,7 @@
  * (the LLM step is the metered part — bind it deliberately).
  */
 import type { Database as DatabaseType } from 'better-sqlite3';
+import { type EmbeddingSpaceIdentity } from '../embedding-space.js';
 import type { RetrievalPolicy } from './policy.js';
 import type { PolicyScorer } from './generation.js';
 /** A pattern retrieved as a few-shot example for test generation. */
@@ -73,6 +74,13 @@ export interface SemanticRetrieverOptions {
     db: DatabaseType;
     /** Embed a query into the pattern-embedding space. Default: all-MiniLM-L6-v2. */
     embed?: (text: string) => Promise<number[]>;
+    /** Storage-side embedding path used by the executable round-trip canary. */
+    writeEmbed?: (text: string) => Promise<number[]>;
+    /** Runtime identities for injected embedders. Defaults to the active AQE embedder. */
+    embeddingSpace?: EmbeddingSpaceIdentity;
+    writeEmbeddingSpace?: EmbeddingSpaceIdentity;
+    /** Explicit non-semantic fallback used when provenance cannot be verified. */
+    fallback?: RetrieveFn;
     topK?: number;
 }
 /**