hippo-memory 1.61.0 → 1.62.0

package/dist/api/context.js

@@ -1,31 +1,29 @@
 // Ambient context injection: the admission policy and getContext.
-import { openHippoDb, closeHippoDb } from '../db.js';
 import { isInitialized } from '../store/open.js';
 import { strengthenRetrieved } from '../store/entry-writes.js';
-import { loadRecallSearchEntries, recallScopeFilter } from '../store/search-rows.js';
+import { loadRecallSearchEntries } from '../store/search-rows.js';
+import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
 import { loadAmbientCandidates, loadContextCandidates, } from '../store/candidates.js';
 import { loadIndex, saveIndex, updateStats } from '../store/index-and-stats.js';
 import { loadFreshActiveTaskSnapshot, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS } from '../store/sessions.js';
 import { loadLatestHandoff } from '../store/handoffs.js';
 import { estimateTokens } from '../token-ledger.js';
-import { calculateStrength, markRetrieved, COMPACTION_MEMORY_TAG } from '../memory.js';
-import { appendAuditEvent, auditQueryFields, isContentWorthStoring } from '../audit.js';
-import { getGlobalRoot, searchBothHybrid } from '../shared.js';
+import { markRetrieved, COMPACTION_MEMORY_TAG } from '../memory.js';
+import { isContentWorthStoring } from '../audit.js';
+import { getGlobalRoot } from '../shared.js';
 import { writeRecallTraceAtRoot } from '../recall-trace.js';
 import { evalNow, isRecallBoostAblated } from '../ablation.js';
-import { hybridSearch } from '../search/hybrid.js';
-import { physicsSearch } from '../search/physics-search.js';
-import { compareScoredResults } from '../compare.js';
 import { dropHeldCopies } from '../same-text.js';
-import { scopeMatch } from '../scope.js';
 import { loadConfig } from '../config.js';
 import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot } from '../project-identity.js';
-import { promptTokens, contentTokens, gatePromptRecall, } from '../prompt-recall.js';
+import { promptTokens } from '../prompt-recall.js';
 import { detectSecret } from '../secret-detect.js';
 import { isSessionDigestRow } from '../session-digest.js';
 import { addAmbientTallies, ambientStateFromTallies } from '../ambient.js';
 import { loadAmbientTallies } from '../ambient-store.js';
 import { passesScopeFilterForRecall, assertScopeRequestAllowed } from '../recall-scope.js';
