hippo-memory 1.64.0 → 1.65.0

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();
 }

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,6 @@
+/** 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);
+}
+//# sourceMappingURL=sqlite-blocked.d.ts.map

package/dist/db/sqlite-blocked.js

@@ -0,0 +1,11 @@
+// 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) {
+        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';
+    }
+}
+//# 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, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './db/request-stores.js';
+export { 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, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './db/request-stores.js';
+export { SqliteBlockedError } from './db/sqlite-blocked.js';
 //# sourceMappingURL=db.js.map

package/dist/embedding-provider.js

@@ -27,7 +27,7 @@
  * egress-blocked in the build sandbox).
  */
 import { envByName } from './env.js';
-import { getEmbedding, isEmbeddingAvailable, resolveEmbeddingModel, DEFAULT_EMBEDDING_MODEL, } from './local-embedding.js';
+import { getEmbedding, isEmbeddingAvailable, requireLocalPipeline, resolveEmbeddingModel, DEFAULT_EMBEDDING_MODEL, } from './local-embedding.js';
 import { loadConfig } from './config.js';
 import { redactSecretsStrict } from './secret-detect.js';
 import { fetchWithRetry } from './http-retry.js';
@@ -57,8 +57,9 @@ class LocalEmbeddingProvider {
         return this.enabled && isEmbeddingAvailable();
     }
     async embed(texts, role) {
-        // Sequential to preserve the historical single-pipeline behaviour and avoid
-        // contending the one cached pipeline instance with N concurrent calls.
+        // A model that cannot load fails the call, as an API outage does; items then run one at a time on the shared pipeline.
+        if (texts.length > 0)
+            await requireLocalPipeline(this.model);
         const out = [];
         for (const text of texts) {
             out.push(await getEmbedding(text, this.model, role));

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;
     }

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;
     /**

package/dist/goals.js

@@ -129,6 +129,17 @@ export function getActiveGoals(hippoRoot, opts) {
         closeHippoDb(db);
     }
 }
+/** The active goals and their policies on one handle, so a goal and its policy never disagree. */
+export function activeGoalsWithPolicies(hippoRoot, opts) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        const goals = getActiveGoalsWithDb(db, opts);
+        return { goals, policies: loadGoalPolicies(db, goals) };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /** Every goal of a (tenant, session), whatever its status, oldest first. */
 export function getSessionGoals(hippoRoot, opts) {
     const db = openHippoDb(hippoRoot);
@@ -163,7 +174,7 @@ export function getActiveGoalsWithDb(db, opts) {
 // can compose onto the base goal-tag boost. Composed result is hard-capped
 // at MAX_FINAL_MULTIPLIER (3.0x) BEFORE applying to score -- even an
 // `errorPriority: 9.0` policy cannot exceed 3.0x.
-function loadGoalPolicies(db, active) {
+export function loadGoalPolicies(db, active) {
     const policiesByGoalId = new Map();
     for (const g of active) {
         if (!g.retrievalPolicyId)
@@ -220,28 +231,11 @@ function goalBoostMultiplier(entry, tags, matches, goalsByTag, policiesByGoalId)
     return Math.min(multiplier, MAX_FINAL_MULTIPLIER);
 }
 /** Log rows for the top `limit` boosted rows, one per matched goal. */
-function buildGoalRecallLog(db, boosted, matchesByEntryId, goalsByTag, opts) {
+function buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) {
     const { sessionId, tenantId, limit } = opts;
-    // Filter to local memories only -- global memory IDs aren't in this DB's
-    // memories table, so the FK on goal_recall_log.memory_id would fail.
-    // dlPFC depth's outcome propagation is session-scoped to local; boost on
-    // ranking still applies to global results, just no log row -> no
-    // propagation.
-    const topKIds = boosted.slice(0, limit).map((r) => r.entry.id);
-    const localIds = new Set();
-    if (topKIds.length > 0) {
-        const placeholders = topKIds.map(() => '?').join(',');
-        // SAFETY: rows come from the SELECT above, which projects exactly one
-        // column, `id`, from memories.
-        const localRows = db.prepare(`SELECT id FROM memories WHERE id IN (${placeholders})`).all(...topKIds);
-        for (const row of localRows)
-            localIds.add(row.id);
-    }
     const recalledAt = new Date().toISOString();
     const log = [];
     for (const r of boosted.slice(0, limit)) {
-        if (!localIds.has(r.entry.id))
-            continue; // global -> skip log insert
         const matches = matchesByEntryId.get(r.entry.id);
         if (!matches || matches.length === 0)
             continue;
@@ -254,6 +248,17 @@ function buildGoalRecallLog(db, boosted, matchesByEntryId, goalsByTag, opts) {
     }
     return log;
 }
+/** 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 function localGoalRecallRows(db, rows) {
+    if (rows.length === 0)
+        return [];
+    const ids = [...new Set(rows.map((r) => r.memoryId))];
+    // SAFETY: the SELECT projects exactly one column, `id`, from memories.
+    const local = db.prepare(`SELECT id FROM memories WHERE id IN (${ids.map(() => '?').join(',')})`).all(...ids);
+    const localIds = new Set(local.map((r) => r.id));
+    return rows.filter((r) => localIds.has(r.memoryId));
+}
 /**
  * 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
@@ -274,12 +279,20 @@ function buildGoalRecallLog(db, boosted, matchesByEntryId, goalsByTag, opts) {
  * @internal Recall ranking helper. Subject to change.
  */
 export function computeGoalStackBoost(db, results, opts) {
-    const { sessionId, tenantId, trace } = opts;
-    const active = getActiveGoalsWithDb(db, { sessionId, tenantId });
-    if (active.length === 0)
+    const goals = getActiveGoalsWithDb(db, { sessionId: opts.sessionId, tenantId: opts.tenantId });
+    if (goals.length === 0)
+        return { results, log: [] };
+    const boost = boostByGoals(results, { goals, policies: loadGoalPolicies(db, goals) }, opts);
+    return { results: boost.results, log: localGoalRecallRows(db, boost.log) };
+}
+/** {@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 function boostByGoals(results, active, opts) {
+    const { trace } = opts;
+    if (active.goals.length === 0)
         return { results, log: [] };
-    const goalsByTag = new Map(active.map((g) => [g.goalName, g]));
-    const policiesByGoalId = loadGoalPolicies(db, active);
+    const goalsByTag = new Map(active.goals.map((g) => [g.goalName, g]));
+    const policiesByGoalId = active.policies;
     // Goal-tag matches per boosted row, keyed by entry id. Kept as a side table
     // (rather than a spread-on `_goalMatches` marker property) so `boosted`
     // stays exactly R[] end to end, with no cast-tag-then-strip round trip.
@@ -313,7 +326,7 @@ export function computeGoalStackBoost(db, results, opts) {
         // inherits its determinism via sort stability, and ties preserve the
         // prior (meaningful) rank instead of reordering by content.
         .sort((a, b) => b.score - a.score);
-    return { results: boosted, log: buildGoalRecallLog(db, boosted, matchesByEntryId, goalsByTag, opts) };
+    return { results: boosted, log: buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) };
 }
 /**
  * Writes goal-boost log rows. INSERT OR IGNORE because UNIQUE(memory_id, goal_id)
@@ -331,17 +344,6 @@ export function writeGoalRecallLog(db, rows) {
         insertLog.run(row.goalId, row.memoryId, row.tenantId, row.sessionId, row.recalledAt, row.score);
     }
 }
-/**
- * {@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 function applyGoalStackBoost(db, results, opts) {
-    const boost = computeGoalStackBoost(db, results, opts);
-    writeGoalRecallLog(db, boost.log);
-    return boost.results;
-}
 const POSITIVE_OUTCOME_THRESHOLD = 0.7;
 const NEGATIVE_OUTCOME_THRESHOLD = 0.3;
 const STRENGTH_BOOST = 1.10;

package/dist/http-util.d.ts

@@ -23,6 +23,8 @@ export interface ApiErrorReply {
     message: string;
 }
 export declare const INTERNAL_ERROR_MESSAGE = "internal server error";
+/** The reply when a request under another store reaches code that still opens hippo.db. */
+export declare const STORE_NOT_PORTED_MESSAGE = "store_not_ported";
 /** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
 export declare function mapApiError<E>(err: E): ApiErrorReply;
 /** Serialises before the head goes out, so a body that is not JSON still reaches the caller's error reply. */

package/dist/http-util.js

@@ -1,4 +1,5 @@
 import { ApiError } from './api-errors.js';
+import { SqliteBlockedError } from './db/sqlite-blocked.js';
 // Leaf module shared by server.ts and the connector webhook receivers; it must not import either.
 export function isJsonObjectRecord(value) {
     return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -35,6 +36,8 @@ export class BodyTooLargeError extends Error {
 export class BodyTimeoutError extends Error {
 }
 export const INTERNAL_ERROR_MESSAGE = 'internal server error';
+/** The reply when a request under another store reaches code that still opens hippo.db. */
+export const STORE_NOT_PORTED_MESSAGE = 'store_not_ported';
 /** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
 export function mapApiError(err) {
     // An add-on can build an HttpError from any number, and writeHead throws on one outside 100-999.
@@ -47,6 +50,8 @@ export function mapApiError(err) {
         return { status: 413, message: err.message };
     if (err instanceof BodyTimeoutError)
         return { status: 408, message: err.message };
+    if (err instanceof SqliteBlockedError)
+        return { status: 501, message: STORE_NOT_PORTED_MESSAGE };
     return { status: 500, message: INTERNAL_ERROR_MESSAGE };
 }
 /** Serialises before the head goes out, so a body that is not JSON still reaches the caller's error reply. */

package/dist/local-embedding.d.ts

@@ -7,6 +7,8 @@ export type EmbeddingRole = 'query' | 'passage';
 export declare function prefixFor(model: string, role?: EmbeddingRole): string;
 /** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
 export declare function isEmbeddingAvailable(): boolean;
+/** Throws, with the reason, when the model's pipeline cannot load: a provider-level failure, not a per-item skip. */
+export declare function requireLocalPipeline(model: string): Promise<void>;
 export declare function resolveEmbeddingModel(hippoRoot: string, explicitModel?: string): string;
 /** Embeds `text` with the local model, or returns `[]` when Transformers.js is missing or fails; `role` adds e5-style prefixes. */
 export declare function getEmbedding(text: string, model?: string, role?: EmbeddingRole): Promise<number[]>;