hippo-memory 1.52.0 → 1.52.2

package/dist/store.js

@@ -13,6 +13,7 @@ import { rowToSessionHandoff, isHandoffOutcome } from './handoff.js';
 import { CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
 import { tokenize, markRetrieved } from './search.js';
 import { isRecallBoostAblated } from './ablation.js';
+import { rarestPromptTerms, RAREST_TERM_COUNT } from './prompt-recall.js';
 import { appendAuditEvent } from './audit.js';
 import { resolveTenantId } from './tenant.js';
 import { deriveOriginProject, originFromSource, findHippoStoreDir, realpathOrResolve } from './project-identity.js';
@@ -113,6 +114,10 @@ export function isInitialized(hippoRoot) {
     return fs.existsSync(path.join(hippoRoot, 'hippo.db'));
 }
 export function initStore(hippoRoot) {
+    closeHippoDb(openStore(hippoRoot));
+}
+/** One open connection with init done on it, for callers who used to pay for `initStore` + a second `openHippoDb`. */
+export function openStore(hippoRoot) {
     ensureMirrorDirectories(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
@@ -121,9 +126,16 @@ export function initStore(hippoRoot) {
             syncMirrorFiles(hippoRoot, db);
         }
         recordHalfLifeBaseForNewStore(db);
+        return db;
     }
-    finally {
-        closeHippoDb(db);
+    catch (error) {
+        try {
+            closeHippoDb(db);
+        }
+        catch {
+            // Best effort only; surface the original init error.
+        }
+        throw error;
     }
 }
 /** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
@@ -1111,8 +1123,7 @@ function syncMirrorFiles(hippoRoot, db) {
 }
 /** Load the derived index from SQLite. Read-only: index.json is only ever written by `rebuildIndex`. */
 export function loadIndex(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return buildIndexFromDb(db);
     }
@@ -1131,8 +1142,7 @@ export function loadIndex(hippoRoot) {
  * is left untouched; only `rebuildIndex` writes it.
  */
 export function saveIndex(hippoRoot, index) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN');
         try {
@@ -1204,10 +1214,9 @@ function stampOriginProjectForImport(hippoRoot, entry) {
     };
 }
 export function writeEntry(hippoRoot, entry, opts) {
-    initStore(hippoRoot);
-    const stamped = stampOriginProject(hippoRoot, entry);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
+        const stamped = stampOriginProject(hippoRoot, entry);
         writeEntryDbOnly(db, stamped, opts);
         opts?.afterCommit?.();
         writeEntryMirrors(hippoRoot, stamped);
@@ -1286,8 +1295,7 @@ export function writeEntryMirrors(hippoRoot, entry) {
  * legacy single-tenant callers and the writeEntry/readEntry round-trip.
  */
 export function readEntry(hippoRoot, id, tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -1310,8 +1318,7 @@ export function loadEntriesByIds(hippoRoot, ids, tenantId) {
     if (ids.length === 0)
         return [];
     const capped = ids.slice(0, 500);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const placeholders = capped.map(() => '?').join(',');
         // T2: no ORDER BY meant row order followed SQLite's IN(...) scan order
@@ -1383,8 +1390,7 @@ export function strengthenRetrieved(hippoRoot, ids, tenantId) {
 export function loadSessionRawMemories(hippoRoot, sessionId, tenantId, cap) {
     if (!sessionId)
         return [];
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const params = [];
         let sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE kind = 'raw' AND source_session_id = ? AND superseded_by IS NULL`;
@@ -1429,8 +1435,7 @@ export function loadSessionRawMemories(hippoRoot, sessionId, tenantId, cap) {
 export function countSessionRawMemories(hippoRoot, sessionId, tenantId, scope) {
     if (!sessionId)
         return 0;
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const params = [];
         let sql = `SELECT COUNT(*) AS c FROM memories WHERE kind = 'raw' AND source_session_id = ? AND superseded_by IS NULL`;
@@ -1483,8 +1488,7 @@ export function loadFreshRawMemories(hippoRoot, count, tenantId, sessionId) {
     if (count <= 0)
         return [];
     const capped = Math.min(count, 200);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const params = [];
         let sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE kind = 'raw' AND superseded_by IS NULL`;
@@ -1517,8 +1521,7 @@ export function loadFreshRawMemories(hippoRoot, count, tenantId, sessionId) {
  * Used by `drillDown` (Task 3).
  */
 export function loadChildrenOf(hippoRoot, parentId, tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -1586,8 +1589,7 @@ export function deleteEntryCore(db, id, opts) {
  * existing caller.
  */
 export function deleteEntry(hippoRoot, id, opts) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const result = deleteEntryCore(db, id, opts);
         if (!result)
@@ -1621,8 +1623,7 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
     const dormantMoves = opts?.dormant ?? [];
     if (toWrite.length === 0 && toDeleteIds.length === 0 && dormantMoves.length === 0)
         return [];
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // BEGIN IMMEDIATE (codex delta-review P2): the AT1 tombstone probes below
         // READ before the first write. Under a deferred BEGIN, that read pins a
@@ -1788,8 +1789,7 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
  * paths that surface results to a user MUST pass a resolved tenant.
  */
 export function loadAllEntries(hippoRoot, tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return selectAllEntries(db, tenantId);
     }
@@ -1806,15 +1806,26 @@ export function selectAllEntries(db, tenantId) {
         : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
     return rows.map(rowToEntry);
 }
+// Content of every tenant row tagged `tag`, without reading the rest of the store.
+// `instr` is a substring prefilter over the raw JSON; `includes` below re-checks exactly.
+export function loadContentsWithTag(hippoRoot, tenantId, tag) {
+    const db = openStore(hippoRoot);
+    try {
+        /** SAFETY: rows' shape matches the two columns named in the SELECT below. */
+        const rows = db.prepare(`SELECT content, tags_json FROM memories WHERE tenant_id = ? AND instr(tags_json, ?) > 0`).all(tenantId, JSON.stringify(tag));
+        return rows.filter((r) => parseJsonArray(r.tags_json).includes(tag)).map((r) => r.content);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 // The pins plus the `recentNeeded` newest rows that pass `admit`, for ambient
-// injection. One connection: opening one costs ~5.8ms on a warm 1896-row store,
-// so a second handle loses more than the narrower scan saves.
-export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit) {
-    initStore(hippoRoot);
+// injection. One connection; `recall` piggybacks the Z1 FTS query on it too.
+export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit, recall) {
     // A SQL LIMIT takes an integer; the Array.slice this replaced truncated one,
     // and include_recent is any non-negative finite number at the HTTP edge.
     const needed = Math.trunc(recentNeeded);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: every `where` below starts from MEMORY_SELECT_COLUMNS' table.
         const run = (where, params) => db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE ${where}`).all(...params).map(rowToEntry);
@@ -1842,10 +1853,17 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit)
         }
         // loadAllEntries' order: rankedPinned's comparator can tie and Array.sort
         // is stable, so input order is load-bearing downstream.
-        return [...byId.values()].sort((a, b) => {
+        const entries = [...byId.values()].sort((a, b) => {
             const byCreated = a.created.localeCompare(b.created);
             return byCreated !== 0 ? byCreated : a.id.localeCompare(b.id);
         });
+        if (!recall)
+            return { entries };
+        const ftsQuery = pickRarestFtsQuery(db, recall.terms);
+        const recallEntries = ftsQuery
+            ? loadRecallSearchEntriesFromDb(db, ftsQuery, recall.limit, tenantId, undefined, 'exact', false)
+            : [];
+        return { entries, recall: recallEntries };
     }
     finally {
         closeHippoDb(db);
@@ -1859,8 +1877,7 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit)
  * by tenant_id. Cross-tenant memories never surface. Omitted = no filter.
  */
 export function loadSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return loadSearchRows(db, query, limit, tenantId).map(rowToEntry);
     }
@@ -1893,30 +1910,53 @@ export function loadSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDI
  * undefined as "no tenant filter" for legacy callers.
  */
 export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
-        // explicitScopeMode only matters when requestedScope is set:
-        //   'exact'    — api.recall semantics: narrow to m.scope = requested.
-        //   'additive' — CLI --scope semantics (v1.25.0): default-admitted set
-        //                PLUS the requested scope; see RecallScopeFilter docs.
-        const scopeFilter = requestedScope && requestedScope !== ''
-            ? explicitScopeMode === 'additive'
-                ? { mode: 'default-deny-or-exact', value: requestedScope }
-                : { mode: 'exact', value: requestedScope }
-            : { mode: 'default-deny' };
-        return loadSearchRows(db, query, limit, tenantId, scopeFilter, includeSuperseded).map(rowToEntry);
+        return loadRecallSearchEntriesFromDb(db, query, limit, tenantId, requestedScope, explicitScopeMode, includeSuperseded);
     }
     finally {
         closeHippoDb(db);
     }
 }
+// Split out so callers with an already-open db (Z1 prompt-recall path) skip
+// the initStore+open/close cycle per store per call.
+export function loadRecallSearchEntriesFromDb(db, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true) {
+    // 'exact' narrows to requestedScope; 'additive' adds it to the default-admitted set.
+    const scopeFilter = requestedScope && requestedScope !== ''
+        ? explicitScopeMode === 'additive'
+            ? { mode: 'default-deny-or-exact', value: requestedScope }
+            : { mode: 'exact', value: requestedScope }
+        : { mode: 'default-deny' };
+    return loadSearchRows(db, query, limit, tenantId, scopeFilter, includeSuperseded).map(rowToEntry);
+}
+/** Rarest-K prompt terms for this connection's FTS index, as a space-joined query string.
+ *  Without FTS, returns the first 32 terms, as before rarest-term selection. */
+export function pickRarestFtsQuery(db, terms, maxTerms = RAREST_TERM_COUNT) {
+    // The LIKE path has no bm25 ranking to bound, so it keeps the pre-rarest 32-term query.
+    if (!isFtsAvailable(db))
+        return terms.slice(0, 32).join(' ');
+    db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.z1_rarest_vocab USING fts5vocab(main, 'memories_fts', 'row')`);
+    // unicode61 splits `journal_mode` into two vocab terms; a term's count is its rarest part's (an upper bound).
+    const partsOf = (t) => t.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    const vocab = Array.from(new Set(terms.flatMap(partsOf)));
+    if (vocab.length === 0)
+        return '';
+    // SAFETY: rows' shape matches the two columns named in the SELECT.
+    const rows = db
+        .prepare(`SELECT term, doc FROM temp.z1_rarest_vocab WHERE term IN (${vocab.map(() => '?').join(', ')})`)
+        .all(...vocab);
+    const counts = new Map(rows.map((r) => [r.term, r.doc]));
+    const docCount = (t) => {
+        const parts = partsOf(t);
+        return parts.length === 0 ? 0 : Math.min(...parts.map((x) => counts.get(x) ?? 0));
+    };
+    return rarestPromptTerms(terms, docCount, maxTerms).join(' ');
+}
 /**
  * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
  */
 export function rebuildIndex(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(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));
@@ -1967,8 +2007,7 @@ export function rebuildIndex(hippoRoot) {
     }
 }
 export function updateStats(hippoRoot, delta) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // One atomic statement per counter, and only for counters the caller
         // named: the read-modify-write this replaces both lost increments to a
@@ -1995,8 +2034,7 @@ export function updateStats(hippoRoot, delta) {
     }
 }
 export function loadStats(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return buildStatsFromDb(db);
     }
@@ -2005,8 +2043,7 @@ export function loadStats(hippoRoot) {
     }
 }
 export function appendConsolidationRun(hippoRoot, run) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.prepare(`INSERT INTO consolidation_runs(timestamp, decayed, merged, removed) VALUES (?, ?, ?, ?)`).run(run.timestamp, run.decayed, run.merged, run.removed);
         pruneConsolidationRuns(db, 50);
@@ -2018,8 +2055,7 @@ export function appendConsolidationRun(hippoRoot, run) {
 }
 /** Rows a tenant created since the last sleep (runs are host-wide), looking back at most 24 hours. */
 export function countCreatedSinceLastSleep(hippoRoot, tenantId, now = new Date()) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const dayAgo = new Date(now.getTime() - 86_400_000).toISOString();
         const row = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE tenant_id = ?
@@ -2035,8 +2071,7 @@ export function countCreatedSinceLastSleep(hippoRoot, tenantId, now = new Date()
  * Uses consolidation_runs timestamps to compute session intervals.
  */
 export function loadSessionDecayContext(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // Get recent consolidation timestamps (last 20)
         // SAFETY: rows' shape matches the single `timestamp` column above.
@@ -2063,8 +2098,7 @@ export function loadSessionDecayContext(hippoRoot) {
  * Increment the sleep counter. Called after each consolidation run.
  */
 export function incrementSleepCount(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const current = Number(getMeta(db, 'sleep_count', '0')) || 0;
         setMeta(db, 'sleep_count', String(current + 1));
@@ -2101,8 +2135,7 @@ export function assertTenantId(fnName, value) {
 }
 export function saveActiveTaskSnapshot(hippoRoot, tenantId, snapshot) {
     assertTenantId('saveActiveTaskSnapshot', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     const now = new Date().toISOString();
     try {
         db.exec('BEGIN');
@@ -2141,8 +2174,7 @@ export function saveActiveTaskSnapshot(hippoRoot, tenantId, snapshot) {
 }
 export function loadActiveTaskSnapshot(hippoRoot, tenantId) {
     assertTenantId('loadActiveTaskSnapshot', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: row's shape matches the ten columns named in the SELECT above.
         const row = db.prepare(`
@@ -2217,8 +2249,7 @@ export function loadFreshActiveTaskSnapshot(hippoRoot, tenantId, opts = {}) {
 }
 export function clearActiveTaskSnapshot(hippoRoot, tenantId, clearedStatus = 'cleared') {
     assertTenantId('clearActiveTaskSnapshot', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     const now = new Date().toISOString();
     try {
         // SAFETY: active's shape matches the single `id` column selected above.
@@ -2246,8 +2277,7 @@ export function clearActiveTaskSnapshot(hippoRoot, tenantId, clearedStatus = 'cl
  */
 export function closeTaskSnapshotsForSession(hippoRoot, tenantId, sessionId, status = 'session-ended') {
     assertTenantId('closeTaskSnapshotsForSession', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(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);
@@ -2259,8 +2289,7 @@ export function closeTaskSnapshotsForSession(hippoRoot, tenantId, sessionId, sta
 }
 export function appendSessionEvent(hippoRoot, tenantId, event) {
     assertTenantId('appendSessionEvent', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     const now = new Date().toISOString();
     // v1.2: scope is wired through. Default-deny in api.recall + cmdRecall
     // continuity reads applies to slack:private:* and 'unknown:legacy' rows.
@@ -2300,8 +2329,7 @@ export function appendSessionEvent(hippoRoot, tenantId, event) {
 }
 export function listSessionEvents(hippoRoot, tenantId, options = {}) {
     assertTenantId('listSessionEvents', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const clauses = ['tenant_id = ?'];
         const params = [tenantId];
@@ -2337,8 +2365,7 @@ export function listSessionEvents(hippoRoot, tenantId, options = {}) {
  */
 export function findPromotableSessions(hippoRoot, tenantId, sinceMs) {
     assertTenantId('findPromotableSessions', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: rows' shape matches the single `session_id` column selected
         // above.
@@ -2358,8 +2385,7 @@ export function findPromotableSessions(hippoRoot, tenantId, sinceMs) {
  */
 export function traceExistsForSession(hippoRoot, tenantId, session_id) {
     assertTenantId('traceExistsForSession', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const row = db.prepare(`
       SELECT 1 FROM memories
@@ -2373,8 +2399,7 @@ export function traceExistsForSession(hippoRoot, tenantId, session_id) {
     }
 }
 export function listMemoryConflicts(hippoRoot, status = 'open', tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // v0.28 — '*' is a sentinel meaning "no status filter, return all rows".
         // Pre-v0.28 callers (cli/mcp/dashboard) always passed 'open' or default,
@@ -2432,8 +2457,7 @@ export function listMemoryConflicts(hippoRoot, status = 'open', tenantId) {
     }
 }
 export function replaceDetectedConflicts(hippoRoot, detected, detectedAt = new Date().toISOString()) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN');
         // Tenant guard (E2): a conflict is meaningful only within one tenant.
@@ -2548,8 +2572,7 @@ export function replaceDetectedConflicts(hippoRoot, detected, detectedAt = new D
  * Returns the resolved conflict, or null if not found.
  */
 export function resolveConflict(hippoRoot, conflictId, keepId, forgetLoser = false, tenantId, opts) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     // When tenantId is set, the conflict lookup requires BOTH members in-tenant
     // and every memories mutation carries AND tenant_id = ?. A cross-tenant probe
     // then returns null, indistinguishable from a bad id. Omitted tenantId =
@@ -2772,8 +2795,7 @@ const HANDOFF_COLUMNS = 'id, session_id, repo_root, task_id, summary, next_actio
  */
 export function saveSessionHandoff(hippoRoot, tenantId, handoff) {
     assertTenantId('saveSessionHandoff', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     const now = new Date().toISOString();
     // v1.2: scope is wired through. Read-side default-deny in api.recall +
     // cmdRecall continuity excludes slack:private:* and 'unknown:legacy'.
@@ -2801,8 +2823,7 @@ export function saveSessionHandoff(hippoRoot, tenantId, handoff) {
 /** Load the most recent handoff, optionally filtered by session ID. */
 export function loadLatestHandoff(hippoRoot, tenantId, sessionId, opts = {}) {
     assertTenantId('loadLatestHandoff', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const conditions = ['tenant_id = ?'];
         const params = [tenantId];
@@ -2846,8 +2867,7 @@ export function loadLatestHandoff(hippoRoot, tenantId, sessionId, opts = {}) {
  */
 export function loadHandoffById(hippoRoot, tenantId, id) {
     assertTenantId('loadHandoffById', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: row's shape matches HANDOFF_COLUMNS.
         const row = db.prepare(`
@@ -2864,8 +2884,7 @@ export function loadHandoffById(hippoRoot, tenantId, id) {
 /** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
 export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
     assertTenantId('stampHandoffOutcome', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const result = db.prepare(`
       UPDATE session_handoffs SET outcome = ?
@@ -3033,8 +3052,7 @@ export function createCard(hippoRoot, tenantId, input) {
     if (input.budget !== undefined && !(Number.isSafeInteger(input.budget) && input.budget > 0)) {
         throw new Error(`Invalid budget: ${input.budget} (expected a positive integer)`);
     }
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const dependsOn = [...new Set(input.dependsOn ?? [])];
         let id = '';
@@ -3086,8 +3104,7 @@ export function createCard(hippoRoot, tenantId, input) {
 /** Returns the card row for id, or null if it does not exist under this tenant. */
 export function loadCard(hippoRoot, tenantId, id) {
     assertTenantId('loadCard', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return loadCardRow(db, tenantId, id);
     }
@@ -3098,8 +3115,7 @@ export function loadCard(hippoRoot, tenantId, id) {
 /** Lists cards for this tenant, optionally filtered to one status, newest-updated first. */
 export function listCards(hippoRoot, tenantId, opts = {}) {
     assertTenantId('listCards', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const conditions = ['tenant_id = ?'];
         const params = [tenantId];
@@ -3120,8 +3136,7 @@ export function listCards(hippoRoot, tenantId, opts = {}) {
 /** Returns this card's parent and child ids from card_deps. */
 export function loadCardDeps(hippoRoot, tenantId, id) {
     assertTenantId('loadCardDeps', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: rows' shape matches the single `parent` column named in the SELECT below.
         const parents = db.prepare(`SELECT parent FROM card_deps WHERE tenant_id = ? AND child = ?`).all(tenantId, id).map((r) => r.parent);
@@ -3136,8 +3151,7 @@ export function loadCardDeps(hippoRoot, tenantId, id) {
 /** Returns this card's run history, most recent first. */
 export function loadCardRuns(hippoRoot, tenantId, id) {
     assertTenantId('loadCardRuns', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: rows' shape matches CardRunRow.
         const rows = db.prepare(`
@@ -3153,8 +3167,7 @@ export function loadCardRuns(hippoRoot, tenantId, id) {
 /** Returns this card's comments, most recent first. */
 export function loadCardComments(hippoRoot, tenantId, id) {
     assertTenantId('loadCardComments', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: rows' shape matches CardCommentRow.
         const rows = db.prepare(`
@@ -3170,8 +3183,7 @@ export function loadCardComments(hippoRoot, tenantId, id) {
 /** Read side of the card <-> handoff round trip: the newest handoff filed against this card. */
 export function loadLatestHandoffForCard(hippoRoot, tenantId, cardId) {
     assertTenantId('loadLatestHandoffForCard', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: row's shape matches HANDOFF_COLUMNS.
         const row = db.prepare(`
@@ -3190,8 +3202,7 @@ export function claimCard(hippoRoot, tenantId, id, runtime, sessionId) {
     if (runtime.trim() === '') {
         throw new Error('runtime must not be empty');
     }
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         let runId = 0;
@@ -3233,8 +3244,7 @@ export function claimCard(hippoRoot, tenantId, id, runtime, sessionId) {
 export function heartbeatCard(hippoRoot, tenantId, id, runId) {
     assertTenantId('heartbeatCard', tenantId);
     assertRunId(runId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         try {
@@ -3272,8 +3282,7 @@ export function blockCard(hippoRoot, tenantId, id, reason, runId) {
     }
     if (runId !== undefined)
         assertRunId(runId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         try {
@@ -3310,8 +3319,7 @@ export function reviewCard(hippoRoot, tenantId, id, runId) {
     assertTenantId('reviewCard', tenantId);
     if (runId !== undefined)
         assertRunId(runId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         try {
@@ -3347,8 +3355,7 @@ export function completeCard(hippoRoot, tenantId, id, outcome, runId) {
     }
     if (runId !== undefined)
         assertRunId(runId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         let promotedChildren = [];
@@ -3404,8 +3411,7 @@ export function completeCard(hippoRoot, tenantId, id, outcome, runId) {
 /** Returns to ready every running card of the tenant whose lease has expired or is missing: clears its assignee, closes its live run as 'reclaimed' and leaves its handoffs alone, all in one write transaction. Returns the reclaimed card ids in id order. */
 export function reclaimExpiredCards(hippoRoot, tenantId) {
     assertTenantId('reclaimExpiredCards', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         try {
@@ -3442,8 +3448,7 @@ export function addCardComment(hippoRoot, tenantId, cardId, author, body) {
     if (body.trim() === '') {
         throw new Error('body must not be empty');
     }
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return insertCardComment(db, tenantId, cardId, author, body);
     }
@@ -3470,8 +3475,7 @@ export function addCardComment(hippoRoot, tenantId, cardId, author, body) {
  */
 export function loadDirtySummaries(hippoRoot, tenantId) {
     assertTenantId('loadDirtySummaries', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -3540,8 +3544,7 @@ export function markSummaryDirtyInTx(db, summaryId, tenantId, actor) {
  */
 export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli') {
     assertTenantId('markSummaryDirty', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // v0.30 / E5: widened dag_level=2 -> IN (2, 3). RETURNING dag_level reads
         // actual level in same round trip.
@@ -3588,8 +3591,7 @@ export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli')
  * tenant-scoped via summary.tenantId.
  */
 export function loadAllL2Summaries(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -3618,8 +3620,7 @@ export function loadAllL2Summaries(hippoRoot) {
  * HIPPO_DAG_REBUILD_CAP takes most-recently-changed summaries first.
  */
 export function loadAllDirtySummaries(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -3645,8 +3646,7 @@ export function loadAllDirtySummaries(hippoRoot) {
  */
 export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
     assertTenantId('loadChildrenOfSummary', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -3679,8 +3679,7 @@ export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
  */
 export function applyRebuildResult(hippoRoot, summary, patch) {
     assertTenantId('applyRebuildResult', summary.tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('SAVEPOINT rebuild_summary');
         try {
@@ -3827,8 +3826,7 @@ export function applyRebuildResult(hippoRoot, summary, patch) {
  */
 export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, actor = 'cli', source = 'buildDag-clean') {
     assertTenantId('clearSummaryDirtyAfterBuild', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     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.