hippo-memory 1.70.0 → 1.71.0

package/dist/store/index-and-stats.d.ts

@@ -4,16 +4,10 @@ import type { HippoIndex, LegacyStats } from './rows.js';
 export declare function loadIndex(hippoRoot: string): HippoIndex;
 /** The last recall's ids and its trace alone, for a caller that needs no index entry. */
 export declare function loadLastRecall(hippoRoot: string): Pick<HippoIndex, 'last_retrieval_ids' | 'last_trace_id'>;
-/**
- * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
- *
- * `last_retrieval_ids` and `last_trace_id` commit in one transaction: callers fold a fresh trace id
- * into the index and rely on both keys moving together. index.json is left to `rebuildIndex`.
- */
+/** Persist mutable index metadata (entry rows are derived from SQLite); `last_retrieval_ids` and `last_trace_id` commit in one transaction, as callers
+ * rely on both moving together. index.json is left to `rebuildIndex`. */
 export declare function saveIndex(hippoRoot: string, index: Pick<HippoIndex, 'last_retrieval_ids' | 'last_trace_id'>): void;
-/**
- * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
- */
+/** Rebuild mirrors from SQLite, importing any legacy markdown files not already present. */
 export declare function rebuildIndex(hippoRoot: string): HippoIndex;
 export declare function updateStats(hippoRoot: string, delta: {
     remembered?: number;
@@ -32,9 +26,7 @@ export declare function appendConsolidationRun(hippoRoot: string, run: {
 }): void;
 /** Rows a tenant created since the last sleep (runs are host-wide), looking back at most 24 hours. */
 export declare function countCreatedSinceLastSleep(hippoRoot: string, tenantId: string, now?: Date): number;
-/**
- * Session decay context: provides the data needed for session-based and adaptive decay.
- */
+/** Session decay context: the data needed for session-based and adaptive decay. */
 export interface SessionDecayContext {
     /** Total number of sleep (consolidation) cycles completed. */
     sleepCount: number;
@@ -43,13 +35,8 @@ export interface SessionDecayContext {
 }
 /** Timestamp of the latest consolidation run, or undefined when there is none. */
 export declare function lastConsolidationAt(db: DatabaseSyncLike): string | undefined;
-/**
- * Load the session decay context from the store.
- * Uses consolidation_runs timestamps to compute session intervals.
- */
+/** Load the session decay context; session intervals come from consolidation_runs timestamps. */
 export declare function loadSessionDecayContext(hippoRoot: string): SessionDecayContext;
-/**
- * Increment the sleep counter. Called after each consolidation run.
- */
+/** Increment the sleep counter after each consolidation run. */
 export declare function incrementSleepCount(hippoRoot: string): void;
 //# sourceMappingURL=index-and-stats.d.ts.map

package/dist/store/index-and-stats.js

@@ -1,55 +1,36 @@
-import { closeHippoDb, withWriteScope, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta } from '../db/index.js';
+import { withWriteScope, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta } from '../db/index.js';
 import { RejectedValueError } from './rejection.js';
 import { log } from '../util/log.js';
 import { audit } from './audit-event.js';
 import { stampOriginProjectForImport, upsertEntryRow } from './entry-row.js';
 import { buildIndexFromDb, readLastRecall, syncMirrorFiles, writeIndexMirror, writeStatsMirror, buildStatsFromDb } from './mirrors.js';
-import { openStore, loadLegacyEntriesFromMarkdown } from './open.js';
+import { onHandle, openStore, loadLegacyEntriesFromMarkdown } from './open.js';
 import { DAY_MS } from '../util/time.js';
 /** Load the derived index from SQLite. Read-only: index.json is only ever written by `rebuildIndex`. */
 export function loadIndex(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return buildIndexFromDb(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** The last recall's ids and its trace alone, for a caller that needs no index entry. */
 export function loadLastRecall(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return readLastRecall(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
- *
- * `last_retrieval_ids` and `last_trace_id` commit in one transaction: callers fold a fresh trace id
- * into the index and rely on both keys moving together. index.json is left to `rebuildIndex`.
- */
+/** Persist mutable index metadata (entry rows are derived from SQLite); `last_retrieval_ids` and `last_trace_id` commit in one transaction, as callers
+ * rely on both moving together. index.json is left to `rebuildIndex`. */
 export function saveIndex(hippoRoot, index) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         withWriteScope(db, 'save_index', () => {
             setMeta(db, 'last_retrieval_ids', JSON.stringify(index.last_retrieval_ids ?? []));
             setMeta(db, 'last_trace_id', index.last_trace_id ?? '');
         });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
- */
+/** Rebuild mirrors from SQLite, importing any legacy markdown files not already present. */
 export function rebuildIndex(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // 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));
@@ -67,7 +48,12 @@ export function rebuildIndex(hippoRoot) {
                     catch (err) {
                         if (err instanceof RejectedValueError) {
                             rejectedCount++;
-                            audit(db, 'reject_refusal', { targetId: err.entryId, metadata: { digest: err.digest, reason: err.reason }, actor: 'cli', tenantId: err.tenantId });
+                            audit(db, 'reject_refusal', {
+                                targetId: err.entryId,
+                                metadata: { digest: err.digest, reason: err.reason },
+                                actor: 'cli',
+                                tenantId: err.tenantId
+                            });
                             continue;
                         }
                         throw err;
@@ -82,25 +68,16 @@ export function rebuildIndex(hippoRoot) {
         const index = buildIndexFromDb(db);
         writeIndexMirror(hippoRoot, index);
         return index;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 export function updateStats(hippoRoot, delta) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         updateStatsOn(db, hippoRoot, delta);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** updateStats on the caller's open store, so a loop of writes opens the store once. */
 export function updateStatsOn(db, hippoRoot, delta) {
-    // One atomic statement per counter, and only for counters the caller
-    // named: the read-modify-write this replaces both lost increments to a
-    // concurrent writer and stamped stale values over the untouched two.
+    // One atomic statement per named counter: a read-modify-write loses concurrent increments and stamps stale values over the untouched two.
     const increments = [
         ['total_remembered', delta.remembered ?? 0],
         ['total_recalled', delta.recalled ?? 0],
@@ -129,37 +106,25 @@ export function updateStatsUnlessBusy(hippoRoot, delta, committed) {
     }
 }
 export function loadStats(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return buildStatsFromDb(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 export function appendConsolidationRun(hippoRoot, run) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         db.prepare(`INSERT INTO consolidation_runs(timestamp, decayed, merged, removed) VALUES (?, ?, ?, ?)`).run(run.timestamp, run.decayed, run.merged, run.removed);
         pruneConsolidationRuns(db, 50);
         writeStatsMirror(hippoRoot, buildStatsFromDb(db));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** 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()) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const dayAgo = new Date(now.getTime() - DAY_MS).toISOString();
         const row = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE tenant_id = ?
          AND created > MAX(?, COALESCE((SELECT MAX(timestamp) FROM consolidation_runs), ''))`).get(tenantId, dayAgo);
         return row.n;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** Timestamp of the latest consolidation run, or undefined when there is none. */
 export function lastConsolidationAt(db) {
@@ -167,13 +132,9 @@ export function lastConsolidationAt(db) {
     const row = db.prepare(`SELECT timestamp FROM consolidation_runs ORDER BY timestamp DESC, id DESC LIMIT 1`).get();
     return row?.timestamp;
 }
-/**
- * Load the session decay context from the store.
- * Uses consolidation_runs timestamps to compute session intervals.
- */
+/** Load the session decay context; session intervals come from consolidation_runs timestamps. */
 export function loadSessionDecayContext(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // 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();
@@ -190,22 +151,13 @@ export function loadSessionDecayContext(hippoRoot) {
         const avgMs = totalInterval / (timestamps.length - 1);
         const avgDays = avgMs / DAY_MS;
         return { sleepCount, avgSessionIntervalDays: Math.max(0, avgDays) };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Increment the sleep counter. Called after each consolidation run.
- */
+/** Increment the sleep counter after each consolidation run. */
 export function incrementSleepCount(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         const current = Number(getMeta(db, 'sleep_count', '0')) || 0;
         setMeta(db, 'sleep_count', String(current + 1));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 //# sourceMappingURL=index-and-stats.js.map

package/dist/store/markdown.d.ts

@@ -1,10 +1,6 @@
 import { type MemoryEntry } from '../core/memory.js';
-/**
- * Serialize a MemoryEntry to markdown with YAML frontmatter.
- */
+/** Serialize a MemoryEntry to markdown with YAML frontmatter. */
 export declare function serializeEntry(entry: MemoryEntry): string;
-/**
- * Deserialize a markdown file to a MemoryEntry.
- */
+/** Deserialize a markdown file to a MemoryEntry. */
 export declare function deserializeEntry(raw: string): MemoryEntry | null;
 //# sourceMappingURL=markdown.d.ts.map

package/dist/store/markdown.js

@@ -1,10 +1,9 @@
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import { FALLBACK_HALF_LIFE_DAYS, DEFAULT_SCHEMA_FIT } from '../core/memory.js';
 import { dumpFrontmatter, parseFrontmatter } from './yaml.js';
-/**
- * Serialize a MemoryEntry to markdown with YAML frontmatter.
- */
-export function serializeEntry(entry) {
-    const frontmatter = {
+/** The fields every mirror file carries; serializeEntry adds the optional ones. */
+function entryFrontmatter(entry) {
+    return {
         id: entry.id,
         created: entry.created,
         last_retrieved: entry.last_retrieved,
@@ -30,11 +29,21 @@ export function serializeEntry(entry) {
         scope: entry.scope ?? null,
         owner: entry.owner ?? null,
         artifact_ref: entry.artifact_ref ?? null,
+        // A rebuild from these files must keep supersession and the DAG; deserializeEntry reads all five.
+        valid_from: entry.valid_from,
+        superseded_by: entry.superseded_by,
+        extracted_from: entry.extracted_from,
+        dag_level: entry.dag_level,
+        dag_parent_id: entry.dag_parent_id,
     };
+}
+/** Serialize a MemoryEntry to markdown with YAML frontmatter. */
+export function serializeEntry(entry) {
+    const frontmatter = entryFrontmatter(entry);
     // Emit tenant_id only when not 'default' to keep diffs clean for the dominant
     // single-tenant case (mirrors the plan's task 7 guidance).
-    const tenantId = entry.tenantId ?? 'default';
-    if (tenantId !== 'default') {
+    const tenantId = entry.tenantId ?? DEFAULT_TENANT_ID;
+    if (tenantId !== DEFAULT_TENANT_ID) {
         frontmatter['tenant_id'] = tenantId;
     }
     // v39: '' (user-global) and null (unknown, hidden by default) must both round-trip;
@@ -42,25 +51,17 @@ export function serializeEntry(entry) {
     if (entry.origin_project !== undefined) {
         frontmatter['origin_project'] = entry.origin_project;
     }
-    // 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.
+    // Spread into a fresh literal: dumpFrontmatter's Record<string, YamlValue> needs an index signature, which the named interface does not structurally provide.
     const fm = dumpFrontmatter({ ...frontmatter });
     return `${fm}\n\n${entry.content}\n`;
 }
-/**
- * Deserialize a markdown file to a MemoryEntry.
- */
+/** Deserialize a markdown file to a MemoryEntry. */
 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.
+    // SAFETY: each `as X` narrows a raw YAML field to a MemoryEntry union member; frontmatter is only written by serializeEntry,
+    // so out-of-range values mean hand-edited files, which this parser may accept (permissive parse).
     return {
         id: String(data['id']),
         created: String(data['created'] ?? new Date().toISOString()),
@@ -97,7 +98,7 @@ export function deserializeEntry(raw) {
         scope: data['scope'] === null || data['scope'] === undefined ? null : String(data['scope']),
         owner: data['owner'] === null || data['owner'] === undefined ? null : String(data['owner']),
         artifact_ref: data['artifact_ref'] === null || data['artifact_ref'] === undefined ? null : String(data['artifact_ref']),
-        tenantId: data['tenant_id'] === null || data['tenant_id'] === undefined ? 'default' : String(data['tenant_id']),
+        tenantId: data['tenant_id'] === null || data['tenant_id'] === undefined ? DEFAULT_TENANT_ID : String(data['tenant_id']),
         origin_project: !('origin_project' in data) ? undefined : data['origin_project'] === null ? null : String(data['origin_project']),
     };
 }

package/dist/store/mirrors.d.ts

@@ -9,12 +9,8 @@ export declare function removeActiveTaskMirror(hippoRoot: string, tenantId: stri
 export declare function writeRecentSessionMirror(hippoRoot: string, tenantId: string, events: SessionEvent[]): void;
 export declare function writeMarkdownMirror(hippoRoot: string, entry: MemoryEntry): void;
 export declare function removeEntryMirrors(hippoRoot: string, id: string): void;
-/**
- * Best-effort mirror purge. Retries the unlink once (most failures are transient locks); the reaper only
- * scans `raw_archive`, so a non-raw id's second failure logs the leftover path(s) to delete by hand.
- *
- * Returns true if the mirror ended up purged (first or second attempt).
- */
+/** Best-effort mirror purge: retries the unlink once (most failures are transient locks); the reaper only scans `raw_archive`,
+ * so a non-raw id's second failure logs the leftover path(s) to delete by hand. Returns true if the mirror ended up purged. */
 export declare function purgeMirrorBestEffort(hippoRoot: string, id: string, isRaw: boolean, logPrefix: string): boolean;
 /** Derive the current `HippoIndex` from SQLite. Exported for `rebuildIndex`
  *  (the only index.json writer) and the longmemeval benchmark. */

package/dist/store/mirrors.js

@@ -1,10 +1,11 @@
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { Layer } from '../core/memory.js';
 import { dumpFrontmatter } from './yaml.js';
 import { getMeta } from '../db/index.js';
 import { oncePerStore } from '../db/connect.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { parseJsonArray, INDEX_VERSION, parseLastTraceId, MEMORY_SELECT_COLUMNS, rowToEntry, rowToMemoryConflict, } from './rows.js';
 import { serializeEntry } from './markdown.js';
 const SCORE_DECIMALS = 3;
@@ -21,16 +22,14 @@ export function ensureMirrorDirectories(hippoRoot) {
         }
     });
 }
-// Tenant-scoped mirror file paths. The single-tenant 'default' deployment
-// keeps the original `active-task.md` / `recent-session.md` filenames for
-// on-disk back-compat; multi-tenant deployments get a `.<tenantId>` suffix
-// so tenant B saving cannot overwrite tenant A's mirror file.
+// Tenant-scoped mirror paths: the 'default' tenant keeps the original `active-task.md` / `recent-session.md` names;
+// other tenants get a `.<tenantId>` suffix so one cannot overwrite another's mirror.
 function activeTaskMirrorPath(hippoRoot, tenantId) {
-    const file = tenantId === 'default' ? 'active-task.md' : `active-task.${tenantId}.md`;
+    const file = tenantId === DEFAULT_TENANT_ID ? 'active-task.md' : `active-task.${tenantId}.md`;
     return path.join(hippoRoot, 'buffer', file);
 }
 function recentSessionMirrorPath(hippoRoot, tenantId) {
-    const file = tenantId === 'default' ? 'recent-session.md' : `recent-session.${tenantId}.md`;
+    const file = tenantId === DEFAULT_TENANT_ID ? 'recent-session.md' : `recent-session.${tenantId}.md`;
     return path.join(hippoRoot, 'buffer', file);
 }
 export function writeActiveTaskMirror(hippoRoot, tenantId, snapshot) {
@@ -155,22 +154,15 @@ export function removeEntryMirrors(hippoRoot, id) {
         }
     }
 }
-/**
- * Mirror paths for `id` still on disk, walked like `removeEntryMirrors`, so a failed purge
- * with no reaper to retry it can name the stuck file.
- */
+/** Mirror paths for `id` still on disk, walked like `removeEntryMirrors`, so a failed purge with no reaper to retry it can name the stuck file. */
 function getExistingEntryMirrorPaths(hippoRoot, id) {
     // Layer list kept in lockstep with removeEntryMirrors.
     return [Layer.Buffer, Layer.Episodic, Layer.Semantic, Layer.Trace]
         .map((layer) => path.join(layerDir(hippoRoot, layer), `${id}.md`))
         .filter((file) => fs.existsSync(file));
 }
-/**
- * Best-effort mirror purge. Retries the unlink once (most failures are transient locks); the reaper only
- * scans `raw_archive`, so a non-raw id's second failure logs the leftover path(s) to delete by hand.
- *
- * Returns true if the mirror ended up purged (first or second attempt).
- */
+/** Best-effort mirror purge: retries the unlink once (most failures are transient locks); the reaper only scans `raw_archive`,
+ * so a non-raw id's second failure logs the leftover path(s) to delete by hand. Returns true if the mirror ended up purged. */
 export function purgeMirrorBestEffort(hippoRoot, id, isRaw, logPrefix) {
     try {
         removeEntryMirrors(hippoRoot, id);
@@ -184,13 +176,13 @@ export function purgeMirrorBestEffort(hippoRoot, id, isRaw, logPrefix) {
         catch (secondErr) {
             const msg = errorMessage(secondErr);
             if (isRaw) {
-                log.error(`${logPrefix}: mirror cleanup failed for ${id} (will retry via reaper on next open): ${msg}`);
+                log.error(`${logPrefix}: mirror cleanup failed for ${id} (will retry via reaper on next open): ${msg}`, errorFields(secondErr));
             }
             else {
                 const leftover = getExistingEntryMirrorPaths(hippoRoot, id);
                 const pathsNote = leftover.length > 0 ? leftover.join(', ') : `${id}.md (path unresolved)`;
                 log.error(`${logPrefix}: mirror cleanup failed for ${id} - no automatic retry exists for this file, ` +
-                    `delete it manually: ${pathsNote} (${msg})`);
+                    `delete it manually: ${pathsNote} (${msg})`, errorFields(secondErr));
             }
             return false;
         }
@@ -211,7 +203,7 @@ export function buildIndexFromDb(db) {
             file: path.join(layer, `${row.id}.md`),
             layer,
             strength: Number(row.strength ?? 0),
-            tags: parseJsonArray(row.tags_json),
+            tags: parseJsonArray(row.tags_json, { table: 'memories', id: row.id, column: 'tags_json' }),
             created: row.created,
             last_retrieved: row.last_retrieved,
             pinned: Boolean(row.pinned),
@@ -221,13 +213,12 @@ export function buildIndexFromDb(db) {
 }
 /** The last recall's ids and its trace, the two meta keys saveIndex writes together. */
 export function readLastRecall(db) {
-    // Read both lockstep keys in ONE statement: two autocommit SELECTs could straddle a concurrent
-    // saveIndex and hand back a mismatched last_retrieval_ids / last_trace_id pair.
+    // Read both lockstep keys in ONE statement: two autocommit SELECTs could straddle a concurrent saveIndex and return a mismatched pair.
     // 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 {
-        last_retrieval_ids: parseJsonArray(lockstep.get('last_retrieval_ids') ?? '[]'),
+        last_retrieval_ids: parseJsonArray(lockstep.get('last_retrieval_ids') ?? '[]', { table: 'meta', id: 'last_retrieval_ids', column: 'value' }),
         last_trace_id: parseLastTraceId(lockstep.get('last_trace_id') ?? ''),
     };
 }

package/dist/store/open.js

@@ -70,12 +70,8 @@ export const HALF_LIFE_BASE_META_KEY = 'default_half_life_base';
 export const TYPED_HALF_LIFE_META_KEY = 'typed_half_life_on_default';
 /** The flat half-life the decision, incident and other object writers gave their memories before they took the default. */
 export const LEGACY_TYPED_HALF_LIFE = 90;
-/**
- * A store with no memories starts on the current default half-life base, so
- * `hippo sleep` never migrates it. A store that already holds memories and
- * no recorded base predates the record, and keeps reading as the legacy
- * 7-day base until sleep migrates it.
- */
+/** A store with no memories starts on the current default half-life base so `hippo sleep` never migrates it; one that holds memories but no recorded base
+ * predates the record and keeps the legacy 7-day base until sleep migrates it. */
 function recordHalfLifeBaseForNewStore(db) {
     if (getMeta(db, HALF_LIFE_BASE_META_KEY, '') !== '')
         return;
@@ -170,9 +166,8 @@ 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.
+        // SAFETY: index.json is only written by writeIndexMirror below, which serializes a HippoIndex;
+        // a hand-edited file that violates the shape falls through to the catch block's fallback.
         return JSON.parse(fs.readFileSync(indexPath, 'utf8'));
     }
     catch (err) {
@@ -191,10 +186,8 @@ 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.
+        // SAFETY: stats.json is only written by writeStatsMirror below with exactly these four fields; callers also guard every read with `?? 0` / `Array.isArray`,
+        // so a hand-edited file is tolerated even if this cast is wrong.
         return JSON.parse(fs.readFileSync(statsPath, 'utf8'));
     }
     catch (err) {

package/dist/store/planning-fallacy-evidence.d.ts

@@ -1,42 +1,14 @@
 import { type PredictionBaserate } from './predictions.js';
 export interface ClassResolution {
     classTag: string | null;
-    /** True when ≥2 classes tied at the best overlap score AND best ≥ 1.
-     *  Caller emits `recall_autodebias_hint_tiebreak` audit and returns
-     *  null hint (silent — prevents the "show wrong class half the time"
-     *  failure mode the alphabetical-tiebreak alternative would create). */
+    /** True when >=2 classes tied at the best overlap score AND best >= 1. Caller emits `recall_autodebias_hint_tiebreak` and returns a null hint
+     * (silent: an alphabetical tiebreak would show the wrong class half the time). */
     tiebreak: boolean;
 }
 /** The prediction class a forward claim resolves to, and that class's closed-prediction stats when one resolved. */
 export interface PlanningFallacyEvidence extends ClassResolution {
     readonly baserate: PredictionBaserate | null;
 }
-/**
- * Resolve a query-token set to a unique best-matching class_tag for the
- * tenant. Scores by lower-cased token overlap; requires best score ≥ 1
- * AND strictly greater than the 2nd-best score.
- *
- * Indexed via idx_predictions_tenant_class (db.ts:1015) → O(log n) seek
- * plus a small DISTINCT scan over the per-tenant class-tag set.
- *
- * Scope behaviour (deliberate): class_tag selection is TENANT-GLOBAL,
- * NOT scope-filtered against
- * the recall's opts.scope. The class_tag is an aggregator label across
- * historical predictions in the class, not a per-memory scope-bound
- * property. A no-scope recall CAN surface a class_tag from a privately-
- * scoped prediction's class in PlanningFallacyHint.classTag — by design,
- * because base-rate reasoning needs the full historical sample.
- * Implications:
- *   - The hint payload itself carries no memory content (only the aggregate
- *     summary string + numeric stats), so memory bodies do not leak.
- *   - The class_tag NAME is the side-channel. If sensitive labels are a
- *     concern, callers should either use opaque class names (e.g. hashes
- *     or numeric tokens) or set HIPPO_AUTODEBIAS=off.
- *   - tests/api-recall-autodebias.test.ts locks this with an explicit
- *     test asserting that scope-set predictions surface via no-scope
- *     recalls (so future "fix" attempts that scope-filter trip CI).
- */
-export declare function resolveClassFromTokens(hippoRoot: string, tenantId: string, queryTokens: readonly string[]): ClassResolution;
 /** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
 export declare function planningFallacyEvidenceAt(hippoRoot: string, tenantId: string, classQueryTokens: readonly string[]): PlanningFallacyEvidence;
 //# sourceMappingURL=planning-fallacy-evidence.d.ts.map

package/dist/store/planning-fallacy-evidence.js

@@ -1,35 +1,11 @@
-import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { onHandle } from './open.js';
 import { computePredictionBaserate } from './predictions.js';
-/**
- * Resolve a query-token set to a unique best-matching class_tag for the
- * tenant. Scores by lower-cased token overlap; requires best score ≥ 1
- * AND strictly greater than the 2nd-best score.
- *
- * Indexed via idx_predictions_tenant_class (db.ts:1015) → O(log n) seek
- * plus a small DISTINCT scan over the per-tenant class-tag set.
- *
- * Scope behaviour (deliberate): class_tag selection is TENANT-GLOBAL,
- * NOT scope-filtered against
- * the recall's opts.scope. The class_tag is an aggregator label across
- * historical predictions in the class, not a per-memory scope-bound
- * property. A no-scope recall CAN surface a class_tag from a privately-
- * scoped prediction's class in PlanningFallacyHint.classTag — by design,
- * because base-rate reasoning needs the full historical sample.
- * Implications:
- *   - The hint payload itself carries no memory content (only the aggregate
- *     summary string + numeric stats), so memory bodies do not leak.
- *   - The class_tag NAME is the side-channel. If sensitive labels are a
- *     concern, callers should either use opaque class names (e.g. hashes
- *     or numeric tokens) or set HIPPO_AUTODEBIAS=off.
- *   - tests/api-recall-autodebias.test.ts locks this with an explicit
- *     test asserting that scope-set predictions surface via no-scope
- *     recalls (so future "fix" attempts that scope-filter trip CI).
- */
-export function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
+/** Resolve a query-token set to a unique best-matching class_tag for the tenant: lower-cased token overlap, best score >= 1 AND above the 2nd-best.
+ * TENANT-GLOBAL by design, not scope-filtered (base rates need the full sample): class_tag NAMES can cross scopes; use opaque names or HIPPO_AUTODEBIAS=off. */
+function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
     if (queryTokens.length === 0)
         return { classTag: null, tiebreak: false };
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: rows' shape matches the single `class_tag` column named in the SELECT above.
         const rows = db.prepare(`SELECT DISTINCT class_tag FROM predictions WHERE tenant_id = ?`).all(tenantId);
         const querySet = new Set(queryTokens);
@@ -51,10 +27,8 @@ export function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
                 bestClass = class_tag;
             }
             else if (score === bestScore && score > 0) {
-                // Tie at current best — bump secondBest. Do NOT update bestClass
-                // (alphabetical tiebreak would pick wrong class on ambiguous query
-                // like "migration will take 3 days" between migration-effort vs
-                // migration-risk; silent on tie instead).
+                // Tie at current best: bump secondBest, do NOT update bestClass (an alphabetical tiebreak would pick the wrong class on ambiguous queries; stay silent
+                // on tie).
                 secondBest = score;
             }
             else if (score > secondBest) {
@@ -66,10 +40,7 @@ export function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
         if (bestScore === secondBest)
             return { classTag: null, tiebreak: true };
         return { classTag: bestClass, tiebreak: false };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
 export function planningFallacyEvidenceAt(hippoRoot, tenantId, classQueryTokens) {