hippo-memory 2.0.0 → 2.1.0

package/dist/api/context-select.js

@@ -1,6 +1,5 @@
 // getContext's selection stages: the pinned-only branch, the strongest-first branch and the search branch.
 import { recallScopeFilter } from '../store/search-rows.js';
-import { heldIdLookup } from '../store/entry-reads.js';
 import { calculateStrength } from '../core/memory.js';
 import { auditQueryFields, recordAuditEvent } from '../store/audit.js';
 import { isWorthSurfacing } from '../core/memory-quality.js';
@@ -12,6 +11,7 @@ import { compareScoredResults } from '../core/compare.js';
 import { scopeMatch } from '../core/active-scope.js';
 import { scopeBoostFor } from '../search/boosts.js';
 import { promptTokens, contentTokens, gatePromptRecall, } from '../core/prompt-recall.js';
+import { heldIds } from './recall/finish.js';
 const GLOBAL_DISCOUNT = 1 / DEFAULT_LOCAL_BUMP;
 // 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.
@@ -34,7 +34,10 @@ export function oneCopyPerMemory(local, global, now) {
     return [local.filter((e) => kept.has(e)), global.filter((e) => kept.has(e))];
 }
 export const finiteOr = (v, dflt, min) => Number.isFinite(v) && v >= min ? v : dflt;
