hippo-memory 1.32.1 → 1.34.0

package/dist/store.js

@@ -175,7 +175,11 @@ export function serializeEntry(entry) {
     if (entry.origin_project !== undefined && entry.origin_project !== null) {
         frontmatter['origin_project'] = entry.origin_project;
     }
-    const fm = dumpFrontmatter(frontmatter);
+    // Spread into a fresh object literal: dumpFrontmatter's Record<string,
+    // YamlValue> parameter needs an index signature, which a named interface
+    // reference (EntryFrontmatterFields) doesn't structurally provide even
+    // though every property's value type already matches.
+    const fm = dumpFrontmatter({ ...frontmatter });
     return `${fm}\n\n${entry.content}\n`;
 }
 /**
@@ -185,6 +189,11 @@ export function deserializeEntry(raw) {
     const { data, content } = parseFrontmatter(raw);
     if (!data['id'] || !data['layer'])
         return null;
+    // SAFETY: every `as X` below narrows a raw YAML frontmatter field to an
+    // enum/union member of MemoryEntry; frontmatter is only ever written by
+    // serializeEntry (whose own fields are typed), so out-of-range values here
+    // would indicate hand-edited files, which this parser is not required to
+    // reject — matches the pre-existing permissive-parse behavior.
     return {
         id: String(data['id']),
         created: String(data['created'] ?? new Date().toISOString()),
@@ -231,7 +240,11 @@ function normalizeStringArray(value) {
     return value.map((item) => String(item));
 }
 function rowToEntry(row) {
-    return {
+    // SAFETY: every `as X` below narrows a SQLite column value to an
+    // enum/union member of MemoryEntry; `row` comes from MEMORY_SELECT_COLUMNS
+    // / MEMORY_SEARCH_COLUMNS, which are the only queries producing MemoryRow,
+    // and the DB layer only ever writes these columns from the same enums.
+    const entry = {
         id: row.id,
         created: row.created,
         last_retrieved: row.last_retrieved,
@@ -273,13 +286,14 @@ function rowToEntry(row) {
         last_rebuilt_at: row.last_rebuilt_at ?? null,
         rebuild_count: Number(row.rebuild_count ?? 0),
         dag_level_3_built_at: row.dag_level_3_built_at ?? null,
-        // F1 (v1.7.0): preserve bm25_score from the FTS path. `'bm25_score' in row`
-        // distinguishes "absent column" (non-FTS path) from "column present but
-        // value 0" — though FTS5 bm25() never returns 0, this is defensive.
-        ...('bm25_score' in row && row.bm25_score !== undefined && row.bm25_score !== null
-            ? { bm25_score: Number(row.bm25_score) }
-            : {}),
     };
+    // F1 (v1.7.0): preserve bm25_score from the FTS path. `'bm25_score' in row`
+    // distinguishes "absent column" (non-FTS path) from "column present but
+    // value 0" — though FTS5 bm25() never returns 0, this is defensive.
+    if ('bm25_score' in row && row.bm25_score !== undefined && row.bm25_score !== null) {
+        entry.bm25_score = Number(row.bm25_score);
+    }
+    return entry;
 }
 function parseJsonArray(raw) {
     if (!raw)
@@ -309,12 +323,15 @@ function parseLastTraceId(raw) {
         return null;
     return trimmed;
 }
+function isPlainJsonObject(x) {
+    return x !== null && typeof x === 'object' && !Array.isArray(x);
+}
 function parseJsonObject(raw) {
     if (!raw)
         return {};
     try {
         const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        if (isPlainJsonObject(parsed)) {
             return parsed;
         }
         return {};
@@ -585,6 +602,8 @@ function loadSearchRows(db, query, limit, tenantId, scopeFilter) {
         // this no-terms path had the same shape). Apply LIMIT so all four
         // candidate paths honour the caller's cap when set.
         const sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories${tenantOnlyPredicate}${archivedClauseTenantOnly}${scopeClauseTenantOnly} ORDER BY created ASC, id ASC LIMIT ?`;
+        // SAFETY: sql selects exactly MEMORY_SELECT_COLUMNS, whose column list
+        // matches MemoryRow's field set.
         return db.prepare(sql).all(...tenantParams, ...scopeParams, limit);
     }
     // v1.7.1 — test/diagnostic hook: `HIPPO_FORCE_LIKE_PATH=1` forces the
@@ -603,6 +622,8 @@ function loadSearchRows(db, query, limit, tenantId, scopeFilter) {
             // F1 (v1.7.0): MEMORY_SEARCH_COLUMNS adds bm25_score as the trailing
             // result column. Every other column is m.<col> AS <col> so rowToEntry
             // sees the same shape it always has.
+            // SAFETY: MEMORY_SEARCH_COLUMNS aliases every column to the same name
+            // MEMORY_SELECT_COLUMNS uses (plus bm25_score), matching MemoryRow.
             const rows = db.prepare(`
         SELECT ${MEMORY_SEARCH_COLUMNS}
         FROM memories m
@@ -624,6 +645,8 @@ function loadSearchRows(db, query, limit, tenantId, scopeFilter) {
         const like = `%${escapeLike(term)}%`;
         return [like, like];
     });
+    // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+    // MemoryRow's field set.
     const rows = db.prepare(`
     SELECT ${MEMORY_SELECT_COLUMNS}
     FROM memories
@@ -639,6 +662,8 @@ function loadSearchRows(db, query, limit, tenantId, scopeFilter) {
     // candidate-pool size. Apply LIMIT here so all four paths honour the
     // caller's cap.
     const fallback = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories${tenantOnlyPredicate}${archivedClauseTenantOnly}${scopeClauseTenantOnly} ORDER BY created ASC, id ASC LIMIT ?`;
+    // SAFETY: fallback selects exactly MEMORY_SELECT_COLUMNS, matching
+    // MemoryRow's field set.
     return db.prepare(fallback).all(...tenantParams, ...scopeParams, limit);
 }
 function writeMarkdownMirror(hippoRoot, entry) {
@@ -724,6 +749,8 @@ export function purgeMirrorBestEffort(hippoRoot, id, isRaw, logPrefix) {
     }
 }
 function bootstrapLegacyStore(db, hippoRoot) {
+    // SAFETY: countRow's shape matches the single `COUNT(*) AS count` column
+    // selected above; `.get()` returns undefined only when no row exists.
     const countRow = db.prepare(`SELECT COUNT(*) AS count FROM memories`).get();
     const memoryCount = Number(countRow?.count ?? 0);
     if (memoryCount > 0)
@@ -788,7 +815,7 @@ function bootstrapLegacyStore(db, hippoRoot) {
         const runs = Array.isArray(legacyStats.consolidation_runs) ? legacyStats.consolidation_runs : [];
         const insertRun = db.prepare(`INSERT INTO consolidation_runs(timestamp, decayed, merged, removed) VALUES (?, ?, ?, ?)`);
         for (const run of runs) {
-            if (!run || typeof run !== 'object')
+            if (!isPlainJsonObject(run))
                 continue;
             const row = run;
             insertRun.run(String(row.timestamp ?? new Date().toISOString()), Number(row.decayed ?? 0), Number(row.merged ?? 0), Number(row.removed ?? 0));
@@ -827,6 +854,9 @@ function loadLegacyIndexFile(hippoRoot) {
         return { version: 1, entries: {}, last_retrieval_ids: [], last_trace_id: null };
     }
     try {
+        // SAFETY: index.json is only ever written by writeIndexMirror below,
+        // which always serializes a HippoIndex; a hand-edited or corrupted file
+        // that violates the shape falls through to the catch block's fallback.
         return JSON.parse(fs.readFileSync(indexPath, 'utf8'));
     }
     catch {
@@ -844,6 +874,10 @@ function loadLegacyStatsFile(hippoRoot) {
         };
     }
     try {
+        // SAFETY: stats.json is only ever written by writeStatsMirror below,
+        // which always emits exactly these four fields; callers additionally
+        // guard every read with `?? 0` / `Array.isArray`, tolerating a
+        // hand-edited or corrupted file even if this optimistic cast is wrong.
         return JSON.parse(fs.readFileSync(statsPath, 'utf8'));
     }
     catch {
@@ -968,9 +1002,12 @@ function deleteFtsRow(db, id) {
  * without duplicating this query.
  */
 export function buildIndexFromDb(db) {
+    // SAFETY: rows' shape matches the seven columns named in the SELECT below.
     const rows = db.prepare(`SELECT id, created, last_retrieved, strength, layer, tags_json, pinned FROM memories ORDER BY created ASC, id ASC`).all();
     const entries = {};
     for (const row of rows) {
+        // SAFETY: layer is only ever written from the Layer enum by this
+        // module's own INSERT/UPDATE paths.
         const layer = row.layer;
         entries[row.id] = {
             id: row.id,
@@ -989,6 +1026,7 @@ export function buildIndexFromDb(db) {
     // them, handing the reader mismatched last_retrieval_ids / last_trace_id
     // and re-opening the mislinkage hole saveIndex's BEGIN/COMMIT closed on
     // the write side. One SELECT = one SQLite read snapshot.
+    // SAFETY: lockstepRows' shape matches the key/value columns named above.
     const lockstepRows = db.prepare(`SELECT key, value FROM meta WHERE key IN ('last_retrieval_ids', 'last_trace_id')`).all();
     const lockstep = new Map(lockstepRows.map((r) => [r.key, r.value]));
     return {
@@ -999,12 +1037,18 @@ export function buildIndexFromDb(db) {
     };
 }
 function buildStatsFromDb(db) {
+    // SAFETY: runs' shape matches the four columns named in the SELECT above.
     const runs = db.prepare(`SELECT timestamp, decayed, merged, removed FROM consolidation_runs ORDER BY timestamp ASC, id ASC`).all();
     return {
         total_remembered: Number(getMeta(db, 'total_remembered', '0')),
         total_recalled: Number(getMeta(db, 'total_recalled', '0')),
         total_forgotten: Number(getMeta(db, 'total_forgotten', '0')),
-        consolidation_runs: runs,
+        consolidation_runs: runs.map((run) => ({
+            timestamp: run.timestamp,
+            decayed: run.decayed,
+            merged: run.merged,
+            removed: run.removed,
+        })),
     };
 }
 /**
@@ -1021,10 +1065,14 @@ function writeStatsMirror(hippoRoot, stats) {
     fs.writeFileSync(path.join(hippoRoot, 'stats.json'), JSON.stringify(stats, null, 2), 'utf8');
 }
 function syncMirrorFiles(hippoRoot, db) {
+    // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+    // MemoryRow's field set.
     const entries = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
     for (const entry of entries.map(rowToEntry)) {
         writeMarkdownMirror(hippoRoot, entry);
     }
+    // SAFETY: conflicts' shape matches the eight columns named in the SELECT
+    // above.
     const conflicts = db.prepare(`
     SELECT id, memory_a_id, memory_b_id, reason, score, status, detected_at, updated_at
     FROM memory_conflicts
@@ -1225,6 +1273,8 @@ export function readEntry(hippoRoot, id, tenantId) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
         const row = tenantId !== undefined
             ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id = ? AND tenant_id = ?`).get(id, tenantId)
             : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id = ?`).get(id);
@@ -1251,6 +1301,8 @@ export function loadEntriesByIds(hippoRoot, ids, tenantId) {
         // T2: no ORDER BY meant row order followed SQLite's IN(...) scan order
         // (undefined w.r.t. the caller's `ids` order). created ASC, id ASC
         // makes it deterministic.
+        // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
         const rows = tenantId !== undefined
             ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (${placeholders}) AND tenant_id = ? ORDER BY created ASC, content ASC, id ASC`).all(...capped, tenantId)
             : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (${placeholders}) ORDER BY created ASC, content ASC, id ASC`).all(...capped);
@@ -1288,10 +1340,12 @@ export function loadSessionRawMemories(hippoRoot, sessionId, tenantId, cap) {
         if (cap !== undefined && cap > 0) {
             sql += ' ORDER BY created DESC, id DESC LIMIT ?';
             params.push(cap);
+            // SAFETY: sql starts from MEMORY_SELECT_COLUMNS, matching MemoryRow.
             const rows = db.prepare(sql).all(...params);
             return rows.reverse().map(rowToEntry);
         }
         sql += ' ORDER BY created ASC, id ASC';
+        // SAFETY: sql starts from MEMORY_SELECT_COLUMNS, matching MemoryRow.
         const rows = db.prepare(sql).all(...params);
         return rows.map(rowToEntry);
     }
@@ -1338,6 +1392,7 @@ export function countSessionRawMemories(hippoRoot, sessionId, tenantId, scope) {
             // AND != 'unknown:legacy'). Mirrors api.passesScopeFilterForRecall.
             sql += ` AND (scope IS NULL OR (scope NOT LIKE '%:private:%' AND scope != 'unknown:legacy'))`;
         }
+        // SAFETY: row's shape matches the single `COUNT(*) AS c` column above.
         const row = db.prepare(sql).get(...params);
         return Number(row?.c ?? 0);
     }
@@ -1392,6 +1447,7 @@ export function loadFreshRawMemories(hippoRoot, count, tenantId, sessionId) {
         // cross-ingest-stable.
         sql += ' ORDER BY created DESC, content ASC, id ASC LIMIT ?';
         params.push(capped);
+        // SAFETY: sql starts from MEMORY_SELECT_COLUMNS, matching MemoryRow.
         const rows = db.prepare(sql).all(...params);
         return rows.map(rowToEntry);
     }
@@ -1408,6 +1464,8 @@ export function loadChildrenOf(hippoRoot, parentId, tenantId) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
         const rows = tenantId !== undefined
             ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE dag_parent_id = ? AND tenant_id = ? ORDER BY created ASC, id ASC`).all(parentId, tenantId)
             : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE dag_parent_id = ? ORDER BY created ASC, id ASC`).all(parentId);
@@ -1437,6 +1495,7 @@ export function loadChildrenOf(hippoRoot, parentId, tenantId) {
  * with `id` existed.
  */
 export function deleteEntryCore(db, id, opts) {
+    // SAFETY: row's shape matches the three columns named in the SELECT above.
     const row = db
         .prepare(`SELECT id, tenant_id, dag_parent_id FROM memories WHERE id = ?`)
         .get(id);
@@ -1511,6 +1570,8 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds) {
         const tenantById = new Map();
         if (toDeleteIds.length > 0) {
             const placeholders = toDeleteIds.map(() => '?').join(',');
+            // SAFETY: rows' shape matches the two columns named in the SELECT
+            // above.
             const rows = db.prepare(`SELECT dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders})`).all(...toDeleteIds);
             for (const row of rows) {
                 if (row.dag_parent_id) {
@@ -1633,6 +1694,8 @@ export function loadAllEntries(hippoRoot, tenantId) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
         const rows = tenantId !== undefined
             ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? ORDER BY created ASC, id ASC`).all(tenantId)
             : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
@@ -1709,6 +1772,7 @@ export function rebuildIndex(hippoRoot) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: rows' shape matches the single `id` column selected above.
         const existingIds = new Set(db.prepare(`SELECT id FROM memories`).all().map((row) => row.id));
         const legacyEntries = loadLegacyEntriesFromMarkdown(hippoRoot).filter((entry) => !existingIds.has(entry.id));
         if (legacyEntries.length > 0) {
@@ -1803,6 +1867,7 @@ export function loadSessionDecayContext(hippoRoot) {
     const db = openHippoDb(hippoRoot);
     try {
         // Get recent consolidation timestamps (last 20)
+        // SAFETY: rows' shape matches the single `timestamp` column above.
         const rows = db.prepare(`SELECT timestamp FROM consolidation_runs ORDER BY timestamp DESC, id DESC LIMIT 20`).all();
         const sleepCount = Number(getMeta(db, 'sleep_count', '0')) || rows.length;
         if (rows.length < 2) {
@@ -1876,6 +1941,7 @@ export function saveActiveTaskSnapshot(hippoRoot, tenantId, snapshot) {
     `).run(snapshot.task, snapshot.summary, snapshot.next_step, snapshot.source ?? 'cli', snapshot.session_id ?? null, snapshot.scope ?? null, tenantId, now, now);
         db.exec('COMMIT');
         const id = Number(result.lastInsertRowid ?? 0);
+        // SAFETY: row's shape matches the ten columns named in the SELECT above.
         const row = db.prepare(`
       SELECT id, task, summary, next_step, status, source, session_id, scope, created_at, updated_at
       FROM task_snapshots
@@ -1906,6 +1972,7 @@ export function loadActiveTaskSnapshot(hippoRoot, tenantId) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: row's shape matches the ten columns named in the SELECT above.
         const row = db.prepare(`
       SELECT id, task, summary, next_step, status, source, session_id, scope, created_at, updated_at
       FROM task_snapshots
@@ -1925,12 +1992,64 @@ export function loadActiveTaskSnapshot(hippoRoot, tenantId) {
         closeHippoDb(db);
     }
 }
+/**
+ * Default freshness bound for AMBIENT active-task-snapshot reads (DF1,
+ * docs/plans/2026-08-23-df1-snapshot-lifecycle.md): 72h, chosen over 48h so
+ * a Friday-evening orphan still offers continuity on Monday morning.
+ * Exported so callers can override via `loadFreshActiveTaskSnapshot`'s
+ * `opts.maxAgeMs`; deliberately no env knob (Simplicity First).
+ */
+export const SNAPSHOT_AMBIENT_MAX_AGE_MS = 72 * 60 * 60 * 1000;
+/** A usable session id: non-null, non-empty string. Named predicate (not an
+ * inline `typeof` check) so the owner-match rule in
+ * `loadFreshActiveTaskSnapshot` states its contract once. */
+function isNonEmptySessionId(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Bounded read for AMBIENT active-task-snapshot surfaces (UserPromptSubmit
+ * hook context, MCP recall block) — the never-expires fix for DF1. A
+ * snapshot written by `hippo pre-compact` has no death path tied to the
+ * session that owns it, so an orphaned row would otherwise inject into
+ * every prompt of every later session forever. Wraps `loadActiveTaskSnapshot`
+ * (unchanged, still the source of truth for explicit continuity surfaces),
+ * then applies, in order:
+ *
+ * 1. Owner match — ONLY when both `opts.sessionId` and the snapshot's
+ *    `session_id` are non-null, non-empty strings and strictly equal
+ *    (`===`). Owner reads are unbounded: the session that owns the snapshot
+ *    can always see its own working state, regardless of age.
+ * 2. Age check — everything else, including absent-vs-absent ids. A
+ *    null/undefined/empty id on EITHER side never counts as an owner match;
+ *    it falls through here instead. (`runPreCompact` can legitimately save a
+ *    snapshot with `session_id = null`; a null-equals-null "match" would
+ *    reopen indefinite ambient injection for exactly those rows.) Returns
+ *    the snapshot only when `age(updated_at) <= maxAgeMs` (default
+ *    `SNAPSHOT_AMBIENT_MAX_AGE_MS`); otherwise null.
+ *
+ * No SQL change — age derives from the existing `updated_at` column.
+ */
+export function loadFreshActiveTaskSnapshot(hippoRoot, tenantId, opts = {}) {
+    const snapshot = loadActiveTaskSnapshot(hippoRoot, tenantId);
+    if (!snapshot)
+        return null;
+    const callerSessionId = opts.sessionId;
+    const isOwnerMatch = isNonEmptySessionId(callerSessionId) &&
+        isNonEmptySessionId(snapshot.session_id) &&
+        callerSessionId === snapshot.session_id;
+    if (isOwnerMatch)
+        return snapshot;
+    const maxAgeMs = opts.maxAgeMs ?? SNAPSHOT_AMBIENT_MAX_AGE_MS;
+    const ageMs = Date.now() - Date.parse(snapshot.updated_at);
+    return ageMs <= maxAgeMs ? snapshot : null;
+}
 export function clearActiveTaskSnapshot(hippoRoot, tenantId, clearedStatus = 'cleared') {
     assertTenantId('clearActiveTaskSnapshot', tenantId);
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     const now = new Date().toISOString();
     try {
+        // SAFETY: active's shape matches the single `id` column selected above.
         const active = db.prepare(`SELECT id FROM task_snapshots WHERE status = 'active' AND tenant_id = ? ORDER BY updated_at DESC, id DESC LIMIT 1`).get(tenantId);
         if (!active?.id) {
             removeActiveTaskMirror(hippoRoot, tenantId);
@@ -1944,6 +2063,28 @@ export function clearActiveTaskSnapshot(hippoRoot, tenantId, clearedStatus = 'cl
         closeHippoDb(db);
     }
 }
+/**
+ * Close the `active` task snapshot(s) owned by `sessionId`, for the T3
+ * session-end death path (DF1, docs/plans/2026-08-23-df1-snapshot-lifecycle.md).
+ * Only one `active` row exists per tenant in practice (supersession happens
+ * at save), but the WHERE clause scopes on `session_id` too — not just
+ * `status='active' AND tenant_id=?` — so an ending session can never close a
+ * different, newer session's active snapshot. Returns the number of rows
+ * closed (0 when no active row is owned by `sessionId`).
+ */
+export function closeTaskSnapshotsForSession(hippoRoot, tenantId, sessionId, status = 'session-ended') {
+    assertTenantId('closeTaskSnapshotsForSession', tenantId);
+    initStore(hippoRoot);
+    const db = openHippoDb(hippoRoot);
+    const now = new Date().toISOString();
+    try {
+        const result = db.prepare(`UPDATE task_snapshots SET status = ?, updated_at = ? WHERE status = 'active' AND tenant_id = ? AND session_id = ?`).run(status, now, tenantId, sessionId);
+        return Number(result.changes ?? 0);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 export function appendSessionEvent(hippoRoot, tenantId, event) {
     assertTenantId('appendSessionEvent', tenantId);
     initStore(hippoRoot);
@@ -1957,6 +2098,8 @@ export function appendSessionEvent(hippoRoot, tenantId, event) {
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(event.session_id, event.task ?? null, event.event_type, event.content, event.source ?? 'cli', event.scope ?? null, JSON.stringify(event.metadata ?? {}), tenantId, now);
         const id = Number(result.lastInsertRowid ?? 0);
+        // SAFETY: row's shape matches the nine columns named in the SELECT
+        // above.
         const row = db.prepare(`
       SELECT id, session_id, task, event_type, content, source, scope, metadata_json, created_at
       FROM session_events
@@ -1966,6 +2109,8 @@ export function appendSessionEvent(hippoRoot, tenantId, event) {
             throw new Error('Failed to reload saved session event');
         }
         const loaded = rowToSessionEvent(row);
+        // SAFETY: recentRows' shape matches the nine columns named in the
+        // SELECT above.
         const recentRows = db.prepare(`
       SELECT id, session_id, task, event_type, content, source, scope, metadata_json, created_at
       FROM session_events
@@ -1999,6 +2144,8 @@ export function listSessionEvents(hippoRoot, tenantId, options = {}) {
         const limit = Math.max(1, Math.trunc(options.limit ?? 8));
         params.push(limit);
         const where = `WHERE ${clauses.join(' AND ')}`;
+        // SAFETY: rows' shape matches the nine columns named in the SELECT
+        // above.
         const rows = db.prepare(`
       SELECT id, session_id, task, event_type, content, source, scope, metadata_json, created_at
       FROM session_events
@@ -2021,6 +2168,8 @@ export function findPromotableSessions(hippoRoot, tenantId, sinceMs) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: rows' shape matches the single `session_id` column selected
+        // above.
         const rows = db.prepare(`
       SELECT DISTINCT session_id FROM session_events
       WHERE event_type = 'session_complete' AND created_at >= ? AND tenant_id = ?
@@ -2065,6 +2214,8 @@ export function listMemoryConflicts(hippoRoot, status = 'open', tenantId) {
             // Tenanted query — JOIN to memories on both conflict members and require
             // each in-tenant, so neither a normal cross-tenant pair nor a stale
             // pre-fix row surfaces (consistent with resolveConflict).
+            // SAFETY: both branches select the same eight mc.* columns (aliased
+            // to MemoryConflictRow's field names) from memory_conflicts.
             rows = allStatuses
                 ? db.prepare(`
             SELECT mc.id, mc.memory_a_id, mc.memory_b_id, mc.reason, mc.score,
@@ -2087,6 +2238,8 @@ export function listMemoryConflicts(hippoRoot, status = 'open', tenantId) {
         }
         else {
             // Unscoped query — legacy direct-mode (CLI, tests, consolidate).
+            // SAFETY: both branches select the same eight columns matching
+            // MemoryConflictRow's field set.
             rows = allStatuses
                 ? db.prepare(`
             SELECT id, memory_a_id, memory_b_id, reason, score, status, detected_at, updated_at
@@ -2116,6 +2269,7 @@ export function replaceDetectedConflicts(hippoRoot, detected, detectedAt = new D
         // inserting rows and when rebuilding conflicts_with_json, so a stale
         // cross-tenant row can neither persist nor leak a foreign id.
         const tenantById = new Map();
+        // SAFETY: rows' shape matches the two columns named in the SELECT below.
         for (const r of db.prepare(`SELECT id, tenant_id FROM memories`).all()) {
             tenantById.set(r.id, r.tenant_id);
         }
@@ -2130,6 +2284,8 @@ export function replaceDetectedConflicts(hippoRoot, detected, detectedAt = new D
             score: conflict.score,
         }));
         const detectedKeys = new Set(canonicalDetected.map((conflict) => `${conflict.memory_a_id}::${conflict.memory_b_id}`));
+        // SAFETY: openRows' shape matches the eight columns named in the SELECT
+        // above.
         const openRows = db.prepare(`
       SELECT id, memory_a_id, memory_b_id, reason, score, status, detected_at, updated_at
       FROM memory_conflicts
@@ -2162,6 +2318,7 @@ export function replaceDetectedConflicts(hippoRoot, detected, detectedAt = new D
           updated_at = excluded.updated_at
       `).run(conflict.memory_a_id, conflict.memory_b_id, conflict.reason, conflict.score, detectedAt, detectedAt);
         }
+        // SAFETY: openConflicts' shape matches the two columns named above.
         const openConflicts = db.prepare(`
       SELECT memory_a_id, memory_b_id
       FROM memory_conflicts
@@ -2180,6 +2337,8 @@ export function replaceDetectedConflicts(hippoRoot, detected, detectedAt = new D
             refMap.get(row.memory_a_id).add(row.memory_b_id);
             refMap.get(row.memory_b_id).add(row.memory_a_id);
         }
+        // SAFETY: memoryRows' shape matches the single `id` column selected
+        // above.
         const memoryRows = db.prepare(`SELECT id FROM memories`).all();
         for (const memory of memoryRows) {
             const refs = Array.from(refMap.get(memory.id) ?? []).sort();
@@ -2226,6 +2385,8 @@ export function resolveConflict(hippoRoot, conflictId, keepId, forgetLoser = fal
     const memScope = tenantId !== undefined ? ' AND tenant_id = ?' : '';
     const memArgs = tenantId !== undefined ? [tenantId] : [];
     try {
+        // SAFETY: both branches select the same eight columns (aliased in the
+        // tenanted branch) matching MemoryConflictRow's field set.
         const row = (tenantId !== undefined
             ? db.prepare(`
           SELECT mc.id, mc.memory_a_id, mc.memory_b_id, mc.reason, mc.score,
@@ -2273,6 +2434,8 @@ export function resolveConflict(hippoRoot, conflictId, keepId, forgetLoser = fal
         const extraRemovedRawIds = [];
         const removeLoser = forgetLoser || opts?.rejectLoserValue === true;
         if (removeLoser) {
+            // SAFETY: loserRow's shape matches the three columns named in the
+            // SELECT above.
             const loserRow = db
                 .prepare(`SELECT kind, content, tenant_id FROM memories WHERE id = ?${memScope}`)
                 .get(loserId, ...memArgs);
@@ -2303,6 +2466,8 @@ export function resolveConflict(hippoRoot, conflictId, keepId, forgetLoser = fal
                     // to keep it in this same resolution, and this branch must not
                     // undo that choice in the same transaction.
                     const loserTenantId = loserRow.tenant_id ?? 'default';
+                    // SAFETY: dupRows' shape matches the three columns named in the
+                    // SELECT above.
                     const dupRows = db
                         .prepare(`SELECT id, kind, content FROM memories WHERE tenant_id = ? AND id != ? AND id != ?`)
                         .all(loserTenantId, loserId, keepId);
@@ -2337,6 +2502,8 @@ export function resolveConflict(hippoRoot, conflictId, keepId, forgetLoser = fal
                 .run(loserId, ...memArgs);
         }
         // Clean up conflicts_with references
+        // SAFETY: keepRow's shape matches the single `conflicts_with_json`
+        // column selected above.
         const keepRow = db.prepare(`SELECT conflicts_with_json FROM memories WHERE id = ?${memScope}`).get(keepId, ...memArgs);
         if (keepRow) {
             const refs = JSON.parse(keepRow.conflicts_with_json || '[]');
@@ -2345,6 +2512,8 @@ export function resolveConflict(hippoRoot, conflictId, keepId, forgetLoser = fal
                 .run(JSON.stringify(cleaned), keepId, ...memArgs);
         }
         if (!loserRemoved) {
+            // SAFETY: loserRow's shape matches the single `conflicts_with_json`
+            // column named in the SELECT below.
             const loserRow = db.prepare(`SELECT conflicts_with_json FROM memories WHERE id = ?${memScope}`).get(loserId, ...memArgs);
             if (loserRow) {
                 const refs = JSON.parse(loserRow.conflicts_with_json || '[]');
@@ -2356,18 +2525,26 @@ export function resolveConflict(hippoRoot, conflictId, keepId, forgetLoser = fal
         // AT1: the missing audit (plan §5 — resolveConflict wrote ZERO audit_log
         // rows on any path before this). Every path — weaken, forget, reject —
         // lands exactly one conflict_resolve row.
-        audit(db, 'conflict_resolve', keepId, {
+        const conflictResolveMeta = {
             conflictId,
             keepId,
             loserId,
             disposition: loserRemoved ? (loserWasRaw ? 'archived_raw' : 'deleted') : 'weakened',
             rejected: Boolean(opts?.rejectLoserValue),
-            rejectedDigest,
             // AT1 P1 fix: every row this call removed, not just loserId — the
             // same-tenant duplicate sweep above (extraRemovedIds) needs an
             // audit trail too.
             removedIds: loserRemoved ? [loserId, ...extraRemovedIds] : [],
-        }, opts?.rejectedBy ?? 'cli', tenantId);
+        };
+        // Assigned only when present so the serialized audit payload keeps
+        // omitting the key, exactly as the pre-migration object literal did.
+        if (rejectedDigest !== undefined)
+            conflictResolveMeta.rejectedDigest = rejectedDigest;
+        // Fresh spread literal: ConflictResolveMeta is a closed interface (no
+        // index signature) and isn't directly assignable to audit()'s
+        // Record<string, JsonValue> metadata param; a spread into a fresh
+        // object literal satisfies it without widening the declared type above.
+        audit(db, 'conflict_resolve', keepId, { ...conflictResolveMeta }, opts?.rejectedBy ?? 'cli', tenantId);
         db.exec('COMMIT');
         syncMirrorFiles(hippoRoot, db);
         // AT1 P1b fix: mirror purge + reaper stamp for EVERY removed loser, not
@@ -2431,6 +2608,8 @@ export function saveSessionHandoff(hippoRoot, tenantId, handoff) {
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(handoff.sessionId, handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, tenantId, now);
         const id = Number(result.lastInsertRowid ?? 0);
+        // SAFETY: row's shape matches the nine columns named in the SELECT
+        // above.
         const row = db.prepare(`
       SELECT id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at
       FROM session_handoffs
@@ -2455,6 +2634,8 @@ export function loadLatestHandoff(hippoRoot, tenantId, sessionId) {
     try {
         let row;
         if (sessionId) {
+            // SAFETY: row's shape matches the nine columns named in the SELECT
+            // below.
             row = db.prepare(`
         SELECT id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at
         FROM session_handoffs
@@ -2464,6 +2645,8 @@ export function loadLatestHandoff(hippoRoot, tenantId, sessionId) {
       `).get(sessionId, tenantId);
         }
         else {
+            // SAFETY: row's shape matches the nine columns named in the SELECT
+            // below.
             row = db.prepare(`
         SELECT id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at
         FROM session_handoffs
@@ -2486,6 +2669,8 @@ export function loadHandoffById(hippoRoot, tenantId, id) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: row's shape matches the nine columns named in the SELECT
+        // above.
         const row = db.prepare(`
       SELECT id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at
       FROM session_handoffs
@@ -2519,6 +2704,8 @@ export function loadDirtySummaries(hippoRoot, tenantId) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
         const rows = db.prepare(`
       SELECT ${MEMORY_SELECT_COLUMNS}
         FROM memories
@@ -2553,6 +2740,8 @@ export function markSummaryDirtyInTx(db, summaryId, tenantId, actor) {
     // v0.30 / E5: widened dag_level=2 -> IN (2, 3). RETURNING dag_level reads
     // actual level in same round trip so audit metadata stays accurate without
     // a SELECT-before-UPDATE extra DB op on this hot path (5 caller sites).
+    // SAFETY: result's shape matches the single `dag_level` column returned
+    // above.
     const result = db.prepare(`
     UPDATE memories
        SET summary_dirty = 1
@@ -2587,6 +2776,8 @@ export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli')
     try {
         // v0.30 / E5: widened dag_level=2 -> IN (2, 3). RETURNING dag_level reads
         // actual level in same round trip.
+        // SAFETY: result's shape matches the single `dag_level` column returned
+        // above.
         const result = db.prepare(`
       UPDATE memories
          SET summary_dirty = 1
@@ -2631,6 +2822,8 @@ export function loadAllL2Summaries(hippoRoot) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
         const rows = db.prepare(`
       SELECT ${MEMORY_SELECT_COLUMNS}
         FROM memories
@@ -2658,6 +2851,8 @@ export function loadAllDirtySummaries(hippoRoot) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
         const rows = db.prepare(`
       SELECT ${MEMORY_SELECT_COLUMNS}
         FROM memories
@@ -2683,6 +2878,8 @@ export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
+        // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
+        // MemoryRow's field set.
         const rows = db.prepare(`
       SELECT ${MEMORY_SELECT_COLUMNS}
         FROM memories
@@ -2864,6 +3061,8 @@ export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, acto
     try {
         // v0.30 / E5: widened dag_level=2 -> IN (2, 3). RETURNING dag_level reads
         // actual level so audit metadata stays accurate without an extra SELECT.
+        // SAFETY: result's shape matches the single `dag_level` column returned
+        // below.
         const result = db.prepare(`
       UPDATE memories
          SET summary_dirty = 0