hippo-memory 1.64.1 → 1.66.0

package/dist/db/open.js

@@ -1,153 +1,81 @@
-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 { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { errorMessage, 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 { OtherStoreFolderError, 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);
 }
-function assertSqliteAllowed() {
-    const storeKind = sqliteBlockedBy.getStore();
-    if (storeKind !== undefined)
-        throw new SqliteBlockedError(storeKind);
+/** Runs `fn` with hippo.db opens allowed again, for a store whose own methods are backed by hippo.db, or a copy that reads the old hippo.db. */
+export function withSqliteAllowed(fn) {
+    return sqliteBlockedBy.exit(() => markerWaived.run(true, fn));
 }
-/** `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;
+/** 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;
 }
-// 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 });
+/** store init --db, store copy --db and serve --db write this file in the hippo root; its text is the store kind. */
+export const OTHER_STORE_MARKER = 'other-store';
+const markerWaived = new AsyncLocalStorage();
+// An empty or unreadable marker still refuses: falling through would write the hippo.db the marker forbids.
+function markerKind(marker) {
     try {
-        fs.closeSync(fs.openSync(getHippoDbPath(hippoRoot), 'wx', 0o600));
+        return readFileSync(marker, 'utf8').trim() || 'unknown';
     }
     catch (err) {
-        if (!(err instanceof Error && 'code' in err && err.code === 'EEXIST'))
-            throw err;
+        log.debug(`${marker} is unreadable, so its store kind reads as unknown: ${errorMessage(err)}`);
+        return 'unknown';
     }
 }
-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;
-    }
+/** Throws where hippo.db must not open; checked on every open, not cached, since the marker can appear while a process runs. */
+export function assertSqliteAllowed(hippoRoot) {
+    const storeKind = sqliteBlockedBy.getStore();
+    if (storeKind !== undefined)
+        throw new SqliteBlockedError(storeKind);
+    if (markerWaived.getStore())
+        return;
+    const marker = join(hippoRoot, OTHER_STORE_MARKER);
+    if (existsSync(marker))
+        throw new OtherStoreFolderError(markerKind(marker), marker);
+}
+/** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
+export function openHippoDb(hippoRoot, opts) {
+    assertSqliteAllowed(hippoRoot);
+    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) {
-    assertSqliteAllowed();
+    assertSqliteAllowed(hippoRoot);
     const db = new DatabaseSync(getHippoDbPath(hippoRoot), { readOnly: true });
     try {
         db.exec('PRAGMA busy_timeout = 5000');
@@ -166,7 +94,7 @@ export function openHippoDbReadOnly(hippoRoot) {
     }
 }
 export function closeHippoDb(db) {
-    if (sharedSet.has(db))
+    if (isScopedHandle(db))
         return;
     db.close();
 }

package/dist/db/request-stores.d.ts

@@ -0,0 +1,30 @@
+import type { DatabaseSyncLike } from './sqlite.js';
+export interface RequestStoresOptions {
+    /** Lock wait of every open in the scope that does not pass its own. */
+    readonly busyWaitMs?: number;
+    /** Set for hook scopes: after one lock wait runs out, {@link RequestStores.noteBusy} makes the scope's later writes skip at once. */
+    readonly failFastWhenBusy?: boolean;
+}
+/** The handles one request opened, keyed by resolved store path and lock wait. */
+export declare class RequestStores {
+    #private;
+    readonly busyWaitMs: number | undefined;
+    constructor(opts?: RequestStoresOptions);
+    get closed(): boolean;
+    /** The scope's handle on `hippoRoot`, opened on first use. `opts.busyWaitMs` overrides the scope's lock wait. */
+    get(hippoRoot: string, opts?: {
+        busyWaitMs?: number;
+    }): DatabaseSyncLike;
+    /** A lock held past one full wait belongs to a long transaction, so a hook scope's later writes skip at once. */
+    noteBusy(): void;
+    close(): void;
+}
+/** Runs `fn` in a request scope whose handles close when `fn` settles; inside an open scope `fn` joins it and `opts` is ignored. */
+export declare function runWithRequestStores<T>(fn: () => T | Promise<T>, opts?: RequestStoresOptions): Promise<T>;
+/** The scope this code runs in, if any. A closed scope still answers: its `get` falls through to a plain open. */
+export declare function currentRequestStores(): RequestStores | undefined;
+/** Runs `fn` outside every scope, for a connection that must outlive the request that happens to open it. */
+export declare function outsideRequestStores<T>(fn: () => T): T;
+/** Whether a scope owns `db` and will close it itself. */
+export declare function isScopedHandle(db: DatabaseSyncLike): boolean;
+//# sourceMappingURL=request-stores.d.ts.map

