hippo-memory 1.64.0 → 1.65.0

package/dist/api/recall.js

@@ -1,18 +1,13 @@
 // Read path: recall (sync) and retrieve (async, adds the vector arm).
 import { envRequireSessionScopedFreshTail } from '../env.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
 import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
-import { strengthenRetrieved } from '../store/entry-writes.js';
 import { isRecallBoostAblated } from '../ablation.js';
 import { loadEntriesByIds, loadFreshRawMemories } from '../store/entry-reads.js';
 import { loadRecallSearchEntries, recallScopeFilter } from '../store/search-rows.js';
-import { loadActiveTaskSnapshot, listSessionEvents } from '../store/sessions.js';
-import { loadLatestHandoff } from '../store/handoffs.js';
 import { estimateTokens } from '../token-ledger.js';
 import { formatHandoffEvidenceLine } from '../handoff.js';
-import { appendAuditEvent, auditQueryFields } from '../audit.js';
-import { writeRecallTrace, writeRecallTraceAtRoot } from '../recall-trace.js';
-import { applyGoalStackBoost } from '../goals.js';
+import { activeGoalsWithPolicies, boostByGoals } from '../goals.js';
+import { continuityAt, finishRecallAt, storeFor } from '../store-port.js';
 import { hybridSearch } from '../search/hybrid.js';
 import { physicsSearch } from '../search/physics-search.js';
 import { churnStaleFactor } from '../search/boosts.js';
@@ -20,11 +15,12 @@ import { compareEntryIdentity } from '../compare.js';
 import { dropHeldCopies, duplicateKey, storedTextKeys } from '../same-text.js';
 import { isSharedStore, loadConfig } from '../config.js';
 import { classifyOriginProject, projectNames } from '../project-identity.js';
-import { computePlanningFallacyOutput } from '../predictions/planning-fallacy.js';
+import { decidePlanningFallacy, detectPlanningClaim, planningFallacyEvidenceAt } from '../predictions/planning-fallacy.js';
 import { detectAnchoring, hashQueryText, biasHintEnabled } from '../recall-history.js';
 import { detectAvailabilityBias } from '../availability.js';
 import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../recall-scope.js';
 import { ownerOrSubject, RecallContractError } from './types.js';
+import { anchoringRows, availabilityRows, recallAuditMetadata, recallAuditRow } from './recall-record.js';
 /**
  * Shared construction helper for `RecallSuppressionSummary`. Used by
  * `api.recall`, `cmdRecall`, and the MCP `hippo_recall` handler so all three
@@ -43,7 +39,8 @@ export function buildSuppressionSummary(counts) {
     };
 }
 /**
- * Domain-level recall. Loads BM25-ranked candidates from SQLite scoped to
+ * Domain-level recall on hippo.db only, never `ctx.store`, since it is synchronous: under another store its first open throws
+ * `SqliteBlockedError`. Loads BM25-ranked candidates from SQLite scoped to
  * `ctx.tenantId` and keeps that order whatever `mode` says; `retrieve` is the
  * mode-aware, strengthening variant the HTTP route uses.
  *
@@ -62,7 +59,11 @@ export function recall(ctx, opts) {
     assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
     const own = personalScopeOf(ctx.actor) ?? undefined;
-    return recallFrom(ctx, opts, windowSize, loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false, recallOrigin(opts), own), own);
+    const all = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false, recallOrigin(opts), own);
+    const plan = planRecall(ctx, opts, all, own);
+    const { result, writes } = composeRecall(ctx, opts, windowSize, all, plan, readRecallSync(ctx, opts, plan));
+    finishRecallAt(ctx.hippoRoot, writes);
+    return result;
 }
 function recallOrigin(opts) {
     return opts.project ? projectNames(opts.project) : undefined;
@@ -70,7 +71,7 @@ function recallOrigin(opts) {
 function inCallerProject(entry, opts) {
     return !opts.project || classifyOriginProject(entry.origin_project, opts.project) !== 'cross-project';
 }
-/** Mode-aware recall that strengthens each returned row; never writes last_retrieval_ids (contract lock). */
+/** Mode-aware recall through the served store that strengthens each returned row; never writes last_retrieval_ids (contract lock). */
 export async function retrieve(ctx, opts) {
     assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
@@ -78,7 +79,8 @@ export async function retrieve(ctx, opts) {
     const own = personalScopeOf(ctx.actor) ?? undefined;
     if (opts.showRanked)
         return retrieveFromStore(ctx, opts, windowSize, opts.showRanked, own);
-    let candidates = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false, recallOrigin(opts), own);
+    const store = storeFor(ctx);
+    let candidates = await store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, windowSize, own));
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
         const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null, vectorCandidates: recallVectorSpec(ctx, opts, own) };
         const ranked = opts.mode === 'physics'
