hippo-memory 1.64.0 → 1.65.0

package/dist/cli/maintenance.js

@@ -3,7 +3,6 @@ import { envAnthropicApiKey } from '../env.js';
 import { loadAllEntries } from '../store/entry-reads.js';
 import { deduplicateStore } from '../dedupe.js';
 import { embedAll, loadEmbeddingIndex } from '../embeddings.js';
-import { resolveEmbeddingModel } from '../local-embedding.js';
 import { resolveEmbeddingProvider } from '../embedding-provider.js';
 import { resetAllPhysicsState } from '../physics-state.js';
 import { loadConfig } from '../config.js';
@@ -93,7 +92,7 @@ export function cmdDedup(hippoRoot, flags) {
 // ---------------------------------------------------------------------------
 // Embed command
 // ---------------------------------------------------------------------------
-export async function cmdEmbed(hippoRoot, flags) {
+export async function cmdEmbed(hippoRoot, flags, given) {
     // --global mirrors resolveAuthRoot (cli.ts:6900): initGlobal() + the global
     // root, skipping the local requireInit entirely, so this is the healing
     // path for pre-1.27.0 global stores from a directory with no local .hippo.
@@ -109,12 +108,13 @@ export async function cmdEmbed(hippoRoot, flags) {
         printEmbedStatus(root);
         return;
     }
-    if (!embedProviderReady(root))
+    const provider = readyEmbedProvider(root, given);
+    if (!provider)
         return;
     console.log('Embedding all memories (this may take a moment on first run to download model)...');
     let count;
     try {
-        count = await embedAll(root, resolveEmbeddingModel(root));
+        count = await embedAll(root, undefined, provider);
     }
     catch (err) {
         printError(`Embedding failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -126,6 +126,11 @@ export async function cmdEmbed(hippoRoot, flags) {
     const entriesAfter = loadAllEntries(root);
     const embIndexAfter = loadEmbeddingIndex(root);
     console.log(`Done. ${count} new embeddings created. ${Object.keys(embIndexAfter).length}/${entriesAfter.length} total.`);
+    const unembedded = entriesAfter.filter((e) => !embIndexAfter[e.id]).length;
+    if (unembedded > 0) {
+        printError(`${unembedded} memories are still not embedded (the warnings above name them). Re-run \`hippo embed\` to retry.`);
+        process.exitCode = 1;
+    }
 }
 function resetPhysics(root) {
     const entries = loadAllEntries(root);
@@ -154,10 +159,10 @@ function printEmbedStatus(root) {
         console.log(`  ${missing.length} memories need embedding (run \`hippo embed\` to embed them)`);
     }
 }
-/** False, after saying why, when no usable provider exists. */
-function embedProviderReady(root) {
+/** The provider to embed with, or null after saying why none is usable. */
+function readyEmbedProvider(root, given) {
     // Embedding (unlike status/reset) needs an available provider.
-    const embedProvider = (() => {
+    const embedProvider = given ?? (() => {
         try {
             return resolveEmbeddingProvider(root);
         }
@@ -168,23 +173,24 @@ function embedProviderReady(root) {
     })();
     if (!embedProvider) {
         process.exitCode = 1;
-        return false;
+        return null;
     }
     if (embedProvider.isAvailable())
-        return true;
+        return embedProvider;
     if (loadConfig(root).embeddings.enabled === false) {
         console.log('Embeddings are disabled in config (embeddings.enabled = false). Set it to true or "auto" to enable.');
-        return false;
+        return null;
     }
     if (embedProvider.kind === 'local') {
         console.log('Embeddings not available. Install @huggingface/transformers to enable:');
         console.log('  npm install @huggingface/transformers');
+        process.exitCode = 1;
     }
     else {
         printError(`Embedding provider '${embedProvider.kind}' is configured but ${embedProvider.keyEnv} is not set.`);
         printError(`Export ${embedProvider.keyEnv}, or set config.embeddings.provider back to 'local'.`);
         process.exitCode = 1;
     }
-    return false;
+    return null;
 }
 //# sourceMappingURL=maintenance.js.map

package/dist/cli/recall.d.ts

@@ -1,5 +1,5 @@
 import { type CliFlags, type CommandContext } from './shared.js';
-/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+/** Test-only: reset the CLI recall rings. Call from beforeEach. */
 export declare function __resetSessionRecallHistoryCli(): void;
 /** Runs `hippo recall`: parse, rank, load continuity, fit the printed block to the budget, audit, then write and print. */
 export declare function cmdRecall(hippoRoot: string, query: string, flags: CliFlags): Promise<void>;

package/dist/cli/recall.js

@@ -20,10 +20,10 @@ import { dropHeldCopies } from '../same-text.js';
 import { isGlobalStoreRoot } from '../project-identity.js';
 import { detectScope } from '../scope.js';
 import { getGlobalRoot } from '../shared.js';
-import { auditQueryFields } from '../audit.js';
 import * as api from '../api.js';
 import { computePlanningFallacyOutput } from '../predictions/planning-fallacy.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled, buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, } from '../recall-history.js';
+import { detectAnchoring, hashQueryText, biasHintEnabled, snapshotRing } from '../recall-history.js';
+import { appendRecallAudit, recallAuditMetadata, recordShownRecall, resetSessionRings, sessionRing } from '../api/recall-record.js';
 import { detectAvailabilityBias } from '../availability.js';
 import { resolveTenantId } from '../tenant.js';
 import { MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from '../graph-recall.js';
@@ -34,13 +34,12 @@ import { isClefModel } from '../rerankers/clef.js';
 import { handoffText, printedTokens, sessionTrailText, settleTokens, snapshotText } from '../context-render.js';
 import { withLedgerDb } from '../ledger-db.js';
 import { printError } from './output.js';
-import { parseLimitFlag, parseBudgetFlag, emitCliAudit, requireInit, recallEntryText, recallHeading, parseAsOfFlag, engineFlags, printActiveTaskSnapshot, printSessionEvents, printHandoff, hostSessionId, captureConsole, hookStoreRoot, } from './shared.js';
+import { parseLimitFlag, parseBudgetFlag, requireInit, recallEntryText, recallHeading, parseAsOfFlag, engineFlags, printActiveTaskSnapshot, printSessionEvents, printHandoff, hostSessionId, captureConsole, hookStoreRoot, } from './shared.js';
 // Per-process rings: a single-shot `hippo recall` starts empty, so anchoring only accumulates in long-lived
 // hosts (in-process loops, `hippo serve`, the MCP server).
-const sessionRecallHistoryCli = new Map();
-/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+/** Test-only: reset the CLI recall rings. Call from beforeEach. */
 export function __resetSessionRecallHistoryCli() {
-    sessionRecallHistoryCli.clear();
+    resetSessionRings('cli');
 }
 // JSON.stringify keeps quotes or parens in the matched phrase from blurring the line.
 function planningLine(p) {
@@ -185,7 +184,7 @@ export async function cmdRecall(hippoRoot, query, flags) {
     const o = parseRecallOptions(hippoRoot, flags);
     const ranked = await rankForRecall(hippoRoot, query, flags, o);
     const fit = fitRecallBlock(hippoRoot, query, o, ranked, loadRecallContinuity(hippoRoot, o));
-    auditRecall(hippoRoot, o.globalRoot, query, fit);
+    auditRecall(hippoRoot, o, query, fit);
     writeRecallResult(hippoRoot, query, o, fit, ranked.localIndex);
 }
 /** Every flag recall reads, parsed in the order the single-body command checked them. */
@@ -281,9 +280,7 @@ function loadRecallContinuity(hippoRoot, o) {
 function recallHinter(query, o, rank) {
     const { tenantId, sessionId } = o;
     // HIPPO_ANCHORING=off and HIPPO_AVAILABILITY=off skip the work entirely.
-    const anchorRing = biasHintEnabled('anchoring') && sessionId
-        ? getOrCreateRing(sessionRecallHistoryCli, buildSessionKey(tenantId, sessionId))
-        : null;
+    const anchorRing = sessionRing('cli', tenantId, sessionId);
     const queryHash = hashQueryText(query);
     const availabilityPool = biasHintEnabled('availability')
         ? [...rank.localEntries, ...rank.globalEntries].map((e) => ({ id: e.id, created: e.created }))
@@ -304,7 +301,7 @@ function recallHinter(query, o, rank) {
         });
         return { anchoring, availability, summary };
     };
-    return { anchorRing, queryHash, hintsFor };
+    return { anchorRing, hintsFor };
 }
 function renderRecallBlock(list, h, v) {
     const { query, showWhy, showPlan, planText, hasContinuity, entryText } = v;
@@ -388,7 +385,7 @@ function fitRecallBlock(hippoRoot, query, o, ranked, loaded) {
     const shown = (n) => dropHeldCopies(fitted.slice(0, n), (r) => r.entry);
     let kept = fitted.length;
     let results = shown(kept);
-    const { anchorRing, queryHash, hintsFor } = recallHinter(query, o, ranked.rank);
+    const { anchorRing, hintsFor } = recallHinter(query, o, ranked.rank);
     const view = { query, showWhy: o.showWhy, showPlan, planText, hasContinuity, continuity, entryText: ranked.entryText };
     let hints = hintsFor(results, kept - results.length);
     let recallText = renderRecallBlock(results, hints, view);
@@ -399,45 +396,17 @@ function fitRecallBlock(hippoRoot, query, o, ranked, loaded) {
         hints = hintsFor(results, kept - results.length);
         recallText = renderRecallBlock(results, hints, view);
     }
-    return { results, hints, recallText, continuity, continuityTokens, cmdPlanningFallacyHint, cmdPlanningFallacyWatching, anchorRing, queryHash };
+    return { results, hints, recallText, continuity, continuityTokens, cmdPlanningFallacyHint, cmdPlanningFallacyWatching, anchorRing };
 }
-function auditRecall(hippoRoot, globalRoot, query, fit) {
-    const { results, anchorRing, queryHash } = fit;
-    const { anchoring: cmdAnchoringHint, availability: cmdAvailabilityHint } = fit.hints;
-    if (anchorRing) {
-        // Appended after every detect: anchoredOn feeds the cooldown for the next recall on this session.
-        appendRecall(anchorRing, queryHash, results[0]?.entry.id ?? null, cmdAnchoringHint?.memoryId);
-    }
-    else if (biasHintEnabled('anchoring')) {
-        // SHA-256/16 per the recall-audit convention; hashQueryText is FNV-1a and brute-forceable on short queries.
-        emitCliAudit(hippoRoot, 'recall_anchor_skipped_no_session', undefined, auditQueryFields(query));
-    }
-    if (cmdAnchoringHint?.reason === 'memory_dominance') {
-        emitCliAudit(hippoRoot, 'recall_anchor_detected_memory_dominance', cmdAnchoringHint.memoryId, {
-            memory_id: cmdAnchoringHint.memoryId,
-            query_count: cmdAnchoringHint.queryCount ?? null,
-        });
-    }
-    else if (cmdAnchoringHint?.reason === 'query_repeat') {
-        emitCliAudit(hippoRoot, 'recall_anchor_detected_query_repeat', cmdAnchoringHint.memoryId, {
-            memory_id: cmdAnchoringHint.memoryId,
-        });
-    }
-    if (cmdAvailabilityHint) {
-        emitCliAudit(hippoRoot, 'recall_availability_detected', undefined, {
-            recent_fraction: cmdAvailabilityHint.recentFraction,
-            older_passed_over: cmdAvailabilityHint.olderCandidatesPassedOver,
-            returned_count: cmdAvailabilityHint.returnedCount,
-        });
-    }
+function auditRecall(hippoRoot, o, query, fit) {
+    const { results, hints } = fit;
+    const who = { hippoRoot, tenantId: o.tenantId, actor: 'cli', bestEffort: true };
+    recordShownRecall(who, { query, ring: fit.anchorRing, topId: results[0]?.entry.id ?? null, anchoring: hints.anchoring, availability: hints.availability });
     // One 'recall' event per query, before the early-empty return, in every participating store.
-    const recallMetadata = {
-        ...auditQueryFields(query),
-        results: results.length,
-    };
-    emitCliAudit(hippoRoot, 'recall', undefined, recallMetadata);
-    if (isInitialized(globalRoot) && globalRoot !== hippoRoot) {
-        emitCliAudit(globalRoot, 'recall', undefined, recallMetadata);
+    const metadata = recallAuditMetadata(query, results.length);
+    appendRecallAudit(who, 'recall', undefined, metadata);
+    if (isInitialized(o.globalRoot) && o.globalRoot !== hippoRoot) {
+        appendRecallAudit({ ...who, hippoRoot: o.globalRoot }, 'recall', undefined, metadata);
     }
 }
 /** Traces the recall, books retrieval for a non-empty list, then prints JSON or the fitted block. */

package/dist/cli/shared.js

@@ -10,7 +10,7 @@ import { confidenceLabel } from '../memory.js';
 import { isInitialized } from '../store/open.js';
 import { explainMatch } from '../search/explain.js';
 import { isSharedStore } from '../config.js';
-import { openHippoDb, closeHippoDb, isSqliteBusy, noteStoreBusy, withSharedStoreHandles, HOOK_DB_WAIT_MS } from '../db.js';
+import { openHippoDb, closeHippoDb, isSqliteBusy, noteStoreBusy, runWithRequestStores, HOOK_DB_WAIT_MS } from '../db.js';
 import { withLedgerDb } from '../ledger-db.js';
 import { sessionPilotArm } from '../pilot-arm.js';
 import { hookPayloadSessionId, isSubagentPayload, recordTokenUse } from '../token-ledger.js';
@@ -474,7 +474,7 @@ export function resolveAuthRoot(hippoRoot, flags) {
 /** Hook commands share one handle per store and wait at most HOOK_DB_WAIT_MS for a lock; a store still busy after that skips the hook's work with one warning, exit 0. */
 export async function runHookWithStores(fn) {
     try {
-        return await withSharedStoreHandles(fn, { busyWaitMs: HOOK_DB_WAIT_MS });
+        return await runWithRequestStores(fn, { busyWaitMs: HOOK_DB_WAIT_MS, failFastWhenBusy: true });
     }
     catch (error) {
         if (!isSqliteBusy(error))

package/dist/cli.d.ts

@@ -54,14 +54,17 @@ export declare const COMMANDS: {
     };
     recall: {
         run: (c: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     drill: {
         run: (c: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     assemble: {
         run: (c: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     supersede: {
@@ -70,6 +73,7 @@ export declare const COMMANDS: {
     };
     explain: {
         run: (c: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     eval: {
@@ -86,6 +90,7 @@ export declare const COMMANDS: {
     };
     sleep: {
         run: ({ hippoRoot, flags }: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     'last-sleep': {
@@ -134,10 +139,12 @@ export declare const COMMANDS: {
     };
     auth: {
         run: ({ hippoRoot, args, flags }: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     goal: {
         run: ({ hippoRoot, args, flags }: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     slack: {
@@ -150,6 +157,7 @@ export declare const COMMANDS: {
     };
     audit: {
         run: (c: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     'correction-latency': {
@@ -166,6 +174,7 @@ export declare const COMMANDS: {
     };
     outcome: {
         run: ({ hippoRoot, flags }: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     conflicts: {
@@ -190,6 +199,7 @@ export declare const COMMANDS: {
     };
     dormant: {
         run: ({ hippoRoot, args, flags }: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     projects: {
@@ -198,14 +208,17 @@ export declare const COMMANDS: {
     };
     quarantine: {
         run: ({ hippoRoot, args, flags }: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     tokens: {
         run: ({ hippoRoot, flags }: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     failures: {
         run: ({ hippoRoot, flags }: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     doctor: {
@@ -242,6 +255,7 @@ export declare const COMMANDS: {
     };
     forget: {
         run: (c: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     inspect: {
@@ -274,10 +288,12 @@ export declare const COMMANDS: {
     };
     learn: {
         run: ({ hippoRoot, flags }: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     promote: {
         run: (c: CommandContext) => Promise<void>;
+        scoped: true;
         usage: string[];
     };
     sync: {

package/dist/cli.js

@@ -209,14 +209,17 @@ export const COMMANDS = {
     },
     recall: {
         run: async (c) => { await (await import('./cli/recall.js')).handleRecall(c); },
+        scoped: true,
         usage: VERB_USAGE.recall,
     },
     drill: {
         run: async (c) => { await (await import('./cli/dag.js')).handleDrill(c); },
+        scoped: true,
         usage: VERB_USAGE.drill,
     },
     assemble: {
         run: async (c) => { await (await import('./cli/dag.js')).handleAssemble(c); },
+        scoped: true,
         usage: VERB_USAGE.assemble,
     },
     supersede: {
@@ -225,6 +228,7 @@ export const COMMANDS = {
     },
     explain: {
         run: async (c) => { await (await import('./cli/explain.js')).handleExplain(c); },
+        scoped: true,
         usage: VERB_USAGE.explain,
     },
     eval: {
@@ -241,6 +245,7 @@ export const COMMANDS = {
     },
     sleep: {
         run: async ({ hippoRoot, flags }) => { await (await import('./cli/sleep.js')).cmdSleep(hippoRoot, flags); },
+        scoped: true,
         usage: VERB_USAGE.sleep,
     },
     'last-sleep': {
@@ -289,10 +294,12 @@ export const COMMANDS = {
     },
     auth: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/auth.js')).cmdAuth(hippoRoot, args, flags); },
+        scoped: true,
         usage: VERB_USAGE.auth,
     },
     goal: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/goals.js')).cmdGoal(hippoRoot, args, flags); },
+        scoped: true,
         usage: VERB_USAGE.goal,
     },
     slack: {
@@ -305,6 +312,7 @@ export const COMMANDS = {
     },
     audit: {
         run: async (c) => { await (await import('./cli/audit.js')).handleAudit(c); },
+        scoped: true,
         usage: VERB_USAGE.audit,
     },
     'correction-latency': {
@@ -321,6 +329,7 @@ export const COMMANDS = {
     },
     outcome: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/curate.js')).cmdOutcome(hippoRoot, flags); },
+        scoped: true,
         usage: VERB_USAGE.outcome,
     },
     conflicts: {
@@ -345,6 +354,7 @@ export const COMMANDS = {
     },
     dormant: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/curate.js')).cmdDormant(hippoRoot, args, flags); },
+        scoped: true,
         usage: VERB_USAGE.dormant,
     },
     projects: {
@@ -353,14 +363,17 @@ export const COMMANDS = {
     },
     quarantine: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/curate.js')).cmdQuarantine(hippoRoot, args, flags); },
+        scoped: true,
         usage: VERB_USAGE.quarantine,
     },
     tokens: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/status.js')).cmdTokens(hippoRoot, flags); },
+        scoped: true,
         usage: VERB_USAGE.tokens,
     },
     failures: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/status.js')).cmdFailures(hippoRoot, flags); },
+        scoped: true,
         usage: VERB_USAGE.failures,
     },
     doctor: {
@@ -397,6 +410,7 @@ export const COMMANDS = {
     },
     forget: {
         run: async (c) => { await (await import('./cli/curate.js')).handleForget(c); },
+        scoped: true,
         usage: VERB_USAGE.forget,
     },
     inspect: {
@@ -429,10 +443,12 @@ export const COMMANDS = {
     },
     learn: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/transfer.js')).cmdLearn(hippoRoot, flags); },
+        scoped: true,
         usage: VERB_USAGE.learn,
     },
     promote: {
         run: async (c) => { await (await import('./cli/transfer.js')).handlePromote(c); },
+        scoped: true,
         usage: VERB_USAGE.promote,
     },
     sync: {
@@ -630,7 +646,8 @@ async function main(command, args, flags, hippoRoot) {
         printUsage();
         process.exit(1);
     }
-    await spec.run({ hippoRoot, args, flags });
+    const run = () => spec.run({ hippoRoot, args, flags });
+    await (spec.scoped ? (await import('./db/request-stores.js')).runWithRequestStores(run) : run());
 }
 export async function runCli(argv = process.argv) {
     const { command, args, flags } = parseArgs(argv);

package/dist/config.d.ts

@@ -159,6 +159,8 @@ export declare function loadConfig(hippoRoot: string): HippoConfig;
 /** True when the store's config.json sets `"sharedStore": true`. Once true, a root stays true for this process,
  *  so a broken edit while a server runs cannot turn it off. Reads only this key: loadConfig has no cache. */
 export declare function isSharedStore(hippoRoot: string): boolean;
+/** Reads the root as shared for the rest of this process, whatever its config.json says. */
+export declare function markSharedStore(hippoRoot: string): void;
 /** Test seam: forget every root seen as shared. */
 export declare function _resetSharedStoreCacheForTests(): void;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -321,6 +321,10 @@ export function isSharedStore(hippoRoot) {
     sharedStoreRoots.add(key);
     return true;
 }
+/** Reads the root as shared for the rest of this process, whatever its config.json says. */
+export function markSharedStore(hippoRoot) {
+    sharedStoreRoots.add(sharedStoreKey(hippoRoot));
+}
 /** Test seam: forget every root seen as shared. */
 export function _resetSharedStoreCacheForTests() {
     sharedStoreRoots.clear();

package/dist/db/connect.d.ts

@@ -0,0 +1,5 @@
+import { type DatabaseSyncLike } from './sqlite.js';
+export declare function getHippoDbPath(hippoRoot: string): string;
+/** A new connection with the store's pragmas, migrations and mirror cleanup applied; the caller owns and closes it. */
+export declare function connectHippoDb(hippoRoot: string, busyWaitMs?: number): DatabaseSyncLike;
+//# sourceMappingURL=connect.d.ts.map

package/dist/db/connect.js

@@ -0,0 +1,52 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { cleanupArchivedMirrors } from '../raw-archive-mirror-cleanup.js';
+import { log } from '../log.js';
+import { DatabaseSync } from './sqlite.js';
+import { execWithBusyRetry } from './busy.js';
+import { runMigrations } from './migrate.js';
+export function getHippoDbPath(hippoRoot) {
+    return path.join(hippoRoot, 'hippo.db');
+}
+// Owner-only on create; SQLite gives the WAL and SHM files the db's mode. Existing paths keep theirs.
+function createStoreFilesOwnerOnly(hippoRoot) {
+    fs.mkdirSync(hippoRoot, { recursive: true, mode: 0o700 });
+    try {
+        fs.closeSync(fs.openSync(getHippoDbPath(hippoRoot), 'wx', 0o600));
+    }
+    catch (err) {
+        if (!(err instanceof Error && 'code' in err && err.code === 'EEXIST'))
+            throw err;
+    }
+}
+/** A new connection with the store's pragmas, migrations and mirror cleanup applied; the caller owns and closes it. */
+export function connectHippoDb(hippoRoot, busyWaitMs) {
+    createStoreFilesOwnerOnly(hippoRoot);
+    const db = new DatabaseSync(getHippoDbPath(hippoRoot));
+    try {
+        db.exec(`PRAGMA busy_timeout = ${busyWaitMs ?? 5000}`);
+        execWithBusyRetry(db, 'PRAGMA journal_mode = WAL', busyWaitMs);
+        db.exec('PRAGMA synchronous = NORMAL');
+        db.exec('PRAGMA wal_autocheckpoint = 100');
+        db.exec('PRAGMA foreign_keys = ON');
+        runMigrations(db, hippoRoot, busyWaitMs);
+        // Orphan mirrors of archived raw rows go here; a filesystem failure must not block the open.
+        try {
+            cleanupArchivedMirrors(hippoRoot, db);
+        }
+        catch (cleanupErr) {
+            log.error(`openHippoDb: cleanupArchivedMirrors failed (non-fatal): ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`);
+        }
+        return db;
+    }
+    catch (error) {
+        try {
+            db.close();
+        }
+        catch {
+            // Best effort only.
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=connect.js.map

package/dist/db/open.d.ts

@@ -1,7 +1,10 @@
 import { type DatabaseSyncLike } from './sqlite.js';
-export declare function getHippoDbPath(hippoRoot: string): string;
+import { getHippoDbPath } from './connect.js';
+export { getHippoDbPath };
 /** Lock wait for hook commands: under the 5 s prompt-hook budget even after a few skipped writes, and far above a normal write's hold. */
 export declare const HOOK_DB_WAIT_MS = 1000;
+/** Lock wait inside an HTTP request: SQLite waits synchronously, so a long wait would stall every other request on the event loop. */
+export declare const SERVER_DB_WAIT_MS = 250;
 /** A busy store made a command skip work: warn once per process (the holder is usually `hippo sleep`). */
 export declare function noteStoreBusy(skipped: string): void;
 /** Runs `fn` with one handle per store: openHippoDb reuses it and closeHippoDb leaves it open until `fn` settles or the process exits.
@@ -9,21 +12,16 @@ export declare function noteStoreBusy(skipped: string): void;
 export declare function withSharedStoreHandles<T>(fn: () => T | Promise<T>, opts?: {
     busyWaitMs?: number;
 }): Promise<T>;
-/** Lock wait inside an HTTP request: SQLite waits synchronously, so a long wait would stall every other request on the event loop. */
-export declare const SERVER_DB_WAIT_MS = 250;
 /** Lock wait for each of sleep's short write transactions, even inside a server request: a run stops only on a writer that holds the lock longer. */
 export declare const SLEEP_DB_WAIT_MS = 5000;
-/** Runs `fn` so that every store opened inside it, across awaits, waits at most `busyWaitMs` for a lock unless the open passes its own. */
-export declare function withBusyWait<T>(busyWaitMs: number, fn: () => T): T;
-/** The lock wait an open here would get without its own `busyWaitMs`, in openHippoDb's order; undefined outside both scopes. */
+/** The lock wait an open here would get without its own `busyWaitMs`: the request scope's; undefined outside every scope. */
 export declare function scopedBusyWait(): number | undefined;
-/** Thrown by a hippo.db open inside a request served from another store: the code path is not ported to the store port yet. */
-export declare class SqliteBlockedError extends Error {
-    readonly storeKind: string;
-    constructor(storeKind: string);
-}
 /** Runs `fn` so that every hippo.db open inside it, across awaits, throws; otherwise a missed port would create and write a hippo.db nobody reads. */
 export declare function withSqliteBlocked<T>(storeKind: string, fn: () => T): T;
+/** Runs `fn` with hippo.db opens allowed again, for a store whose own methods are backed by hippo.db. */
+export declare function withSqliteAllowed<T>(fn: () => T): T;
+/** First line of a best-effort catch around a hippo.db open: an unported path must fail closed, not fall back silently. */
+export declare function rethrowIfSqliteBlocked<E>(err: E): void;
 /** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
 export declare function openHippoDb(hippoRoot: string, opts?: {
     busyWaitMs?: number;