package/dist/db/request-stores.js

@@ -0,0 +1,100 @@
+// One store handle per store for each request (HTTP call, MCP tool call, scoped CLI command), opened lazily and closed with it.
+import * as path from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { connectHippoDb, getHippoDbPath } from './connect.js';
+// Handles a scope owns, so closeHippoDb leaves them open for the rest of the request.
+const scopedHandles = new WeakSet();
+// process.exit skips every finally, so one exit listener closes the handles of scopes still open.
+const liveScopes = new Set();
+let exitListenerInstalled = false;
+function closeLiveScopes() {
+    for (const scope of liveScopes)
+        scope.close();
+}
+function trackLive(scope) {
+    liveScopes.add(scope);
+    if (exitListenerInstalled)
+        return;
+    process.on('exit', closeLiveScopes);
+    exitListenerInstalled = true;
+}
+/** The handles one request opened, keyed by resolved store path and lock wait. */
+export class RequestStores {
+    busyWaitMs;
+    #failFastWhenBusy;
+    #handles = new Map();
+    #closed = false;
+    constructor(opts = {}) {
+        this.busyWaitMs = opts.busyWaitMs;
+        this.#failFastWhenBusy = opts.failFastWhenBusy === true;
+    }
+    get closed() {
+        return this.#closed;
+    }
+    /** The scope's handle on `hippoRoot`, opened on first use. `opts.busyWaitMs` overrides the scope's lock wait. */
+    get(hippoRoot, opts) {
+        const busyWaitMs = opts?.busyWaitMs ?? this.busyWaitMs;
+        // A listener or timer that outlives its request still sees this scope, so it gets a connection of its own.
+        if (this.#closed)
+            return connectHippoDb(hippoRoot, busyWaitMs);
+        const key = `${path.resolve(getHippoDbPath(hippoRoot))}\0${busyWaitMs ?? ''}`;
+        const cached = this.#handles.get(key);
+        if (cached?.isOpen && !cached.isTransaction)
+            return cached;
+        const db = connectHippoDb(hippoRoot, busyWaitMs);
+        // An open nested inside a transaction gets its own connection, which its caller closes.
+        if (cached?.isOpen)
+            return db;
+        this.#handles.set(key, db);
+        scopedHandles.add(db);
+        trackLive(this);
+        return db;
+    }
+    /** A lock held past one full wait belongs to a long transaction, so a hook scope's later writes skip at once. */
+    noteBusy() {
+        if (!this.#failFastWhenBusy)
+            return;
+        for (const db of this.#handles.values()) {
+            if (db.isOpen !== false)
+                db.exec('PRAGMA busy_timeout = 0');
+        }
+    }
+    close() {
+        this.#closed = true;
+        liveScopes.delete(this);
+        for (const db of this.#handles.values()) {
+            if (db.isOpen !== false)
+                db.close();
+        }
+        this.#handles.clear();
+    }
+}
+const scopes = new AsyncLocalStorage();
+/** Runs `fn` in a request scope whose handles close when `fn` settles; inside an open scope `fn` joins it and `opts` is ignored. */
+export async function runWithRequestStores(fn, opts) {
+    const outer = scopes.getStore();
+    if (outer && !outer.closed)
+        return fn();
+    const stores = new RequestStores(opts);
+    return scopes.run(stores, async () => {
+        try {
+            return await fn();
+        }
+        finally {
+            stores.close();
+        }
+    });
+}
+/** The scope this code runs in, if any. A closed scope still answers: its `get` falls through to a plain open. */
+export function currentRequestStores() {
+    return scopes.getStore();
+}
+/** Runs `fn` outside every scope, for a connection that must outlive the request that happens to open it. */
+export function outsideRequestStores(fn) {
+    return scopes.exit(fn);
+}
+/** Whether a scope owns `db` and will close it itself. */
+export function isScopedHandle(db) {
+    return scopedHandles.has(db);
+}
+//# sourceMappingURL=request-stores.js.map

package/dist/db/sqlite-blocked.d.ts

@@ -0,0 +1,16 @@
+/** 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, message?: string);
+}
+/** A store that lacks a whole group of port methods; it maps to the same 501, and the log names the group instead of hippo.db. */
+export declare class StoreNotPortedError extends SqliteBlockedError {
+    readonly group: string;
+    constructor(storeKind: string, group: string);
+}
+/** Thrown by a hippo.db open in a folder whose marker file names the store that holds its memories, from the CLI as from a request. */
+export declare class OtherStoreFolderError extends SqliteBlockedError {
+    readonly markerPath: string;
+    constructor(storeKind: string, markerPath: string);
+}
+//# sourceMappingURL=sqlite-blocked.d.ts.map

package/dist/db/sqlite-blocked.js

@@ -0,0 +1,29 @@
+// A leaf module, so http-util can map this error to a 501 without importing db/open, whose migrations reach back to http-util.
+/** 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, message = `hippo.db is not opened while the '${storeKind}' store serves this request; this code path is not ported to the store yet`) {
+        super(message);
+        this.storeKind = storeKind;
+        this.name = 'SqliteBlockedError';
+    }
+}
+/** A store that lacks a whole group of port methods; it maps to the same 501, and the log names the group instead of hippo.db. */
+export class StoreNotPortedError extends SqliteBlockedError {
+    group;
+    constructor(storeKind, group) {
+        super(storeKind, `the '${storeKind}' store has no '${group}' reads; this code path is not ported to the store yet`);
+        this.group = group;
+        this.name = 'StoreNotPortedError';
+    }
+}
+/** Thrown by a hippo.db open in a folder whose marker file names the store that holds its memories, from the CLI as from a request. */
+export class OtherStoreFolderError extends SqliteBlockedError {
+    markerPath;
+    constructor(storeKind, markerPath) {
+        super(storeKind, `This folder's memories live in the '${storeKind}' store, so hippo.db is not used here (marker: ${markerPath})`);
+        this.markerPath = markerPath;
+        this.name = 'OtherStoreFolderError';
+    }
+}
+//# sourceMappingURL=sqlite-blocked.js.map

package/dist/db.d.ts

@@ -3,5 +3,7 @@ export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWith
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
 export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
 export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, withBusyWait, scopedBusyWait, SqliteBlockedError, withSqliteBlocked, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, rethrowIfSqliteBlocked, OTHER_STORE_MARKER, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './db/request-stores.js';
+export { OtherStoreFolderError, SqliteBlockedError } from './db/sqlite-blocked.js';
 //# sourceMappingURL=db.d.ts.map

package/dist/db.js

@@ -2,5 +2,7 @@ export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWith
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
 export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
 export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, withBusyWait, scopedBusyWait, SqliteBlockedError, withSqliteBlocked, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, rethrowIfSqliteBlocked, OTHER_STORE_MARKER, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './db/request-stores.js';
+export { OtherStoreFolderError, SqliteBlockedError } from './db/sqlite-blocked.js';
 //# sourceMappingURL=db.js.map

package/dist/embeddings.d.ts

@@ -64,8 +64,19 @@ export declare function embeddingInputText(entry: {
  * consistent with the compare side in `embeddingModelRequiresReindex`.
  */
 export declare function saveStoredEmbeddingModel(hippoRoot: string, model: string): void;
+/** What a store's vector index was built by: the stored identity, and whether any vector exists. */
+export interface EmbeddingIndexState {
+    readonly storedModel: string | null;
+    readonly hasVectors: boolean;
+}
+/** The model the index was built by: the stored identity, else the default model when vectors exist. */
+export declare function indexedModel(state: EmbeddingIndexState): string | null;
+/** The one rebuild rule every store applies to its indexed model. */
+export declare function indexNeedsRebuild(indexed: string | null, providerId: string): boolean;
 export declare function resolveIndexedEmbeddingModel(hippoRoot: string, index?: Record<string, number[]>): string | null;
 export declare function embeddingModelRequiresReindex(hippoRoot: string, model: string, index?: Record<string, number[]>): boolean;
+/** hippo.db's index state, the meta row and the EXISTS on one handle. */
+export declare function embeddingIndexStateAt(hippoRoot: string): EmbeddingIndexState;
 /**
  * Cosine similarity between two vectors. Handles unnormalized vectors.
  * Returns 0 for empty or mismatched vectors.
@@ -75,8 +86,6 @@ export declare function cosineSimilarity(a: number[], b: number[]): number;
 export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, number[]>;
 /** Stored vectors for `ids` only. */
 export declare function loadStoredVectors(hippoRoot: string, ids: readonly string[]): Map<string, number[]>;
-/** Whether the store holds any vector at all. */
-export declare function hasEmbeddings(hippoRoot: string): boolean;
 /** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
 export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>, model?: string): void;
 /**

package/dist/embeddings.js

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
 import { loadAllEntries } from './store/entry-reads.js';
-import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
+import { openHippoDb, closeHippoDb, getMeta, rethrowIfSqliteBlocked, setMeta } from './db.js';
 import { EMBEDDING_MODEL_META_KEY, deleteOrphanVectors, hasStoredVectors, loadVectors, replaceAllVectors, storedVectorIds, upsertVectors, } from './vector-store.js';
 import { initializeParticle, savePhysicsState, loadPhysicsState, resetAllPhysicsState } from './physics-state.js';
 import { loadConfig } from './config.js';
@@ -81,6 +81,7 @@ function loadStoredEmbeddingModel(hippoRoot) {
         }
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         log.debug(`stored embedding model unreadable: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
@@ -100,16 +101,29 @@ export function saveStoredEmbeddingModel(hippoRoot, model) {
         closeHippoDb(db);
     }
 }
+/** The model the index was built by: the stored identity, else the default model when vectors exist. */
+export function indexedModel(state) {
+    return state.storedModel ?? (state.hasVectors ? DEFAULT_EMBEDDING_MODEL : null);
+}
+/** The one rebuild rule every store applies to its indexed model. */
+export function indexNeedsRebuild(indexed, providerId) {
+    return indexed !== null && indexed !== embeddingIndexIdentity(providerId);
+}
 export function resolveIndexedEmbeddingModel(hippoRoot, index) {
-    const stored = loadStoredEmbeddingModel(hippoRoot);
-    if (stored)
-        return stored;
-    const hasVectors = index ? Object.keys(index).length > 0 : withVectorDb(hippoRoot, hasStoredVectors);
-    return hasVectors ? DEFAULT_EMBEDDING_MODEL : null;
+    const storedModel = loadStoredEmbeddingModel(hippoRoot);
+    if (storedModel)
+        return storedModel;
+    return indexedModel({ storedModel, hasVectors: index ? Object.keys(index).length > 0 : withVectorDb(hippoRoot, hasStoredVectors) });
 }
 export function embeddingModelRequiresReindex(hippoRoot, model, index) {
-    const stored = resolveIndexedEmbeddingModel(hippoRoot, index);
-    return stored !== null && stored !== embeddingIndexIdentity(model);
+    return indexNeedsRebuild(resolveIndexedEmbeddingModel(hippoRoot, index), model);
+}
+/** hippo.db's index state, the meta row and the EXISTS on one handle. */
+export function embeddingIndexStateAt(hippoRoot) {
+    return withVectorDb(hippoRoot, (db) => ({
+        storedModel: getMeta(db, EMBEDDING_MODEL_META_KEY, '').trim() || null,
+        hasVectors: hasStoredVectors(db),
+    }));
 }
 async function rebuildEmbeddingIndex(entries, provider) {
     const rebuilt = {};
@@ -188,10 +202,6 @@ export function loadEmbeddingIndex(hippoRoot) {
 export function loadStoredVectors(hippoRoot, ids) {
     return ids.length === 0 ? new Map() : withVectorDb(hippoRoot, (db) => loadVectors(db, ids));
 }
-/** Whether the store holds any vector at all. */
-export function hasEmbeddings(hippoRoot) {
-    return withVectorDb(hippoRoot, hasStoredVectors);
-}
 /** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
 export function saveEmbeddingIndex(hippoRoot, index, model) {
     withVectorDb(hippoRoot, (db) => replaceAllVectors(db, index, model ?? getMeta(db, EMBEDDING_MODEL_META_KEY, '')));

package/dist/goals.d.ts

@@ -78,6 +78,13 @@ export interface GetActiveGoalsOpts {
     tenantId: string;
 }
 export declare function getActiveGoals(hippoRoot: string, opts: GetActiveGoalsOpts): Goal[];
+/** A session's active goals, oldest first, and the retrieval policy of each goal that names one. */
+export interface ActiveGoals {
+    readonly goals: Goal[];
+    readonly policies: ReadonlyMap<string, RetrievalPolicy>;
+}
+/** The active goals and their policies on one handle, so a goal and its policy never disagree. */
+export declare function activeGoalsWithPolicies(hippoRoot: string, opts: GetActiveGoalsOpts): ActiveGoals;
 /** Every goal of a (tenant, session), whatever its status, oldest first. */
 export declare function getSessionGoals(hippoRoot: string, opts: GetActiveGoalsOpts): Goal[];
 export declare function getActiveGoalsWithDb(db: DatabaseSyncLike, opts: GetActiveGoalsOpts): Goal[];
@@ -90,7 +97,7 @@ export interface GoalRecallLogRow {
     recalledAt: string;
     score: number;
 }
-/** Options shared by {@link computeGoalStackBoost} and {@link applyGoalStackBoost}. */
+/** Options shared by {@link computeGoalStackBoost} and {@link boostByGoals}. */
 export interface GoalStackBoostOpts {
     sessionId: string;
     tenantId: string;
@@ -107,6 +114,10 @@ export interface GoalStackBoost<R> {
     results: R[];
     log: GoalRecallLogRow[];
 }
+export declare function loadGoalPolicies(db: DatabaseSyncLike, active: readonly Goal[]): Map<string, RetrievalPolicy>;
+/** The rows whose memory lives in this store: goal_recall_log.memory_id references memories, so a global row would fail
+ *  the insert. A global result keeps its boost; it only earns no log row, so no outcome propagation. */
+export declare function localGoalRecallRows(db: DatabaseSyncLike, rows: readonly GoalRecallLogRow[]): GoalRecallLogRow[];
 /**
  * dlPFC goal-stack boost. Applies the multi-goal boost to entry-backed scored
  * rows when (tenant, session) has active goals and returns the log rows to
@@ -130,21 +141,17 @@ export declare function computeGoalStackBoost<R extends {
     entry: MemoryEntry;
     score: number;
 }>(db: DatabaseSyncLike, results: R[], opts: GoalStackBoostOpts): GoalStackBoost<R>;
+/** {@link computeGoalStackBoost} over goals already read, touching no store. Its log keeps rows whose memory is global,
+ *  since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
+export declare function boostByGoals<R extends {
+    entry: MemoryEntry;
+    score: number;
+}>(results: R[], active: ActiveGoals, opts: GoalStackBoostOpts): GoalStackBoost<R>;
 /**
  * Writes goal-boost log rows. INSERT OR IGNORE because UNIQUE(memory_id, goal_id)
  * makes a re-recall during the same goal life a no-op for outcome attribution.
  */
 export declare function writeGoalRecallLog(db: DatabaseSyncLike, rows: readonly GoalRecallLogRow[]): void;
-/**
- * {@link computeGoalStackBoost} plus {@link writeGoalRecallLog} in one call, for
- * pipelines that boost and log on the same handle.
- *
- * @internal Recall ranking helper. Subject to change.
- */
-export declare function applyGoalStackBoost<R extends {
-    entry: MemoryEntry;
-    score: number;
-}>(db: DatabaseSyncLike, results: R[], opts: GoalStackBoostOpts): R[];
 export interface CompleteGoalOpts {
     outcomeScore?: number;
     /**