agentic-qe 3.15.5 → 3.15.7

package/dist/kernel/shared-dirs.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared temp/system directory detection and the per-user scratch root (#1006).
+ *
+ * AQE must never adopt or create a learning store in a directory that many
+ * unrelated runs share (the OS temp dir, `/tmp`, `/`, `/home`, ...): every
+ * project without a marker below it would then read and pollute one store.
+ *
+ * Dependency-free (fs/os/path/crypto only) so `project-root` stays light.
+ *
+ * @module kernel/shared-dirs
+ */
+/**
+ * Fixed POSIX system directories that are never a project root. A `.agentic-qe`,
+ * `.git` or `package.json` found in one of these is a stray left by another run.
+ */
+export declare const POSIX_SYSTEM_DIRS: readonly string[];
+/** Platform facts, injectable so Windows/macOS rules are testable anywhere. */
+export interface PlatformContext {
+    platform: NodeJS.Platform;
+    tmpdir: string;
+    homedir: string;
+    env: NodeJS.ProcessEnv;
+    /** Resolve symlinks and (on Windows) 8.3 short names; return input on failure. */
+    realpath: (p: string) => string;
+}
+export declare function currentPlatformContext(): PlatformContext;
+/**
+ * Canonical form for comparing two directory paths on `platform`: absolute,
+ * symlinks/8.3 names resolved, no trailing separator, and case-folded on
+ * Windows (whose file system is case-insensitive).
+ */
+export declare function normalizeForCompare(p: string, ctx?: PlatformContext): string;
+/** True when `a` and `b` name the same directory on the given platform. */
+export declare function samePath(a: string, b: string, ctx?: PlatformContext): boolean;
+/**
+ * True for a directory the project-root walk must never cross or adopt: the OS
+ * temp dir, a drive root on Windows, or a fixed POSIX system directory.
+ */
+export declare function isHardStopDir(dir: string, ctx?: PlatformContext): boolean;
+/** True for a sticky world-writable directory (mode 1777, the shape of a shared temp dir). */
+export declare function isStickyWorldWritable(dir: string, ctx?: PlatformContext): boolean;
+/**
+ * True when `dir` is shared by unrelated runs: a hard-stop directory or a
+ * sticky world-writable one. A plain chmod-777 directory (no sticky bit) is
+ * not shared: container workspaces often look like that and are real projects.
+ */
+export declare function isSharedSystemDir(dir: string, ctx?: PlatformContext): boolean;
+/**
+ * Per-user cache base for scratch roots:
+ * - Windows: `%LOCALAPPDATA%` (or `~/AppData/Local`)
+ * - macOS:   `~/Library/Caches`
+ * - other:   `$XDG_CACHE_HOME` when absolute, else `~/.cache`
+ */
+export declare function userScratchBase(ctx?: PlatformContext): string;
+/** Stable scratch-root path for `dir`: `<base>/<sha256(canonical dir) first 16 hex>`. */
+export declare function scratchRootPath(dir: string, ctx?: PlatformContext): string;
+/**
+ * Create (or reuse) the private scratch root that stands in for a shared
+ * directory with no project marker. The location is stable per user and per
+ * directory, so memory persists across runs and no new directory is minted
+ * per process; it lives outside every shared dir, so no other walk adopts it.
+ * Falls back to `<tmpdir>/agentic-qe-scratch-<uid>/<key>` (0700) when the
+ * user cache dir cannot be created.
+ */
+export declare function ensureScratchRoot(dir: string, ctx?: PlatformContext): string;
+//# sourceMappingURL=shared-dirs.d.ts.map

package/dist/kernel/shared-dirs.js

@@ -0,0 +1,180 @@
+/**
+ * Shared temp/system directory detection and the per-user scratch root (#1006).
+ *
+ * AQE must never adopt or create a learning store in a directory that many
+ * unrelated runs share (the OS temp dir, `/tmp`, `/`, `/home`, ...): every
+ * project without a marker below it would then read and pollute one store.
+ *
+ * Dependency-free (fs/os/path/crypto only) so `project-root` stays light.
+ *
+ * @module kernel/shared-dirs
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/**
+ * Fixed POSIX system directories that are never a project root. A `.agentic-qe`,
+ * `.git` or `package.json` found in one of these is a stray left by another run.
+ */
+export const POSIX_SYSTEM_DIRS = [
+    '/', '/tmp', '/var/tmp', '/usr/tmp', '/dev/shm', '/run/shm',
+    '/private', '/private/tmp', '/private/var', '/private/var/tmp',
+    '/var', '/usr', '/etc', '/opt', '/srv', '/mnt', '/media', '/run',
+    '/home', '/Users', '/Volumes',
+];
+function nativeRealpath(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch {
+        return p;
+    }
+}
+export function currentPlatformContext() {
+    let tmpdir = '';
+    let homedir = '';
+    try {
+        tmpdir = os.tmpdir();
+    }
+    catch { /* none configured */ }
+    try {
+        homedir = os.homedir();
+    }
+    catch { /* none configured */ }
+    return { platform: process.platform, tmpdir, homedir, env: process.env, realpath: nativeRealpath };
+}
+function pathApi(platform) {
+    return platform === 'win32' ? path.win32 : path.posix;
+}
+/**
+ * Canonical form for comparing two directory paths on `platform`: absolute,
+ * symlinks/8.3 names resolved, no trailing separator, and case-folded on
+ * Windows (whose file system is case-insensitive).
+ */
+export function normalizeForCompare(p, ctx = currentPlatformContext()) {
+    const api = pathApi(ctx.platform);
+    let out = api.resolve(ctx.realpath(api.resolve(p)));
+    const rootLength = api.parse(out).root.length;
+    while (out.length > rootLength && /[\\/]$/.test(out))
+        out = out.slice(0, -1);
+    return ctx.platform === 'win32' ? out.toLowerCase() : out;
+}
+/** True when `a` and `b` name the same directory on the given platform. */
+export function samePath(a, b, ctx = currentPlatformContext()) {
+    return normalizeForCompare(a, ctx) === normalizeForCompare(b, ctx);
+}
+/**
+ * True for a directory the project-root walk must never cross or adopt: the OS
+ * temp dir, a drive root on Windows, or a fixed POSIX system directory.
+ */
+export function isHardStopDir(dir, ctx = currentPlatformContext()) {
+    const api = pathApi(ctx.platform);
+    const target = normalizeForCompare(dir, ctx);
+    if (ctx.tmpdir && target === normalizeForCompare(ctx.tmpdir, ctx))
+        return true;
+    if (ctx.platform === 'win32') {
+        return target === api.parse(target).root.toLowerCase();
+    }
+    // Compare against the literal and the resolved form (macOS /tmp -> /private/tmp).
+    const literal = api.resolve(dir);
+    return POSIX_SYSTEM_DIRS.some(sys => sys === literal || normalizeForCompare(sys, ctx) === target);
+}
+/** True for a sticky world-writable directory (mode 1777, the shape of a shared temp dir). */
+export function isStickyWorldWritable(dir, ctx = currentPlatformContext()) {
+    if (ctx.platform === 'win32')
+        return false;
+    try {
+        return (fs.statSync(dir).mode & 0o1002) === 0o1002;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when `dir` is shared by unrelated runs: a hard-stop directory or a
+ * sticky world-writable one. A plain chmod-777 directory (no sticky bit) is
+ * not shared: container workspaces often look like that and are real projects.
+ */
+export function isSharedSystemDir(dir, ctx = currentPlatformContext()) {
+    return isHardStopDir(dir, ctx) || isStickyWorldWritable(dir, ctx);
+}
+/**
+ * Per-user cache base for scratch roots:
+ * - Windows: `%LOCALAPPDATA%` (or `~/AppData/Local`)
+ * - macOS:   `~/Library/Caches`
+ * - other:   `$XDG_CACHE_HOME` when absolute, else `~/.cache`
+ */
+export function userScratchBase(ctx = currentPlatformContext()) {
+    const api = pathApi(ctx.platform);
+    let base;
+    if (ctx.platform === 'win32') {
+        base = ctx.env.LOCALAPPDATA || api.join(ctx.homedir, 'AppData', 'Local');
+    }
+    else if (ctx.platform === 'darwin') {
+        base = api.join(ctx.homedir, 'Library', 'Caches');
+    }
+    else {
+        const xdg = ctx.env.XDG_CACHE_HOME;
+        base = xdg && api.isAbsolute(xdg) ? xdg : api.join(ctx.homedir, '.cache');
+    }
+    return api.join(base, 'agentic-qe', 'scratch');
+}
+/** Stable scratch-root path for `dir`: `<base>/<sha256(canonical dir) first 16 hex>`. */
+export function scratchRootPath(dir, ctx = currentPlatformContext()) {
+    const key = createHash('sha256').update(normalizeForCompare(dir, ctx)).digest('hex').slice(0, 16);
+    return pathApi(ctx.platform).join(userScratchBase(ctx), key);
+}
+function ensurePrivateDir(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32')
+        fs.chmodSync(dir, 0o700);
+}
+/**
+ * Create (or reuse) the private scratch root that stands in for a shared
+ * directory with no project marker. The location is stable per user and per
+ * directory, so memory persists across runs and no new directory is minted
+ * per process; it lives outside every shared dir, so no other walk adopts it.
+ * Falls back to `<tmpdir>/agentic-qe-scratch-<uid>/<key>` (0700) when the
+ * user cache dir cannot be created.
+ */
+export function ensureScratchRoot(dir, ctx = currentPlatformContext()) {
+    const preferred = scratchRootPath(dir, ctx);
+    try {
+        ensurePrivateDir(preferred);
+        writeOrigin(preferred, dir);
+        return preferred;
+    }
+    catch (preferredError) {
+        const uid = typeof process.getuid === 'function' ? String(process.getuid()) : 'user';
+        const fallbackBase = path.join(ctx.tmpdir || os.tmpdir(), `agentic-qe-scratch-${uid}`);
+        const fallback = path.join(fallbackBase, path.basename(preferred));
+        try {
+            ensurePrivateDir(fallbackBase);
+            ensurePrivateDir(fallback);
+            writeOrigin(fallback, dir);
+            return fallback;
+        }
+        catch (fallbackError) {
+            // Never fall back to the shared directory itself: that would mix data
+            // from unrelated projects. Give callers a usable diagnosis instead of
+            // an opaque EEXIST/ENOTDIR from the final mkdir.
+            const reason = (error) => error instanceof Error ? error.message : String(error);
+            throw new Error(`Cannot create a private AQE scratch root for "${dir}". ` +
+                `User cache "${preferred}" failed: ${reason(preferredError)}. ` +
+                `Temporary fallback "${fallback}" failed: ${reason(fallbackError)}. ` +
+                'Set AQE_PROJECT_ROOT to a project directory or make the user cache writable.');
+        }
+    }
+}
+function writeOrigin(root, dir) {
+    const origin = path.join(root, 'SCRATCH_ROOT_FOR');
+    try {
+        if (!fs.existsSync(origin))
+            fs.writeFileSync(origin, `${path.resolve(dir)}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Informational only.
+    }
+}
+//# sourceMappingURL=shared-dirs.js.map

package/dist/learning/daily-log.js

@@ -6,6 +6,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { getProjectStorePath } from '../kernel/project-root.js';
 const LOG_ICONS = {
     'pattern-learned': '\u{1F9E0}',
     'pattern-promoted': '\u2B06\uFE0F',
@@ -20,7 +21,7 @@ export class DailyLogger {
     flushTimer = null;
     constructor(config) {
         this.config = {
-            logDir: config?.logDir ?? path.join(process.cwd(), '.agentic-qe', 'logs'),
+            logDir: config?.logDir ?? getProjectStorePath('logs'),
             enabled: config?.enabled ?? true,
             maxEntriesPerDay: config?.maxEntriesPerDay ?? 500,
         };

package/dist/learning/experience-capture-middleware.d.ts

@@ -80,6 +80,28 @@ export declare function startExperience(task: string, agent: string, domain: QED
  * Record a step in an active experience
  */
 export declare function recordExperienceStep(experienceId: string, step: ExperienceStep): void;
+/**
+ * #1002: a result whose status or evidenceStatus is "insufficient-evidence"
+ * carries no verdict, so it is neither a success nor a failure to learn from.
+ * #1014: likewise a successful coverage-analysis result that is not a
+ * measurement (static estimate, unmeasured target, or no provenance).
+ * Implemented by the shared `isLearnableResult` (#1014 / #1021 dedupe, #1027 B1).
+ */
+export declare function isInsufficientEvidenceResult(result: {
+    success: boolean;
+    data?: unknown;
+}, domain?: string): boolean;
+/**
+ * #1021 round 2b: a failure caused by the caller's input (marked
+ * `callerError: true`, e.g. a target outside the project root) says nothing
+ * about the component, so it is not recorded as a failure experience.
+ */
+export declare function isCallerInputFailure(result: {
+    success: boolean;
+    data?: unknown;
+}): boolean;
+/** Drop an active experience without persisting it (no verdict to record). */
+export declare function abandonExperience(experienceId: string): boolean;
 /**
  * Complete an experience and persist to database
  */

package/dist/learning/experience-capture-middleware.js

@@ -15,6 +15,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { getUnifiedMemory } from '../kernel/unified-memory.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { createLogger } from '../logging/logger-factory.js';
+import { isLearnableResult } from './learnable-result.js';
 const ecLogger = createLogger('ExperienceCapture');
 // ============================================================================
 // Active Experience Tracking
@@ -233,6 +234,34 @@ export function recordExperienceStep(experienceId, step) {
     }
     experience.steps.push(step);
 }
+/**
+ * #1002: a result whose status or evidenceStatus is "insufficient-evidence"
+ * carries no verdict, so it is neither a success nor a failure to learn from.
+ * #1014: likewise a successful coverage-analysis result that is not a
+ * measurement (static estimate, unmeasured target, or no provenance).
+ * Implemented by the shared `isLearnableResult` (#1014 / #1021 dedupe, #1027 B1).
+ */
+export function isInsufficientEvidenceResult(result, domain) {
+    // Delegates to the shared predicate (#1014/#1021 dedupe). A FAILED
+    // coverage-analysis call is still a real failure record, so only the
+    // insufficient-evidence status applies to it.
+    if (domain === 'coverage-analysis' && !result.success)
+        return !isLearnableResult('', result.data);
+    return !isLearnableResult(domain ?? '', result.data);
+}
+/**
+ * #1021 round 2b: a failure caused by the caller's input (marked
+ * `callerError: true`, e.g. a target outside the project root) says nothing
+ * about the component, so it is not recorded as a failure experience.
+ */
+export function isCallerInputFailure(result) {
+    const data = result.data;
+    return !result.success && !!data && typeof data === 'object' && data.callerError === true;
+}
+/** Drop an active experience without persisting it (no verdict to record). */
+export function abandonExperience(experienceId) {
+    return activeExperiences.delete(experienceId);
+}
 /**
  * Complete an experience and persist to database
  */
@@ -384,6 +413,12 @@ export function wrapWithExperienceCapture(handler, domain, agent) {
             // Execute the handler
             const result = await handler(params);
             const durationMs = Date.now() - startTime;
+            // #1002/#1014: a run with no measured verdict is not recorded as success or failure.
+            if (isInsufficientEvidenceResult(result, domain) || isCallerInputFailure(result)) {
+                abandonExperience(expId);
+                ecLogger.debug('Skipped capture: insufficient evidence carries no verdict', { domain, agent });
+                return result;
+            }
             // Record execution step
             recordExperienceStep(expId, {
                 action: `execute-${domain}`,

package/dist/learning/learnable-result.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Agentic QE v3 - Which tool results may become learning (#1014)
+ *
+ * A tool run that produced no evidence must not be learned from as if it did:
+ *
+ *   - coverage-analysis results are learnable only when they are MEASURED
+ *     (`measured === true`). A static estimate or an UNMEASURED target is a
+ *     hypothesis / an absence — learning from it records invented coverage in
+ *     coverage_sessions, captured experiences and pattern-usage success;
+ *   - any result whose status is `insufficient-evidence` (quality gate without
+ *     measured evidence) is not a success to learn from.
+ *
+ * Fail-closed: a coverage result without provenance is not learnable.
+ */
+export declare function isLearnableResult(domain: string, data: unknown): boolean;
+//# sourceMappingURL=learnable-result.d.ts.map

package/dist/learning/learnable-result.js

@@ -0,0 +1,24 @@
+/**
+ * Agentic QE v3 - Which tool results may become learning (#1014)
+ *
+ * A tool run that produced no evidence must not be learned from as if it did:
+ *
+ *   - coverage-analysis results are learnable only when they are MEASURED
+ *     (`measured === true`). A static estimate or an UNMEASURED target is a
+ *     hypothesis / an absence — learning from it records invented coverage in
+ *     coverage_sessions, captured experiences and pattern-usage success;
+ *   - any result whose status is `insufficient-evidence` (quality gate without
+ *     measured evidence) is not a success to learn from.
+ *
+ * Fail-closed: a coverage result without provenance is not learnable.
+ */
+const INSUFFICIENT = 'insufficient-evidence';
+export function isLearnableResult(domain, data) {
+    const record = data && typeof data === 'object' ? data : null;
+    if (record && (record.status === INSUFFICIENT || record.evidenceStatus === INSUFFICIENT))
+        return false;
+    if (domain === 'coverage-analysis')
+        return record?.measured === true;
+    return true;
+}
+//# sourceMappingURL=learnable-result.js.map

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

@@ -6,4 +6,12 @@ export declare class PatternMutationError extends Error {
     readonly cause: unknown;
     constructor(patternId: string, disposition: PatternMutationDisposition, cause: unknown);
 }
+/**
+ * The pattern id when `error` proves the authoritative SQLite row committed and
+ * only the derived vector index (HNSW/RVF) is pending, e.g. no embedding runtime
+ * was available (#981). Callers treat that as a stored pattern whose vector can
+ * be filled later by `aqe learning backfill-embeddings`. Any other error,
+ * including a `FAILED` disposition, returns null.
+ */
+export declare function committedPendingIndexPatternId(error: unknown): string | null;
 //# sourceMappingURL=pattern-mutation-error.d.ts.map

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

@@ -11,4 +11,16 @@ export class PatternMutationError extends Error {
         this.cause = cause;
     }
 }
+/**
+ * The pattern id when `error` proves the authoritative SQLite row committed and
+ * only the derived vector index (HNSW/RVF) is pending, e.g. no embedding runtime
+ * was available (#981). Callers treat that as a stored pattern whose vector can
+ * be filled later by `aqe learning backfill-embeddings`. Any other error,
+ * including a `FAILED` disposition, returns null.
+ */
+export function committedPendingIndexPatternId(error) {
+    return error instanceof PatternMutationError && error.disposition === 'COMMITTED_PENDING_INDEX'
+        ? error.patternId
+        : null;
+}
 //# sourceMappingURL=pattern-mutation-error.js.map

package/dist/learning/qe-reasoning-bank.d.ts

@@ -19,6 +19,7 @@ import { QEPattern, QEPatternContext, QEDomain, ProgrammingLanguage, TestFramewo
 import { QEGuidance } from './qe-guidance.js';
 import { PatternSearchOptions, PatternSearchResult } from './pattern-store.js';
 import type { RvfDualWriter } from '../integrations/ruvector/rvf-dual-writer.js';
+import { type RvfReconcileResult } from './rvf-reconcile.js';
 import type { QEReasoningBankConfig, QERoutingRequest, QERoutingResult, LearningOutcome, IQEReasoningBank, QEReasoningBankStats } from './qe-reasoning-bank-types.js';
 /**
  * QE ReasoningBank - Pattern learning for quality engineering
@@ -76,6 +77,15 @@ export declare class QEReasoningBank implements IQEReasoningBank {
     initialize(options?: {
         signal?: AbortSignal;
     }): Promise<void>;
+    /** Result of the last RVF↔SQLite vector reconcile (#981 review B2). */
+    private lastVectorReconcile;
+    getLastVectorReconcile(): RvfReconcileResult | null;
+    /**
+     * Ingest SQLite vectors of the active embedding space that the RVF index
+     * does not hold yet (#981 review B2). Idempotent and capped per pass by
+     * AQE_RVF_BACKFILL_LIMIT (default 1000). Non-fatal.
+     */
+    reconcileVectorIndex(): RvfReconcileResult | null;
     /**
      * Load pre-trained patterns for common QE scenarios
      */

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 { reconcileRvfWithSqlite } from './rvf-reconcile.js';
 import { PatternMutationError } from './pattern-mutation-error.js';
 // Import extracted modules
 import { DEFAULT_QE_REASONING_BANK_CONFIG } from './qe-reasoning-bank-types.js';
@@ -174,6 +175,36 @@ export class QEReasoningBank {
         }
         logger.info('Initialized');
     }
+    /** Result of the last RVF↔SQLite vector reconcile (#981 review B2). */
+    lastVectorReconcile = null;
+    getLastVectorReconcile() {
+        return this.lastVectorReconcile;
+    }
+    /**
+     * Ingest SQLite vectors of the active embedding space that the RVF index
+     * does not hold yet (#981 review B2). Idempotent and capped per pass by
+     * AQE_RVF_BACKFILL_LIMIT (default 1000). Non-fatal.
+     */
+    reconcileVectorIndex() {
+        const adapter = this.patternStore.getAdapter?.();
+        const spaceId = getActiveEmbeddingSpaceIdentity()?.spaceId;
+        if (!adapter || !spaceId)
+            return null;
+        try {
+            const env = Number(process.env.AQE_RVF_BACKFILL_LIMIT);
+            const limit = Number.isFinite(env) && env > 0 ? Math.floor(env) : 1000;
+            const result = reconcileRvfWithSqlite(adapter, this.getSqliteStore(), spaceId, limit);
+            if (result.missing > 0) {
+                logger.info('Reconciled RVF index with SQLite vectors', { ...result });
+            }
+            this.lastVectorReconcile = result;
+            return result;
+        }
+        catch (err) {
+            logger.warn('RVF reconcile failed (non-fatal)', { error: toErrorMessage(err) });
+            return null;
+        }
+    }
     /**
      * Load pre-trained patterns for common QE scenarios
      */
@@ -229,6 +260,12 @@ export class QEReasoningBank {
                     logger.warn('RVF backfill failed (non-fatal)', { error: toErrorMessage(err) });
                 }
             }
+            else if (adapter) {
+                // #981 review B2: a non-empty index can still lag SQLite, e.g. after
+                // `aqe learning backfill-embeddings` filled vectors for patterns that
+                // were learned text-only. Ingest exactly the missing active-space ids.
+                this.reconcileVectorIndex();
+            }
             return;
         }
         // Use storePattern() (not patternStore.create() directly) so that:
@@ -280,7 +317,19 @@ export class QEReasoningBank {
         // Generate embedding if not provided
         if (!options.embedding) {
             const embedding = await this.embed(`${options.name} ${options.description} ${options.context?.tags?.join(' ') || ''}`);
-            options = { ...options, embedding };
+            // #981: with no embedding runtime, embed() returns a hash-fallback vector
+            // that has no embedding-space provenance, and the pattern store refuses
+            // to persist it (VECTOR_SPACE_UNVERIFIED), losing the pattern. Store it
+            // text-only instead, as search already does for such vectors; the vector
+            // is filled later by `aqe learning backfill-embeddings`.
+            const hasProvenance = this.embeddingProvenance.has(embedding)
+                || Boolean(getActiveEmbeddingSpaceIdentity()?.spaceId);
+            if (hasProvenance) {
+                options = { ...options, embedding };
+            }
+            else {
+                logger.debug('No embedding runtime provenance; storing pattern without a vector', { name: options.name });
+            }
         }
         const result = await this.patternStore.create(options);
         // A pending-index error still proves the authoritative SQLite mutation

package/dist/learning/rvf-reconcile.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reconcile the derived RVF vector index with authoritative SQLite vectors
+ * (#981 review B2).
+ *
+ * `aqe learning backfill-embeddings` and any other SQLite-only vector write
+ * leave patterns.rvf behind. The original re-ingest only ran while the index
+ * was empty, so a single pattern learned with an embedder blocked every later
+ * backfill from reaching vector search. This pass ingests exactly the vectors
+ * that are in SQLite for the active embedding space but not in the index.
+ */
+import type { RvfNativeAdapter } from '../integrations/ruvector/rvf-native-adapter.js';
+export interface RvfReconcileSource {
+    /** Pattern ids with a stored vector in `spaceId`; `ordered`: most recently used first. */
+    getEmbeddingIdsInSpace(spaceId: string, options?: {
+        ordered?: boolean;
+    }): string[];
+    /** Stored vectors for `ids`. */
+    getEmbeddingsByIds(ids: string[]): Array<{
+        patternId: string;
+        embedding: number[];
+    }>;
+}
+export type RvfReconcileTarget = Pick<RvfNativeAdapter, 'ingest'> & Partial<Pick<RvfNativeAdapter, 'has'>>;
+export interface RvfReconcileResult {
+    /** SQLite vectors in the active space that the index did not hold. */
+    missing: number;
+    ingested: number;
+    rejected: number;
+    /** True when `missing` exceeded `limit` and the rest waits for a later pass. */
+    capped: boolean;
+}
+/**
+ * Ingest SQLite vectors (active space only) missing from the RVF index.
+ * Idempotent: ids the index already holds are skipped, so repeated runs add
+ * nothing. An adapter without `has()` cannot be reconciled safely (ingest is
+ * not idempotent), so the pass is skipped.
+ */
+export declare function reconcileRvfWithSqlite(adapter: RvfReconcileTarget, sqlite: RvfReconcileSource, activeSpaceId: string, limit: number): RvfReconcileResult;
+//# sourceMappingURL=rvf-reconcile.d.ts.map

package/dist/learning/rvf-reconcile.js

@@ -0,0 +1,40 @@
+/**
+ * Reconcile the derived RVF vector index with authoritative SQLite vectors
+ * (#981 review B2).
+ *
+ * `aqe learning backfill-embeddings` and any other SQLite-only vector write
+ * leave patterns.rvf behind. The original re-ingest only ran while the index
+ * was empty, so a single pattern learned with an embedder blocked every later
+ * backfill from reaching vector search. This pass ingests exactly the vectors
+ * that are in SQLite for the active embedding space but not in the index.
+ */
+/**
+ * Ingest SQLite vectors (active space only) missing from the RVF index.
+ * Idempotent: ids the index already holds are skipped, so repeated runs add
+ * nothing. An adapter without `has()` cannot be reconciled safely (ingest is
+ * not idempotent), so the pass is skipped.
+ */
+export function reconcileRvfWithSqlite(adapter, sqlite, activeSpaceId, limit) {
+    const none = { missing: 0, ingested: 0, rejected: 0, capped: false };
+    if (typeof adapter.has !== 'function')
+        return none;
+    // Cheap no-op path first: an unordered id scan + has() per id. The ordered
+    // (join + sort) query runs only when one pass cannot ingest everything and
+    // the most recently used vectors should go first.
+    const missing = (ids) => ids.filter((id) => !adapter.has(id));
+    let missingIds = missing(sqlite.getEmbeddingIdsInSpace(activeSpaceId));
+    if (missingIds.length === 0)
+        return none;
+    const cap = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 1000;
+    if (missingIds.length > cap) {
+        missingIds = missing(sqlite.getEmbeddingIdsInSpace(activeSpaceId, { ordered: true }));
+    }
+    const batchIds = missingIds.slice(0, cap);
+    const vectors = sqlite
+        .getEmbeddingsByIds(batchIds)
+        .filter(({ embedding }) => embedding && embedding.length > 0)
+        .map(({ patternId, embedding }) => ({ id: patternId, vector: new Float32Array(embedding) }));
+    const { accepted, rejected } = vectors.length > 0 ? adapter.ingest(vectors) : { accepted: 0, rejected: 0 };
+    return { missing: missingIds.length, ingested: accepted, rejected, capped: missingIds.length > cap };
+}
+//# sourceMappingURL=rvf-reconcile.js.map

package/dist/learning/sqlite-persistence.d.ts

@@ -124,6 +124,20 @@ export declare class SQLitePatternStore {
         embedding: number[];
         spaceId: string | null;
     }>;
+    /**
+     * Pattern ids that have a stored vector in `spaceId` (#981 review B2: find
+     * vectors the RVF index is missing). Unordered by default, which is a plain
+     * indexed scan; `ordered` returns most recently used first (join + sort),
+     * which the reconcile only needs when more ids are missing than one pass ingests.
+     */
+    getEmbeddingIdsInSpace(spaceId: string, options?: {
+        ordered?: boolean;
+    }): string[];
+    /** Stored vectors for the given pattern ids (#981 review B2). */
+    getEmbeddingsByIds(ids: string[]): Array<{
+        patternId: string;
+        embedding: number[];
+    }>;
     /**
      * Get up to `limit` embeddings, most-recently-used first.
      *