-/** Pins plus the prompt-recall or recent-N backfill; null means the hook block is turned off, so task state stays out too. */
+/**
+ * Pins plus the prompt-recall or recent-N backfill; null means the hook block is turned off, so task state stays out
+ * too.
+ */
 export function selectPinned(opts, plan, left, pools, admission) {
     const { obs, primaryIsGlobal, config: pinnedCfg } = plan;
     if (!pinnedCfg.pinnedInject.enabled) {
@@ -50,7 +53,8 @@ export function selectPinned(opts, plan, left, pools, admission) {
     const [localPool, globalPool] = oneCopyPerMemory(localEntries, globalEntries, nowP);
     obs?.dropMissing([...localEntries, ...globalEntries], [...localPool, ...globalPool], 'load', 'duplicate');
     const picked = { items: [], ids: new Set(), used: 0 };
-    // Pinned entries are explicit intent, the recent-N list an automatic backfill; both share ONE budget and the recent loop runs first,
+    // Pinned entries are explicit intent, the recent-N list an automatic backfill; both 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);
@@ -76,7 +80,9 @@ function rankPinned(plan, pinnedLocal, pinnedGlobal, nowP) {
         const scopeBoost = scopeBoostFor(scopeMatch(entry.tags, plan.activeScope));
         return {
             entry,
-            score: calculateStrength(entry, nowP, { ablation: strengthAblation() }) * (isGlobal ? GLOBAL_DISCOUNT : 1) * scopeBoost,
+            score: calculateStrength(entry, nowP, { ablation: strengthAblation() }) *
+                (isGlobal ? GLOBAL_DISCOUNT : 1) *
+                scopeBoost,
             tokens: plan.price(entry, isGlobal),
             isGlobal,
         };
@@ -84,7 +90,8 @@ function rankPinned(plan, pinnedLocal, pinnedGlobal, nowP) {
         .sort(compareScoredResults);
 }
 // Mirrors the pin loop's continue-not-break so a big pin cannot block smaller ones from reserving, and dedupes by id
-// because a synced pin sits in both stores. A pin also in the recent slice is counted twice: recents under-fill, safely.
+// because a synced pin sits in both stores. A pin also in the recent slice is counted twice: recents under-fill,
+// safely.
 function reservePinned(rankedPinned, effBudget) {
     let pinnedReserve = 0;
     const reservedIds = new Set();
@@ -248,11 +255,12 @@ export async function selectBySearch(ctx, plan, left, pools, admission) {
 async function searchBothStores(ctx, plan, options) {
     const { left, minResults, pools, admit } = options;
     const { cost, price } = plan;
-    // A local pool row is local by construction; sync keeps a global row's id on its local copy, so the global pool is looked up.
+    // A local pool row is local by construction; sync keeps a global row's id on its local copy, so the global pool is
+    // looked up.
     const poolIds = (pool) => [...pool.entries, ...(pool.recall ?? [])].map((e) => e.id);
     const localIds = new Set(poolIds(pools.local));
-    const alsoLocal = heldIdLookup(ctx.hippoRoot, ctx.tenantId, poolIds(pools.global).filter((id) => !localIds.has(id)));
-    const isGlobalHit = (e) => !localIds.has(e.id) && !alsoLocal(e.id);
+    const alsoLocal = await heldIds(plan.local.store, poolIds(pools.global).filter((id) => !localIds.has(id)), ctx.tenantId);
+    const isGlobalHit = (e) => !localIds.has(e.id) && !alsoLocal.has(e.id);
     const roots = { local: ctx.hippoRoot, global: plan.globalRoot };
     const merged = await rankBothStores(plan.query, roots, { local: pools.local.entries, global: pools.global.entries }, contextVectorSpec(ctx, plan, admit), {
         budget: left,
@@ -269,7 +277,12 @@ async function searchBothStores(ctx, plan, options) {
 }
 /** The vector arm under the lexical window's own tenant, scope and current-row rules. */
 function contextVectorSpec(ctx, plan, admit) {
-    return { tenantId: ctx.tenantId, scope: recallScopeFilter(plan.exactScope, 'exact', plan.ownScope), includeSuperseded: false, admit };
+    return {
+        tenantId: ctx.tenantId,
+        scope: recallScopeFilter(plan.exactScope, 'exact', plan.ownScope),
+        includeSuperseded: false,
+        admit,
+    };
 }
 async function searchLocalRows(ctx, plan, options) {
     const { left, minResults, localEntries, admit } = options;
@@ -300,12 +313,8 @@ async function auditContextRecall(ctx, plan, resultCount) {
         op: 'recall',
         metadata: { ...auditQueryFields(plan.query), results: resultCount, mode: 'context' },
     };
-    if (plan.other) {
-        await plan.other.appendAuditEvents([row]);
-        return;
-    }
     if (plan.hasLocal)
-        recordAuditEvent(ctx.hippoRoot, row);
+        await plan.local.store.appendAuditEvents([row]);
     if (plan.hasGlobal && !plan.primaryIsGlobal)
         recordAuditEvent(plan.globalRoot, row);
 }

package/dist/api/context-types.d.ts

@@ -4,8 +4,12 @@ import type { MemoryEntry } from '../core/memory.js';
 import type { DeliveryObserver } from '../store/delivery-recorder.js';
 import type { AmbientState } from '../core/ambient.js';
 import type { ProjectRef } from '../core/project-identity.js';
-/** Options for `getContext`: a budget-bounded bundle of recalled memories, active task snapshot, handoff and recent events.
- * Rendering opts (`format`, `framing`, `rendered`) and host-side opts (`auto`) stay in the CLI, whose print helpers are shared. */
+/**
+ * Options for `getContext`: a budget-bounded bundle of recalled memories, active task snapshot, handoff and recent
+ * events.
+ * Rendering opts (`format`, `framing`, `rendered`) and host-side opts (`auto`) stay in the CLI, whose print helpers are
+ * shared.
+ */
 export interface ContextOpts {
     q?: string;
     /** Default 1500 tokens. */
@@ -13,18 +17,35 @@ export interface ContextOpts {
     limit?: number;
     pinnedOnly?: boolean;
     scope?: string;
-    /** Envelope scope to match exactly, as in `recall`: admits that scope even when private, after the actor's scope check. */
+    /**
+     * Envelope scope to match exactly, as in `recall`: admits that scope even when private, after the actor's scope
+     * check.
+     */
     exactScope?: string;
-    /** With `pinnedOnly`, also inject the N most recent writes that pass the quality floor (`isWorthSurfacing`); pinned entries bypass it.
-     *  Filtering happens BEFORE the take-N, so asking for 5 gets 5 qualifying entries. Ignored when `pinnedOnly` is false. */
+    /**
+     * With `pinnedOnly`, also inject the N most recent writes that pass the quality floor (`isWorthSurfacing`); pinned
+     * entries bypass it.
+     * Filtering happens BEFORE the take-N, so asking for 5 gets 5 qualifying entries. Ignored when `pinnedOnly` is false.
+     */
     includeRecent?: number;
-    /** Re-include other-project memories the origin partition excludes by default; they come back tagged `category: 'cross-project'`. */
+    /**
+     * Re-include other-project memories the origin partition excludes by default; they come back tagged `category:
+     * 'cross-project'`.
+     */
     crossProject?: boolean;
-    /** The active project for the origin partition ('' = not in a project): a name, or an identity whose rows may carry its legacy folder name.
-     *  Defaults to `resolveProjectIdentity(process.cwd())`; surfaces whose cwd is not the caller's project (HTTP server) should pass it. */
+    /**
+     * The active project for the origin partition ('' = not in a project): a name, or an identity whose rows may carry
+     * its legacy folder name.
+     * Defaults to `resolveProjectIdentity(process.cwd())`; surfaces whose cwd is not the caller's project (HTTP server)
+     * should pass it.
+     */
     currentProject?: ProjectRef;
-    /** The calling session's id, stamped on this call's recall trace. When it strictly equals the active snapshot's `session_id` the read is unbounded;
-     *  otherwise the snapshot must pass the freshness bound. Absent (undefined/null/'') never matches. Host-resolved, so this stays host-agnostic. */
+    /**
+     * The calling session's id, stamped on this call's recall trace. When it strictly equals the active snapshot's
+     * `session_id` the read is unbounded;
+     * otherwise the snapshot must pass the freshness bound. Absent (undefined/null/'') never matches. Host-resolved, so
+     * this stays host-agnostic.
+     */
     currentSessionId?: string | null;
     /** Raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
     prompt?: string;
@@ -60,7 +81,10 @@ export interface ContextResultEntry {
     promptRecall?: boolean;
     /** v39: the entry's owning project ('' = user-global, null = legacy row). */
     origin?: string | null;
-    /** How the origin relates to the active project; 'cross-project' appears only when `crossProject` was set (or isolation is disabled). */
+    /**
+     * How the origin relates to the active project; 'cross-project' appears only when `crossProject` was set (or
+     * isolation is disabled).
+     */
     category?: 'project' | 'user-global' | 'cross-project';
 }
 export interface ContextResult {
@@ -70,7 +94,9 @@ export interface ContextResult {
     sessionHandoff?: SessionHandoff | null;
     recentEvents?: SessionEvent[];
     /** The ambient landscape summary over every live row the read may see in the local and global stores,
-     *  not just the rows loaded. Present only when ambient config is on, the caller is not pinned-only, and an entry was returned. */
+     * not just the rows loaded. Present only when ambient config is on, the caller is not pinned-only, and an entry was
+     * returned.
+     */
     ambientState?: AmbientState;
 }
 //# sourceMappingURL=context-types.d.ts.map

package/dist/api/context.d.ts

@@ -1,13 +1,16 @@
 import { type MemoryEntry } from '../core/memory.js';
 import { type ProjectRef } from '../core/project-identity.js';
 import type { ContextOpts, ContextResult } from './context-types.js';
-import { type Context } from './types.js';
+import { type ContextWith } from './types.js';
 export { oneCopyPerMemory } from './context-select.js';
-/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only inside its owning project. */
+/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only
+ * inside its owning project. */
 export declare function ambientSecretAdmit(e: MemoryEntry, currentProject: ProjectRef): boolean;
 /** Tokens a context block may use when the caller sets no budget; the hook command and the CLI default match it. */
 export declare const DEFAULT_CONTEXT_BUDGET = 1500;
-/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit row for non-pinned, non-'*' queries.
- * Returns an empty result when there are no memories, snapshot, handoff or recent events. CLI rendering stays in `cli.ts`. */
-export declare function getContext(ctx: Context, opts?: ContextOpts): Promise<ContextResult>;
+export declare const NO_QUERY = "*";
+/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit
+ * row for non-pinned, non-'*' queries. Returns an empty result when there are no memories, snapshot, handoff or recent
+ * events. CLI rendering stays in `cli.ts`. */
+export declare function getContext(ctx: ContextWith<'contextReads'>, opts?: ContextOpts): Promise<ContextResult>;
 //# sourceMappingURL=context.d.ts.map

package/dist/api/context.js

@@ -4,27 +4,28 @@ import { freshActiveSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS } from '../store/sessi
 import { estimateTokens } from '../util/token-text.js';
 import { markRetrieved, COMPACTION_MEMORY_TAG } from '../core/memory.js';
 import { isWorthSurfacing } from '../core/memory-quality.js';
-import { getGlobalRoot } from '../sharing/global-store.js';
 import { evalNow, strengthAblation } from '../core/ablation.js';
 import { dropHeldCopies } from '../util/same-text.js';
 import { BadRequestError } from '../core/api-errors.js';
-import { isSharedStore, loadConfig } from '../core/config.js';
+import { isSharedStore } from '../core/config.js';
+import { configOf } from './config-of.js';
 import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
-import { errorMessage, log } from '../util/log.js';
-import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot, isInitialized, projectId, projectNames, } from '../core/project-identity.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
+import { resolveProjectIdentity, classifyOriginProject, projectId, projectNames, } from '../core/project-identity.js';
 import { promptTokens } from '../core/prompt-recall.js';
 import { detectSecret } from '../util/secret-detect.js';
 import { isSessionDigestRow } from '../core/session-digest-row.js';
 import { addAmbientTallies, ambientStateFromTallies } from '../core/ambient.js';
-import { hasGroup, requireGroup, sqliteStore } from '../store/index.js';
-import { storeFor } from '../store/sqlite/store.js';
+import { hasGroup } from '../store/index.js';
 import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../core/recall-scope.js';
 import { finiteOr, selectBySearch, selectPinned, selectStrongest, } from './context-select.js';
-import { strengthenOf } from './recall-record.js';
+import { strengthenOf } from './recall/finish.js';
+import { tokenPurse } from './recall/render.js';
 import { ownerOrSubject } from './types.js';
 export { oneCopyPerMemory } from './context-select.js';
-/** The single ambient-injection admission policy, shared by getContext and the CLI ambient-state summary so they cannot drift.
- * Secret veto is unconditional (flagged rows inject only in their own project); private scopes need `exactScope`, other projects `includeCrossProject`. */
+/** The single ambient-injection admission policy, shared by getContext and the CLI ambient-state summary so they cannot
+ * drift. Secret veto is unconditional (flagged rows inject only in their own project); private scopes need
+ * `exactScope`, other projects `includeCrossProject`. */
 function ambientAdmitEntry(e, currentProject, includeCrossProject, exactScope, own) {
     if (!ambientSecretAdmit(e, currentProject))
         return false;
@@ -34,7 +35,8 @@ function ambientAdmitEntry(e, currentProject, includeCrossProject, exactScope, o
         return true;
     return classifyOriginProject(e.origin_project, currentProject) !== 'cross-project';
 }
-/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only inside its owning project. */
+/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only
+ * inside its owning project. */
 export function ambientSecretAdmit(e, currentProject) {
     if (!detectSecret(e).flagged)
         return true;
@@ -45,11 +47,13 @@ export function ambientSecretAdmit(e, currentProject) {
 }
 /** Tokens a context block may use when the caller sets no budget; the hook command and the CLI default match it. */
 export const DEFAULT_CONTEXT_BUDGET = 1500;
+// The plan's query when the caller gave none: context then ranks by strength instead of searching.
+export const NO_QUERY = '*';
 /** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
 const CONTEXT_CANDIDATE_CAP = 2000;
 /** A store's base search and context reads; a store without the group throws StoreNotPortedError. */
 function sourceOf(store) {
-    return { store, reads: requireGroup(store, 'contextReads') };
+    return { store, reads: store.contextReads };
 }
 // The pinned-only branch needs pins and recent-N candidates, not the corpus.
 async function loadAmbientEntries(source, tenantId, options) {
@@ -79,30 +83,37 @@ async function loadAmbientEntries(source, tenantId, options) {
         onQualityDrop?.(e);
         return false;
     };
-    const loaded = await source.reads.ambientCandidates(tenantId, { recentNeeded: recent.needed, admit: admitAmbient, recall, origins: recent.origins });
-    // Pins and recent rows reach core only through the store's own call to admit, so core applies it again with the tenant.
+    const loaded = await source.reads.ambientCandidates(tenantId, {
+        recentNeeded: recent.needed,
+        admit: admitAmbient,
+        recall,
+        origins: recent.origins,
+    });
+    // Pins and recent rows reach core only through the store's own
+    // call to admit, so core applies it again with the tenant.
     const entries = loaded.entries.filter((e) => ownTenant(e) && recheck(e));
     return loaded.recall ? { entries, recall: loaded.recall.filter(ownTenant) } : { entries };
 }
-/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit row for non-pinned, non-'*' queries.
- * Returns an empty result when there are no memories, snapshot, handoff or recent events. CLI rendering stays in `cli.ts`. */
+/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit
+ * row for non-pinned, non-'*' queries. Returns an empty result when there are no memories, snapshot, handoff or recent
+ * events. CLI rendering stays in `cli.ts`. */
 export async function getContext(ctx, opts = {}) {
     const budget = opts.budget ?? DEFAULT_CONTEXT_BUDGET;
     assertScopeRequestAllowed(ctx.actor, opts.exactScope);
     if (budget <= 0) {
         return { entries: [], tokens: 0 };
     }
-    const plan = planContext(ctx, opts, sourceOf(storeFor(ctx)));
+    const plan = planContext(ctx, opts, sourceOf(ctx.store));
     const sections = await loadTaskSections(ctx, opts, plan, openBlockBudget(plan, opts, budget));
     const admission = ambientAdmission(opts, plan, sections.shownHandoff);
     const pools = await 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) {
+    if (nothingToInject(plan, pools, noSections)) {
         return { entries: [], tokens: 0 };
     }
     const picked = plan.pinnedOnly
         ? selectPinned(opts, plan, sections.left, pools, admission)
-        : plan.query === '*'
+        : plan.query === NO_QUERY
             ? selectStrongest(plan, sections.left, pools)
             : await selectBySearch(ctx, plan, sections.left, pools, admission);
     if (picked === null) {
@@ -129,8 +140,12 @@ export async function getContext(ctx, opts = {}) {
         ambientState: recorded.ambientState,
     };
 }
+function nothingToInject(plan, pools, noSections) {
+    return (!plan.promptRecallPending && pools.local.entries.length === 0 && pools.global.entries.length === 0 && noSections);
+}
 const isolationWarned = new Set();
-/** A laptop config copied onto a team store must not open every member's rows to every prompt, so the flag loses there. */
+/** A laptop config copied onto a team store must not open every
+ * member's rows to every prompt, so the flag loses there. */
 function warnIsolationIgnored(hippoRoot) {
     if (isolationWarned.has(hippoRoot))
         return;
@@ -140,34 +155,54 @@ function warnIsolationIgnored(hippoRoot) {
 /** Which stores this read can draw on, and what kind the primary one is. */
 function storesInReach(ctx, opts, local) {
     const other = hasGroup(local.store, 'localFiles') ? undefined : local.store;
-    // Global memories do not establish a project boundary for task state.
-    const hasLocal = other !== undefined || isInitialized(ctx.hippoRoot);
-    const globalRoot = getGlobalRoot();
+    // No reach means an integrator's own store: one project, no global store beside it.
+    const reach = ctx.reach ?? { hasLocal: true, isGlobal: false, shared: isSharedStore(ctx.hippoRoot) };
     // The store's own flag counts too, so no surface can read a shared store as its owner.
-    const sharedStore = opts.sharedStore === true || isSharedStore(ctx.hippoRoot);
+    const sharedStore = opts.sharedStore === true || reach.shared;
     // A store serving many people is not its operator's, so the operator's own global store stays out.
-    const hasGlobal = !sharedStore && other === undefined && isInitialized(globalRoot);
-    const primaryIsGlobal = isGlobalStoreRoot(ctx.hippoRoot);
-    return { other, hasLocal, globalRoot, sharedStore, hasGlobal, primaryIsGlobal };
+    const hasGlobal = !sharedStore && other === undefined && reach.global !== undefined;
+    // Global memories do not establish a project boundary for task state.
+    return {
+        other,
+        hasLocal: other !== undefined || reach.hasLocal,
+        globalRoot: reach.global?.root ?? '',
+        sharedStore,
+        hasGlobal,
+        primaryIsGlobal: reach.isGlobal,
+    };
+}
+/** The operator's global store, which planContext proved present before it set hasGlobal. */
+function globalSource(ctx) {
+    const global = ctx.reach?.global;
+    if (global === undefined)
+        throw new Error('hasGlobal without a global store in reach');
+    return sourceOf(global.store);
 }
 /** Prices one entry against the budget: the caller's cost model when it gave one, else a token estimate. */
 function entryPricer(cost, currentProject) {
     return (entry, isGlobal, promptRecall) => cost
-        ? cost.entry({ entry, isGlobal, promptRecall, origin: entry.origin_project ?? null, category: classifyOriginProject(entry.origin_project, currentProject) })
+        ? cost.entry({
+            entry,
+            isGlobal,
+            promptRecall,
+            origin: entry.origin_project ?? null,
+            category: classifyOriginProject(entry.origin_project, currentProject),
+        })
         : estimateTokens(entry.content);
 }
 function planContext(ctx, opts, local) {
     const pinnedOnly = opts.pinnedOnly === true;
     const { other, hasLocal, globalRoot, sharedStore, hasGlobal, primaryIsGlobal } = storesInReach(ctx, opts, local);
-    const query = (opts.q ?? '').trim() || '*';
+    const query = (opts.q ?? '').trim() || NO_QUERY;
     // 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 config = configOf(ctx);
     const isolationEnabled = config.contextProjectIsolation !== false;
     const currentProject = opts.currentProject ?? resolveProjectIdentity(process.cwd());
     // A caller with no project reads every row as its own; on a shared store those rows are other people's.
-    if (sharedStore && projectId(currentProject).trim() === '')
-        throw new BadRequestError('a shared store needs the caller\'s project');
+    if (sharedStore && projectId(currentProject).trim() === '') {
+        throw new BadRequestError("a shared store needs the caller's project");
+    }
     if (sharedStore && !isolationEnabled)
         warnIsolationIgnored(ctx.hippoRoot);
     const includeCrossProject = opts.crossProject === true || (!isolationEnabled && !sharedStore);
@@ -208,14 +243,22 @@ function promptRecallRequest(opts, plan) {
         ? Array.from(promptTokens(opts.prompt ?? ''))
         : [];
     return promptRecallTerms.length > 0
-        ? { terms: promptRecallTerms, limit: Math.floor(finiteOr(pinnedInject.promptRecallCandidates, 100, 1)), ownScope: plan.ownScope }
+        ? {
+            terms: promptRecallTerms,
+            limit: Math.floor(finiteOr(pinnedInject.promptRecallCandidates, 100, 1)),
+            ownScope: plan.ownScope,
+        }
         : 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;
-    obs?.facts({ projectName: projectId(plan.currentProject), budgetTokens: blockBudget, promptRecall: promptRecallPending });
+    obs?.facts({
+        projectName: projectId(plan.currentProject),
+        budgetTokens: blockBudget,
+        promptRecall: promptRecallPending,
+    });
     if (pinnedOnly && !config.pinnedInject.enabled)
         obs?.disabled();
     if (!pinnedOnly)
@@ -234,7 +277,8 @@ async function loadRawTaskState(ctx, opts, plan) {
     if (!plan.hasLocalTaskState)
         return NO_TASK_STATE;
     const { store, reads } = plan.local;
-    // On a shared store task state is one person's, keyed by owner and project so it follows them into their next session.
+    // On a shared store task state is one person's, keyed by owner
+    // and project so it follows them into their next session.
     const key = plan.sharedStore
         ? { owner: ownerOrSubject(ctx.actor), project: projectNames(plan.currentProject) }
         : null;
@@ -245,18 +289,17 @@ async function loadRawTaskState(ctx, opts, plan) {
     if (snapshot?.session_id)
         return { snapshot, handoff: block.sessionHandoff, events: block.recentSessionEvents };
     // An unfinished handoff's scope is admitted in the read, so a newer denied row can't hide an older eligible one.
-    return { snapshot, handoff: await reads.unfinishedHandoff(ctx.tenantId, SNAPSHOT_AMBIENT_MAX_AGE_MS, key), events: [] };
+    return {
+        snapshot,
+        handoff: await reads.unfinishedHandoff(ctx.tenantId, SNAPSHOT_AMBIENT_MAX_AGE_MS, key),
+        events: [],
+    };
 }
-// 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.
 async function loadTaskSections(ctx, opts, plan, startLeft) {
     const { exactScope, ownScope, cost } = plan;
-    let left = startLeft;
-    const pays = (tokens) => {
-        if (tokens > left)
-            return false;
-        left -= tokens;
-        return true;
-    };
+    const { pays, left } = tokenPurse(startLeft);
     const rowScope = (r) => r?.scope ?? null;
     const raw = await loadRawTaskState(ctx, opts, plan);
     // The same envelope rule ambientAdmitEntry applies to memory rows.
@@ -266,15 +309,20 @@ async function loadTaskSections(ctx, opts, plan, startLeft) {
     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 : [];
-    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 };
+    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: left() };
 }
 function ambientAdmission(opts, plan, shownHandoff) {
     const transcriptHandoffSession = shownHandoff?.evidence?.derivedFrom === 'transcript' ? shownHandoff.sessionId : null;
     const ambientAdmit = (e) => {
         // A printed handoff already carries the session's closing message, which its digest would print a second time.
-        if (transcriptHandoffSession !== null && e.source_session_id === transcriptHandoffSession && isSessionDigestRow(e))
+        if (transcriptHandoffSession !== null &&
+            e.source_session_id === transcriptHandoffSession &&
+            isSessionDigestRow(e)) {
             return false;
+        }
         return ambientAdmitEntry(e, plan.currentProject, plan.includeCrossProject, plan.exactScope, plan.ownScope);
     };
     const ownSessionId = opts.currentSessionId || '';
@@ -282,13 +330,15 @@ function ambientAdmission(opts, plan, shownHandoff) {
     const isOwnCompactionItem = (e) => ownSessionId !== '' &&
         e.source_session_id === ownSessionId &&
         e.tags.includes(COMPACTION_MEMORY_TAG);
-    // Superseded rows never inject; which rows reach ambientAdmitEntry matters because it regex-scans content for secrets.
+    // 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);
     // 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 };
 }
-/** Origins the recent backfill may read past its first window; on a shared store, only the caller's own project rows. */
+/** Origins the recent backfill may read past its first window;
+ * on a shared store, only the caller's own project rows. */
 function recentOrigins(plan) {
     if (plan.sharedStore)
         return { names: projectNames(plan.currentProject).filter((n) => n !== ''), userGlobal: false };
@@ -297,7 +347,7 @@ function recentOrigins(plan) {
 async function loadPools(ctx, plan, admission, recallRequest) {
     const { obs, pinnedOnly, primaryIsGlobal, hasGlobal, exactScope, ownScope } = plan;
     const recent = { needed: plan.includeRecent, origins: recentOrigins(plan) };
-    const searches = plan.query !== '*' && !pinnedOnly;
+    const searches = plan.query !== NO_QUERY && !pinnedOnly;
     const searchesBoth = searches && hasGlobal && !primaryIsGlobal;
     const poolAdmit = searchesBoth ? admission.bothStoresAdmit : admission.admit;
     const loadAdmit = obs ? obs.watchAdmit(poolAdmit) : poolAdmit;
@@ -318,7 +368,10 @@ async function loadPools(ctx, plan, admission, recallRequest) {
         ? await loadAmbientEntries(plan.local, ctx.tenantId, { ...read, onQualityDrop: qualityDrop(primaryIsGlobal) })
         : { entries: [] };
     const global = hasGlobal && !primaryIsGlobal
-        ? await loadAmbientEntries(sourceOf(sqliteStore(plan.globalRoot)), ctx.tenantId, { ...read, onQualityDrop: qualityDrop(true) })
+        ? await loadAmbientEntries(globalSource(ctx), ctx.tenantId, {
+            ...read,
+            onQualityDrop: qualityDrop(true),
+        })
         : { entries: [] };
     return { local, global };
 }
@@ -327,7 +380,7 @@ function finalizeSelection(picked, plan) {
     const { obs } = plan;
     // Ranking reports nothing itself, so its results are offered here and the cuts below can name what they drop.
     if (!plan.pinnedOnly && obs) {
-        const pool = plan.query === '*' ? 'strength' : 'search';
+        const pool = plan.query === NO_QUERY ? 'strength' : 'search';
         obs.offer(picked.filter((r) => r.isGlobal !== true).map((r) => r.entry), false, pool);
         obs.offer(picked.filter((r) => r.isGlobal === true).map((r) => r.entry), true, pool);
     }
@@ -337,11 +390,13 @@ function finalizeSelection(picked, plan) {
         obs?.dropMissing(selected.map((r) => r.entry), cut.map((r) => r.entry), 'limit', 'limit');
         selected = cut;
     }
-    const heldDropped = dropHeldCopies(selected, (r) => r.entry); // after the last cut, so a merged row that was cut hides nothing
+    // After the last cut, so a merged row that was cut hides nothing.
+    const heldDropped = dropHeldCopies(selected, (r) => r.entry);
     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.
+    // 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,
@@ -363,11 +418,11 @@ async function traceEmptyContext(ctx, opts, plan) {
     };
     // The empty reply is already decided, so a lost trace is logged and the call still answers.
     try {
-        await storeFor(ctx).finishRecall({ goalLog: [], audit: [], trace });
+        await ctx.store.finishRecall({ goalLog: [], audit: [], trace });
     }
     catch (error) {
         rethrowIfSqliteBlocked(error);
-        log.error(`recall trace write failed: ${errorMessage(error)}`);
+        log.error(`recall trace write failed: ${errorMessage(error)}`, errorFields(error));
     }
 }
 /** Strengthens and marks the returned rows, then writes the trace and index together. */
@@ -388,7 +443,7 @@ async function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
     };
     const writes = { goalLog: [], audit: [], trace, strengthen: strengthenOf(ctx, retrievedIds) };
     // The last recall feeds only outcomeForLastRecall, so a store that keeps none still finishes the recall without one.
-    const store = storeFor(ctx);
+    const store = ctx.store;
     const traceId = store.lastRecall
         ? await store.lastRecall.finishRecall(writes, plan.hasGlobal ? plan.globalRoot : undefined)
         : await store.finishRecall(writes).then(() => null);
@@ -413,7 +468,7 @@ async function readAmbientState(ctx, plan) {
     };
     const sources = [
         ...(plan.hasLocal ? [plan.local.reads] : []),
-        ...(plan.hasGlobal && !plan.primaryIsGlobal ? [sourceOf(sqliteStore(plan.globalRoot)).reads] : []),
+        ...(plan.hasGlobal && !plan.primaryIsGlobal ? [globalSource(ctx).reads] : []),
     ];
     const tallies = [];
     for (const reads of sources)