+import { finiteOr, selectBySearch, selectPinned, selectStrongest, } from './context-select.js';
+export { oneCopyPerMemory } from './context-select.js';
 /**
  * v39: the single ambient-injection admission policy, shared by getContext
  * and the CLI-side ambient-state summary so the two cannot drift.
@@ -67,7 +65,7 @@ export const CONTEXT_CANDIDATE_CAP = 2000;
 function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admit, window, recall, onQualityDrop) {
     if (!pinnedOnly) {
         const rows = 'query' in window
-            ? loadRecallSearchEntries(hippoRoot, window.query, CONTEXT_CANDIDATE_CAP, tenantId, window.exactScope, 'exact', false)
+            ? loadRecallSearchEntries(hippoRoot, window.query, DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, window.exactScope, 'exact', false, window.project)
             : loadContextCandidates(hippoRoot, tenantId, window);
         return { entries: rows.filter(admit) };
     }
@@ -83,27 +81,6 @@ function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admi
     };
     return loadAmbientCandidates(hippoRoot, tenantId, includeRecent, admitAmbient, recall);
 }
-// Share and promote copy a memory to the global store under a new id, so equal content is the only link.
-// A pinned copy wins, then the stronger one after the ranking's own global discount; a tie keeps the local copy.
-export function oneCopyPerMemory(local, global, now) {
-    const score = (e, isGlobal) => calculateStrength(e, now) * (isGlobal ? 1 / 1.2 : 1);
-    const best = new Map();
-    const offer = (entry, isGlobal) => {
-        const held = best.get(entry.content);
-        const wins = !held || (held.entry.pinned !== entry.pinned
-            ? entry.pinned
-            : score(entry, isGlobal) > score(held.entry, held.isGlobal));
-        if (wins)
-            best.set(entry.content, { entry, isGlobal });
-    };
-    for (const e of local)
-        offer(e, false);
-    for (const e of global)
-        offer(e, true);
-    const kept = new Set([...best.values()].map((b) => b.entry));
-    return [local.filter((e) => kept.has(e)), global.filter((e) => kept.has(e))];
-}
-const finiteOr = (v, dflt, min) => Number.isFinite(v) && v >= min ? v : dflt;
 /**
  * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
  * fallback / hybrid search) + active task snapshot + session handoff + recent
@@ -117,77 +94,134 @@ const finiteOr = (v, dflt, min) => Number.isFinite(v) && v >= min ? v : dflt;
  * Tenant scope: all `loadAllEntries` / snapshot / handoff / events reads use
  * `ctx.tenantId`. Cross-tenant rows are filtered out.
  *
- * Returns an empty result (`entries: []`, snapshot/handoff/events undefined)
+ * @returns An empty result (`entries: []`, snapshot/handoff/events undefined)
  * when there's nothing to surface (no memories AND no snapshot AND no handoff
  * AND no recent events).
  */
 export async function getContext(ctx, opts = {}) {
-    const pinnedOnly = opts.pinnedOnly === true;
     const budget = opts.budget ?? 1500;
-    const limit = opts.limit ?? Number.POSITIVE_INFINITY;
-    const includeRecent = opts.includeRecent ?? 0;
-    const activeScope = opts.scope ?? '';
     assertScopeRequestAllowed(ctx.actor, opts.exactScope);
-    const exactScope = opts.exactScope || undefined;
     if (budget <= 0) {
         return { entries: [], tokens: 0 };
     }
+    const plan = planContext(ctx, opts);
+    const sections = loadTaskSections(ctx, opts, plan, openBlockBudget(plan, opts, budget));
+    const admission = ambientAdmission(opts, plan, sections.shownHandoff);
+    const pools = loadPools(ctx, plan, admission, promptRecallRequest(opts, plan));
+    const noSections = !sections.shownSnapshot && !sections.shownHandoff && sections.shownEvents.length === 0;
+    if (!plan.promptRecallPending && pools.local.entries.length === 0 && pools.global.entries.length === 0 && noSections) {
+        return { entries: [], tokens: 0 };
+    }
+    const picked = plan.pinnedOnly
+        ? selectPinned(ctx, opts, plan, sections.left, pools, admission)
+        : plan.query === '*'
+            ? selectStrongest(plan, sections.left, pools)
+            : await selectBySearch(ctx, plan, sections.left, pools, admission);
+    if (picked === null) {
+        return { entries: [], tokens: 0 };
+    }
+    const { items, tokens } = finalizeSelection(picked, plan);
+    if (items.length === 0 && noSections) {
+        // A query that found nothing is the coverage-gap signal, so it still gets a trace; pinned-only stays read-only.
+        if (!plan.pinnedOnly)
+            traceEmptyContext(ctx, opts, plan.query);
+        return { entries: [], tokens: 0 };
+    }
+    // pinnedOnly is the UserPromptSubmit hot path — read-only so pinned
+    // memories don't inflate retrieval_count or extend half_life every turn.
+    const recorded = plan.pinnedOnly
+        ? { items, ambientState: undefined }
+        : recordRetrieval(ctx, opts, plan, items, sections.activeSnapshot);
+    return {
+        entries: recorded.items,
+        tokens,
+        activeSnapshot: sections.shownSnapshot ?? undefined,
+        sessionHandoff: sections.shownHandoff ?? undefined,
+        recentEvents: sections.shownEvents.length > 0 ? sections.shownEvents : undefined,
+        ambientState: recorded.ambientState,
+    };
+}
+function planContext(ctx, opts) {
+    const pinnedOnly = opts.pinnedOnly === true;
     // Global memories do not establish a project boundary for task state.
     const hasLocal = isInitialized(ctx.hippoRoot);
     const query = (opts.q ?? '').trim() || '*';
     const globalRoot = getGlobalRoot();
     const hasGlobal = isInitialized(globalRoot);
     const primaryIsGlobal = isGlobalStoreRoot(ctx.hippoRoot);
-    const hasLocalTaskState = hasLocal && !primaryIsGlobal;
-    // v39 memory scope isolation (docs/plans/2026-07-01-memory-scope-isolation.md).
-    // S2: envelope-filter parity with api.recall; opts.scope is only the tag boost, opts.exactScope the envelope request.
-    // S3: origin partition - other-project memories are excluded unless the
-    // caller explicitly asks for them (crossProject) or isolation is disabled.
+    // opts.scope is only the tag boost, opts.exactScope the envelope request; other-project memories are
+    // excluded unless the caller asks for them (crossProject) or isolation is disabled.
     const config = loadConfig(ctx.hippoRoot);
     const isolationEnabled = config.contextProjectIsolation !== false;
     const currentProjectName = opts.currentProject ?? resolveProjectIdentity(process.cwd()).name;
     const includeCrossProject = opts.crossProject === true || !isolationEnabled;
-    // Z1: decided before the ambient loads so the FTS candidate query below (pinned-only
-    // branch) can piggyback on that connection instead of opening its own.
+    // Decided before the ambient loads so the pinned-only FTS candidate query can share their connection.
     const promptRecallPending = pinnedOnly && Boolean(opts.prompt?.trim()) && config.pinnedInject.promptRecall === true;
-    const promptRecallTerms = promptRecallPending && config.pinnedInject.enabled
-        ? Array.from(promptTokens(opts.prompt ?? ''))
-        : [];
-    const recallRequest = promptRecallTerms.length > 0
-        ? { terms: promptRecallTerms, limit: Math.floor(finiteOr(config.pinnedInject.promptRecallCandidates, 100, 1)) }
-        : undefined;
     const cost = opts.cost;
     const price = (entry, isGlobal, promptRecall) => cost
         ? cost.entry({ entry, isGlobal, promptRecall, origin: entry.origin_project ?? null, category: classifyOriginProject(entry.origin_project, currentProjectName) })
         : estimateTokens(entry.content);
+    return {
+        pinnedOnly,
+        limit: opts.limit ?? Number.POSITIVE_INFINITY,
+        includeRecent: opts.includeRecent ?? 0,
+        activeScope: opts.scope ?? '',
+        exactScope: opts.exactScope || undefined,
+        query,
+        hasLocal,
+        hasGlobal,
+        globalRoot,
+        primaryIsGlobal,
+        hasLocalTaskState: hasLocal && !primaryIsGlobal,
+        config,
+        currentProjectName,
+        includeCrossProject,
+        originProject: includeCrossProject || currentProjectName === '' ? undefined : currentProjectName,
+        promptRecallPending,
+        cost,
+        price,
+        obs: opts.deliveryObserver,
+    };
+}
+/** The prompt-recall candidate request the ambient loads carry, when the prompt has any terms. */
+function promptRecallRequest(opts, plan) {
+    const { pinnedInject } = plan.config;
+    const promptRecallTerms = plan.promptRecallPending && pinnedInject.enabled
+        ? Array.from(promptTokens(opts.prompt ?? ''))
+        : [];
+    return promptRecallTerms.length > 0
+        ? { terms: promptRecallTerms, limit: Math.floor(finiteOr(pinnedInject.promptRecallCandidates, 100, 1)) }
+        : undefined;
+}
+/** Reports the block's facts to the observer and returns the budget left after the fixed headers. */
+function openBlockBudget(plan, opts, budget) {
+    const { config, cost, obs, pinnedOnly, promptRecallPending } = plan;
     const blockBudget = pinnedOnly && opts.budget === undefined ? config.pinnedInject.budget : budget;
-    const obs = opts.deliveryObserver;
-    obs?.facts({ projectName: currentProjectName, budgetTokens: blockBudget, promptRecall: promptRecallPending });
+    obs?.facts({ projectName: plan.currentProjectName, budgetTokens: blockBudget, promptRecall: promptRecallPending });
     if (pinnedOnly && !config.pinnedInject.enabled)
         obs?.disabled();
-    let left = cost
-        ? Math.max(0, blockBudget - cost.fixed(blockBudget, { cross: includeCrossProject, promptRecall: promptRecallPending, ambient: !pinnedOnly && config.ambient.enabled }))
+    return cost
+        ? Math.max(0, blockBudget - cost.fixed(blockBudget, { cross: plan.includeCrossProject, promptRecall: promptRecallPending, ambient: !pinnedOnly && config.ambient.enabled }))
         : blockBudget;
-    // Sections print ahead of the memories, so they are paid first; one that does not fit is dropped, as an oversize entry is.
+}
+// Sections print ahead of the memories, so they are paid first; one that does not fit is dropped, as an oversize entry is.
+function loadTaskSections(ctx, opts, plan, startLeft) {
+    const { exactScope, hasLocalTaskState, cost } = plan;
+    let left = startLeft;
     const pays = (tokens) => {
         if (tokens > left)
             return false;
         left -= tokens;
         return true;
     };
-    // DF1 T2: bounded read — an orphaned snapshot (no later pre-compact
-    // superseded it, no session-end closed it) must age out of this ambient
-    // surface instead of injecting into every future prompt forever. Owner
-    // reads (opts.currentSessionId matches the snapshot's session_id) stay
-    // unbounded; see loadFreshActiveTaskSnapshot's own doc comment for the
-    // exact null/empty-id matching rules.
+    // Bounded read: an orphaned snapshot ages out of this ambient surface; the owner session's read stays unbounded.
     const rowScope = (r) => r?.scope ?? null;
     const rawActiveSnapshot = hasLocalTaskState
         ? loadFreshActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, {
             sessionId: opts.currentSessionId,
         })
         : null;
