ghagga-core 3.0.0 → 3.2.0

package/dist/memory/sqlite.d.ts

@@ -20,6 +20,23 @@ export interface SqliteMemoryStorageOptions {
      * is used for search. When undefined, falls back to keyword-only search.
      */
     embeddingProvider?: EmbeddingProvider;
+    /**
+     * Identifier for the active embedding model (e.g. "text-embedding-3-small").
+     * Persisted per-row alongside the vector and compared on read (design D3).
+     *
+     * NOTE: `EmbeddingProvider` (packages/core/src/embed.ts) does not currently
+     * expose a model name, so this is supplied by the caller out-of-band. When
+     * omitted, the read guard only enforces dimension compatibility (never
+     * throws either way) — the model-mismatch check is a no-op until callers
+     * start passing it (wired in PR5).
+     */
+    embeddingModel?: string;
+    /**
+     * Bounded cosine candidate set size (design D4). Defaults to 200.
+     * Callers should pass `resolveEmbeddingConfig(env).candidateK` (PR1) rather
+     * than relying on this default once wired (PR5).
+     */
+    embeddingCandidateK?: number;
 }
 export declare class SqliteMemoryStorage implements MemoryStorage {
     private db;
@@ -27,6 +44,8 @@ export declare class SqliteMemoryStorage implements MemoryStorage {
     private dedupWindowMinutes;
     private decayConfig;
     private embeddingProvider;
+    private embeddingModel;
+    private embeddingCandidateK;
     private pageIndex;
     private constructor();
     /**
@@ -50,16 +69,26 @@ export declare class SqliteMemoryStorage implements MemoryStorage {
         type?: string;
     }): Promise<MemoryObservationRow[]>;
     /**
-     * Hybrid BM25 + semantic search (70% semantic, 30% keyword).
-     * Only called when embeddingProvider is set.
+     * Hybrid keyword + semantic search: unions a bounded cosine candidate set
+     * with the keyword (FTS5) candidate set before scoring (spec R5.7-R5.10,
+     * design D4/D5). Only called when embeddingProvider is set.
      *
      * Strategy:
-     *   1. Run FTS5 to get keyword candidates (up to limit * 5 to have enough for re-ranking)
-     *   2. Embed the query
-     *   3. For each candidate, deserialize its stored embedding and compute cosine similarity
-     *   4. Candidates without embeddings get cosine_sim = 0 (keyword-only score still applies)
-     *   5. Combine: final_score = 0.7 * cosine_sim + 0.3 * normalized_bm25
-     *   6. Sort descending, apply decay filter, return top-k
+     *   1. Run FTS5 to get keyword candidates (up to limit * 5), preserving
+     *      native bm25() order (best match first).
+     *   2. Run a bounded, project(+type)-scoped cosine candidate query
+     *      (embedding IS NOT NULL, ORDER BY last_accessed_at DESC LIMIT K).
+     *   3. Compute cosine similarity in JS for candidates that pass the
+     *      dimension/model read guard (mismatches are excluded, never thrown).
+     *   4. Union both sets by id, dedup: an overlapping candidate keeps its
+     *      real keyword score; a cosine-only candidate gets keyword-score 0.
+     *   5. Keyword score uses the unified positional-rank convention
+     *      `1 - i/(n-1)` over the keyword-ordered list (design D5) — shared
+     *      with the PostgreSQL backend so both engines score identically
+     *      post-union.
+     *   6. Combine: finalScore = 0.7 * cosineSim + 0.3 * keywordScore.
+     *   7. Apply the decay filter, sort descending, cap at limit, update
+     *      last_accessed_at only for the rows actually returned (R5.10).
      */
     private _hybridSearch;
     saveObservation(data: {
@@ -73,11 +102,14 @@ export declare class SqliteMemoryStorage implements MemoryStorage {
         severity?: string;
     }): Promise<MemoryObservationRow>;
     /**
-     * Compute embedding buffer for storage.
-     * Returns the serialized float32 Buffer when embeddingProvider is available,
-     * or null (no-op) when it is not — enabling graceful degradation.
+     * Compute the embedding buffer plus its provider metadata for storage
+     * (design D3 — per-row `embedding_model`/`embedding_dim`, task 3.6).
+     * Returns all-null when no embeddingProvider is configured (no-op) or when
+     * embedding generation fails — a failed embed is non-fatal: the row is
+     * still saved with a NULL embedding rather than throwing (spec: Graceful
+     * Degradation on Provider/API Failure).
      */
-    private _computeEmbeddingBuffer;
+    private _computeEmbeddingMeta;
     createSession(data: {
         project: string;
         prNumber?: number;
@@ -125,6 +157,40 @@ export declare class SqliteMemoryStorage implements MemoryStorage {
      * Returns true if a row was deleted, false otherwise.
      */
     deleteNegativeExample(findingHash: string): boolean;
+    /**
+     * Export the in-memory WASM database and write it to disk WITHOUT closing
+     * the underlying handle — shared by close() and flush() (design D6).
+     */
+    private _writeToDisk;
+    /**
+     * Durability hook for the backfill script (design D6, task 6.1): flushes
+     * the in-memory WASM database to disk after each batch so a mid-run crash
+     * loses at most the in-flight batch, not prior progress. Unlike close(),
+     * the database handle stays open and usable.
+     */
+    flush(): Promise<void>;
     close(): Promise<void>;
+    /**
+     * List up to `limit` observations needing an embedding for the active
+     * provider/model, ordered by id ascending starting after `afterId`.
+     * Always matches NULL-embedding rows; with `includeMismatched` also
+     * matches rows whose stored `embedding_model`/`embedding_dim` disagree
+     * with the active provider (backfill `--re-embed`).
+     */
+    listObservationsNeedingEmbedding(options: {
+        afterId: number;
+        limit: number;
+        activeModel: string;
+        activeDim: number;
+        includeMismatched: boolean;
+    }): Promise<{
+        id: number;
+        text: string;
+    }[]>;
+    /**
+     * Persist a backfilled embedding for a single observation (design D6).
+     * Metadata-only write — content/updated_at/last_accessed_at are untouched.
+     */
+    updateObservationEmbedding(id: number, embedding: number[], model: string, dim: number): Promise<void>;
 }
 //# sourceMappingURL=sqlite.d.ts.map

package/dist/memory/sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/memory/sqlite.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/memory/sqlite.ts"],"names":[],"mappings":"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"}

package/dist/memory/sqlite.js

@@ -45,7 +45,9 @@ const SCHEMA_SQL = `
     revision_count INTEGER NOT NULL DEFAULT 1,
     created_at TEXT NOT NULL DEFAULT (datetime('now')),
     updated_at TEXT NOT NULL DEFAULT (datetime('now')),
-    last_accessed_at TEXT NOT NULL DEFAULT (datetime('now'))
+    last_accessed_at TEXT NOT NULL DEFAULT (datetime('now')),
+    embedding_model TEXT,
+    embedding_dim INTEGER
   );
 
   CREATE INDEX IF NOT EXISTS idx_obs_project ON memory_observations(project);
@@ -124,6 +126,8 @@ const SCHEMA_SQL = `
   CREATE INDEX IF NOT EXISTS idx_neg_context_hash ON negative_examples(context_hash);
 `;
 const DEFAULT_DEDUP_WINDOW_MINUTES = 15;
+/** Default bounded cosine candidate set size (design D4) when not configured. */
+const DEFAULT_EMBEDDING_CANDIDATE_K = 200;
 /**
  * Runs an ADD COLUMN migration idempotently.
  * Swallows 'duplicate column name' (migration already ran) and rethrows
@@ -146,6 +150,8 @@ export class SqliteMemoryStorage {
     dedupWindowMinutes;
     decayConfig;
     embeddingProvider;
+    embeddingModel;
+    embeddingCandidateK;
     pageIndex;
     constructor(db, filePath, options = {}) {
         this.db = db;
@@ -153,6 +159,8 @@ export class SqliteMemoryStorage {
         this.dedupWindowMinutes = options.dedupWindowMinutes ?? DEFAULT_DEDUP_WINDOW_MINUTES;
         this.decayConfig = options.decayConfig ?? DEFAULT_DECAY_CONFIG;
         this.embeddingProvider = options.embeddingProvider;
+        this.embeddingModel = options.embeddingModel;
+        this.embeddingCandidateK = options.embeddingCandidateK ?? DEFAULT_EMBEDDING_CANDIDATE_K;
         this.pageIndex = new ProjectPageIndexService(this.db);
     }
     /**
@@ -199,11 +207,22 @@ export class SqliteMemoryStorage {
         db.run('CREATE INDEX IF NOT EXISTS idx_obs_last_accessed ON memory_observations(last_accessed_at)');
         // Migration: add embedding column for hybrid search (NULL when no embedding provider)
         runIdempotentAlter(db, 'ALTER TABLE memory_observations ADD COLUMN embedding BLOB');
+        // Migration: add per-row embedding provider metadata (NULL when embedding is NULL).
+        // Used by the read guard to detect provider/dimension mismatches (design D3).
+        runIdempotentAlter(db, 'ALTER TABLE memory_observations ADD COLUMN embedding_model TEXT');
+        runIdempotentAlter(db, 'ALTER TABLE memory_observations ADD COLUMN embedding_dim INTEGER');
         return new SqliteMemoryStorage(db, filePath, options);
     }
     async searchObservations(project, query, options = {}) {
         const { limit = 10, type } = options;
-        // ── Hybrid search (BM25 + semantic) ──────────────────────────
+        // ── Hybrid search (BM25 + semantic RE-RANKING) ───────────────
+        // NOTE (MEM-HYBRID-006): this is semantic *re-ranking* of a keyword
+        // candidate set, NOT pure semantic retrieval. Even with an embedding
+        // provider, candidates are first gated by the FTS5 MATCH below, so an
+        // observation with no lexical overlap with the query is never a candidate
+        // and cannot be surfaced by embedding similarity alone (e.g. "secret
+        // leakage" will not recall a "credential exposure" note). Closing this
+        // would require unioning an ANN/vector candidate set with the keyword set.
         if (this.embeddingProvider) {
             return this._hybridSearch(project, query, { limit, type });
         }
@@ -268,19 +287,32 @@ export class SqliteMemoryStorage {
         return rows;
     }
     /**
-     * Hybrid BM25 + semantic search (70% semantic, 30% keyword).
-     * Only called when embeddingProvider is set.
+     * Hybrid keyword + semantic search: unions a bounded cosine candidate set
+     * with the keyword (FTS5) candidate set before scoring (spec R5.7-R5.10,
+     * design D4/D5). Only called when embeddingProvider is set.
      *
      * Strategy:
-     *   1. Run FTS5 to get keyword candidates (up to limit * 5 to have enough for re-ranking)
-     *   2. Embed the query
-     *   3. For each candidate, deserialize its stored embedding and compute cosine similarity
-     *   4. Candidates without embeddings get cosine_sim = 0 (keyword-only score still applies)
-     *   5. Combine: final_score = 0.7 * cosine_sim + 0.3 * normalized_bm25
-     *   6. Sort descending, apply decay filter, return top-k
+     *   1. Run FTS5 to get keyword candidates (up to limit * 5), preserving
+     *      native bm25() order (best match first).
+     *   2. Run a bounded, project(+type)-scoped cosine candidate query
+     *      (embedding IS NOT NULL, ORDER BY last_accessed_at DESC LIMIT K).
+     *   3. Compute cosine similarity in JS for candidates that pass the
+     *      dimension/model read guard (mismatches are excluded, never thrown).
+     *   4. Union both sets by id, dedup: an overlapping candidate keeps its
+     *      real keyword score; a cosine-only candidate gets keyword-score 0.
+     *   5. Keyword score uses the unified positional-rank convention
+     *      `1 - i/(n-1)` over the keyword-ordered list (design D5) — shared
+     *      with the PostgreSQL backend so both engines score identically
+     *      post-union.
+     *   6. Combine: finalScore = 0.7 * cosineSim + 0.3 * keywordScore.
+     *   7. Apply the decay filter, sort descending, cap at limit, update
+     *      last_accessed_at only for the rows actually returned (R5.10).
      */
     async _hybridSearch(project, query, options) {
         const { limit, type } = options;
+        const provider = this.embeddingProvider;
+        if (!provider)
+            return [];
         const ftsQuery = query
             .trim()
             .split(/\s+/)
@@ -291,80 +323,149 @@ export class SqliteMemoryStorage {
             return [];
         // Fetch a larger candidate set for re-ranking
         const fetchLimit = limit * 5;
-        let sql = `
+        const mapCandidateRow = (row) => ({
+            id: row.id,
+            type: row.type,
+            title: row.title,
+            content: row.content,
+            filePaths: row.file_paths ? JSON.parse(row.file_paths) : null,
+            severity: row.severity ?? null,
+            lastAccessed: row.last_accessed_at ? new Date(row.last_accessed_at) : new Date(),
+            embedding: row.embedding ? row.embedding : null,
+            embeddingModel: row.embedding_model ?? null,
+            embeddingDim: row.embedding_dim ?? null,
+        });
+        // ── Step 1: keyword candidates (FTS5, unchanged gate) ────────────
+        let keywordSql = `
       SELECT o.id, o.type, o.title, o.content, o.file_paths, o.severity,
-             o.last_accessed_at, o.embedding,
-             bm25(memory_observations_fts) AS bm25_score
+             o.last_accessed_at, o.embedding, o.embedding_model, o.embedding_dim
       FROM memory_observations o
       JOIN memory_observations_fts fts ON fts.rowid = o.id
       WHERE memory_observations_fts MATCH ?
         AND o.project = ?
     `;
-        const params = [ftsQuery, project];
+        const keywordParams = [ftsQuery, project];
         if (type) {
-            sql += ' AND o.type = ?';
-            params.push(type);
+            keywordSql += ' AND o.type = ?';
+            keywordParams.push(type);
         }
-        sql += ' ORDER BY bm25(memory_observations_fts) LIMIT ?';
-        params.push(fetchLimit);
-        const stmt = this.db.prepare(sql);
-        stmt.bind(params);
-        const candidates = [];
-        while (stmt.step()) {
-            const row = stmt.getAsObject();
-            candidates.push({
-                id: row.id,
-                type: row.type,
-                title: row.title,
-                content: row.content,
-                filePaths: row.file_paths ? JSON.parse(row.file_paths) : null,
-                severity: row.severity ?? null,
-                lastAccessed: row.last_accessed_at ? new Date(row.last_accessed_at) : new Date(),
-                embedding: row.embedding ? row.embedding : null,
-                bm25Score: row.bm25_score,
+        keywordSql += ' ORDER BY bm25(memory_observations_fts) LIMIT ?';
+        keywordParams.push(fetchLimit);
+        const keywordStmt = this.db.prepare(keywordSql);
+        keywordStmt.bind(keywordParams);
+        const keywordCandidates = [];
+        while (keywordStmt.step()) {
+            keywordCandidates.push(mapCandidateRow(keywordStmt.getAsObject()));
+        }
+        keywordStmt.free();
+        // ── Step 2: bounded cosine candidates (spec R5.7, design D4) ─────
+        let cosineSql = `
+      SELECT o.id, o.type, o.title, o.content, o.file_paths, o.severity,
+             o.last_accessed_at, o.embedding, o.embedding_model, o.embedding_dim
+      FROM memory_observations o
+      WHERE o.project = ?
+        AND o.embedding IS NOT NULL
+    `;
+        const cosineParams = [project];
+        if (type) {
+            cosineSql += ' AND o.type = ?';
+            cosineParams.push(type);
+        }
+        cosineSql += ' ORDER BY o.last_accessed_at DESC LIMIT ?';
+        cosineParams.push(this.embeddingCandidateK);
+        const cosineStmt = this.db.prepare(cosineSql);
+        cosineStmt.bind(cosineParams);
+        const cosineBoundedCandidates = [];
+        while (cosineStmt.step()) {
+            cosineBoundedCandidates.push(mapCandidateRow(cosineStmt.getAsObject()));
+        }
+        cosineStmt.free();
+        if (keywordCandidates.length === 0 && cosineBoundedCandidates.length === 0)
+            return [];
+        // Compute query embedding once. A query-time embed failure is non-fatal
+        // (spec: Graceful Degradation on Provider/API Failure): warn once and fall
+        // back to keyword-only for this query. `queryVec === null` makes every
+        // cosine 0 and empties the cosine-only candidate set, so the union/decay/cap
+        // pipeline below runs over the keyword candidates alone — unchanged.
+        let queryVec;
+        try {
+            queryVec = await provider.embed(query);
+        }
+        catch (error) {
+            console.warn(`[ghagga] query embedding failed — degrading to keyword-only for this search: ${error instanceof Error ? error.message : String(error)}`);
+            queryVec = null;
+        }
+        // Dimension/model read guard (design D3): a row whose stored dimension or
+        // model doesn't match the active provider is excluded from the cosine set
+        // (task 3.2) — mirrors the pre-existing "no embedding → cosine 0" rule.
+        // `this.embeddingModel` may be undefined (EmbeddingProvider does not yet
+        // expose a model name) — when undefined, only dimension is enforced.
+        const isEmbeddingUsable = (row) => {
+            if (!row.embedding)
+                return false;
+            if (row.embeddingDim !== null && row.embeddingDim !== provider.dimension)
+                return false;
+            if (this.embeddingModel !== undefined && row.embeddingModel !== this.embeddingModel) {
+                return false;
+            }
+            return true;
+        };
+        const computeCosine = (row) => {
+            if (queryVec === null || !row.embedding || !isEmbeddingUsable(row))
+                return 0;
+            try {
+                const storedVec = deserializeEmbedding(row.embedding);
+                if (storedVec.length !== queryVec.length)
+                    return 0;
+                return cosineSimilarity(queryVec, storedVec);
+            }
+            catch {
+                // Malformed embedding — treat as 0
+                return 0;
+            }
+        };
+        // ── Step 3: unified positional-rank keyword score (design D5) ────
+        // keywordCandidates is already ordered by bm25() ASC (best match first).
+        const n = keywordCandidates.length;
+        const keywordScoreById = new Map();
+        keywordCandidates.forEach((candidate, i) => {
+            keywordScoreById.set(candidate.id, n > 1 ? 1 - i / (n - 1) : 1);
+        });
+        // ── Step 4: cosine similarity, top limit*5 of the GUARDED set ────
+        // When the query embed failed (queryVec === null), there are no cosine
+        // candidates — the union below sees keyword candidates only.
+        const cosineTop = queryVec === null
+            ? []
+            : cosineBoundedCandidates
+                .filter(isEmbeddingUsable)
+                .map((candidate) => ({ candidate, cosineSim: computeCosine(candidate) }))
+                .sort((a, b) => b.cosineSim - a.cosineSim)
+                .slice(0, fetchLimit);
+        const merged = new Map();
+        for (const candidate of keywordCandidates) {
+            merged.set(candidate.id, {
+                candidate,
+                cosineSim: computeCosine(candidate),
+                keywordScore: keywordScoreById.get(candidate.id) ?? 0,
             });
         }
-        stmt.free();
-        if (candidates.length === 0)
+        for (const { candidate, cosineSim } of cosineTop) {
+            if (merged.has(candidate.id))
+                continue; // keep the real keyword score (R5.8)
+            merged.set(candidate.id, { candidate, cosineSim, keywordScore: 0 }); // vector-only (R5.9)
+        }
+        if (merged.size === 0)
             return [];
-        // Compute query embedding
-        // biome-ignore lint/style/noNonNullAssertion: embeddingProvider is checked by the caller (_hybridSearch is only called when it's set)
-        const queryVec = await this.embeddingProvider.embed(query);
-        // BM25 scores from FTS5 are negative (lower = better match).
-        // Normalize to [0, 1]: higher is better.
-        const bm25Scores = candidates.map((c) => c.bm25Score);
-        const minBm25 = Math.min(...bm25Scores);
-        const maxBm25 = Math.max(...bm25Scores);
-        const bm25Range = maxBm25 - minBm25;
+        // ── Step 6: score, decay filter, sort, cap (spec R5.5/R5.8) ──────
         const now = new Date();
         const scored = [];
-        for (const candidate of candidates) {
+        for (const { candidate, cosineSim, keywordScore } of merged.values()) {
             const strength = computeStrength(candidate.lastAccessed, now, this.decayConfig);
             if (strength < this.decayConfig.minStrength)
                 continue;
-            // Normalize BM25 to [0, 1]. FTS5 bm25() is MORE NEGATIVE = BETTER match,
-            // so the best candidate (minBm25) must map to 1 and the worst (maxBm25) to 0.
-            const normalizedBm25 = bm25Range === 0 ? 1 : (maxBm25 - candidate.bm25Score) / bm25Range;
-            // Cosine similarity from stored embedding (0 if not present)
-            let cosineSim = 0;
-            if (candidate.embedding) {
-                try {
-                    const storedVec = deserializeEmbedding(candidate.embedding);
-                    // Dimension guard: a stored vector from a different embedding model
-                    // is meaningless against this query — skip cosine (mirror queries.ts)
-                    if (storedVec.length === queryVec.length) {
-                        cosineSim = cosineSimilarity(queryVec, storedVec);
-                    }
-                }
-                catch {
-                    // Malformed embedding — treat as 0
-                }
-            }
-            // 70/30 weighted combination
-            const finalScore = 0.7 * cosineSim + 0.3 * normalizedBm25;
+            const finalScore = 0.7 * cosineSim + 0.3 * keywordScore;
             scored.push({ candidate, finalScore, strength });
         }
-        // Sort by final score descending
         scored.sort((a, b) => b.finalScore - a.finalScore);
         const results = [];
         const accessedIds = [];
@@ -382,7 +483,7 @@ export class SqliteMemoryStorage {
                 strength,
             });
         }
-        // Update last_accessed_at for returned observations
+        // Update last_accessed_at only for the final returned rows (R5.10)
         if (accessedIds.length > 0) {
             const placeholders = accessedIds.map(() => '?').join(',');
             this.db.run(`UPDATE memory_observations SET last_accessed_at = datetime('now') WHERE id IN (${placeholders})`, accessedIds);
@@ -432,12 +533,12 @@ export class SqliteMemoryStorage {
             if (existingByTopic.length > 0 && existingByTopic[0]?.values.length > 0) {
                 const existingId = existingByTopic[0]?.values[0]?.[0];
                 const filePathsJson = JSON.stringify(data.filePaths ?? []);
-                // Compute and store embedding if provider available
-                const embeddingBuf = await this._computeEmbeddingBuffer(`${data.title} ${data.content}`);
+                // Compute and store embedding + its provider metadata if provider available
+                const embeddingMeta = await this._computeEmbeddingMeta(`${data.title} ${data.content}`);
                 const updated = this.db.exec(`
           UPDATE memory_observations
           SET content = ?, title = ?, content_hash = ?, file_paths = ?,
-              severity = ?, embedding = ?,
+              severity = ?, embedding = ?, embedding_model = ?, embedding_dim = ?,
               revision_count = revision_count + 1,
               updated_at = datetime('now'),
               last_accessed_at = datetime('now')
@@ -449,7 +550,9 @@ export class SqliteMemoryStorage {
                     contentHash,
                     filePathsJson,
                     data.severity ?? null,
-                    embeddingBuf,
+                    embeddingMeta.buffer,
+                    embeddingMeta.model,
+                    embeddingMeta.dim,
                     existingId,
                 ]);
                 const row = updated[0]?.values[0];
@@ -465,13 +568,14 @@ export class SqliteMemoryStorage {
                 };
             }
         }
-        // New observation — compute embedding if provider available
-        const embeddingBuf = await this._computeEmbeddingBuffer(`${data.title} ${data.content}`);
+        // New observation — compute embedding + its provider metadata if provider available
+        const embeddingMeta = await this._computeEmbeddingMeta(`${data.title} ${data.content}`);
         const filePathsJson = JSON.stringify(data.filePaths ?? []);
         const inserted = this.db.exec(`
       INSERT INTO memory_observations
-        (session_id, project, type, title, content, severity, topic_key, file_paths, content_hash, embedding, last_accessed_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+        (session_id, project, type, title, content, severity, topic_key, file_paths, content_hash,
+         embedding, embedding_model, embedding_dim, last_accessed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
       RETURNING id, type, title, content, file_paths, severity
     `, [
             data.sessionId ?? null,
@@ -483,7 +587,9 @@ export class SqliteMemoryStorage {
             data.topicKey ?? null,
             filePathsJson,
             contentHash,
-            embeddingBuf,
+            embeddingMeta.buffer,
+            embeddingMeta.model,
+            embeddingMeta.dim,
         ]);
         const row = inserted[0]?.values[0];
         if (!row)
@@ -501,20 +607,28 @@ export class SqliteMemoryStorage {
         };
     }
     /**
-     * Compute embedding buffer for storage.
-     * Returns the serialized float32 Buffer when embeddingProvider is available,
-     * or null (no-op) when it is not — enabling graceful degradation.
+     * Compute the embedding buffer plus its provider metadata for storage
+     * (design D3 — per-row `embedding_model`/`embedding_dim`, task 3.6).
+     * Returns all-null when no embeddingProvider is configured (no-op) or when
+     * embedding generation fails — a failed embed is non-fatal: the row is
+     * still saved with a NULL embedding rather than throwing (spec: Graceful
+     * Degradation on Provider/API Failure).
      */
-    async _computeEmbeddingBuffer(text) {
+    async _computeEmbeddingMeta(text) {
         if (!this.embeddingProvider)
-            return null;
+            return { buffer: null, model: null, dim: null };
         try {
             const vec = await this.embeddingProvider.embed(text);
-            return serializeEmbedding(vec);
+            return {
+                buffer: serializeEmbedding(vec),
+                model: this.embeddingModel ?? null,
+                dim: this.embeddingProvider.dimension,
+            };
         }
-        catch {
+        catch (error) {
             // Embedding failure is non-fatal — store NULL and continue
-            return null;
+            console.warn(`[ghagga] embedding computation failed during save — persisting NULL embedding: ${error instanceof Error ? error.message : String(error)}`);
+            return { buffer: null, model: null, dim: null };
         }
     }
     async createSession(data) {
@@ -744,14 +858,80 @@ export class SqliteMemoryStorage {
         this.db.run('DELETE FROM negative_examples WHERE finding_hash = ?', [findingHash]);
         return this.db.getRowsModified() > 0;
     }
-    async close() {
+    /**
+     * Export the in-memory WASM database and write it to disk WITHOUT closing
+     * the underlying handle — shared by close() and flush() (design D6).
+     */
+    _writeToDisk() {
         const dir = dirname(this.filePath);
         if (!existsSync(dir)) {
             mkdirSync(dir, { recursive: true });
         }
         const data = this.db.export();
         writeFileSync(this.filePath, Buffer.from(data));
+    }
+    /**
+     * Durability hook for the backfill script (design D6, task 6.1): flushes
+     * the in-memory WASM database to disk after each batch so a mid-run crash
+     * loses at most the in-flight batch, not prior progress. Unlike close(),
+     * the database handle stays open and usable.
+     */
+    async flush() {
+        this._writeToDisk();
+    }
+    async close() {
+        this._writeToDisk();
         this.db.close();
     }
+    // ── Backfill (design D6) ────────────────────────────────────────
+    /**
+     * List up to `limit` observations needing an embedding for the active
+     * provider/model, ordered by id ascending starting after `afterId`.
+     * Always matches NULL-embedding rows; with `includeMismatched` also
+     * matches rows whose stored `embedding_model`/`embedding_dim` disagree
+     * with the active provider (backfill `--re-embed`).
+     */
+    async listObservationsNeedingEmbedding(options) {
+        const { afterId, limit, activeModel, activeDim, includeMismatched } = options;
+        let sql = `
+      SELECT id, title, content FROM memory_observations
+      WHERE id > ?
+        AND (
+          embedding IS NULL
+    `;
+        const params = [afterId];
+        if (includeMismatched) {
+            sql += `
+          OR embedding_model IS NULL OR embedding_model != ?
+          OR embedding_dim IS NULL OR embedding_dim != ?
+      `;
+            params.push(activeModel, activeDim);
+        }
+        sql += `
+        )
+      ORDER BY id ASC
+      LIMIT ?
+    `;
+        params.push(limit);
+        const stmt = this.db.prepare(sql);
+        stmt.bind(params);
+        const rows = [];
+        while (stmt.step()) {
+            const row = stmt.getAsObject();
+            rows.push({
+                id: row.id,
+                text: `${row.title} ${row.content}`,
+            });
+        }
+        stmt.free();
+        return rows;
+    }
+    /**
+     * Persist a backfilled embedding for a single observation (design D6).
+     * Metadata-only write — content/updated_at/last_accessed_at are untouched.
+     */
+    async updateObservationEmbedding(id, embedding, model, dim) {
+        this.db.run('UPDATE memory_observations SET embedding = ?, embedding_model = ?, embedding_dim = ? WHERE id = ?', [serializeEmbedding(embedding), model, dim, id]);
+    }
 }
 //# sourceMappingURL=sqlite.js.map