hippo-memory 1.69.0 → 1.71.0

package/dist/store/mirrors.js

@@ -1,36 +1,35 @@
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
-import { Layer } from '../memory.js';
-import { dumpFrontmatter } from '../yaml.js';
-import { getMeta } from '../db.js';
-import { log } from '../log.js';
+import { Layer } from '../core/memory.js';
+import { dumpFrontmatter } from './yaml.js';
+import { getMeta } from '../db/index.js';
+import { oncePerStore } from '../db/connect.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;
 export function layerDir(root, layer) {
     return path.join(root, layer);
 }
+// Owner-only wherever a mirror folder is made, at open or by a writer that finds it gone.
+const MIRROR_FOLDER = { recursive: true, mode: 0o700 };
+/** Makes the mirror folders on a store's first open in this process; a writer makes its own folder if one goes missing later. */
 export function ensureMirrorDirectories(hippoRoot) {
-    const dirs = [
-        hippoRoot,
-        path.join(hippoRoot, 'buffer'),
-        path.join(hippoRoot, 'episodic'),
-        path.join(hippoRoot, 'semantic'),
-        path.join(hippoRoot, 'conflicts'),
-    ];
-    for (const dir of dirs) {
-        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    }
+    oncePerStore(hippoRoot, 'mirror-folders', () => {
+        for (const sub of ['buffer', 'episodic', 'semantic', 'conflicts']) {
+            fs.mkdirSync(path.join(hippoRoot, sub), MIRROR_FOLDER);
+        }
+    });
 }