-    // W1: the same envelope rule ambientAdmitEntry applies to memory rows.
+    // The same envelope rule ambientAdmitEntry applies to memory rows.
     const activeSnapshot = rawActiveSnapshot && passesScopeFilterForRecall(rowScope(rawActiveSnapshot), exactScope)
         ? rawActiveSnapshot
         : null;
@@ -199,7 +233,7 @@ export async function getContext(ctx, opts = {}) {
             : loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, undefined, {
                 unfinishedOnly: true,
                 maxAgeMs: SNAPSHOT_AMBIENT_MAX_AGE_MS,
-                // codex P2: admit scope in SQL so a newer denied row can't hide an older eligible one before LIMIT 1.
+                // Scope is admitted in SQL so a newer denied row can't hide an older eligible one before LIMIT 1.
                 scopeFilter: 'default-deny',
             });
     const sessionHandoff = rawSessionHandoff && passesScopeFilterForRecall(rowScope(rawSessionHandoff), exactScope)
@@ -215,7 +249,10 @@ export async function getContext(ctx, opts = {}) {
     const shownSnapshot = activeSnapshot && (!cost || pays(cost.snapshot(activeSnapshot))) ? activeSnapshot : null;
     const shownHandoff = sessionHandoff && (!cost || pays(cost.handoff(sessionHandoff))) ? sessionHandoff : null;
     const shownEvents = recentSessionEvents.length > 0 && (!cost || pays(cost.trail(recentSessionEvents))) ? recentSessionEvents : [];
-    obs?.sections(Number(shownSnapshot !== null) + Number(shownHandoff !== null) + Number(shownEvents.length > 0), Number(activeSnapshot !== shownSnapshot) + Number(sessionHandoff !== shownHandoff) + Number(recentSessionEvents.length !== shownEvents.length));
+    plan.obs?.sections(Number(shownSnapshot !== null) + Number(shownHandoff !== null) + Number(shownEvents.length > 0), Number(activeSnapshot !== shownSnapshot) + Number(sessionHandoff !== shownHandoff) + Number(recentSessionEvents.length !== shownEvents.length));
+    return { activeSnapshot, shownSnapshot, shownHandoff, shownEvents, left };
+}
+function ambientAdmission(opts, plan, shownHandoff) {
     const transcriptHandoffSession = shownHandoff?.evidence?.derivedFrom === 'transcript' ? shownHandoff.sessionId : null;
     let digestHiddenForHandoff = false;
     const ambientAdmit = (e) => {
@@ -224,7 +261,7 @@ export async function getContext(ctx, opts = {}) {
             digestHiddenForHandoff = true;
             return false;
         }
-        return ambientAdmitEntry(e, currentProjectName, includeCrossProject, exactScope);
+        return ambientAdmitEntry(e, plan.currentProjectName, plan.includeCrossProject, plan.exactScope);
     };
     const ownSessionId = opts.currentSessionId || '';
     // Inside admit, not after the load, so the loader's window widens past a session's own items.
@@ -233,473 +270,109 @@ export async function getContext(ctx, opts = {}) {
         e.tags.includes(COMPACTION_MEMORY_TAG);
     // Superseded rows never inject; which rows reach ambientAdmitEntry matters because it regex-scans content for secrets.
     const admit = (e) => !e.superseded_by && !isOwnCompactionItem(e) && ambientAdmit(e);
-    const loadAdmit = obs ? obs.watchAdmit(admit) : admit;
-    const qualityDrop = (isGlobal) => obs && !promptRecallPending ? (e) => obs.qualityDropped(e, isGlobal) : undefined;
+    // The two-store search has always ranked a session's own compaction items; only the local search drops them.
+    const bothStoresAdmit = (e) => !e.superseded_by && ambientAdmit(e);
+    return { ambientAdmit, admit, bothStoresAdmit, digestHidden: () => digestHiddenForHandoff };
+}
+function loadPools(ctx, plan, admission, recallRequest) {
+    const { obs, pinnedOnly, primaryIsGlobal, hasGlobal, exactScope } = plan;
+    const searches = plan.query !== '*' && !pinnedOnly;
+    const searchesBoth = searches && hasGlobal && !primaryIsGlobal;
+    const poolAdmit = searchesBoth ? admission.bothStoresAdmit : admission.admit;
+    const loadAdmit = obs ? obs.watchAdmit(poolAdmit) : poolAdmit;
+    const qualityDrop = (isGlobal) => obs && !plan.promptRecallPending ? (e) => obs.qualityDropped(e, isGlobal) : undefined;
     // The window's predicates are ones admit applies anyway, so below the cap the admitted rows are unchanged.
-    const searchesLocalRows = query !== '*' && !(hasGlobal && !primaryIsGlobal);
-    const originProject = includeCrossProject || currentProjectName === '' ? undefined : currentProjectName;
-    const window = searchesLocalRows && !pinnedOnly
-        ? { query, exactScope }
+    const window = searches
+        ? { query: plan.query, exactScope, project: plan.originProject }
         : {
             exactScope,
-            project: originProject,
+            project: plan.originProject,
             cap: CONTEXT_CANDIDATE_CAP,
             now: evalNow(),
         };
-    // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
-    const localLoad = hasLocal
-        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, loadAdmit, window, recallRequest, qualityDrop(primaryIsGlobal))
+    // Tenant-scoped loads: never resolveTenantId({}) here.
+    const local = plan.hasLocal
+        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, plan.includeRecent, loadAdmit, window, recallRequest, qualityDrop(primaryIsGlobal))
         : { entries: [] };
