@jbarket/loomai 0.5.0 → 0.6.0

package/dist/backends/sqlite-vec.js

@@ -18,6 +18,10 @@ import { mmrSelect, DEFAULT_DIVERSITY } from './mmr.js';
 import { globToMatcher } from './glob.js';
 import { runMigrations } from './migrations.js';
 import { retryWrite } from './retry.js';
+import { computeUniqKey } from './dedup.js';
+import { effectiveScope, isVisibleInProject } from './scope.js';
+import { FEEDBACK_CATEGORY } from '../categories.js';
+import { FEEDBACK_CONFIDENCE_DEFAULT, applyObservation, decayedConfidence, } from './salience.js';
 function slugify(text) {
     return text
         .toLowerCase()
@@ -37,36 +41,82 @@ export class SqliteVecBackend {
         mkdirSync(dirname(config.dbPath), { recursive: true });
         this.db = new BetterSqlite3(config.dbPath);
         this.db.pragma('journal_mode = WAL');
-        // Single-writer (c-loom-strictness §single-writer): WAL admits one writer at
-        // a time; busy_timeout = 0 makes a second concurrent writer FAIL FAST with
-        // SQLITE_BUSY rather than block for the better-sqlite3 default 5s. loom is
-        // synchronous with one connection per call, so this never bites the daemon
-        // itself — only a genuine second writer (e.g. a stray second instance) is
-        // refused, which is exactly the guarantee. No torn write, no silent race.
-        this.db.pragma('busy_timeout = 0');
+        // WAL + 5s busy_timeout: concurrent sleeves (wakes, lanes, voice) each open
+        // their own connection. A brief write-lock window (checkpoint, concurrent
+        // write) retries for up to 5s rather than failing immediately. A genuine
+        // second loom instance will still fail — it won't hold the lock that long.
+        this.db.pragma('busy_timeout = 5000');
         sqliteVec.load(this.db);
         this.initSchema();
     }
     // ── MemoryBackend interface ──
     async remember(input) {
-        const uuid = randomUUID();
         const timestamp = new Date().toISOString();
+        const uniqKey = computeUniqKey({
+            category: input.category,
+            project: input.project,
+            title: input.title,
+            content: input.content,
+            scope: input.scope,
+        });
+        // Write-time dedup (t-335): a character-identical restatement (after
+        // normalizing) reheats the existing active row instead of inserting a
+        // second one. Scoped to active rows only — an archived memory that gets
+        // restated is a deliberate un-archive-by-rewrite, not a reheat.
+        //
+        // This first lookup is only a fast path that skips the embedder for a
+        // restatement. It is NOT the guarantee: another writer (this process or
+        // another connection on the same file) can insert the same key while we
+        // await the embedder. The authoritative check is repeated inside the
+        // IMMEDIATE insert transaction below, and the partial UNIQUE index
+        // idx_memories_uniq_exact makes a second active holder impossible
+        // (PR120 review).
+        const hit = this.db
+            .prepare('SELECT 1 FROM memories WHERE uniq = ? AND archived = 0')
+            .get(uniqKey);
+        if (hit) {
+            // Re-read under the write lock; if the holder was archived meanwhile,
+            // fall through to a fresh insert.
+            const reheated = retryWrite(() => this.reheatTx(uniqKey, timestamp).immediate());
+            if (reheated)
+                return reheated;
+        }
+        const uuid = randomUUID();
         const slug = slugify(input.title);
         const ref = `${input.category}/${slug}-${uuid.slice(0, 8)}`;
         const expiresAt = computeExpiresAt(timestamp, input.ttl);
         const vector = await this.embedder.embed(`${input.title}\n\n${input.content}`);
+        // A feedback memory is evidence-backed from the moment it's written: the
+        // observation that created it is the first piece of evidence. Every other
+        // category leaves confidence NULL ("not applicable") — this model is
+        // scoped to feedback, per t-338, not a generic trust score.
+        const isFeedback = input.category === FEEDBACK_CATEGORY;
+        const confidence = isFeedback ? FEEDBACK_CONFIDENCE_DEFAULT : null;
+        const evidenceCount = isFeedback ? 1 : 0;
         const insertMem = this.db.prepare(`
       INSERT INTO memories (
         uuid, ref, title, category, project, content, metadata,
-        created, ttl, expires_at, salience
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        created, ttl, expires_at, salience, sourcing, provenance,
+        confidence, evidence_count, observed_at, scope, uniq
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
         const insertVec = this.db.prepare('INSERT INTO vec_memories(rowid, embedding) VALUES (?, ?)');
         const tx = this.db.transaction(() => {
-            const result = insertMem.run(uuid, ref, input.title, input.category, input.project ?? null, input.content, JSON.stringify(input.metadata ?? {}), timestamp, input.ttl ?? null, expiresAt, 1.0);
+            // Recheck under the write lock: a concurrent writer may have stored
+            // this exact content while we were embedding.
+            const winner = this.reheatTx(uniqKey, timestamp)();
+            if (winner)
+                return winner;
+            const result = insertMem.run(uuid, ref, input.title, input.category, input.project ?? null, input.content, JSON.stringify(input.metadata ?? {}), timestamp, input.ttl ?? null, expiresAt, 1.0, // a freshly authored memory is hot; the lane decays it from here
+            input.sourcing ?? null, input.provenance ?? null, confidence, evidenceCount, isFeedback ? timestamp : null, input.scope ?? null, uniqKey);
             insertVec.run(BigInt(result.lastInsertRowid), toVecBuffer(vector));
+            return undefined;
         });
-        retryWrite(() => tx());
+        // IMMEDIATE: take the write lock before the recheck, so no other
+        // connection can commit the same key between the check and the insert.
+        const reheated = retryWrite(() => tx.immediate());
+        if (reheated)
+            return reheated;
         return {
             ref,
             category: input.category,
@@ -88,13 +138,17 @@ export class SqliteVecBackend {
         const candidates = this.searchVectors(queryVector, poolSize, poolSize * 4, (mem) => {
             if (categoryFilter && mem.category !== categoryFilter)
                 return false;
-            if (projectFilter && mem.project !== projectFilter)
+            if (!isVisibleInProject(mem, projectFilter))
                 return false;
             return true;
         });
         // MMR only re-orders/selects among candidates that already passed the
         // filters; with <= limit candidates it returns them in relevance order.
+        // `blended` carries the score that actually drove each pick, aligned by
+        // index with `hits` — null means MMR didn't touch anything, so the
+        // blended score is just the raw similarity (see rowToMatch).
         let hits = candidates;
+        let blended = null;
         let diversityDrops = 0;
         if (diversity > 0 && candidates.length > limit) {
             const vectors = this.loadVectors(candidates.map((c) => c.mem.id));
@@ -105,9 +159,10 @@ export class SqliteVecBackend {
             }));
             const picked = mmrSelect(pool, limit, diversity);
             hits = picked.selected.map((c) => c.hit);
+            blended = picked.scores;
             diversityDrops = picked.diversityDrops;
         }
-        const results = hits.map((h) => rowToMatch(h.mem, h.distance));
+        const results = hits.map((h, i) => rowToMatch(h.mem, h.distance, blended?.[i]));
         const hitIds = hits.map((h) => h.mem.id);
         if (hitIds.length > 0) {
             const now = new Date().toISOString();
@@ -181,48 +236,90 @@ export class SqliteVecBackend {
         return { deleted: targets.map((r) => r.ref) };
     }
     async update(input) {
-        let row;
+        let found;
         if (input.ref) {
-            row = this.db
-                .prepare('SELECT * FROM memories WHERE ref = ?')
+            found = this.db
+                .prepare('SELECT id, ref, title FROM memories WHERE ref = ?')
                 .get(input.ref);
         }
         else if (input.category && input.title) {
-            row = this.db
-                .prepare('SELECT * FROM memories WHERE category = ? AND title = ?')
+            found = this.db
+                .prepare('SELECT id, ref, title FROM memories WHERE category = ? AND title = ?')
                 .get(input.category, input.title);
         }
         else {
             return { updated: false };
         }
-        if (!row)
+        if (!found)
             return { updated: false };
-        const newContent = input.content ?? row.content;
-        const existingMeta = JSON.parse(row.metadata);
-        const newMeta = input.metadata
-            ? { ...existingMeta, ...input.metadata }
-            : existingMeta;
+        const { id, ref, title } = found;
+        // The only async step, so it runs before the transaction. Everything that
+        // reads the row runs INSIDE the transaction below, against a fresh read —
+        // a row read up here would be stale by the time an overlapping update()
+        // commits, and writing it back would drop that update's content, metadata
+        // or evidence (PR130 review).
+        const vector = input.content !== undefined ? await this.embedder.embed(`${title}\n\n${input.content}`) : undefined;
         const updatedAt = new Date().toISOString();
-        const updateStmt = this.db.prepare(`
-      UPDATE memories
-      SET content = ?, metadata = ?, updated = ?
-      WHERE id = ?
-    `);
-        const updateVec = this.db.prepare('UPDATE vec_memories SET embedding = ? WHERE rowid = ?');
-        const vector = await this.embedder.embed(`${row.title}\n\n${newContent}`);
-        // Snapshot the current body before overwriting — same protection the knowledge
-        // wing added after the 2026-06-01 verify run stomped 13 pages with no recovery.
-        // Only snapshot when content actually changes to avoid noise in the history.
         let snapshotId;
-        if (input.content !== undefined && input.content !== row.content) {
-            snapshotId = this.snapshotRevision(row.id, row.ref, row.content, 'update', updatedAt);
-        }
+        let newConfidence;
+        let newEvidenceCount;
         const tx = this.db.transaction(() => {
-            updateStmt.run(newContent, JSON.stringify(newMeta), updatedAt, row.id);
-            updateVec.run(toVecBuffer(vector), BigInt(row.id));
+            const row = this.db.prepare('SELECT * FROM memories WHERE id = ?').get(id);
+            if (!row)
+                return false; // deleted between lookup and write
+            // Only the columns this call is about get written; everything else is
+            // left as the row has it now.
+            const sets = ['updated = ?'];
+            const params = [updatedAt];
+            const contentChanged = input.content !== undefined && input.content !== row.content;
+            if (contentChanged) {
+                // Snapshot the current body before overwriting — same protection the
+                // knowledge wing added after the 2026-06-01 verify run stomped 13
+                // pages with no recovery. Only on a real change, to keep history quiet.
+                snapshotId = this.snapshotRevision(row.id, row.ref, row.content, 'update', updatedAt);
+                sets.push('content = ?', 'uniq = ?');
+                // The dedup key describes the current body — a stale one would make
+                // remember() of the OLD body return this row (PR120 review).
+                params.push(input.content, this.claimableUniq(row.id, { ...row, content: input.content }));
+            }
+            if (input.metadata) {
+                const existingMeta = JSON.parse(row.metadata);
+                sets.push('metadata = ?');
+                params.push(JSON.stringify({ ...existingMeta, ...input.metadata }));
+            }
+            // Confirm/contradict (t-338): computed in code, feedback memories only.
+            // The delta applies to the confidence as it reads NOW (decay
+            // materialized), then the evidence clock restarts — so a contradict
+            // always lowers the current value and a confirm always raises it, and
+            // the evidence an aged score has already lost can't come back.
+            if (input.observation && row.category === FEEDBACK_CATEGORY) {
+                const current = row.confidence !== null
+                    ? decayedConfidence(row.confidence, row.observed_at ?? row.created, row.category, Date.parse(updatedAt))
+                    : FEEDBACK_CONFIDENCE_DEFAULT;
+                newConfidence = applyObservation(current, input.observation);
+                newEvidenceCount = row.evidence_count + 1;
+                sets.push('confidence = ?', 'evidence_count = ?', 'observed_at = ?');
+                params.push(newConfidence, newEvidenceCount, updatedAt);
+            }
+            this.db.prepare(`UPDATE memories SET ${sets.join(', ')} WHERE id = ?`).run(...params, row.id);
+            if (contentChanged) {
+                this.db
+                    .prepare('UPDATE vec_memories SET embedding = ? WHERE rowid = ?')
+                    .run(toVecBuffer(vector), BigInt(row.id));
+            }
+            return true;
         });
-        retryWrite(() => tx());
-        return { updated: true, ref: row.ref, snapshotId };
+        // IMMEDIATE takes the write lock before the read, so another process
+        // (loom-http and the CLI share the file) can't commit between them.
+        if (!retryWrite(() => tx.immediate()))
+            return { updated: false };
+        return {
+            updated: true,
+            ref,
+            snapshotId,
+            confidence: newConfidence,
+            evidenceCount: newEvidenceCount,
+        };
     }
     async prune(options) {
         const dryRun = options?.dryRun ?? false;
@@ -250,7 +347,20 @@ export class SqliteVecBackend {
             }
         }
         if (!dryRun && expiredIds.length > 0) {
-            this.deleteById(expiredIds);
+            // Archive instead of hard-delete: content is preserved for recovery,
+            // the embedding is dropped (no KNN slots wasted), archived = 1 hides
+            // the row from recall/list/audit — matching the contract in t-332.
+            const now = new Date().toISOString();
+            const tombstone = JSON.stringify({ note: 'TTL elapsed', archived_at: now });
+            const archiveStmt = this.db.prepare('UPDATE memories SET archived = 1, archive_note = ?, updated = ? WHERE id = ?');
+            const delVec = this.db.prepare('DELETE FROM vec_memories WHERE rowid = ?');
+            const tx = this.db.transaction(() => {
+                for (const id of expiredIds) {
+                    archiveStmt.run(tombstone, now, id);
+                    delVec.run(BigInt(id));
+                }
+            });
+            retryWrite(() => tx());
         }
         return { expired, stale };
     }
@@ -269,7 +379,8 @@ export class SqliteVecBackend {
         const where = `WHERE ${clauses.join(' AND ')}`;
         params.push(input.limit ?? 50);
         const rows = this.db
-            .prepare(`SELECT ref, title, category, project, created
+            .prepare(`SELECT ref, title, category, project, created, sourcing, provenance,
+                confidence, evidence_count, observed_at
          FROM memories ${where}
          ORDER BY created DESC LIMIT ?`)
             .all(...params);
@@ -279,6 +390,12 @@ export class SqliteVecBackend {
             category: r.category,
             project: r.project ?? undefined,
             created: r.created,
+            sourcing: r.sourcing ?? undefined,
+            provenance: r.provenance ?? undefined,
+            confidence: r.confidence !== null
+                ? decayedConfidence(r.confidence, r.observed_at ?? r.created, r.category, Date.now())
+                : undefined,
+            evidenceCount: r.confidence !== null ? r.evidence_count : undefined,
         }));
     }
     async findSimilar(input) {
@@ -299,7 +416,7 @@ export class SqliteVecBackend {
                 .get(BigInt(row.id));
             if (!vecRow)
                 throw new Error(`findSimilar: embedding missing for ${input.ref}`);
-            queryVector = Array.from(new Float32Array(vecRow.embedding.buffer, vecRow.embedding.byteOffset, vecRow.embedding.byteLength / 4));
+            queryVector = Array.from(bufToF32(vecRow.embedding));
         }
         else {
             queryVector = await (this.embedder.embedQuery?.(input.text) ??
@@ -316,7 +433,7 @@ export class SqliteVecBackend {
                 return false;
             if (categoryFilter && mem.category !== categoryFilter)
                 return false;
-            if (projectFilter && (mem.project ?? null) !== projectFilter)
+            if (!isVisibleInProject(mem, projectFilter))
                 return false;
             if (1 - vr.distance < minRelevance)
                 return false;
@@ -357,24 +474,33 @@ export class SqliteVecBackend {
                 });
             }
         }
-        // Duplicate detection: for each memory, MATCH its stored embedding,
-        // take the top non-self neighbour, keep pairs above threshold, dedupe.
-        const duplicates = [];
+        // Duplicate detection: batch-load all embeddings in one query, then
+        // for each memory find its k-nearest neighbours (k=10 to surface
+        // clusters, not just the single closest), collect ALL pairs above the
+        // threshold, sort by descending similarity, and truncate to maxDuplicates.
+        // One DB query per row (the MATCH) instead of two (fetch + MATCH).
+        const allPairs = [];
         const seenPair = new Set();
         const pairKey = (a, b) => a < b ? `${a}:${b}` : `${b}:${a}`;
         const byIdRow = new Map(rows.map((r) => [r.id, r]));
+        // Load all stored embeddings in one pass so the inner loop only runs
+        // the MATCH query rather than a fetch-then-match pair.
+        const allEmbedRows = this.db
+            .prepare('SELECT rowid, embedding FROM vec_memories')
+            .all();
+        const embeddingMap = new Map();
+        for (const er of allEmbedRows) {
+            embeddingMap.set(Number(er.rowid), er.embedding);
+        }
+        const kNeighbours = 10;
         const vecStmt = this.db.prepare(`SELECT rowid, distance FROM vec_memories
-       WHERE embedding MATCH ? AND k = 2
+       WHERE embedding MATCH ? AND k = ${kNeighbours}
        ORDER BY distance`);
         for (const r of rows) {
-            if (duplicates.length >= maxDuplicates)
-                break;
-            const stored = this.db
-                .prepare('SELECT embedding FROM vec_memories WHERE rowid = ?')
-                .get(BigInt(r.id));
-            if (!stored)
+            const emb = embeddingMap.get(r.id);
+            if (!emb)
                 continue;
-            const hits = vecStmt.all(stored.embedding);
+            const hits = vecStmt.all(emb);
             for (const h of hits) {
                 if (h.rowid === r.id)
                     continue;
@@ -388,15 +514,17 @@ export class SqliteVecBackend {
                 const other = byIdRow.get(h.rowid);
                 if (!other)
                     continue;
-                duplicates.push({
+                allPairs.push({
                     a: { ref: r.ref, title: r.title },
                     b: { ref: other.ref, title: other.title },
                     relevance,
                 });
-                if (duplicates.length >= maxDuplicates)
-                    break;
             }
         }
+        // Sort highest-similarity pairs first so the truncation keeps the worst
+        // duplicates, not just the ones discovered first by insertion order.
+        allPairs.sort((x, y) => y.relevance - x.relevance);
+        const duplicates = allPairs.slice(0, maxDuplicates);
         return {
             totalMemories: rows.length,
             byCategory,
@@ -443,14 +571,14 @@ export class SqliteVecBackend {
         let rows = [];
         if (input.ref) {
             const row = this.db
-                .prepare('SELECT id, ref, title, content FROM memories WHERE ref = ? AND archived = 1')
+                .prepare('SELECT id, ref, title, content, category, project, scope FROM memories WHERE ref = ? AND archived = 1')
                 .get(input.ref);
             if (row)
                 rows = [row];
         }
         else if (input.category && input.title) {
             rows = this.db
-                .prepare('SELECT id, ref, title, content FROM memories WHERE category = ? AND title = ? AND archived = 1')
+                .prepare('SELECT id, ref, title, content, category, project, scope FROM memories WHERE category = ? AND title = ? AND archived = 1')
                 .all(input.category, input.title);
         }
         else {
@@ -461,19 +589,22 @@ export class SqliteVecBackend {
         // Archive dropped the embedding; rebuild it from the stored content.
         const vectors = await this.embedder.embedBatch(rows.map((r) => `${r.title}\n\n${r.content}`));
         const now = new Date().toISOString();
-        const stmt = this.db.prepare('UPDATE memories SET archived = 0, archive_note = NULL, updated = ? WHERE id = ?');
+        const stmt = this.db.prepare('UPDATE memories SET archived = 0, archive_note = NULL, uniq = ?, updated = ? WHERE id = ?');
         // Delete-then-insert: legacy rows archived before delete-on-archive
         // may still hold a vector, and vec0 rowids must stay unique.
         const delVec = this.db.prepare('DELETE FROM vec_memories WHERE rowid = ?');
         const insVec = this.db.prepare('INSERT INTO vec_memories(rowid, embedding) VALUES (?, ?)');
         const tx = this.db.transaction(() => {
             rows.forEach((row, i) => {
-                stmt.run(now, row.id);
+                // Re-derive the key: the row may carry a stale or pre-rekey one, and
+                // while it sat archived the same body may have been remembered again
+                // — that active row keeps the key (PR120 review).
+                stmt.run(this.claimableUniq(row.id, row), now, row.id);
                 delVec.run(BigInt(row.id));
                 insVec.run(BigInt(row.id), toVecBuffer(vectors[i]));
             });
         });
-        retryWrite(() => tx());
+        retryWrite(() => tx.immediate());
         return { restored: rows.map((r) => r.ref) };
     }
     listRevisions(ref) {
@@ -517,13 +648,13 @@ export class SqliteVecBackend {
         // Snapshot the current body before replacing it.
         const snapshotId = this.snapshotRevision(mem.id, mem.ref, mem.content, 'revision-restore', timestamp);
         const vector = await this.embedder.embed(`${mem.title}\n\n${rev.content}`);
-        const updateStmt = this.db.prepare('UPDATE memories SET content = ?, updated = ? WHERE id = ?');
+        const updateStmt = this.db.prepare('UPDATE memories SET content = ?, uniq = ?, updated = ? WHERE id = ?');
         const updateVec = this.db.prepare('UPDATE vec_memories SET embedding = ? WHERE rowid = ?');
         const tx = this.db.transaction(() => {
-            updateStmt.run(rev.content, timestamp, mem.id);
+            updateStmt.run(rev.content, this.claimableUniq(mem.id, { ...mem, content: rev.content }), timestamp, mem.id);
             updateVec.run(toVecBuffer(vector), BigInt(mem.id));
         });
-        retryWrite(() => tx());
+        retryWrite(() => tx.immediate());
         return { ref: input.ref, revision_id: input.revision_id, restored: true, snapshot_id: snapshotId };
     }
     supersede(input) {
@@ -563,6 +694,83 @@ export class SqliteVecBackend {
         retryWrite(() => tx());
         return Promise.resolve({ old_ref: input.old_ref, new_ref: input.new_ref, archived: true });
     }
+    async mergeMemories(input) {
+        if (!input.source_refs || input.source_refs.length === 0) {
+            return Promise.reject(new Error('mergeMemories: source_refs must not be empty'));
+        }
+        const targetRow = this.db
+            .prepare('SELECT * FROM memories WHERE ref = ? AND archived = 0')
+            .get(input.target_ref);
+        if (!targetRow) {
+            return Promise.reject(new Error(`mergeMemories: target_ref not found or already archived: ${input.target_ref}`));
+        }
+        const sourceRows = [];
+        for (const ref of input.source_refs) {
+            if (ref === input.target_ref) {
+                return Promise.reject(new Error(`mergeMemories: source_ref '${ref}' is the same as target_ref — cannot merge a memory into itself`));
+            }
+            const row = this.db
+                .prepare('SELECT * FROM memories WHERE ref = ? AND archived = 0')
+                .get(ref);
+            if (!row) {
+                return Promise.reject(new Error(`mergeMemories: source_ref not found or already archived: ${ref}`));
+            }
+            sourceRows.push(row);
+        }
+        const timestamp = new Date().toISOString();
+        const losers = sourceRows.map((r) => ({ ref: r.ref, title: r.title, content: r.content }));
+        const combinedTimesSeen = targetRow.times_seen + sourceRows.reduce((sum, r) => sum + r.times_seen, 0);
+        let newContent = targetRow.content;
+        if (input.append_loser_bodies) {
+            for (const loser of losers) {
+                newContent += `\n\n--- merged from ${loser.ref} ---\n\n${loser.content}`;
+            }
+        }
+        let vector;
+        if (newContent !== targetRow.content) {
+            // Snapshot the target body before overwriting — same protection update() gives.
+            this.snapshotRevision(targetRow.id, targetRow.ref, targetRow.content, 'update', timestamp);
+            vector = await this.embedder.embed(`${targetRow.title}\n\n${newContent}`);
+        }
+        const updateTarget = this.db.prepare('UPDATE memories SET content = ?, times_seen = ?, updated = ?, uniq = ? WHERE id = ?');
+        const updateVec = this.db.prepare('UPDATE vec_memories SET embedding = ? WHERE rowid = ?');
+        const repointRevisions = this.db.prepare('UPDATE memory_revisions SET memory_id = ? WHERE memory_id = ?');
+        const archiveSource = this.db.prepare('UPDATE memories SET archived = 1, archive_note = ?, updated = ? WHERE id = ?');
+        const delVec = this.db.prepare('DELETE FROM vec_memories WHERE rowid = ?');
+        const insertSup = this.db.prepare('INSERT INTO memory_supersessions (old_ref, new_ref, note, created) VALUES (?, ?, ?, ?)');
+        const tx = this.db.transaction(() => {
+            for (const source of sourceRows) {
+                // Re-parent revision history before the source row can be deleted.
+                repointRevisions.run(targetRow.id, source.id);
+                const tombstoneNote = input.note
+                    ? `Merged into ${input.target_ref}. ${input.note}`
+                    : `Merged into ${input.target_ref}.`;
+                archiveSource.run(JSON.stringify({ note: tombstoneNote, archived_at: timestamp }), timestamp, source.id);
+                delVec.run(BigInt(source.id));
+                insertSup.run(source.ref, input.target_ref, input.note ?? null, timestamp);
+                if (input.hard_delete_losers) {
+                    // Journaled like every other hard delete (t-436); nested here, so
+                    // the journal row and the delete commit or roll back with the merge.
+                    this.deleteByIdTx([source.id], 'merge')();
+                }
+            }
+            // After the sources are archived, so a key one of them held is free
+            // for the target's (possibly concatenated) body.
+            const newUniq = newContent !== targetRow.content
+                ? this.claimableUniq(targetRow.id, { ...targetRow, content: newContent })
+                : targetRow.uniq;
+            updateTarget.run(newContent, combinedTimesSeen, timestamp, newUniq, targetRow.id);
+            if (vector)
+                updateVec.run(toVecBuffer(vector), BigInt(targetRow.id));
+        });
+        retryWrite(() => tx.immediate());
+        return {
+            target_ref: input.target_ref,
+            sources_merged: sourceRows.length,
+            times_seen: combinedTimesSeen,
+            losers,
+        };
+    }
     close() {
         this.db.close();
     }
@@ -570,6 +778,45 @@ export class SqliteVecBackend {
         return this.db;
     }
     // ── Internals ──
+    /**
+     * A transaction that reheats the active row holding `uniqKey` (times_seen
+     * + 1, updated = timestamp) and returns its ref, or returns undefined if no
+     * active row holds it. Run it with .immediate() on its own, or call it
+     * inside another transaction (better-sqlite3 nests it as a savepoint).
+     */
+    reheatTx(uniqKey, timestamp) {
+        return this.db.transaction(() => {
+            const existing = this.db
+                .prepare('SELECT id, ref, title, category FROM memories WHERE uniq = ? AND archived = 0 LIMIT 1')
+                .get(uniqKey);
+            if (!existing)
+                return undefined;
+            this.db
+                .prepare('UPDATE memories SET times_seen = times_seen + 1, updated = ? WHERE id = ?')
+                .run(timestamp, existing.id);
+            const slashIdx = existing.ref.indexOf('/');
+            return {
+                ref: existing.ref,
+                category: existing.category,
+                filename: slashIdx >= 0 ? existing.ref.slice(slashIdx + 1) : existing.ref,
+                title: existing.title,
+            };
+        });
+    }
+    /**
+     * The dedup key a row should hold for the given body, or NULL when another
+     * ACTIVE row already holds that key — the existing holder keeps it, same
+     * policy as the migration backfill (rebuildUniqKeys). Call inside the
+     * write transaction that changes the body, so the check and the write see
+     * the same state.
+     */
+    claimableUniq(id, row) {
+        const key = computeUniqKey(row);
+        const holder = this.db
+            .prepare('SELECT id FROM memories WHERE uniq = ? AND archived = 0 AND id != ? LIMIT 1')
+            .get(key, id);
+        return holder ? null : key;
+    }
     /**
      * Insert a content snapshot into memory_revisions and prune beyond the per-memory
      * cap. Mirrors the knowledge wing's snapshotRevision() in sqlite-knowledge.ts.
@@ -660,7 +907,7 @@ export class SqliteVecBackend {
             const row = stmt.get(BigInt(id));
             if (!row)
                 continue;
-            out.set(id, new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.embedding.byteLength / 4));
+            out.set(id, bufToF32(row.embedding));
         }
         return out;
     }
@@ -697,31 +944,97 @@ export class SqliteVecBackend {
         // aborts startup loudly rather than leaving memory half-broken.
         runMigrations(this.db, { strict: true });
     }
-    deleteById(ids) {
+    /**
+     * Hard-delete rows by id. Every call is journaled to memory_deletions first
+     * (t-436) — this is the ONLY path that permanently destroys a memory, so it
+     * is the one place that must record what it destroyed. The journal table is
+     * standalone (keyed by ref, no FK to memories) so it survives the delete it
+     * describes.
+     */
+    deleteById(ids, op = 'forget') {
         if (ids.length === 0)
             return;
+        const tx = this.deleteByIdTx(ids, op);
+        retryWrite(() => tx());
+    }
+    /**
+     * The journal-then-delete transaction behind deleteById. Callers already
+     * inside a transaction (mergeMemories with hard_delete_losers) invoke it
+     * directly; better-sqlite3 nests it as a savepoint.
+     */
+    deleteByIdTx(ids, op) {
         const placeholders = ids.map(() => '?').join(',');
+        const selectRows = this.db.prepare(`SELECT ref, category, title, project, content, created
+       FROM memories WHERE id IN (${placeholders})`);
+        const journalStmt = this.db.prepare(`INSERT INTO memory_deletions (ref, category, title, project, content, created, deleted_at, op)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
         const delMem = this.db.prepare(`DELETE FROM memories WHERE id IN (${placeholders})`);
         const delVec = this.db.prepare(`DELETE FROM vec_memories WHERE rowid IN (${placeholders})`);
         const bigIds = ids.map((n) => BigInt(n));
-        const tx = this.db.transaction(() => {
+        return this.db.transaction(() => {
+            // Read inside the transaction, so the journal records exactly the
+            // rows this delete removes.
+            const rows = selectRows.all(...ids);
+            const deletedAt = new Date().toISOString();
+            for (const row of rows) {
+                journalStmt.run(row.ref, row.category, row.title, row.project, row.content, row.created, deletedAt, op);
+            }
             delMem.run(...ids);
             delVec.run(...bigIds);
         });
-        retryWrite(() => tx());
     }
 }
-// ── Helpers ──
 const EMPTY_VECTOR = new Float32Array(0);
+/** Float32Array view of a Buffer; copies only when alignment forces it. */
+export function bufToF32(buf) {
+    if (buf.byteOffset % Float32Array.BYTES_PER_ELEMENT === 0) {
+        return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / Float32Array.BYTES_PER_ELEMENT);
+    }
+    return new Float32Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+}
 function clamp01(x) {
     if (!Number.isFinite(x))
         return DEFAULT_DIVERSITY;
     return Math.min(1, Math.max(0, x));
 }
+/**
+ * An all-zero (or otherwise signal-free) embedding matches every row
+ * equally in cosine search — it doesn't fail loudly, it just sits there
+ * forever as a vector that neither rejects nor ever truly matches
+ * anything. Refuse to persist one instead of writing that landmine (t-334;
+ * mirrors Memori's embedding_rows_have_signal).
+ */
+function hasEmbeddingSignal(vector) {
+    let sumSq = 0;
+    for (const v of vector)
+        sumSq += v * v;
+    return sumSq > 1e-12;
+}
 function toVecBuffer(vector) {
+    if (!hasEmbeddingSignal(vector)) {
+        throw new Error(`refusing to persist a degenerate embedding — ${vector.length} dims with no real signal (all-zero or near-zero)`);
+    }
     return Buffer.from(new Float32Array(vector).buffer);
 }
-function rowToMatch(row, distance) {
+/**
+ * Decayed confidence for display: undefined for non-feedback memories (NULL
+ * stored confidence), else the raw value relaxed toward neutral by how long
+ * it's been since the last observation. `observed_at` (not `updated`, which
+ * every edit stamps, nor `last_accessed`) is the decay clock — see decayedConfidence()'s doc comment in salience.ts.
+ */
+function decayedRowConfidence(row) {
+    if (row.confidence === null)
+        return undefined;
+    const lastObserved = row.observed_at ?? row.created;
+    return decayedConfidence(row.confidence, lastObserved, row.category, Date.now());
+}
+/**
+ * `blendedRelevance`, when given, is the MMR score that actually placed this
+ * row (see recall()'s `blended` array) — omit it (findSimilar, or recall
+ * when MMR didn't run) and relevance falls back to the raw similarity.
+ */
+function rowToMatch(row, distance, blendedRelevance) {
+    const similarity = 1 - distance;
     return {
         path: row.ref,
         title: row.title,
@@ -729,9 +1042,15 @@ function rowToMatch(row, distance) {
         project: row.project ?? undefined,
         created: row.created,
         content: row.content,
-        relevance: 1 - distance,
+        relevance: blendedRelevance ?? similarity,
+        similarity,
+        scope: effectiveScope(row),
         lastAccessed: row.last_accessed ?? undefined,
         ttl: row.ttl ?? undefined,
         expiresAt: row.expires_at ?? undefined,
+        sourcing: row.sourcing ?? undefined,
+        provenance: row.provenance ?? undefined,
+        confidence: decayedRowConfidence(row),
+        evidenceCount: row.confidence !== null ? row.evidence_count : undefined,
     };
 }