@@ -87,10 +89,26 @@ export async function retrieve(ctx, opts) {
         const rankedIds = new Set(ranked.map((r) => r.entry.id));
         candidates = [...ranked.map((r) => r.entry), ...candidates.filter((e) => !rankedIds.has(e.id))];
     }
-    const result = recallFrom(ctx, opts, windowSize, candidates, own);
-    strengthenRetrieved(ctx.hippoRoot, result.results.map((r) => r.id), { tenantId: ctx.tenantId, recallBoostAblated: isRecallBoostAblated() });
+    const plan = planRecall(ctx, opts, candidates, own);
+    const { result, writes } = composeRecall(ctx, opts, windowSize, candidates, plan, await readRecall(store, ctx, opts, plan));
+    await store.finishRecall({ ...writes, strengthen: strengthenOf(ctx, result.results.map((r) => r.id)) });
     return result;
 }
+/** The recall load's arguments: exact scope, current rows only, the caller's project and personal scope. */
+function recallSearchArgs(ctx, opts, limit, own) {
+    return {
+        limit,
+        tenantId: ctx.tenantId,
+        requestedScope: opts.scope,
+        explicitScopeMode: 'exact',
+        includeSuperseded: false,
+        originProjects: recallOrigin(opts),
+        ownScope: own,
+    };
+}
+function strengthenOf(ctx, ids) {
+    return { ids, opts: { tenantId: ctx.tenantId, recallBoostAblated: isRecallBoostAblated() } };
+}
 /** api.retrieve's vector arm: the recall load's exact-scope rule, current rows only. */
 function recallVectorSpec(ctx, opts, own) {
     return {
@@ -105,39 +123,44 @@ function recallVectorSpec(ctx, opts, own) {
 const SHOW_RANKED_LEXICAL_WINDOW = 1000;
 /** `retrieve` under `showRanked`: physics when `mode` says so, hybrid otherwise, over a wide lexical window plus the nearest vectors. */
 async function retrieveFromStore(ctx, opts, windowSize, show, own) {
-    const loaded = loadRecallSearchEntries(ctx.hippoRoot, opts.query, Math.max(windowSize, SHOW_RANKED_LEXICAL_WINDOW), ctx.tenantId, opts.scope, 'exact', false, recallOrigin(opts), own);
+    const store = storeFor(ctx);
+    const loaded = await store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, Math.max(windowSize, SHOW_RANKED_LEXICAL_WINDOW), own));
     const pool = loaded.filter((e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope, own));
     // No scope option: the scope boost follows HIPPO_SCOPE and the skill env, as MCP recall always ranked.
     const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, vectorCandidates: recallVectorSpec(ctx, opts, own) };
     let ranked = opts.mode === 'physics'
         ? await physicsSearch(opts.query, pool, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
         : await hybridSearch(opts.query, pool, searchOpts);
-    if (opts.sessionId && !opts.goalTag) {
-        const db = openHippoDb(ctx.hippoRoot);
-        try {
-            ranked = applyGoalStackBoost(db, ranked, { sessionId: opts.sessionId, tenantId: ctx.tenantId, limit: ranked.length });
-        }
-        finally {
-            closeHippoDb(db);
-        }
+    // One goal read serves both boosts; the ranked list's log rows come first, so its scores win the log's first-write.
+    const goals = opts.sessionId && !opts.goalTag ? await store.activeGoals({ sessionId: opts.sessionId, tenantId: ctx.tenantId }) : null;
+    let rankedLog = [];
+    if (goals && opts.sessionId) {
+        const boost = boostByGoals(ranked, goals, { sessionId: opts.sessionId, tenantId: ctx.tenantId, limit: ranked.length });
+        ranked = boost.results;
+        rankedLog = boost.log;
     }
     const window = ranked.slice(0, windowSize).map((r) => r.entry);
-    const result = recallFrom(ctx, { ...opts, suppressRecallTrace: true }, windowSize, window, own);
+    const bandOpts = { ...opts, suppressRecallTrace: true };
+    const plan = planRecall(ctx, bandOpts, window, own);
+    const { result, writes } = composeRecall(ctx, bandOpts, windowSize, window, plan, await readRecall(store, ctx, bandOpts, plan, goals), false);
     // Rows the vector arm added count as candidates too.
     const inPool = new Set(pool.map((e) => e.id));
     const candidates = [...pool, ...ranked.map((r) => r.entry).filter((e) => !inPool.has(e.id))];
     const shown = show({ ranked, pool: candidates, droppedByScope: loaded.length - pool.length }, result);
-    strengthenRetrieved(ctx.hippoRoot, shown, { tenantId: ctx.tenantId, recallBoostAblated: isRecallBoostAblated() });
-    if (!opts.suppressRecallTrace) {
-        const scores = new Map(ranked.map((r) => [r.entry.id, r.score]));
-        writeRecallTraceAtRoot(ctx.hippoRoot, {
+    const scores = new Map(ranked.map((r) => [r.entry.id, r.score]));
+    const shownRow = recallAuditRow(callerOf(ctx), 'recall', undefined, recallAuditMetadata(opts.query, shown.ids.length));
+    await store.finishRecall({
+        goalLog: [...rankedLog, ...writes.goalLog],
+        audit: [...writes.audit, shownRow, ...shown.audit],
+        trace: opts.suppressRecallTrace ? undefined : {
             tenantId: ctx.tenantId,
             sessionId: opts.sessionId ?? null,
             pipeline: 'mcp',
             query: opts.query,
-            results: shown.map((id) => ({ memoryId: id, score: scores.get(id) ?? 0 })),
-        });
-    }
+            results: shown.ids.map((id) => ({ memoryId: id, score: scores.get(id) ?? 0 })),
+        },
+        strengthen: strengthenOf(ctx, shown.ids),
+    });
     return result;
 }
 /** Contract preflight: throws before any store-touching work. */
@@ -162,36 +185,66 @@ function recallWindowSize(opts) {
     }
     return opts.scorerWindow ?? DEFAULT_SEARCH_CANDIDATE_LIMIT;
 }
-function recallFrom(ctx, opts, windowSize, all, own) {
+const CONTINUITY_EVENT_LIMIT = 5;
+function planRecall(ctx, opts, all, own) {
     const limit = opts.limit ?? 10;
     const window = admitCandidates(opts, all, limit, own);
-    // One db handle spans the goal-stack boost and the audit and trace rows; it closes before the continuity block.
-    const db = openHippoDb(ctx.hippoRoot);
-    let bands;
-    try {
-        bands = rankBands(db, ctx, opts, window, limit, own);
-        auditAndTraceRecall(db, ctx, opts, bands.rankedOut);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    return {
+        limit,
+        window,
+        own,
+        goalBoost: opts.sessionId && !opts.goalTag ? { sessionId: opts.sessionId, tenantId: ctx.tenantId, limit } : null,
+        overflow: (opts.summarizeOverflow ?? true) && window.entries.length > limit ? overflowGroups(window, limit) : new Map(),
+        claim: detectPlanningClaim(opts.query),
+    };
+}
+/** The plan's reads on hippo.db directly, for the synchronous recall that cannot await the port. */
+function readRecallSync(ctx, opts, plan) {
+    const { hippoRoot, tenantId } = ctx;
+    const freshCount = opts.freshTailCount ?? 0;
+    return {
+        goals: plan.goalBoost ? activeGoalsWithPolicies(hippoRoot, { sessionId: plan.goalBoost.sessionId, tenantId }) : null,
+        parents: plan.overflow.size > 0 ? loadEntriesByIds(hippoRoot, [...plan.overflow.keys()], tenantId) : [],
+        freshRaws: freshCount > 0 ? loadFreshRawMemories(hippoRoot, freshCount, tenantId, opts.freshTailSessionId, recallOrigin(opts)) : [],
+        continuity: opts.includeContinuity ? continuityAt(hippoRoot, tenantId, CONTINUITY_EVENT_LIMIT, continuityKey(ctx, opts)) : undefined,
+        planning: plan.claim ? planningFallacyEvidenceAt(hippoRoot, tenantId, plan.claim.classQueryTokens) : null,
+    };
+}
+/** The plan's reads through the store; `goals` already read by the caller skips that read. */
+async function readRecall(store, ctx, opts, plan, goals) {
+    const { tenantId } = ctx;
+    const freshCount = opts.freshTailCount ?? 0;
+    return {
+        goals: goals !== undefined ? goals : plan.goalBoost ? await store.activeGoals({ sessionId: plan.goalBoost.sessionId, tenantId }) : null,
+        parents: plan.overflow.size > 0 ? await store.entriesByIds([...plan.overflow.keys()], tenantId) : [],
+        freshRaws: freshCount > 0 ? await store.freshRawEntries(freshCount, tenantId, opts.freshTailSessionId, recallOrigin(opts) ?? null) : [],
+        continuity: opts.includeContinuity ? await store.continuity(tenantId, CONTINUITY_EVENT_LIMIT, continuityKey(ctx, opts)) : undefined,
+        planning: plan.claim ? await store.planningFallacyEvidence(tenantId, plan.claim.classQueryTokens) : null,
+    };
+}
+// On a shared store the tenant's newest row is another developer's; no project keys to nothing, so the block is empty.
+function continuityKey(ctx, opts) {
+    if (!isSharedStore(ctx.hippoRoot))
+        return null;
+    return { owner: ownerOrSubject(ctx.actor), project: opts.project ? projectNames(opts.project) : [] };
+}
+/** The reply and the rows it writes, from the candidates and the plan's reads; touches no store.
+ *  `auditBand` false: the caller shows a cut of the band and audits the rows it shows. */
+function composeRecall(ctx, opts, windowSize, all, plan, reads, auditBand = true) {
+    const { window } = plan;
+    const bands = rankBands(opts, plan, reads);
     const rankedOut = bands.rankedOut;
-    const { continuity, continuityTokens } = opts.includeContinuity
-        ? loadContinuity(ctx, opts, own)
-        : { continuity: undefined, continuityTokens: undefined };
+    const continuity = reads.continuity ? scopeContinuity(reads.continuity, opts, plan.own) : undefined;
     // Query-derived, so MCP and CLI read this one hint instead of recomputing; HIPPO_AUTODEBIAS=off disables it.
-    // The hint and the no-class-match / tiebreak watching variant are mutually exclusive; both go out as optional fields.
-    const planningFallacyOutput = computePlanningFallacyOutput(ctx.hippoRoot, ctx.tenantId, opts.query, { actor: ctx.actor.subject });
-    const planningFallacyHint = planningFallacyOutput.hint ?? null;
-    const planningFallacyWatching = planningFallacyOutput.watching ?? null;
-    const { anchoringHint, suppressedByInterference } = detectRecallAnchoring(ctx, opts, rankedOut[0]?.id ?? null);
-    const availabilityHint = detectRecallAvailability(ctx, opts, bands.baseSlice, window.entries);
+    const planning = plan.claim && reads.planning ? decidePlanningFallacy(plan.claim, reads.planning, ctx.tenantId, ctx.actor.subject) : null;
+    const { anchoringHint, suppressedByInterference } = detectRecallAnchoring(opts, rankedOut[0]?.id ?? null);
+    const availabilityHint = detectRecallAvailability(opts, bands.baseSlice, window.entries);
     const result = {
         results: rankedOut,
         total: window.entries.length,
         tokens: rankedOut.reduce((acc, r) => acc + estimateTokens(r.content), 0),
         continuity,
-        continuityTokens,
+        continuityTokens: continuity ? continuityTokensOf(continuity) : undefined,
         windowSize,
         suppressionSummary: buildSuppressionSummary({
             totalCandidates: all.length,
@@ -202,15 +255,21 @@ function recallFrom(ctx, opts, windowSize, all, own) {
             suppressedByInterference,
         }),
     };
-    if (planningFallacyHint)
-        result.planningFallacyHint = planningFallacyHint;
-    if (planningFallacyWatching)
-        result.planningFallacyWatching = planningFallacyWatching;
+    // The hint and the no-class-match / tiebreak watching variant are mutually exclusive; both go out as optional fields.
+    if (planning?.output.hint)
+        result.planningFallacyHint = planning.output.hint;
+    if (planning?.output.watching)
+        result.planningFallacyWatching = planning.output.watching;
     if (anchoringHint)
         result.anchoringHint = anchoringHint;
     if (availabilityHint)
         result.availabilityHint = availabilityHint;
-    return result;
+    const who = callerOf(ctx);
+    const audit = auditBand ? [recallAuditRow(who, 'recall', undefined, recallAuditMetadata(opts.query, rankedOut.length))] : [];
+    if (planning?.audit)
+        audit.push(planning.audit);
+    audit.push(...anchoringRows(who, anchoringHint), ...availabilityRows(who, availabilityHint));
+    return { result, writes: { goalLog: bands.goalLog, audit, trace: recallTrace(ctx, opts, rankedOut) } };
 }
 // The SQL load already applied tenant and scope; any recall-mode loader must go through loadRecallSearchEntries.
 function admitCandidates(opts, all, limit, own) {
@@ -234,24 +293,21 @@ function admitCandidates(opts, all, limit, own) {
     return { entries, baseSlice, droppedPreRank, droppedByBudget: entries.length - baseSlice.length };
 }
 // The goal-stack boost touches the primary band only; the fresh-tail and summary bands keep their fixed placement.
-function rankBands(db, ctx, opts, window, limit, own) {
+function rankBands(opts, plan, reads) {
+    const { window, limit, own } = plan;
     let baseScored = window.baseSlice.map((entry, idx) => ({
         entry,
         score: Math.max(0, 1 - idx / Math.max(1, limit)),
     }));
     // Allocated only under explain, so the boost's default-path math stays byte-identical.
     const explainTrace = opts.explain ? new Map() : undefined;
-    if (opts.sessionId && !opts.goalTag) {
-        baseScored = applyGoalStackBoost(db, baseScored, {
-            sessionId: opts.sessionId,
-            tenantId: ctx.tenantId,
-            limit,
-            trace: explainTrace,
-        });
+    let goalLog = [];
+    if (plan.goalBoost && reads.goals) {
+        const boost = boostByGoals(baseScored, reads.goals, { ...plan.goalBoost, trace: explainTrace });
+        baseScored = boost.results;
+        goalLog = boost.log;
     }
-    let substituted = (opts.summarizeOverflow ?? true) && window.entries.length > limit
-        ? substituteOverflow(ctx, opts, window.entries, baseScored.map((r) => r.entry), limit, own)
-        : [];
+    let substituted = substituteOverflow(opts, plan.overflow, reads.parents, limit, own);
     let heldDropped = 0;
     if (!opts.keepHeldCopies) {
         const shownIds = new Set(dropHeldCopies([...baseScored.map((r) => r.entry), ...substituted.map((s) => s.entry)], (e) => e).map((e) => e.id));
@@ -263,7 +319,7 @@ function rankBands(db, ctx, opts, window, limit, own) {
     const baseRanked = baseScored.map((r) => baseItem(r, opts, explainTrace));
     const summaryRanked = substituted.map((s) => summaryItem(s, opts));
     const freshRanked = (opts.freshTailCount ?? 0) > 0
-        ? freshTailBand(ctx, opts, baseRanked, summaryRanked, opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)], own)
+        ? freshTailBand(opts, reads.freshRaws, baseRanked, summaryRanked, opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)], own)
         : [];
     return {
         rankedOut: [...freshRanked, ...baseRanked, ...summaryRanked],
@@ -271,28 +327,12 @@ function rankBands(db, ctx, opts, window, limit, own) {
         heldDropped,
         summarySubstitutions: substituted.length,
         freshTailAdded: freshRanked.length,
+        goalLog,
     };
 }
 // When the overflow holds 2+ children of one level-2 summary, that summary stands in for them, capped at 30% of
 // `limit`. Each one is tenant-scoped and re-checked against the scope filter; drillDown recovers the children.
-function substituteOverflow(ctx, opts, entries, baseSlice, limit, own) {
-    const overflow = entries.slice(limit);
-    const baseIds = new Set(baseSlice.map((e) => e.id));
-    const overflowByParent = new Map();
-    for (const e of overflow) {
-        const parentId = e.dag_parent_id;
-        if (!parentId)
-            continue;
-        if ((e.dag_level ?? 0) > 1)
-            continue;
-        const list = overflowByParent.get(parentId) ?? [];
-        list.push(e);
-        overflowByParent.set(parentId, list);
-    }
-    const eligibleParentIds = Array.from(overflowByParent.keys()).filter((pid) => (overflowByParent.get(pid)?.length ?? 0) >= 2 && !baseIds.has(pid));
-    if (eligibleParentIds.length === 0)
-        return [];
-    const parents = loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId);
+function substituteOverflow(opts, overflowByParent, parents, limit, own) {
     const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by && passesScopeFilterForRecall(p.scope ?? null, opts.scope, own) && inCallerProject(p, opts));
     const maxSub = Math.max(1, Math.ceil(limit * 0.3));
     // Most overflowed children first; compareEntryIdentity only breaks a tie, which used to fall to scan order.
@@ -306,6 +346,23 @@ function substituteOverflow(ctx, opts, entries, baseSlice, limit, own) {
         childIds: (overflowByParent.get(p.id) ?? []).map((e) => e.id),
     }));
 }
+/** Overflowed leaf rows by summary parent, kept only for a parent with 2+ of them that is not already in the base band. */
+function overflowGroups(window, limit) {
+    // The goal boost only re-scores the base band, so its ids are known before the boost runs.
+    const baseIds = new Set(window.baseSlice.map((e) => e.id));
+    const overflowByParent = new Map();
+    for (const e of window.entries.slice(limit)) {
+        const parentId = e.dag_parent_id;
+        if (!parentId)
+            continue;
+        if ((e.dag_level ?? 0) > 1)
+            continue;
+        const list = overflowByParent.get(parentId) ?? [];
+        list.push(e);
+        overflowByParent.set(parentId, list);
+    }
+    return new Map([...overflowByParent].filter(([pid, children]) => children.length >= 2 && !baseIds.has(pid)));
+}
 function baseItem(r, opts, explainTrace) {
     const item = {
         id: r.entry.id,
@@ -341,10 +398,8 @@ function summaryItem(s, opts) {
 }
 // The last N raw rows, so "what did I just see" always covers the recent window. A recent row already in the BM25
 // band is only tagged isFreshTail; new ones are prepended, so every recent row appears exactly once.
-function freshTailBand(ctx, opts, baseRanked, summaryRanked, shownEntries, own) {
-    // The session-id contract was already checked by recallWindowSize's preflight.
-    const recent = loadFreshRawMemories(ctx.hippoRoot, opts.freshTailCount ?? 0, ctx.tenantId, opts.freshTailSessionId, recallOrigin(opts));
-    const recentScoped = recent.filter((m) => passesScopeFilterForRecall(m.scope ?? null, opts.scope, own));
+function freshTailBand(opts, recent, baseRanked, summaryRanked, shownEntries, own) {
+    const recentScoped = recent.filter((m) => passesScopeFilterForRecall(m.scope ?? null, opts.scope, own) && inCallerProject(m, opts));
     const recentIdSet = new Set(recentScoped.map((m) => m.id));
     for (const r of baseRanked) {
         if (recentIdSet.has(r.id))
@@ -372,58 +427,32 @@ function freshTailBand(ctx, opts, baseRanked, summaryRanked, shownEntries, own)
     }
     return freshRanked;
 }
-// The audit row stores a hash of the query, never its text, so an archived memory's words cannot persist there.
-// The trace sits beside it as observability, not retrieval state; a caller that traces its own result set suppresses it.
-function auditAndTraceRecall(db, ctx, opts, rankedOut) {
-    appendAuditEvent(db, {
+// The trace is observability, not retrieval state; a caller that traces its own result set suppresses it.
+function recallTrace(ctx, opts, rankedOut) {
+    if (opts.suppressRecallTrace)
+        return undefined;
+    return {
         tenantId: ctx.tenantId,
-        actor: ctx.actor.subject,
-        op: 'recall',
-        metadata: {
-            ...auditQueryFields(opts.query),
-            results: rankedOut.length,
-        },
-    });
-    if (!opts.suppressRecallTrace) {
-        writeRecallTrace(db, {
-            tenantId: ctx.tenantId,
-            sessionId: opts.sessionId ?? null,
-            pipeline: 'api',
-            query: opts.query,
-            explainMode: opts.explain === true,
-            results: rankedOut.map((r) => ({
-                memoryId: r.id,
-                score: r.score,
-                rerankSteps: r.rerankTrace,
-            })),
-        });
-    }
+        sessionId: opts.sessionId ?? null,
+        pipeline: 'api',
+        query: opts.query,
+        explainMode: opts.explain === true,
+        results: rankedOut.map((r) => ({
+            memoryId: r.id,
+            score: r.score,
+            rerankSteps: r.rerankTrace,
+        })),
+    };
 }
-// No active snapshot means no anchor, so no handoff or events: a stale handoff from a closed session never resurfaces.
-function loadContinuity(ctx, opts, own) {
-    // On a shared store the tenant's newest row is another developer's; no project keys to nothing, so the block is empty.
-    const key = isSharedStore(ctx.hippoRoot)
-        ? { owner: ownerOrSubject(ctx.actor), project: opts.project ? projectNames(opts.project) : [] }
-        : undefined;
-    const snapshot = loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, key);
-    const sessionId = snapshot?.session_id ?? undefined;
-    const sessionHandoff = sessionId
-        ? loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, sessionId, {}, key)
-        : null;
-    const recentSessionEvents = sessionId
-        ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, { session_id: sessionId, limit: 5 })
-        : [];
-    // The memory-recall scope rule: an explicit scope must match exactly; without one, private and legacy rows are denied.
+// The memory-recall scope rule: an explicit scope must match exactly; without one, private and legacy rows are denied.
+function scopeContinuity(block, opts, own) {
     const rowScope = (r) => r?.scope ?? null;
-    const filteredSnapshot = snapshot && passesScopeFilterForRecall(rowScope(snapshot), opts.scope, own) ? snapshot : null;
-    const filteredHandoff = sessionHandoff && passesScopeFilterForRecall(rowScope(sessionHandoff), opts.scope, own) ? sessionHandoff : null;
-    const filteredEvents = recentSessionEvents.filter((e) => passesScopeFilterForRecall(rowScope(e), opts.scope, own));
-    const continuity = {
-        activeSnapshot: filteredSnapshot,
-        sessionHandoff: filteredHandoff,
-        recentSessionEvents: filteredEvents,
+    const { activeSnapshot: snapshot, sessionHandoff } = block;
+    return {
+        activeSnapshot: snapshot && passesScopeFilterForRecall(rowScope(snapshot), opts.scope, own) ? snapshot : null,
+        sessionHandoff: sessionHandoff && passesScopeFilterForRecall(rowScope(sessionHandoff), opts.scope, own) ? sessionHandoff : null,
+        recentSessionEvents: block.recentSessionEvents.filter((e) => passesScopeFilterForRecall(rowScope(e), opts.scope, own)),
     };
-    return { continuity, continuityTokens: continuityTokensOf(continuity) };
 }
 function continuityTokensOf(c) {
     const filteredSnapshot = c.activeSnapshot;
@@ -442,62 +471,26 @@ function continuityTokensOf(c) {
         tokenize(filteredHandoff?.cardId) +
         c.recentSessionEvents.reduce((acc, e) => acc + tokenize(e.content), 0);
 }
-/** One audit row on its own short-lived handle, as each bias detector writes it. */
-function appendRecallAudit(ctx, event) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        appendAuditEvent(db, { tenantId: ctx.tenantId, actor: ctx.actor.subject, ...event });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+function callerOf(ctx) {
+    return { tenantId: ctx.tenantId, actor: ctx.actor.subject };
 }
 // A pure read of the caller's recallHistory snapshot against this top-1. HIPPO_ANCHORING=off skips even the detect
 // call; CLI paths pass no history (cmdRecall computes its own hint), so the hint stays absent there.
-function detectRecallAnchoring(ctx, opts, topMemoryId) {
+function detectRecallAnchoring(opts, topMemoryId) {
     if (!biasHintEnabled('anchoring') || !opts.recallHistory)
         return { anchoringHint: null, suppressedByInterference: 0 };
     const queryHash = hashQueryText(opts.query);
     const anchoringHint = detectAnchoring(opts.recallHistory, queryHash, topMemoryId);
-    if (anchoringHint?.reason === 'memory_dominance') {
-        appendRecallAudit(ctx, {
-            op: 'recall_anchor_detected_memory_dominance',
-            targetId: anchoringHint.memoryId,
-            metadata: {
-                memory_id: anchoringHint.memoryId,
-                query_count: anchoringHint.queryCount ?? null,
-            },
-        });
-        return { anchoringHint, suppressedByInterference: 1 };
-    }
-    if (anchoringHint?.reason === 'query_repeat') {
-        appendRecallAudit(ctx, {
-            op: 'recall_anchor_detected_query_repeat',
-            targetId: anchoringHint.memoryId,
-            metadata: { memory_id: anchoringHint.memoryId },
-        });
-    }
-    return { anchoringHint, suppressedByInterference: 0 };
+    return { anchoringHint, suppressedByInterference: anchoringHint?.reason === 'memory_dominance' ? 1 : 0 };
 }
 // Compares the returned top-K's ages with the scope-filtered pool it came from, never `all`, whose hidden rows would
 // leak pool shape. A soft warning only; HIPPO_AVAILABILITY=off or a caller computing its own hint skips it.
-function detectRecallAvailability(ctx, opts, baseSlice, entries) {
+function detectRecallAvailability(opts, baseSlice, entries) {
     if (!biasHintEnabled('availability') || opts.suppressAvailabilityHint)
         return null;
-    const availabilityHint = detectAvailabilityBias({
+    return detectAvailabilityBias({
         topK: baseSlice.map((e) => ({ id: e.id, created: e.created })),
         pool: entries.map((e) => ({ id: e.id, created: e.created })),
     });
-    if (availabilityHint) {
-        appendRecallAudit(ctx, {
-            op: 'recall_availability_detected',
-            metadata: {
-                recent_fraction: availabilityHint.recentFraction,
-                older_passed_over: availabilityHint.olderCandidatesPassedOver,
-                returned_count: availabilityHint.returnedCount,
-            },
-        });
-    }
-    return availabilityHint;
 }
 //# sourceMappingURL=recall.js.map

package/dist/api/tokens.d.ts

@@ -10,7 +10,7 @@ export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
     items: number;
     tokens: number;
     sessionId?: string | null;
-}): void;
+}): Promise<void>;
 /**
  * Token ledger totals for the tenant over the last `days` days (default 30):
  * tokens sent, skipped as unchanged and re-read by later model calls, per

package/dist/api/tokens.js

@@ -1,6 +1,7 @@
 // Token-use and failure reports.
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { recordTokenUse, summarizeTokenUse } from '../token-ledger.js';
+import { openHippoDb, closeHippoDb, rethrowIfSqliteBlocked } from '../db.js';
+import { summarizeTokenUse } from '../token-ledger.js';
+import { storeFor } from '../store-port.js';
 import { summarizeFailures } from '../failure-log.js';
 import { log } from '../log.js';
 /**
@@ -8,24 +9,19 @@ import { log } from '../log.js';
  * Best-effort: never throws, because a ledger failure must not fail the
  * recall or context call that produced the text.
  */
-export function recordTokens(ctx, surface, use) {
+export async function recordTokens(ctx, surface, use) {
     try {
-        const db = openHippoDb(ctx.hippoRoot);
-        try {
-            recordTokenUse(db, {
-                tenantId: ctx.tenantId,
-                sessionId: use.sessionId ?? null,
-                surface,
-                event: 'inject',
-                items: use.items,
-                tokens: use.tokens,
-            });
-        }
-        finally {
-            closeHippoDb(db);
-        }
+        await storeFor(ctx).recordTokens({
+            tenantId: ctx.tenantId,
+            sessionId: use.sessionId ?? null,
+            surface,
+            event: 'inject',
+            items: use.items,
+            tokens: use.tokens,
+        });
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         log.warnThenDebug('api-token-ledger', `token ledger write failed; the reply is unaffected: ${err instanceof Error ? err.message : String(err)}`);
     }
 }

package/dist/cli/maintenance.d.ts

@@ -1,4 +1,5 @@
+import { type EmbeddingProvider } from '../embedding-provider.js';
 export declare function cmdRefine(hippoRoot: string, flags: Record<string, string | boolean | string[]>): Promise<void>;
 export declare function cmdDedup(hippoRoot: string, flags: Record<string, string | boolean | string[]>): void;
-export declare function cmdEmbed(hippoRoot: string, flags: Record<string, string | boolean | string[]>): Promise<void>;
+export declare function cmdEmbed(hippoRoot: string, flags: Record<string, string | boolean | string[]>, given?: EmbeddingProvider): Promise<void>;
 //# sourceMappingURL=maintenance.d.ts.map