-    const globalLoad = hasGlobal && !primaryIsGlobal
-        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, loadAdmit, window, recallRequest, qualityDrop(true))
+    const global = hasGlobal && !primaryIsGlobal
+        ? loadAmbientEntries(plan.globalRoot, ctx.tenantId, pinnedOnly, plan.includeRecent, loadAdmit, window, recallRequest, qualityDrop(true))
         : { entries: [] };
-    let localEntries = localLoad.entries;
-    let globalEntries = globalLoad.entries;
-    // Computed after markRetrieved runs, so avgStrength reflects post-retrieval strengths.
-    let ambientState;
-    if (!promptRecallPending &&
-        localEntries.length === 0 &&
-        globalEntries.length === 0 &&
-        !shownSnapshot &&
-        !shownHandoff &&
-        shownEvents.length === 0) {
-        return { entries: [], tokens: 0 };
-    }
-    let selectedItems = [];
-    let totalTokens = 0;
-    if (pinnedOnly) {
-        // loadConfig is safe even when local isn't initialised — returns defaults.
-        const pinnedCfg = loadConfig(ctx.hippoRoot);
-        if (!pinnedCfg.pinnedInject.enabled) {
-            return { entries: [], tokens: 0 };
-        }
-        // Effective budget: explicit opts.budget wins over config, less what the sections took.
-        const effBudget = left;
-        const nowP = evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
-        obs?.offer(localEntries, primaryIsGlobal);
-        obs?.offer(globalEntries, true);
-        const [localPool, globalPool] = oneCopyPerMemory(localEntries, globalEntries, nowP);
-        obs?.dropMissing([...localEntries, ...globalEntries], [...localPool, ...globalPool], 'load', 'duplicate');
-        const selectedIds = new Set();
-        let usedP = 0;
-        // Pinned entries are explicit user intent, the recent-N list an automatic
-        // backfill. Both loops share ONE budget and the recent loop runs first, so
-        // pins are ranked here and reserve their share before it can spend.
-        const pinnedLocal = localPool.filter((e) => e.pinned);
-        const pinnedGlobal = globalPool.filter((e) => e.pinned);
-        const rankedPinned = [
-            ...pinnedLocal.map((e) => ({ entry: e, isGlobal: primaryIsGlobal })),
-            ...pinnedGlobal.map((e) => ({ entry: e, isGlobal: true })),
-        ]
-            .map(({ entry, isGlobal }) => {
-            const scopeSig = scopeMatch(entry.tags, activeScope);
-            const sBst = scopeSig === 1 ? 1.5 : scopeSig === -1 ? 0.5 : 1.0;
-            return {
-                entry,
-                score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1) * sBst,
-                tokens: price(entry, isGlobal),
-                isGlobal,
-            };
-        })
-            .sort(compareScoredResults);
-        // Mirror the pinned admission loop's own `continue`-not-`break`
-        // semantics (further down) so the reserve equals what that loop will
-        // actually admit -- a big pin near the front should not block smaller
-        // pins behind it from reserving their share too.
-        // Dedupe by id: `syncGlobalToLocal` copies global rows into the local
-        // store preserving `entry.id`, so a synced pin appears in BOTH
-        // `pinnedLocal` and `pinnedGlobal` and would otherwise reserve its cost
-        // twice. The admission loop already dedupes via `selectedIds`; the
-        // reserve has to mirror that or it silently starves recents of budget a
-        // single returned pin never needed.
-        let pinnedReserve = 0;
-        const reservedIds = new Set();
-        for (const r of rankedPinned) {
-            if (reservedIds.has(r.entry.id))
-                continue;
-            if (pinnedReserve + r.tokens <= effBudget) {
-                pinnedReserve += r.tokens;
-                reservedIds.add(r.entry.id);
-            }
-        }
-        // Known, accepted tradeoff: a pin that also lands in the recent-N slice
-        // is counted once in `pinnedReserve` (here) AND admitted again by the
-        // recent loop below, so a little budget goes unused (`recentBudget` is
-        // more conservative than it needs to be in that case). That only
-        // under-fills recents slightly -- it never displaces a pin -- so it is
-        // the safe direction and is not worth extra bookkeeping to recover.
-        const recentBudget = Math.max(0, effBudget - pinnedReserve);
-        // Z1: gate the backfill on the prompt instead of recency (docs/plans/2026-09-26-z1-prompt-recall.md).
-        const promptRecallOn = promptRecallPending;
-        if (promptRecallOn) {
-            const rawMetric = pinnedCfg.pinnedInject.promptRecallMetric;
-            const metric = rawMetric === 'cosine' ? 'cosine' : 'jaccard';
-            const gate = {
-                metric,
-                threshold: finiteOr(pinnedCfg.pinnedInject.promptRecallThreshold, 0.04, 0),
-                minShared: finiteOr(pinnedCfg.pinnedInject.promptRecallMinShared, 2, 0),
-                maxItems: finiteOr(pinnedCfg.pinnedInject.promptRecallMaxItems, 5, 1),
-            };
-            const p = promptTokens(opts.prompt ?? '');
-            if (p.size > 0) {
-                // Candidates came off the ambient load's own connection (recallRequest above), not a fresh open.
-                // A candidate carrying a pin's text would inject that memory a second time.
-                const pinnedText = new Set(rankedPinned.map((r) => r.entry.content));
-                const ineligibleReason = (e) => !admit(e) ? 'scope'
-                    : e.pinned ? 'pinned'
-                        : !isContentWorthStoring(e.content) ? 'quality'
-                            : pinnedText.has(e.content) ? 'duplicate'
-                                : null;
-                const eligible = (e) => {
-                    const why = ineligibleReason(e);
-                    if (why !== null && why !== 'pinned')
-                        obs?.reject(e, 'eligible', why);
-                    return why === null;
-                };
-                obs?.offer(localLoad.recall ?? [], primaryIsGlobal, 'prompt-recall');
-                obs?.offer(globalLoad.recall ?? [], true, 'prompt-recall');
-                const localEligible = (localLoad.recall ?? []).filter(eligible);
-                const globalEligible = (globalLoad.recall ?? []).filter(eligible);
-                const [localCandidates, globalCandidates] = oneCopyPerMemory(localEligible, globalEligible, nowP);
-                obs?.dropMissing([...localEligible, ...globalEligible], [...localCandidates, ...globalCandidates], 'eligible', 'duplicate');
-                const seenCandidateIds = new Set();
-                const candidateItems = [];
-                // Local wins the id collision (a global row synced into the local store).
-                for (const e of localCandidates) {
-                    if (seenCandidateIds.has(e.id))
-                        continue;
-                    seenCandidateIds.add(e.id);
-                    candidateItems.push({ id: e.id, tokens: contentTokens(e.content), entry: e, isGlobal: primaryIsGlobal });
-                }
-                for (const e of globalCandidates) {
-                    if (seenCandidateIds.has(e.id))
-                        continue;
-                    seenCandidateIds.add(e.id);
-                    candidateItems.push({ id: e.id, tokens: contentTokens(e.content), entry: e, isGlobal: true });
-                }
-                const gated = gatePromptRecall(p, candidateItems, gate);
-                obs?.gated(p, candidateItems, gate, gated);
-                for (const g of gated) {
-                    if (selectedIds.has(g.item.id))
-                        continue;
-                    const tokens = price(g.item.entry, g.item.isGlobal, true);
-                    if (usedP + tokens > recentBudget) {
-                        obs?.reject(g.item.entry, 'budget', 'budget', g.score, tokens);
-                        continue;
-                    }
-                    selectedItems.push({ entry: g.item.entry, score: g.score, tokens, isGlobal: g.item.isGlobal, promptRecall: true });
-                    selectedIds.add(g.item.id);
-                    usedP += tokens;
-                }
-            }
-        }
-        else if (includeRecent > 0) {
-            const recent = [
-                ...localPool.map((entry) => ({ entry, isGlobal: primaryIsGlobal })),
-                ...globalPool.map((entry) => ({ entry, isGlobal: true })),
-            ]
-                // T2 (src/compare.ts) note: this already carries an explicit
-                // per-instance tiebreak (created desc -> id localeCompare) and is
-                // deliberately left as-is rather than routed through
-                // compareEntryIdentity. `created` reflects ingest order, so it is
-                // cross-ingest stable at ms granularity; the residual is honest,
-                // not silently ignored — rows created in the same millisecond fall
-                // to `id.localeCompare`, which is per-instance random (id is
-                // crypto.randomUUID()), so this listing is per-instance-
-                // deterministic but NOT cross-ingest-stable under same-ms
-                // collisions.
-                .sort((a, b) => {
-                const byCreated = Date.parse(b.entry.created) - Date.parse(a.entry.created);
-                return byCreated !== 0 ? byCreated : b.entry.id.localeCompare(a.entry.id);
-            })
-                // DF3 (docs/plans/2026-08-23-df3-include-recent-quality-floor.md):
-                // filter before slice, not after — the caller asked for N recent
-                // *useful* entries, so a junk row must be skipped and backfilled
-                // past, not counted against the N. Skip-only: no mutation, no audit
-                // row, nothing becomes unrecoverable.
-                //
-                // `entry.pinned ||` bypass IS needed here (codex review finding,
-                // corrects the earlier claim in this comment that it wasn't): under
-                // budget pressure, a pinned entry that fails the heuristic gets
-                // dropped from this recent slice, and an unpinned entry backfills
-                // into its slot and consumes `usedP` in the loop below. By the time
-                // the pinned block runs (further down), the budget it needed is
-                // already spent, so it hits `continue` and the pinned entry is
-                // omitted entirely — the pinned block is NOT a safety net once the
-                // recent loop has already spent the shared budget.
-                .filter(({ entry }) => entry.pinned || isContentWorthStoring(entry.content))
-                .slice(0, includeRecent)
-                .map(({ entry, isGlobal }) => ({
-                entry,
-                score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1),
-                tokens: price(entry, isGlobal),
-                isGlobal,
-            }));
-            for (const r of recent) {
-                if (selectedIds.has(r.entry.id))
-                    continue;
-                if (usedP + r.tokens > recentBudget) {
-                    obs?.reject(r.entry, 'budget', 'budget', r.score, r.tokens);
-                    continue;
-                }
-                selectedItems.push(r);
-                selectedIds.add(r.entry.id);
-                usedP += r.tokens;
-            }
-        }
-        if (pinnedLocal.length === 0 &&
-            pinnedGlobal.length === 0 &&
-            selectedItems.length === 0 &&
-            !digestHiddenForHandoff) {
-            return { entries: [], tokens: 0 };
-        }
-        for (const r of rankedPinned) {
-            if (selectedIds.has(r.entry.id))
-                continue;
-            if (usedP + r.tokens > effBudget) {
-                obs?.reject(r.entry, 'budget', 'budget', r.score, r.tokens);
-                continue;
-            }
-            selectedItems.push(r);
-            selectedIds.add(r.entry.id);
-            usedP += r.tokens;
-        }
-        totalTokens = usedP;
-    }
-    else if (query === '*') {
-        // No query: return strongest memories by strength, up to budget.
-        const now = evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
-        const [localPool, globalPool] = oneCopyPerMemory(localEntries, globalEntries, now);
-        const localRanked = localPool
-            .map((e) => ({
-            entry: e,
-            score: calculateStrength(e, now),
-            tokens: price(e, primaryIsGlobal),
-            isGlobal: primaryIsGlobal,
-        }))
-            .sort(compareScoredResults);
-        const globalRanked = globalPool
-            .map((e) => ({
-            entry: e,
-            score: calculateStrength(e, now) * (1 / 1.2),
-            tokens: price(e, true),
-            isGlobal: true,
-        }))
-            .sort(compareScoredResults);
-        const combined = [...localRanked, ...globalRanked].sort(compareScoredResults);
-        let used = 0;
-        for (const r of combined) {
-            if (used + r.tokens > left)
-                continue;
-            selectedItems.push(r);
-            used += r.tokens;
-        }
-        totalTokens = used;
-    }
-    else {
-        // Real query: hybrid search (global + local) or physics+hybrid (local only).
-        let results;
-        const minResults = cost ? 0 : undefined; // a priced block skips an oversize top hit too, so the budget bounds it
-        if (hasGlobal && !primaryIsGlobal) {
-            // searchBothHybrid loads from the store roots itself, so the ambient
-            // filter above never saw its candidates. Admission runs INSIDE the
-            // search via the opt-in entryFilter, BEFORE ranking, cross-store
-            // content-dedupe, and budgeting - a post-filter instead would let an
-            // excluded row saturate the budget (codex rounds 1+3) or shadow its
-            // admitted duplicate in the dedupe pass (codex round 4). Recall paths
-            // never set entryFilter, so their behavior is unchanged.
-            const localIndex = loadIndex(ctx.hippoRoot);
-            const isGlobalHit = (e) => !localIndex.entries[e.id];
-            const merged = await searchBothHybrid(query, ctx.hippoRoot, globalRoot, {
-                budget: left,
-                minResults,
-                cost: cost && ((r) => price(r.entry, isGlobalHit(r.entry))),
-                scope: activeScope,
-                tenantId: ctx.tenantId,
-                entryFilter: ambientAdmit,
-            });
-            results = merged.map((r) => ({
-                entry: r.entry,
-                score: r.score,
-                tokens: price(r.entry, isGlobalHit(r.entry)),
-                isGlobal: isGlobalHit(r.entry),
-            }));
-        }
-        else {
-            const ctxConfig = loadConfig(ctx.hippoRoot);
-            const usePhysicsCtx = ctxConfig.physics?.enabled !== false;
-            const localCost = cost && ((r) => price(r.entry, primaryIsGlobal));
-            const vectorCandidates = {
-                tenantId: ctx.tenantId, scope: recallScopeFilter(exactScope, 'exact'), includeSuperseded: false, admit,
-            };
-            const ctxResults = usePhysicsCtx
-                ? await physicsSearch(query, localEntries, {
-                    budget: left,
-                    minResults,
-                    cost: localCost,
-                    hippoRoot: ctx.hippoRoot,
-                    physicsConfig: ctxConfig.physics,
-                    scope: activeScope,
-                    vectorCandidates,
-                })
-                : await hybridSearch(query, localEntries, {
-                    budget: left,
-                    minResults,
-                    cost: localCost,
-                    hippoRoot: ctx.hippoRoot,
-                    scope: activeScope,
-                    vectorCandidates,
-                });
-            results = ctxResults.map((r) => ({
-                entry: r.entry,
-                score: r.score,
-                tokens: price(r.entry, primaryIsGlobal),
-                isGlobal: primaryIsGlobal,
-            }));
-        }
-        selectedItems = results;
-        totalTokens = results.reduce((sum, r) => sum + r.tokens, 0);
-        // A5 H4: emit recall audit row for context-mode searches (matches the
-        // 'recall' op emitted by api.recall for parity). pinnedOnly + '*' fallback
-        // never hit the search engines, so they don't emit (matches cmdContext).
-        const ctxRecallMetadata = {
-            ...auditQueryFields(query),
-            results: selectedItems.length,
-            mode: 'context',
-        };
-        if (hasLocal) {
-            const localDb = openHippoDb(ctx.hippoRoot);
-            try {
-                appendAuditEvent(localDb, {
-                    tenantId: ctx.tenantId,
-                    actor: ctx.actor.subject,
-                    op: 'recall',
-                    metadata: ctxRecallMetadata,
-                });
-            }
-            finally {
-                closeHippoDb(localDb);
-            }
-        }
-        if (hasGlobal && !primaryIsGlobal) {
-            const globalDb = openHippoDb(globalRoot);
-            try {
-                appendAuditEvent(globalDb, {
-                    tenantId: ctx.tenantId,
-                    actor: ctx.actor.subject,
-                    op: 'recall',
-                    metadata: ctxRecallMetadata,
-                });
-            }
-            finally {
-                closeHippoDb(globalDb);
-            }
-        }
-    }
-    if (limit < selectedItems.length) {
-        const cut = selectedItems.slice(0, limit);
-        obs?.dropMissing(selectedItems.map((r) => r.entry), cut.map((r) => r.entry), 'limit', 'limit');
-        selectedItems = cut;
+    return { local, global };
+}
+/** The `limit` cut, then the held-copy drop, then each entry's origin annotation. */
+function finalizeSelection(picked, plan) {
+    const { obs } = plan;
+    let selected = picked;
+    if (plan.limit < selected.length) {
+        const cut = selected.slice(0, plan.limit);
+        obs?.dropMissing(selected.map((r) => r.entry), cut.map((r) => r.entry), 'limit', 'limit');
+        selected = cut;
     }
-    const heldDropped = dropHeldCopies(selectedItems, (r) => r.entry); // after the last cut, so a merged row that was cut hides nothing
-    obs?.dropMissing(selectedItems.map((r) => r.entry), heldDropped.map((r) => r.entry), 'limit', 'duplicate');
-    selectedItems = heldDropped;
-    totalTokens = selectedItems.reduce((sum, r) => sum + r.tokens, 0);
-    // v39: annotate every returned entry with its origin and how it relates to
-    // the active project, so renderers can demarcate cross-project inclusions.
-    selectedItems = selectedItems.map((r) => ({
+    const heldDropped = dropHeldCopies(selected, (r) => r.entry); // after the last cut, so a merged row that was cut hides nothing
+    obs?.dropMissing(selected.map((r) => r.entry), heldDropped.map((r) => r.entry), 'limit', 'duplicate');
+    selected = heldDropped;
+    const tokens = selected.reduce((sum, r) => sum + r.tokens, 0);
+    // Every returned entry carries its origin and how it relates to the active project, so renderers can mark cross-project rows.
+    selected = selected.map((r) => ({
         ...r,
         origin: r.entry.origin_project ?? null,
-        category: classifyOriginProject(r.entry.origin_project, currentProjectName),
+        category: classifyOriginProject(r.entry.origin_project, plan.currentProjectName),
     }));
-    obs?.selected(selectedItems);
-    if (selectedItems.length === 0 &&
-        !shownSnapshot &&
-        !shownHandoff &&
-        shownEvents.length === 0) {
-        // LC1 F5 fix: this bare early-return used to skip tracing entirely — a
-        // query that found nothing is exactly the coverage-gap signal Track LC
-        // needs. Write an empty trace (result_count 0, no result rows) so it
-        // lands in the training corpus. Never touches localIndex/
-        // last_retrieval_ids/last_trace_id — by construction it can't desync
-        // (mirrors the CLI zero-result path). Skipped under pinnedOnly (hot
-        // path stays read-only, same reason it skips markRetrieved). Fail-soft
-        // internally; never throws.
-        if (!pinnedOnly) {
-            // No snapshot in this branch, so the caller's own id is the only session to stamp.
-            writeRecallTraceAtRoot(ctx.hippoRoot, {
-                tenantId: ctx.tenantId,
-                sessionId: opts.currentSessionId || null,
-                pipeline: 'context',
-                query,
-                explainMode: false,
-                results: [],
-            });
-        }
-        return { entries: [], tokens: 0 };
-    }
-    // pinnedOnly is the UserPromptSubmit hot path — read-only so pinned
-    // memories don't inflate retrieval_count or extend half_life by 2 days per
-    // turn over a long session.
-    if (!pinnedOnly) {
-        const toUpdate = selectedItems.map((s) => s.entry);
-        const updatedEntries = markRetrieved(toUpdate);
-        const localIndex = loadIndex(ctx.hippoRoot);
-        const retrievedIds = updatedEntries.map((u) => u.id);
-        const strengthenedHere = strengthenRetrieved(ctx.hippoRoot, retrievedIds, { recallBoostAblated: isRecallBoostAblated() });
-        if (hasGlobal)
-            strengthenRetrieved(globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)), { recallBoostAblated: isRecallBoostAblated() });
-        localIndex.last_retrieval_ids = retrievedIds;
-        // LC1 F1 structural fix (docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
-        // write the trace FIRST — post-limit, post-annotation `selectedItems`
-        // actually returned, on a fresh short-lived connection (the audit
-        // handles above ~2410 are already closed by this point, matching this
-        // block's own per-call-handle convention: writeEntry, saveIndex) — then
-        // fold the resulting id into `localIndex` so the SAME `saveIndex` call
-        // below persists last_retrieval_ids + last_trace_id atomically.
-        // LOCKSTEP INVARIANT: last_trace_id must only ever advance together
-        // with last_retrieval_ids; a two-connection stamp-then-clear design
-        // could desync them on a crash between writes. A failed trace write
-        // (traceId null) sets last_trace_id to null rather than leaving the
-        // OLD id pointing at ids that are about to be overwritten. Fail-soft
-        // internally; never throws.
-        const traceId = writeRecallTraceAtRoot(ctx.hippoRoot, {
-            tenantId: ctx.tenantId,
-            sessionId: opts.currentSessionId || activeSnapshot?.session_id || null,
-            pipeline: 'context',
-            query,
-            explainMode: false,
-            results: selectedItems.map((s) => ({
-                memoryId: s.entry.id,
-                score: s.score,
-            })),
-        });
-        localIndex.last_trace_id = traceId !== null ? String(traceId) : null;
-        saveIndex(ctx.hippoRoot, localIndex);
-        updateStats(ctx.hippoRoot, { recalled: selectedItems.length });
-        // Replace selectedItems entries with markRetrieved-updated copies so
-        // the returned ContextResult reflects post-recall state.
-        selectedItems = selectedItems.map((s) => ({
-            ...s,
-            entry: updatedEntries.find((u) => u.id === s.entry.id) ?? s.entry,
-        }));
-        // Read after strengthenRetrieved commits, so the rows just retrieved count at their new strength.
-        if (config.ambient.enabled) {
-            const filter = { exactScope, project: originProject, currentProject: currentProjectName, now: evalNow() };
-            const roots = [...(hasLocal ? [ctx.hippoRoot] : []), ...(hasGlobal && !primaryIsGlobal ? [globalRoot] : [])];
-            const tallies = roots.map((root) => loadAmbientTallies(root, ctx.tenantId, filter));
-            const total = tallies.length > 0 ? tallies.reduce(addAmbientTallies) : undefined;
-            if (total && total.total > 0)
-                ambientState = ambientStateFromTallies(total);
-        }
-    }
-    return {
-        entries: selectedItems,
-        tokens: totalTokens,
-        activeSnapshot: shownSnapshot ?? undefined,
-        sessionHandoff: shownHandoff ?? undefined,
-        recentEvents: shownEvents.length > 0 ? shownEvents : undefined,
-        ambientState,
-    };
+    obs?.selected(selected);
+    return { items: selected, tokens };
+}
+// Never touches the index, so it cannot desync last_retrieval_ids from last_trace_id; fail-soft, never throws.
+function traceEmptyContext(ctx, opts, query) {
+    // No snapshot in this branch, so the caller's own id is the only session to stamp.
+    writeRecallTraceAtRoot(ctx.hippoRoot, {
+        tenantId: ctx.tenantId,
+        sessionId: opts.currentSessionId || null,
+        pipeline: 'context',
+        query,
+        explainMode: false,
+        results: [],
+    });
+}
+/** Strengthens and marks the returned rows, then writes the trace and index together. */
+function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
+    const toUpdate = selected.map((s) => s.entry);
+    const updatedEntries = markRetrieved(toUpdate);
+    const localIndex = loadIndex(ctx.hippoRoot);
+    const retrievedIds = updatedEntries.map((u) => u.id);
+    const strengthenedHere = strengthenRetrieved(ctx.hippoRoot, retrievedIds, { recallBoostAblated: isRecallBoostAblated() });
+    if (plan.hasGlobal)
+        strengthenRetrieved(plan.globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)), { recallBoostAblated: isRecallBoostAblated() });
+    localIndex.last_retrieval_ids = retrievedIds;
+    // Trace first on its own short-lived connection, then fold its id into localIndex so one saveIndex moves
+    // last_retrieval_ids and last_trace_id in lockstep; a failed trace write stores null, never a stale id.
+    const traceId = writeRecallTraceAtRoot(ctx.hippoRoot, {
+        tenantId: ctx.tenantId,
+        sessionId: opts.currentSessionId || activeSnapshot?.session_id || null,
+        pipeline: 'context',
+        query: plan.query,
+        explainMode: false,
+        results: selected.map((s) => ({
+            memoryId: s.entry.id,
+            score: s.score,
+        })),
+    });
+    localIndex.last_trace_id = traceId !== null ? String(traceId) : null;
+    saveIndex(ctx.hippoRoot, localIndex);
+    updateStats(ctx.hippoRoot, { recalled: selected.length });
+    // Replace selectedItems entries with markRetrieved-updated copies so
+    // the returned ContextResult reflects post-recall state.
+    const items = selected.map((s) => ({
+        ...s,
+        entry: updatedEntries.find((u) => u.id === s.entry.id) ?? s.entry,
+    }));
+    // Read after strengthenRetrieved commits, so the rows just retrieved count at their new strength.
+    return { items, ambientState: plan.config.ambient.enabled ? readAmbientState(ctx, plan) : undefined };
+}
+function readAmbientState(ctx, plan) {
+    const filter = { exactScope: plan.exactScope, project: plan.originProject, currentProject: plan.currentProjectName, now: evalNow() };
+    const roots = [...(plan.hasLocal ? [ctx.hippoRoot] : []), ...(plan.hasGlobal && !plan.primaryIsGlobal ? [plan.globalRoot] : [])];
+    const tallies = roots.map((root) => loadAmbientTallies(root, ctx.tenantId, filter));
+    const total = tallies.length > 0 ? tallies.reduce(addAmbientTallies) : undefined;
+    return total && total.total > 0 ? ambientStateFromTallies(total) : undefined;
 }
 //# sourceMappingURL=context.js.map