hippo-memory 1.64.1 → 1.65.0

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;

package/dist/db/open.js

@@ -1,84 +1,46 @@
-import * as fs from 'fs';
-import * as path from 'path';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { cleanupArchivedMirrors } from '../raw-archive-mirror-cleanup.js';
 import { log } from '../log.js';
 import { DatabaseSync } from './sqlite.js';
-import { execWithBusyRetry } from './busy.js';
 import { tableExists } from './tables.js';
-import { assertBinaryCompatible, runMigrations } from './migrate.js';
-export function getHippoDbPath(hippoRoot) {
-    return path.join(hippoRoot, 'hippo.db');
-}
-// Hook commands run on every prompt, so inside withSharedStoreHandles each store pays its pragmas, migration check and mirror cleanup once.
-const sharedHandles = new Map();
-const sharedSet = new WeakSet();
-let shareDepth = 0;
-let shareBusyWaitMs;
+import { assertBinaryCompatible } from './migrate.js';
+import { connectHippoDb, getHippoDbPath } from './connect.js';
+import { currentRequestStores, isScopedHandle, runWithRequestStores } from './request-stores.js';
+import { SqliteBlockedError } from './sqlite-blocked.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 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 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 function noteStoreBusy(skipped) {
     log.once('store-busy', 'warn', `store busy (another hippo process holds the write lock); ${skipped}`);
-    // A lock held past one full wait belongs to a long transaction, so the hook's later writes skip at once.
-    for (const db of sharedHandles.values()) {
-        if (db.isOpen !== false)
-            db.exec('PRAGMA busy_timeout = 0');
-    }
-}
-function closeSharedStoreHandles() {
-    for (const db of sharedHandles.values()) {
-        sharedSet.delete(db);
-        if (db.isOpen !== false)
-            db.close();
-    }
-    sharedHandles.clear();
+    currentRequestStores()?.noteBusy();
 }
 /** Runs `fn` with one handle per store: openHippoDb reuses it and closeHippoDb leaves it open until `fn` settles or the process exits.
  *  `busyWaitMs` is the lock wait of every open inside `fn` that does not pass its own. */
 export async function withSharedStoreHandles(fn, opts) {
-    if (shareDepth++ === 0) {
-        process.once('exit', closeSharedStoreHandles);
-        shareBusyWaitMs = opts?.busyWaitMs;
-    }
-    try {
-        return await fn();
-    }
-    finally {
-        if (--shareDepth === 0) {
-            process.off('exit', closeSharedStoreHandles);
-            closeSharedStoreHandles();
-            shareBusyWaitMs = undefined;
-        }
-    }
+    return runWithRequestStores(fn, { busyWaitMs: opts?.busyWaitMs });
 }
-/** Lock wait inside an HTTP request: SQLite waits synchronously, so a long wait would stall every other request on the event loop. */
-export 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 const SLEEP_DB_WAIT_MS = 5000;
-const scopedBusyWaitMs = new AsyncLocalStorage();
-/** 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 function withBusyWait(busyWaitMs, fn) {
-    return scopedBusyWaitMs.run(busyWaitMs, fn);
-}
-/** 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 function scopedBusyWait() {
-    return shareBusyWaitMs ?? scopedBusyWaitMs.getStore();
-}
-/** 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 class SqliteBlockedError extends Error {
-    storeKind;
-    constructor(storeKind) {
-        super(`hippo.db is not opened while the '${storeKind}' store serves this request; this code path is not ported to the store yet`);
-        this.storeKind = storeKind;
-        this.name = 'SqliteBlockedError';
-    }
+    return currentRequestStores()?.busyWaitMs;
 }
 const sqliteBlockedBy = new AsyncLocalStorage();
 /** 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 function withSqliteBlocked(storeKind, fn) {
     return sqliteBlockedBy.run(storeKind, fn);
 }
+/** Runs `fn` with hippo.db opens allowed again, for a store whose own methods are backed by hippo.db. */
+export function withSqliteAllowed(fn) {
+    return sqliteBlockedBy.exit(fn);
+}
+/** First line of a best-effort catch around a hippo.db open: an unported path must fail closed, not fall back silently. */
+export function rethrowIfSqliteBlocked(err) {
+    if (err instanceof SqliteBlockedError)
+        throw err;
+}
 function assertSqliteAllowed() {
     const storeKind = sqliteBlockedBy.getStore();
     if (storeKind !== undefined)
@@ -87,63 +49,8 @@ function assertSqliteAllowed() {
 /** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
 export function openHippoDb(hippoRoot, opts) {
     assertSqliteAllowed();
-    if (shareDepth === 0)
-        return openOwnHippoDb(hippoRoot, { busyWaitMs: opts?.busyWaitMs ?? scopedBusyWaitMs.getStore() });
-    const busyWaitMs = opts?.busyWaitMs ?? shareBusyWaitMs ?? scopedBusyWaitMs.getStore();
-    const key = `${path.resolve(getHippoDbPath(hippoRoot))}\0${busyWaitMs ?? ''}`;
-    const shared = sharedHandles.get(key);
-    if (shared?.isOpen && !shared.isTransaction)
-        return shared;
-    const db = openOwnHippoDb(hippoRoot, { busyWaitMs });
-    // An open nested inside a transaction gets its own connection, as it did before sharing.
-    if (!shared?.isOpen) {
-        sharedHandles.set(key, db);
-        sharedSet.add(db);
-    }
-    return 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;
-    }
-}
-function openOwnHippoDb(hippoRoot, opts) {
-    createStoreFilesOwnerOnly(hippoRoot);
-    const db = new DatabaseSync(getHippoDbPath(hippoRoot));
-    const busyWaitMs = opts?.busyWaitMs;
-    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);
-        // Path A backfill: delete any orphan markdown mirrors for already-archived
-        // raw_archive rows. Idempotent via per-row raw_archive.mirror_cleaned_at
-        // (v21). Wrapped in try/catch — a filesystem failure must not prevent DB 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;
-    }
+    const stores = currentRequestStores();
+    return stores ? stores.get(hippoRoot, opts) : connectHippoDb(hippoRoot, opts?.busyWaitMs);
 }
 /** Open an existing store without changing it: no mkdir, WAL switch, migration or mirror cleanup. Throws when hippo.db is missing. */
 export function openHippoDbReadOnly(hippoRoot) {
@@ -166,7 +73,7 @@ export function openHippoDbReadOnly(hippoRoot) {
     }
 }
 export function closeHippoDb(db) {
-    if (sharedSet.has(db))
+    if (isScopedHandle(db))
         return;
     db.close();
 }