-// 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) {
@@ -61,7 +60,7 @@ export function writeActiveTaskMirror(hippoRoot, tenantId, snapshot) {
     if (snapshot.session_id) {
         body.push(`## Session`, snapshot.session_id, '');
     }
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.mkdirSync(path.dirname(filePath), MIRROR_FOLDER);
     fs.writeFileSync(filePath, `${fm}\n\n${body.join('\n')}`, 'utf8');
 }
 export function removeActiveTaskMirror(hippoRoot, tenantId) {
@@ -99,12 +98,12 @@ export function writeRecentSessionMirror(hippoRoot, tenantId, events) {
         lines.push(`- [${event.created_at}] (${event.event_type}) ${event.content}`);
     }
     lines.push('');
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.mkdirSync(path.dirname(filePath), MIRROR_FOLDER);
     fs.writeFileSync(filePath, `${fm}\n\n${lines.join('\n')}`, 'utf8');
 }
 function writeConflictMirrors(hippoRoot, conflicts) {
     const conflictDir = path.join(hippoRoot, 'conflicts');
-    fs.mkdirSync(conflictDir, { recursive: true });
+    fs.mkdirSync(conflictDir, MIRROR_FOLDER);
     const keep = new Set();
     for (const conflict of conflicts) {
         const filename = `conflict_${conflict.id}.md`;
@@ -125,7 +124,7 @@ function writeConflictMirrors(hippoRoot, conflicts) {
             `- Memory A: ${conflict.memory_a_id}`,
             `- Memory B: ${conflict.memory_b_id}`,
             `- Reason: ${conflict.reason}`,
-            `- Score: ${conflict.score.toFixed(3)}`,
+            `- Score: ${conflict.score.toFixed(SCORE_DECIMALS)}`,
             `- Status: ${conflict.status}`,
             '',
         ].join('\n');
@@ -142,7 +141,7 @@ function writeConflictMirrors(hippoRoot, conflicts) {
 export function writeMarkdownMirror(hippoRoot, entry) {
     removeEntryMirrors(hippoRoot, entry.id);
     const dir = layerDir(hippoRoot, entry.layer);
-    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(dir, MIRROR_FOLDER);
     fs.writeFileSync(path.join(dir, `${entry.id}.md`), serializeEntry(entry), 'utf8');
 }
 // Every layer, Trace included: `writeMarkdownMirror` writes any layer, and a stale trace mirror
@@ -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.
- */
-export function getExistingEntryMirrorPaths(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. */
+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);
@@ -182,15 +174,15 @@ export function purgeMirrorBestEffort(hippoRoot, id, isRaw, logPrefix) {
             return true;
         }
         catch (secondErr) {
-            const msg = secondErr instanceof Error ? secondErr.message : String(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,21 +203,22 @@ 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),
         };
     }
-    // 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.
+    return { version: INDEX_VERSION, entries, ...readLastRecall(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 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 {
-        version: INDEX_VERSION,
-        entries,
-        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') ?? ''),
     };
 }
@@ -250,7 +243,19 @@ export function writeIndexMirror(hippoRoot, index) {
     mirrorBestEffort('index.json', () => fs.writeFileSync(path.join(hippoRoot, 'index.json'), JSON.stringify(index, null, 2), 'utf8'));
 }
 export function writeStatsMirror(hippoRoot, stats) {
-    mirrorBestEffort('stats.json', () => fs.writeFileSync(path.join(hippoRoot, 'stats.json'), JSON.stringify(stats, null, 2), 'utf8'));
+    mirrorBestEffort('stats.json', () => overwriteInPlace(path.join(hippoRoot, 'stats.json'), JSON.stringify(stats, null, 2)));
+}
+// A truncate waits for the file's last write to reach the disk, so a file rewritten on every recall keeps its blocks.
+function overwriteInPlace(file, text) {
+    const bytes = Buffer.from(text, 'utf8');
+    const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT, 0o666);
+    try {
+        fs.writeSync(fd, bytes, 0, bytes.length, 0);
+        fs.ftruncateSync(fd, bytes.length);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
 }
 /** Mirrors are derived from SQLite and written after COMMIT, so a failed write warns instead of failing a committed change. */
 export function mirrorBestEffort(what, write) {
@@ -258,7 +263,7 @@ export function mirrorBestEffort(what, write) {
         write();
     }
     catch (err) {
-        log.warn(`${what} not refreshed (${err instanceof Error ? err.message : String(err)}); the database write succeeded`);
+        log.warn(`${what} not refreshed (${errorMessage(err)}); the database write succeeded`);
     }
 }
 export function syncMirrorFiles(hippoRoot, db) {

package/dist/store/object-types.d.ts

@@ -0,0 +1,189 @@
+export type DecisionStatus = 'active' | 'superseded' | 'closed';
+export interface Decision {
+    id: number;
+    memoryId: string | null;
+    tenantId: string;
+    decisionText: string;
+    context: string | null;
+    status: DecisionStatus;
+    /** Successor decision id; set only when status === 'superseded'. */
+    supersededBy: number | null;
+    supersededAt: string | null;
+    closedAt: string | null;
+    createdAt: string;
+}
+export type IncidentStatus = 'open' | 'resolved' | 'closed';
+export interface Incident {
+    id: number;
+    memoryId: string | null;
+    tenantId: string;
+    incidentText: string;
+    context: string | null;
+    status: IncidentStatus;
+    /** Set only when status === 'resolved'. */
+    resolutionText: string | null;
+    resolvedAt: string | null;
+    closedAt: string | null;
+    /** Linked receipts: memory ids that are this incident's evidence. */
+    linkedMemoryIds: string[];
+    createdAt: string;
+}
+export type ProcessStatus = 'active' | 'superseded' | 'closed';
+export interface Process {
+    id: number;
+    memoryId: string | null;
+    tenantId: string;
+    processName: string;
+    description: string | null;
+    /** Ordered step list (the process body). Stored as a JSON array of strings. */
+    steps: string[];
+    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
+    version: number;
+    status: ProcessStatus;
+    /** Successor process id; set only when status === 'superseded'. */
+    supersededBy: number | null;
+    supersededAt: string | null;
+    /** The per-version delta note; set on a successor row only (NULL on a v1). */
+    changeSummary: string | null;
+    closedAt: string | null;
+    createdAt: string;
+}
+export type PolicyStatus = 'active' | 'superseded' | 'closed';
+export interface Policy {
+    id: number;
+    memoryId: string | null;
+    tenantId: string;
+    policyName: string;
+    policyText: string;
+    /** ISO-8601 datetime as `toISOString` gives it; when the policy takes effect. Always set. */
+    validFrom: string;
+    /** ISO-8601 datetime as `toISOString` gives it; when it expires. null = open-ended. */
+    validTo: string | null;
+    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
+    version: number;
+    status: PolicyStatus;
+    supersededBy: number | null;
+    supersededAt: string | null;
+    /** The per-version delta note; set on a successor row only (NULL on a v1). */
+    changeSummary: string | null;
+    closedAt: string | null;
+    createdAt: string;
+}
+export type SkillStatus = 'active' | 'superseded' | 'closed';
+export interface Skill {
+    id: number;
+    memoryId: string | null;
+    tenantId: string;
+    skillName: string;
+    instructions: string;
+    /** Optional "when to apply"; stored in the trigger_text column. */
+    trigger: string | null;
+    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
+    version: number;
+    status: SkillStatus;
+    supersededBy: number | null;
+    supersededAt: string | null;
+    /** The per-version delta note; set on a successor row only (NULL on a v1). */
+    changeSummary: string | null;
+    closedAt: string | null;
+    createdAt: string;
+}
+export type BriefStatus = 'active' | 'superseded' | 'closed';
+export interface ProjectBrief {
+    id: number;
+    memoryId: string | null;
+    tenantId: string;
+    /** The repo identifier this brief is scoped to (e.g. `hippo`). */
+    repo: string;
+    /** The brief body. */
+    summary: string;
+    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
+    version: number;
+    status: BriefStatus;
+    supersededBy: number | null;
+    supersededAt: string | null;
+    /** The per-version delta note; set on a successor row only (NULL on a v1). */
+    changeSummary: string | null;
+    closedAt: string | null;
+    createdAt: string;
+}
+export type NoteStatus = 'active' | 'superseded' | 'closed';
+export interface CustomerNote {
+    id: number;
+    memoryId: string | null;
+    tenantId: string;
+    /** The account/customer entity this note is scoped to (free-form identifier). */
+    customer: string;
+    /** The note body. */
+    note: string;
+    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
+    version: number;
+    status: NoteStatus;
+    supersededBy: number | null;
+    supersededAt: string | null;
+    /** The per-version delta note; set on a successor row only (NULL on a v1). */
+    changeSummary: string | null;
+    closedAt: string | null;
+    createdAt: string;
+}
+/** Each kind is named by the `source` its mirror memory carries. */
+export interface ObjectByKind {
+    decision: Decision;
+    incident: Incident;
+    process: Process;
+    policy: Policy;
+    skill: Skill;
+    project_brief: ProjectBrief;
+    customer_note: CustomerNote;
+}
+export type ObjectKind = keyof ObjectByKind;
+/** What one save stores, per kind the shared save writes; core has checked and resolved every value. */
+export interface ObjectFields {
+    decision: {
+        readonly decisionText: string;
+        readonly context: string | undefined;
+    };
+    process: {
+        readonly processName: string;
+        readonly description: string | undefined;
+        readonly steps: readonly string[];
+    };
+    policy: {
+        readonly policyName: string;
+        readonly policyText: string;
+        readonly validFrom: string;
+        readonly validTo: string | null;
+    };
+    skill: {
+        readonly name: string;
+        readonly instructions: string;
+        readonly trigger: string | null;
+    };
+    /** `receiptCount` is set only when a refresh wrote this version. */
+    project_brief: {
+        readonly repo: string;
+        readonly summary: string;
+        readonly receiptCount: number | undefined;
+    };
+    customer_note: {
+        readonly customer: string;
+        readonly note: string;
+    };
+}
+/** The kinds whose rows are active until a successor supersedes them; an incident is opened and resolved instead. */
+export type SavableKind = keyof ObjectFields;
+/** What opening an incident stores; core has checked the text, and the store checks each linked id. */
+export interface IncidentFields {
+    readonly incidentText: string;
+    readonly context: string | undefined;
+    /** The memories that are the incident's evidence, in the order the caller gave them. */
+    readonly linkedMemoryIds: readonly string[];
+}
+/** One memory a brief refresh cites. */
+export interface BriefReceipt {
+    id: string;
+    created: string;
+    source: string;
+    content: string;
+}
+//# sourceMappingURL=object-types.d.ts.map

package/dist/store/object-types.js

@@ -0,0 +1,4 @@
+// The typed objects as every store hands them over, and what a save carries for each kind.
+// `memoryId` is null once the mirror memory is forgotten or archived; the object row outlives it.
+export {};
+//# sourceMappingURL=object-types.js.map

package/dist/store/open.d.ts

@@ -1,6 +1,6 @@
-import { type MemoryEntry } from '../memory.js';
-import { type DatabaseSyncLike } from '../db.js';
-import { type ResolveProjectIdentityOpts } from '../project-identity.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+import { type ResolveProjectIdentityOpts } from '../core/project-identity.js';
 /** Nearest ancestor store like git; the strict join is the fallback so `hippo init` still creates `<cwd>/.hippo`. */
 export declare function getHippoRoot(cwd?: string, opts?: ResolveProjectIdentityOpts): string;
 export declare function isInitialized(hippoRoot: string): boolean;
@@ -11,9 +11,11 @@ export declare function openStore(hippoRoot: string, opts?: {
 }): DatabaseSyncLike;
 /** One call on a handle of its own, closed after; pass openStore where the call also sets up mirror folders and legacy rows. */
 export declare function onHandle<T>(hippoRoot: string, fn: (db: DatabaseSyncLike) => T, open?: (hippoRoot: string) => DatabaseSyncLike): T;
-/** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
+/** `meta` key holding the default half-life base a store's memories are on (src/consolidate/half-life-migration.ts). */
 export declare const HALF_LIFE_BASE_META_KEY = "default_half_life_base";
 /** `meta` key set once no memory of a decision, incident or other object sits on the old flat 90 days. */
 export declare 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 declare const LEGACY_TYPED_HALF_LIFE = 90;
 export declare function loadLegacyEntriesFromMarkdown(hippoRoot: string): MemoryEntry[];
 //# sourceMappingURL=open.d.ts.map

package/dist/store/open.js

@@ -1,16 +1,18 @@
 // Opens the SQLite store, the source of truth; Markdown and JSON files are human-readable mirrors of it.
 import * as fs from 'fs';
 import * as path from 'path';
-import { DEFAULT_HALF_LIFE_DAYS, Layer } from '../memory.js';
-import { closeHippoDb, openHippoDb, getMeta, setMeta } from '../db.js';
-import { findHippoStoreDir, realpathOrResolve } from '../project-identity.js';
-import { RejectedValueError } from '../rejection.js';
-import { log } from '../log.js';
-import { isPlainJsonObject } from './rows.js';
+import { DEFAULT_HALF_LIFE_DAYS, Layer } from '../core/memory.js';
+import { closeHippoDb, currentRequestStores, openHippoDb, getMeta, setMeta, withWriteScope } from '../db/index.js';
+import { openHippoDbWithFacts } from '../db/open.js';
+import { findHippoStoreDir } from '../core/project-identity.js';
+import { realpathOrResolve } from '../util/real-path.js';
+import { RejectedValueError } from './rejection.js';
+import { errorMessage, log } from '../util/log.js';
 import { audit } from './audit-event.js';
 import { deserializeEntry } from './markdown.js';
 import { stampOriginProjectForImport, upsertEntryRow } from './entry-row.js';
 import { ensureMirrorDirectories, syncMirrorFiles, layerDir } from './mirrors.js';
+import { isJsonObject } from '../util/json.js';
 /** Nearest ancestor store like git; the strict join is the fallback so `hippo init` still creates `<cwd>/.hippo`. */
 export function getHippoRoot(cwd = process.cwd(), opts) {
     return findHippoStoreDir(cwd, opts) ?? path.join(realpathOrResolve(cwd), '.hippo');
@@ -26,9 +28,15 @@ export function initStore(hippoRoot) {
 /** One open connection with init done on it, for callers who used to pay for `initStore` + a second `openHippoDb`. */
 export function openStore(hippoRoot, opts) {
     // Open first: a folder marked for another store must refuse before any mirror folder appears.
-    const db = openHippoDb(hippoRoot, opts);
+    const { db, facts } = openHippoDbWithFacts(hippoRoot, opts);
+    // A store worker's reader: its writer ran the steps below before this thread was sent a job, and this connection cannot write them.
+    if (currentRequestStores()?.setupDoneFor === hippoRoot)
+        return db;
     try {
         ensureMirrorDirectories(hippoRoot);
+        // Both steps act only on a store with no memory row, which the open's own probe has just ruled out.
+        if (facts?.hasMemories)
+            return db;
         const bootstrapped = bootstrapLegacyStore(db, hippoRoot);
         if (bootstrapped) {
             syncMirrorFiles(hippoRoot, db);
@@ -56,16 +64,14 @@ export function onHandle(hippoRoot, fn, open = openHippoDb) {
         closeHippoDb(db);
     }
 }
-/** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
+/** `meta` key holding the default half-life base a store's memories are on (src/consolidate/half-life-migration.ts). */
 export const HALF_LIFE_BASE_META_KEY = 'default_half_life_base';
 /** `meta` key set once no memory of a decision, incident or other object sits on the old flat 90 days. */
 export const TYPED_HALF_LIFE_META_KEY = 'typed_half_life_on_default';
-/**
- * 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.
- */
+/** 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; 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;
@@ -85,21 +91,12 @@ function bootstrapLegacyStore(db, hippoRoot) {
     const legacyEntries = loadLegacyEntriesFromMarkdown(hippoRoot);
     if (legacyEntries.length === 0)
         return false;
-    db.exec('BEGIN IMMEDIATE');
-    try {
+    withWriteScope(db, 'bootstrap_legacy_store', () => {
         importLegacyEntries(db, hippoRoot, legacyEntries);
         importLegacyIndexAndStats(db, hippoRoot);
         // Stamp completion even when every row was rejected; see the gate above.
         setMeta(db, 'legacy_bootstrap_completed', '1');
-        db.exec('COMMIT');
-    }
-    catch (error) {
-        try {
-            db.exec('ROLLBACK');
-        }
-        catch { /* already rolled back; keep the original error */ }
-        throw error;
-    }
+    });
     return true;
 }
 function importLegacyEntries(db, hippoRoot, legacyEntries) {
@@ -116,7 +113,7 @@ function importLegacyEntries(db, hippoRoot, legacyEntries) {
         catch (err) {
             if (err instanceof RejectedValueError) {
                 rejectedCount++;
-                audit(db, 'reject_refusal', err.entryId, { digest: err.digest, reason: err.reason }, 'cli', err.tenantId);
+                audit(db, 'reject_refusal', { targetId: err.entryId, metadata: { digest: err.digest, reason: err.reason }, actor: 'cli', tenantId: err.tenantId });
                 continue;
             }
             throw err;
@@ -140,7 +137,7 @@ function importLegacyIndexAndStats(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 (!isPlainJsonObject(run))
+        if (!isJsonObject(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));
@@ -169,13 +166,12 @@ 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) {
-        log.debug(`store: unreadable index.json read as empty: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`store: unreadable index.json read as empty: ${errorMessage(err)}`);
         return { version: 1, entries: {}, last_retrieval_ids: [], last_trace_id: null };
     }
 }
@@ -190,14 +186,12 @@ 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) {
-        log.debug(`store: unreadable stats.json read as zero: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`store: unreadable stats.json read as zero: ${errorMessage(err)}`);
         return {
             total_remembered: 0,
             total_recalled: 0,

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

@@ -0,0 +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` 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;
+}
+/** 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

@@ -0,0 +1,52 @@
+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: 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 };
+    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);
+        let bestScore = 0;
+        let bestClass = null;
+        let secondBest = 0;
+        for (const { class_tag } of rows) {
+            const classTokens = class_tag
+                .toLowerCase()
+                .split(/[-_\s]+/)
+                .filter((t) => t.length >= 3);
+            let score = 0;
+            for (const t of classTokens)
+                if (querySet.has(t))
+                    score++;
+            if (score > bestScore) {
+                secondBest = bestScore;
+                bestScore = score;
+                bestClass = class_tag;
+            }
+            else if (score === bestScore && score > 0) {
+                // 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) {
+                secondBest = score;
+            }
+        }
+        if (bestScore < 1)
+            return { classTag: null, tiebreak: false };
+        if (bestScore === secondBest)
+            return { classTag: null, tiebreak: true };
+        return { classTag: bestClass, tiebreak: false };
+    });
+}
+/** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
+export function planningFallacyEvidenceAt(hippoRoot, tenantId, classQueryTokens) {
+    const resolution = resolveClassFromTokens(hippoRoot, tenantId, classQueryTokens);
+    // emitAudit=false: the recall_autodebias_hint row carries n_closed and mean_ratio, so predict_baserate stays off.
+    const baserate = resolution.classTag ? computePredictionBaserate(hippoRoot, tenantId, resolution.classTag, 'recall', false) : null;
+    return { ...resolution, baserate };
+}
+//# sourceMappingURL=planning-fallacy-evidence.js.map