hippo-memory 1.60.0 → 1.62.0

package/dist/api/auth.js

@@ -0,0 +1,178 @@
+// API key management: create, list, revoke, and grant or ungrant restricted scopes.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from '../api-errors.js';
+import { appendAuditEvent, reportAuditWriteFailure } from '../audit.js';
+import { createApiKey, listApiKeyRows, revokeApiKey, grantScope, ungrantScope } from '../auth.js';
+import { isRestrictedScope } from '../recall-scope.js';
+import { selectApiKeyOwner } from '../store/tenant-lookup.js';
+/**
+ * Mint a new API key. The new key is ALWAYS bound to `ctx.tenantId`. Callers
+ * cannot override the tenant via the opts bag — a previous `tenantId` field
+ * was removed because the HTTP layer would happily forward `body.tenantId`,
+ * letting tenant A mint a key for tenant B. The HTTP route handler at
+ * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
+ * `tenantId` and uses the resolved Bearer's tenant exclusively.
+ *
+ * Only an admin actor can mint (ForbiddenError otherwise), and a key never
+ * outranks its minter: a resolver admin is tenant-only, so it mints members.
+ */
+export function authCreate(ctx, opts) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can create API keys');
+    }
+    if (ctx.actor.viaAuthResolver && opts.role === 'admin') {
+        throw new ForbiddenError('A key minted through the auth resolver can only be a member key');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : 'admin');
+        const result = createApiKey(db, { tenantId: ctx.tenantId, label: opts.label, role });
+        // v1.12.4: audit emit (closes the gap v1.12.3 CHANGELOG flagged as deferred).
+        // Mirrors the auth_revoke pattern at authRevoke — same try/catch so audit
+        // failure can't crash a successful mint. The plaintext is NEVER logged;
+        // metadata carries label + role + the keyId (which is non-secret).
+        try {
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'auth_create',
+                targetId: result.keyId,
+                metadata: {
+                    label: opts.label ?? null,
+                    role,
+                },
+            });
+        }
+        catch (error) {
+            // Audit must not crash a successful mint.
+            reportAuditWriteFailure('auth_create', String(error), result.keyId);
+        }
+        return { keyId: result.keyId, plaintext: result.plaintext, tenantId: ctx.tenantId, role };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * List API keys visible to the calling tenant.
+ *
+ * Divergence from `cmdAuthList` in src/cli.ts: the CLI today returns ALL keys
+ * regardless of tenant (single-tenant deployments). The API surface is tenant-
+ * scoped because future multi-tenant deployments will share a hippoRoot, and
+ * tenant A must not see tenant B's keys. Read-only — no audit emit (matches A5).
+ */
+export function authList(ctx, opts) {
+    return authListRows(ctx, opts).map((r) => r.key);
+}
+/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from. */
+export function authListRows(ctx, opts) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return listApiKeyRows(db, { ...opts, tenantId: ctx.tenantId });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function authRevoke(ctx, keyId) {
+    if (ctx.actor.role !== 'admin' && ctx.actor.subject !== `api_key:${keyId}`) {
+        throw new ForbiddenError('A member key can revoke only itself');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const row = selectApiKeyOwner(db, keyId);
+        // Cross-tenant access denied: same message as missing key, no info leak.
+        if (!row || row.tenantId !== ctx.tenantId) {
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
+        }
+        if (ctx.actor.viaAuthResolver && row.role === 'admin') {
+            throw new ForbiddenError('An auth resolver admin cannot revoke an admin key, which outranks it');
+        }
+        let revokedAt;
+        let alreadyRevoked = false;
+        if (row.revokedAt) {
+            alreadyRevoked = true;
+            revokedAt = row.revokedAt;
+        }
+        else {
+            revokeApiKey(db, keyId);
+            revokedAt = selectApiKeyOwner(db, keyId)?.revokedAt ?? new Date().toISOString();
+        }
+        if (!alreadyRevoked) {
+            try {
+                appendAuditEvent(db, {
+                    tenantId: row.tenantId, // M1: KEY's tenant, not ctx.tenantId.
+                    actor: ctx.actor.subject,
+                    op: 'auth_revoke',
+                    targetId: keyId,
+                });
+            }
+            catch (error) {
+                // Audit must not crash a successful revoke.
+                reportAuditWriteFailure('auth_revoke', String(error), keyId);
+            }
+        }
+        return { ok: true, revokedAt };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * The tenant that owns `keyId`, or undefined for an unknown key. Host admin only: it reads across tenants,
+ * so the local CLI can run revoke and grant in the key's own tenant.
+ */
+export function authKeyTenant(ctx, keyId) {
+    if (!ctx.actor.hostAdmin) {
+        throw new ForbiddenError('Only the host admin can look up a key across tenants');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return selectApiKeyOwner(db, keyId)?.tenantId;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Grant `keyId` read access to one restricted `scope` (ROADMAP Part VIII EI2). Admin only. */
+export function authGrant(ctx, keyId, scope) {
+    return changeScopeGrant(ctx, keyId, scope, 'auth_grant');
+}
+/** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
+export function authUngrant(ctx, keyId, scope) {
+    return changeScopeGrant(ctx, keyId, scope, 'auth_ungrant');
+}
+function changeScopeGrant(ctx, keyId, scope, op) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can change scope grants');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const row = selectApiKeyOwner(db, keyId);
+        if (!row || row.tenantId !== ctx.tenantId) {
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
+        }
+        if (op === 'auth_grant' && row.revokedAt) {
+            throw new ConflictError(`${keyId} is revoked; a grant on it would never apply`);
+        }
+        if (!isRestrictedScope(scope)) {
+            throw new BadRequestError(`${scope} is not a restricted scope; it is already readable by default`);
+        }
+        if (op === 'auth_grant')
+            grantScope(db, keyId, scope);
+        else
+            ungrantScope(db, keyId, scope);
+        try {
+            appendAuditEvent(db, { tenantId: ctx.tenantId, actor: ctx.actor.subject, op, targetId: keyId, metadata: { scope } });
+        }
+        catch (err) {
+            // Audit must not undo a grant change that already committed; surface it instead.
+            reportAuditWriteFailure(op, String(err), keyId);
+        }
+        return { ok: true };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=auth.js.map

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

@@ -0,0 +1,49 @@
+import type { AmbientLoadResult } from '../store/candidates.js';
+import { type MemoryEntry } from '../memory.js';
+import { type HippoConfig } from '../config.js';
+import type { DeliveryObserver } from '../delivery-recorder.js';
+import type { ContextCost, ContextOpts, ContextResultEntry } from './context-types.js';
+import type { Context } from './types.js';
+/** What getContext resolved from opts and config before it read a row. */
+export interface ContextPlan {
+    pinnedOnly: boolean;
+    limit: number;
+    includeRecent: number;
+    activeScope: string;
+    exactScope: string | undefined;
+    query: string;
+    hasLocal: boolean;
+    hasGlobal: boolean;
+    globalRoot: string;
+    primaryIsGlobal: boolean;
+    hasLocalTaskState: boolean;
+    config: HippoConfig;
+    currentProjectName: string;
+    includeCrossProject: boolean;
+    originProject: string | undefined;
+    promptRecallPending: boolean;
+    cost: ContextCost | undefined;
+    price: (entry: MemoryEntry, isGlobal: boolean, promptRecall?: boolean) => number;
+    obs: DeliveryObserver | undefined;
+}
+/** The ambient admit rules; `digestHidden` is read late because a prompt-recall eligibility check can still set it. */
+export interface ContextAdmission {
+    ambientAdmit: (e: MemoryEntry) => boolean;
+    admit: (e: MemoryEntry) => boolean;
+    /** What the two-store search admits: `admit` without the own-session compaction rule. */
+    bothStoresAdmit: (e: MemoryEntry) => boolean;
+    digestHidden: () => boolean;
+}
+export interface ContextPools {
+    local: AmbientLoadResult;
+    global: AmbientLoadResult;
+}
+export declare function oneCopyPerMemory(local: readonly MemoryEntry[], global: readonly MemoryEntry[], now: Date): [MemoryEntry[], MemoryEntry[]];
+export declare const finiteOr: (v: number, dflt: number, min: number) => number;
+/** Pins plus the prompt-recall or recent-N backfill; null means the block is empty. */
+export declare function selectPinned(ctx: Context, opts: ContextOpts, plan: ContextPlan, left: number, pools: ContextPools, admission: ContextAdmission): ContextResultEntry[] | null;
+/** No query: the strongest memories by strength, up to budget. */
+export declare function selectStrongest(plan: ContextPlan, left: number, pools: ContextPools): ContextResultEntry[];
+/** Real query: hybrid search over both stores, or physics/hybrid over the local rows; emits the 'recall' audit row. */
+export declare function selectBySearch(ctx: Context, plan: ContextPlan, left: number, pools: ContextPools, admission: ContextAdmission): Promise<ContextResultEntry[]>;
+//# sourceMappingURL=context-select.d.ts.map

package/dist/api/context-select.js

@@ -0,0 +1,344 @@
+// getContext's selection stages: the pinned-only branch, the strongest-first branch and the search branch.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { recallScopeFilter } from '../store/search-rows.js';
+import { loadIndex } from '../store/index-and-stats.js';
+import { calculateStrength } from '../memory.js';
+import { appendAuditEvent, auditQueryFields, isContentWorthStoring } from '../audit.js';
+import { rankBothStores } from '../shared.js';
+import { evalNow } from '../ablation.js';
+import { hybridSearch } from '../search/hybrid.js';
+import { physicsSearch } from '../search/physics-search.js';
+import { compareScoredResults } from '../compare.js';
+import { scopeMatch } from '../scope.js';
+import { loadConfig } from '../config.js';
+import { promptTokens, contentTokens, gatePromptRecall, } from '../prompt-recall.js';
+// 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))];
+}
+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 block is empty. */
+export function selectPinned(ctx, opts, plan, left, pools, admission) {
+    const { obs, primaryIsGlobal } = plan;
+    // loadConfig is safe even when local isn't initialised — returns defaults.
+    const pinnedCfg = loadConfig(ctx.hippoRoot);
+    if (!pinnedCfg.pinnedInject.enabled) {
+        return null;
+    }
+    // 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)
+    const localEntries = pools.local.entries;
+    const globalEntries = pools.global.entries;
+    obs?.offer(localEntries, primaryIsGlobal);
+    obs?.offer(globalEntries, true);
+    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 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 = rankPinned(plan, pinnedLocal, pinnedGlobal, nowP);
+    const recentBudget = Math.max(0, effBudget - reservePinned(rankedPinned, effBudget));
+    // Prompt recall gates the backfill on the prompt instead of recency.
+    if (plan.promptRecallPending) {
+        const candidates = () => promptRecallCandidates(plan, pools, admission.admit, rankedPinned, nowP);
+        backfillFromPrompt(opts, plan, pinnedCfg, candidates, picked, recentBudget);
+    }
+    else if (plan.includeRecent > 0) {
+        backfillRecent(plan, localPool, globalPool, picked, recentBudget, nowP);
+    }
+    if (pinnedLocal.length === 0 &&
+        pinnedGlobal.length === 0 &&
+        picked.items.length === 0 &&
+        !admission.digestHidden()) {
+        return null;
+    }
+    admitWithinBudget(rankedPinned, picked, effBudget, obs);
+    return picked.items;
+}
+function rankPinned(plan, pinnedLocal, pinnedGlobal, nowP) {
+    return [
+        ...pinnedLocal.map((e) => ({ entry: e, isGlobal: plan.primaryIsGlobal })),
+        ...pinnedGlobal.map((e) => ({ entry: e, isGlobal: true })),
+    ]
+        .map(({ entry, isGlobal }) => {
+        const scopeSig = scopeMatch(entry.tags, plan.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: plan.price(entry, isGlobal),
+            isGlobal,
+        };
+    })
+        .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.
+function reservePinned(rankedPinned, effBudget) {
+    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);
+        }
+    }
+    return pinnedReserve;
+}
+/** Skips ids already picked and rows past the budget, so a large row never blocks smaller ones behind it. */
+function admitWithinBudget(rows, picked, budget, obs) {
+    for (const r of rows) {
+        if (picked.ids.has(r.entry.id))
+            continue;
+        if (picked.used + r.tokens > budget) {
+            obs?.reject(r.entry, 'budget', 'budget', r.score, r.tokens);
+            continue;
+        }
+        picked.items.push(r);
+        picked.ids.add(r.entry.id);
+        picked.used += r.tokens;
+    }
+}
+function backfillFromPrompt(opts, plan, pinnedCfg, candidates, picked, recentBudget) {
+    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)
+        return;
+    const candidateItems = candidates();
+    const gated = gatePromptRecall(p, candidateItems, gate);
+    plan.obs?.gated(p, candidateItems, gate, gated);
+    for (const g of gated) {
+        if (picked.ids.has(g.item.id))
+            continue;
+        const tokens = plan.price(g.item.entry, g.item.isGlobal, true);
+        if (picked.used + tokens > recentBudget) {
+            plan.obs?.reject(g.item.entry, 'budget', 'budget', g.score, tokens);
+            continue;
+        }
+        picked.items.push({ entry: g.item.entry, score: g.score, tokens, isGlobal: g.item.isGlobal, promptRecall: true });
+        picked.ids.add(g.item.id);
+        picked.used += tokens;
+    }
+}
+// Candidates came off the ambient load's own connection (the recall request), not a fresh open.
+function promptRecallCandidates(plan, pools, admit, rankedPinned, nowP) {
+    const { obs, primaryIsGlobal } = plan;
+    // 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(pools.local.recall ?? [], primaryIsGlobal, 'prompt-recall');
+    obs?.offer(pools.global.recall ?? [], true, 'prompt-recall');
+    const localEligible = (pools.local.recall ?? []).filter(eligible);
+    const globalEligible = (pools.global.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 });
+    }
+    return candidateItems;
+}
+function backfillRecent(plan, localPool, globalPool, picked, recentBudget, nowP) {
+    const recent = [
+        ...localPool.map((entry) => ({ entry, isGlobal: plan.primaryIsGlobal })),
+        ...globalPool.map((entry) => ({ entry, isGlobal: true })),
+    ]
+        // Newest first, then id: stable within one store, but same-millisecond rows fall to random ids across ingests.
+        .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);
+    })
+        // Filter before slice so a junk row is backfilled past, not counted against N. Pins bypass the floor: a dropped
+        // pin's share of the shared budget would go to a backfilled row, and the pin loop could not win it back.
+        .filter(({ entry }) => entry.pinned || isContentWorthStoring(entry.content))
+        .slice(0, plan.includeRecent)
+        .map(({ entry, isGlobal }) => ({
+        entry,
+        score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1),
+        tokens: plan.price(entry, isGlobal),
+        isGlobal,
+    }));
+    admitWithinBudget(recent, picked, recentBudget, plan.obs);
+}
+/** No query: the strongest memories by strength, up to budget. */
+export function selectStrongest(plan, left, pools) {
+    const now = evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
+    const [localPool, globalPool] = oneCopyPerMemory(pools.local.entries, pools.global.entries, now);
+    const localRanked = localPool
+        .map((e) => ({
+        entry: e,
+        score: calculateStrength(e, now),
+        tokens: plan.price(e, plan.primaryIsGlobal),
+        isGlobal: plan.primaryIsGlobal,
+    }))
+        .sort(compareScoredResults);
+    const globalRanked = globalPool
+        .map((e) => ({
+        entry: e,
+        score: calculateStrength(e, now) * (1 / 1.2),
+        tokens: plan.price(e, true),
+        isGlobal: true,
+    }))
+        .sort(compareScoredResults);
+    const combined = [...localRanked, ...globalRanked].sort(compareScoredResults);
+    const selected = [];
+    let used = 0;
+    for (const r of combined) {
+        if (used + r.tokens > left)
+            continue;
+        selected.push(r);
+        used += r.tokens;
+    }
+    return selected;
+}
+/** Real query: hybrid search over both stores, or physics/hybrid over the local rows; emits the 'recall' audit row. */
+export async function selectBySearch(ctx, plan, left, pools, admission) {
+    const minResults = plan.cost ? 0 : undefined; // a priced block skips an oversize top hit too, so the budget bounds it
+    const results = plan.hasGlobal && !plan.primaryIsGlobal
+        ? await searchBothStores(ctx, plan, left, minResults, pools, admission.bothStoresAdmit)
+        : await searchLocalRows(ctx, plan, left, minResults, pools.local.entries, admission.admit);
+    auditContextRecall(ctx, plan, results.length);
+    return results;
+}
+// The pools were admitted at load, before ranking, dedupe and budget: a post-filter would let an excluded row fill the
+// budget or shadow its admitted duplicate.
+async function searchBothStores(ctx, plan, left, minResults, pools, admit) {
+    const { cost, price } = plan;
+    const localIndex = loadIndex(ctx.hippoRoot);
+    const isGlobalHit = (e) => !localIndex.entries[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,
+        minResults,
+        cost: cost && ((r) => price(r.entry, isGlobalHit(r.entry))),
+        scope: plan.activeScope,
+    });
+    return merged.map((r) => ({
+        entry: r.entry,
+        score: r.score,
+        tokens: price(r.entry, isGlobalHit(r.entry)),
+        isGlobal: isGlobalHit(r.entry),
+    }));
+}
+/** 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'), includeSuperseded: false, admit };
+}
+async function searchLocalRows(ctx, plan, left, minResults, localEntries, admit) {
+    const { cost, price, primaryIsGlobal, query } = plan;
+    const ctxConfig = loadConfig(ctx.hippoRoot);
+    const usePhysicsCtx = ctxConfig.physics?.enabled !== false;
+    const localCost = cost && ((r) => price(r.entry, primaryIsGlobal));
+    const vectorCandidates = contextVectorSpec(ctx, plan, admit);
+    const ctxResults = usePhysicsCtx
+        ? await physicsSearch(query, localEntries, {
+            budget: left,
+            minResults,
+            cost: localCost,
+            hippoRoot: ctx.hippoRoot,
+            physicsConfig: ctxConfig.physics,
+            scope: plan.activeScope,
+            vectorCandidates,
+        })
+        : await hybridSearch(query, localEntries, {
+            budget: left,
+            minResults,
+            cost: localCost,
+            hippoRoot: ctx.hippoRoot,
+            scope: plan.activeScope,
+            vectorCandidates,
+        });
+    return ctxResults.map((r) => ({
+        entry: r.entry,
+        score: r.score,
+        tokens: price(r.entry, primaryIsGlobal),
+        isGlobal: primaryIsGlobal,
+    }));
+}
+// Same 'recall' op api.recall emits; the pinned-only and no-query branches never search, so they never emit.
+function auditContextRecall(ctx, plan, resultCount) {
+    const ctxRecallMetadata = {
+        ...auditQueryFields(plan.query),
+        results: resultCount,
+        mode: 'context',
+    };
+    if (plan.hasLocal) {
+        const localDb = openHippoDb(ctx.hippoRoot);
+        try {
+            appendAuditEvent(localDb, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'recall',
+                metadata: ctxRecallMetadata,
+            });
+        }
+        finally {
+            closeHippoDb(localDb);
+        }
+    }
+    if (plan.hasGlobal && !plan.primaryIsGlobal) {
+        const globalDb = openHippoDb(plan.globalRoot);
+        try {
+            appendAuditEvent(globalDb, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'recall',
+                metadata: ctxRecallMetadata,
+            });
+        }
+        finally {
+            closeHippoDb(globalDb);
+        }
+    }
+}
+//# sourceMappingURL=context-select.js.map

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

@@ -0,0 +1,105 @@
+import type { TaskSnapshot, SessionEvent } from '../store/rows.js';
+import type { SessionHandoff } from '../handoff.js';
+import type { MemoryEntry } from '../memory.js';
+import type { DeliveryObserver } from '../delivery-recorder.js';
+import type { AmbientState } from '../ambient.js';
+/**
+ * Options for `getContext` — assemble a budget-bounded context bundle
+ * (recalled memories + active task snapshot + handoff + recent events).
+ * Extracted from `cmdContext` in `cli.ts` in Episode A of the api.ts refactor.
+ *
+ * Named `getContext` (not `context`) to avoid collision with the `Context`
+ * interface above and the ubiquitous `ctx: Context` convention. Follows the
+ * existing `getEntry` naming pattern in store.ts.
+ *
+ * Scope narrow (T5 execute decision): rendering opts (`format`, `framing`,
+ * `rendered`) and host-side opts (`auto`) are NOT included here. The print
+ * helpers (`printContextMarkdown`, `printActiveTaskSnapshot`, `printHandoff`,
+ * `printSessionEvents`) are shared with `cmdRecall` / `cmdSnapshot` /
+ * `cmdHandoffShow` — moving them into api.ts would expand T5 to also rewire
+ * those commands. CLI handles rendering + auto-resolution. Episode B can add
+ * `api.renderContext` once a shared rendering need actually materializes.
+ */
+export interface ContextOpts {
+    q?: string;
+    /** Default 1500 tokens. */
+    budget?: number;
+    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. */
+    exactScope?: string;
+    /** With `pinnedOnly`, also inject the N most recent writes that pass the
+     *  quality floor (`isContentWorthStoring`, DF3). Filtering happens BEFORE
+     *  the take-N, so a caller asking for 5 gets 5 qualifying entries rather
+     *  than 5-minus-junk; pinned entries bypass the floor. Entries are only
+     *  skipped for this read, never mutated or deleted. Ignored when
+     *  `pinnedOnly` is false — no other path reads it. */
+    includeRecent?: number;
+    /** v39 memory scope isolation: re-include other-project memories that the
+     *  origin partition excludes by default. They come back tagged
+     *  `category: 'cross-project'` so renderers can demarcate them. */
+    crossProject?: boolean;
+    /** The active project name for the origin partition ('' = not in a
+     *  project). Defaults to `resolveProjectIdentity(process.cwd()).name`;
+     *  surfaces whose process cwd is not the caller's project (HTTP server)
+     *  should pass it explicitly. */
+    currentProject?: string;
+    /** DF1 (docs/plans/2026-08-23-df1-snapshot-lifecycle.md, T2): the calling
+     *  session's id. Stamped on this call's recall trace, and the owner-match input to
+     *  `loadFreshActiveTaskSnapshot` — when it strictly equals the active
+     *  snapshot's `session_id`, the read is unbounded (same-session
+     *  continuity); otherwise the snapshot must pass the freshness bound to
+     *  surface. Absent (undefined/null/'') never short-circuits as a match;
+     *  it just means every snapshot goes through the age check. Host-resolved
+     *  (stdin payload, HIPPO_SESSION_ID, else the host's session var) so this stays host-agnostic. */
+    currentSessionId?: string | null;
+    /** Z1: raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
+    prompt?: string;
+    /** What the budget pays for, from the caller that renders the block. Absent = the memory text alone. */
+    cost?: ContextCost;
+    /** @internal The CLI's delivery-ledger observer; it only reads, so selection is the same with or without it. */
+    deliveryObserver?: DeliveryObserver;
+}
+/** Budget prices in the text a caller prints, so the budget bounds what reaches the model. */
+export interface ContextCost {
+    /** Tokens of one entry as printed. */
+    entry: (item: Pick<ContextResultEntry, 'entry' | 'isGlobal' | 'promptRecall' | 'origin' | 'category'>) => number;
+    /** Tokens of the headers and footer the block can print at this budget, reserved before any entry. */
+    fixed: (budget: number, can: {
+        cross: boolean;
+        promptRecall: boolean;
+        ambient: boolean;
+    }) => number;
+    /** Tokens of the sections printed ahead of the memories, each as printed. */
+    snapshot: (s: TaskSnapshot) => number;
+    handoff: (h: SessionHandoff) => number;
+    trail: (events: SessionEvent[]) => number;
+}
+export interface ContextResultEntry {
+    entry: MemoryEntry;
+    score: number;
+    /** What this entry cost the budget: its printed line under `ContextOpts.cost`, else its memory text. */
+    tokens: number;
+    isGlobal?: boolean;
+    isFreshTail?: boolean;
+    /** Z1: admitted by the prompt-recall gate, not the recent-N backfill or a pin. */
+    promptRecall?: boolean;
+    /** v39: the entry's owning project ('' = user-global, null = legacy row). */
+    origin?: string | null;
+    /** v39: how the origin relates to the active project. 'cross-project'
+     *  entries only appear when ContextOpts.crossProject was set (or isolation
+     *  is disabled). */
+    category?: 'project' | 'user-global' | 'cross-project';
+}
+export interface ContextResult {
+    entries: ContextResultEntry[];
+    tokens: number;
+    activeSnapshot?: TaskSnapshot | null;
+    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. */
+    ambientState?: AmbientState;
+}
+//# sourceMappingURL=context-types.d.ts.map

package/dist/api/context-types.js

@@ -0,0 +1,3 @@
+// Option and result shapes for getContext.
+export {};
+//# sourceMappingURL=context-types.js.map