hippo-memory 1.56.0 → 1.58.0

package/dist/project-briefs.js

@@ -21,8 +21,11 @@
  * Lifecycle: active -> superseded (a newer version replaces it) or active ->
  * closed (retired).
  */
+import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, assertTenantId, RECALL_DEFAULT_DENY_SCOPES } from './store.js';
+import { writeEntry } from './store.js';
+import { assertTenantId } from './tenant.js';
+import { RECALL_DEFAULT_DENY_SCOPES } from './recall-scope.js';
 import { markGraphDirty, removeGraphEntitiesForObject } from './graph.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
@@ -54,21 +57,21 @@ export const MAX_RECEIPT_HEADLINE_LEN = 200;
 function validateBriefFields(repo, summary, changeSummary) {
     const normalizedRepo = (repo ?? '').trim();
     if (normalizedRepo.length === 0)
-        throw new Error('saveProjectBrief: repo is required');
+        throw new BadRequestError('saveProjectBrief: repo is required');
     if (/[\r\n]/.test(normalizedRepo)) {
-        throw new Error('saveProjectBrief: repo must be a single line (no newlines)');
+        throw new BadRequestError('saveProjectBrief: repo must be a single line (no newlines)');
     }
     if (normalizedRepo.length > MAX_REPO_LEN) {
-        throw new Error(`saveProjectBrief: repo exceeds the ${MAX_REPO_LEN}-char cap`);
+        throw new BadRequestError(`saveProjectBrief: repo exceeds the ${MAX_REPO_LEN}-char cap`);
     }
     if (!summary || summary.trim().length === 0) {
-        throw new Error('saveProjectBrief: summary is required');
+        throw new BadRequestError('saveProjectBrief: summary is required');
     }
     if (summary.length > MAX_BRIEF_SUMMARY_LEN) {
-        throw new Error(`saveProjectBrief: summary exceeds the ${MAX_BRIEF_SUMMARY_LEN}-char cap`);
+        throw new BadRequestError(`saveProjectBrief: summary exceeds the ${MAX_BRIEF_SUMMARY_LEN}-char cap`);
     }
     if (changeSummary !== undefined && changeSummary.length > MAX_CHANGE_SUMMARY_LEN) {
-        throw new Error(`saveProjectBrief: changeSummary exceeds the ${MAX_CHANGE_SUMMARY_LEN}-char cap`);
+        throw new BadRequestError(`saveProjectBrief: changeSummary exceeds the ${MAX_CHANGE_SUMMARY_LEN}-char cap`);
     }
     return { repo: normalizedRepo };
 }
@@ -143,10 +146,10 @@ export function saveProjectBrief(hippoRoot, tenantId, opts, actor = 'cli') {
                 // shape for the matching row, or undefined when no brief/tenant pair matches.
                 const pred = db.prepare(`SELECT status, version FROM project_briefs WHERE id = ? AND tenant_id = ?`).get(opts.supersedesBriefId, tenantId);
                 if (!pred) {
-                    throw new Error(`saveProjectBrief: brief ${opts.supersedesBriefId} to supersede not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`saveProjectBrief: brief ${opts.supersedesBriefId} to supersede not found for tenant ${tenantId}`);
                 }
                 if (pred.status !== 'active') {
-                    throw new Error(`saveProjectBrief: brief ${opts.supersedesBriefId} is not active (status='${pred.status}'); only active briefs can be superseded.`);
+                    throw new ConflictError(`saveProjectBrief: brief ${opts.supersedesBriefId} is not active (status='${pred.status}'); only active briefs can be superseded.`);
                 }
                 version = pred.version + 1;
             }
@@ -164,7 +167,7 @@ export function saveProjectBrief(hippoRoot, tenantId, opts, actor = 'cli') {
           WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
         `).run(briefId, now, opts.supersedesBriefId, tenantId, briefId);
                 if (sup.changes === 0) {
-                    throw new Error(`saveProjectBrief: brief ${opts.supersedesBriefId} could not be superseded (no longer active or self-reference).`);
+                    throw new ConflictError(`saveProjectBrief: brief ${opts.supersedesBriefId} could not be superseded (no longer active or self-reference).`);
                 }
                 appendAuditEvent(db, {
                     tenantId,
@@ -232,9 +235,9 @@ export function closeProjectBrief(hippoRoot, tenantId, id, actor = 'cli') {
                 // shape, or undefined when the id/tenant pair doesn't exist.
                 const existing = db.prepare(`SELECT status FROM project_briefs WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closeProjectBrief: brief ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closeProjectBrief: brief ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closeProjectBrief: brief ${id} is not active (status='${existing.status}'); only active briefs can be closed.`);
+                throw new ConflictError(`closeProjectBrief: brief ${id} is not active (status='${existing.status}'); only active briefs can be closed.`);
             }
             // SAFETY: SELECT ${BRIEF_COLS} projects exactly the ProjectBriefRow
             // columns; .get() returns that row for the just-updated id, or undefined
@@ -242,7 +245,7 @@ export function closeProjectBrief(hippoRoot, tenantId, id, actor = 'cli') {
             const row = db.prepare(`SELECT ${BRIEF_COLS} FROM project_briefs WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`closeProjectBrief: brief ${id} not found after UPDATE`);
+                throw new NotFoundError(`closeProjectBrief: brief ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -296,7 +299,7 @@ export function loadProjectBriefs(hippoRoot, tenantId, opts = {}) {
     assertTenantId('loadProjectBriefs', tenantId);
     const limit = opts.limit ?? 100;
     if (opts.status && !VALID_BRIEF_STATES.has(opts.status)) {
-        throw new Error(`loadProjectBriefs: status must be one of ${Array.from(VALID_BRIEF_STATES).join('|')}; got ${opts.status}`);
+        throw new BadRequestError(`loadProjectBriefs: status must be one of ${Array.from(VALID_BRIEF_STATES).join('|')}; got ${opts.status}`);
     }
     const db = openHippoDb(hippoRoot);
     try {
@@ -383,7 +386,7 @@ export function assembleBriefFromReceipts(hippoRoot, tenantId, repo) {
     assertTenantId('assembleBriefFromReceipts', tenantId);
     const normalizedRepo = (repo ?? '').trim();
     if (normalizedRepo.length === 0) {
-        throw new Error('assembleBriefFromReceipts: repo is required');
+        throw new BadRequestError('assembleBriefFromReceipts: repo is required');
     }
     const tag = `path:${normalizedRepo.toLowerCase()}`;
     const likeParam = `%"${escapeLike(tag)}"%`;
@@ -476,7 +479,7 @@ export function refreshBrief(hippoRoot, tenantId, repo, actor = 'cli') {
     assertTenantId('refreshBrief', tenantId);
     const normalizedRepo = (repo ?? '').trim();
     if (normalizedRepo.length === 0)
-        throw new Error('refreshBrief: repo is required');
+        throw new BadRequestError('refreshBrief: repo is required');
     const { markdown, receiptCount } = assembleBriefFromReceipts(hippoRoot, tenantId, normalizedRepo);
     const active = loadActiveBriefForRepo(hippoRoot, tenantId, normalizedRepo);
     return saveProjectBrief(hippoRoot, tenantId, {

package/dist/project-identity.d.ts

@@ -19,7 +19,7 @@
 export interface ProjectIdentity {
     /** Realpath-resolved root directory of the project (the start dir when not in a project). */
     root: string;
-    /** Lowercased basename of the project root; empty string when not in a project. */
+    /** Lowercased basename of the project root, or of its repo for a linked worktree with no `.hippo` (a store keeps the name its rows carry); '' outside a project. */
     name: string;
     /** True when the directory resolves to the user home working set. */
     isHome: boolean;

package/dist/project-identity.js

@@ -66,7 +66,8 @@ export function resolveProjectIdentity(cwd, opts) {
     let identity;
     const root = hippoRoot ?? gitRoot;
     if (root !== null) {
-        identity = { root, name: path.basename(root).toLowerCase(), isHome: false };
+        const name = (hippoRoot === null ? linkedWorktreeRepoName(root, home) : null) ?? path.basename(root).toLowerCase();
+        identity = { root, name, isHome: false };
     }
     else if (reachedHome || isUnder(start, home)) {
         identity = { root: home, name: '', isHome: true };
@@ -80,6 +81,29 @@ export function resolveProjectIdentity(cwd, opts) {
         identityCache.set(startInput, identity);
     return identity;
 }
+/** The repo name a linked worktree shares with its main checkout (`repo.git` or `repo/.bare` for a bare repo), so one repo is one project; null for any other checkout. */
+function linkedWorktreeRepoName(gitRoot, home) {
+    const marker = path.join(gitRoot, '.git');
+    if (!fs.existsSync(marker) || isDirectoryAt(marker))
+        return null;
+    try {
+        const gitDir = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(marker, 'utf8'))?.[1]?.trim();
+        if (!gitDir)
+            return null;
+        const linkDir = path.resolve(gitRoot, gitDir);
+        const commondir = path.join(linkDir, 'commondir');
+        if (!fs.existsSync(commondir))
+            return null; // a submodule's or a separate git dir's own checkout
+        const common = realpathOrResolve(path.resolve(linkDir, fs.readFileSync(commondir, 'utf8').trim()));
+        const repo = ['.git', '.bare'].includes(path.basename(common)) ? path.dirname(common) : common;
+        if (samePath(repo, home))
+            return null; // a dotfiles repo at home must not make its worktrees user-global
+        return path.basename(repo).replace(/\.git$/i, '').toLowerCase() || null;
+    }
+    catch {
+        return null; // an unreadable link is still a checkout, named after its own folder
+    }
+}
 /** Climb from start toward the root; home (never a project) and every stop dir end the walk unchecked. */
 function walkProjectMarkers(start, home, stopDirs) {
     let hippoRoot = null;

package/dist/prompt-recall.js

@@ -1,6 +1,6 @@
 /** Z1: recall gated on the hook prompt, not the five newest memories (pure, no I/O).
  *  See docs/plans/2026-09-26-z1-prompt-recall.md. */
-import { tokenize } from './search.js';
+import { tokenize } from './tokenize.js';
 import { STOP_WORDS } from './audit.js';
 // Latency bound, not tuned: fixed in the prereg regardless of gate config.
 export const PROMPT_RECALL_MAX_CHARS = 4000;

package/dist/raw-archive.js

@@ -1,5 +1,6 @@
+import { BadRequestError, NotFoundError } from './api-errors.js';
 import { isFtsAvailable } from './db.js';
-import { appendAuditEvent } from './audit.js';
+import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { markSummaryDirtyInTx } from './store.js';
 export function archiveRawMemory(db, id, opts) {
     // SAFETY: SELECT * FROM memories returns every column of the memories table; only
@@ -7,9 +8,9 @@ export function archiveRawMemory(db, id, opts) {
     // null) by the memories schema.
     const row = db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id);
     if (!row)
-        throw new Error(`memory not found: ${id}`);
+        throw new NotFoundError(`memory not found: ${id}`);
     if (row.kind !== 'raw') {
-        throw new Error(`memory ${id} is not raw (kind=${String(row.kind)})`);
+        throw new BadRequestError(`memory ${id} is not raw (kind=${String(row.kind)})`);
     }
     // SAVEPOINT (not BEGIN) so this works whether or not we're already inside a
     // transaction. SQLite refuses BEGIN within a transaction; SAVEPOINT nests safely.
@@ -58,9 +59,9 @@ export function archiveRawMemory(db, id, opts) {
                 metadata: { reason: opts.reason },
             });
         }
-        catch {
-            // Audit must not crash the archive. Failures here mean the audit table
-            // is unwritable; the archive itself has already succeeded.
+        catch (error) {
+            // The archive itself has already succeeded; an unwritable audit table must not undo it.
+            reportAuditWriteFailure('archive_raw', String(error), id);
         }
         // v0.30 / E2 — DAG live-coupling: archive of a child under a level-2
         // summary marks parent dirty. Inside the SAVEPOINT so the dirty-mark

package/dist/recall-history.d.ts

@@ -124,4 +124,9 @@ export declare function getOrCreateRing(map: Map<string, RingBuffer>, key: strin
 export declare function appendRecall(ring: RingBuffer, queryHash: number, topMemoryId: string | null, anchoredOn?: string): void;
 /** Snapshot a ring as a readonly RecallHistorySnapshot. */
 export declare function snapshotRing(ring: RingBuffer): RecallHistorySnapshot;
+/**
+ * Whether a recall bias hint is enabled. Reads the env at call time, so
+ * `HIPPO_ANCHORING=off` or `HIPPO_AVAILABILITY=off` disables only that kind.
+ */
+export declare function biasHintEnabled(kind: 'anchoring' | 'availability'): boolean;
 //# sourceMappingURL=recall-history.d.ts.map

package/dist/recall-history.js

@@ -232,4 +232,13 @@ export function appendRecall(ring, queryHash, topMemoryId, anchoredOn) {
 export function snapshotRing(ring) {
     return ring.snapshot();
 }
+/**
+ * Whether a recall bias hint is enabled. Reads the env at call time, so
+ * `HIPPO_ANCHORING=off` or `HIPPO_AVAILABILITY=off` disables only that kind.
+ */
+export function biasHintEnabled(kind) {
+    return kind === 'anchoring'
+        ? process.env.HIPPO_ANCHORING !== 'off'
+        : process.env.HIPPO_AVAILABILITY !== 'off';
+}
 //# sourceMappingURL=recall-history.js.map

package/dist/recall-pipeline.d.ts

@@ -0,0 +1,101 @@
+import { type GoalRecallLogRow } from './goals.js';
+import { type MemoryEntry } from './memory.js';
+import type { PhysicsConfig } from './physics-config.js';
+import type { RerankerFn } from './rerankers/types.js';
+import { type ResultCost, type SearchResult } from './search.js';
+/** Stores rankRecall reads and where it sends operator notes. */
+export interface RankRecallCtx {
+    hippoRoot: string;
+    /** A second store searched beside `hippoRoot`; leave undefined when there is none. */
+    globalRoot?: string;
+    tenantId: string;
+    /** Receives each operator note when the pipeline reaches it, so it interleaves with other stderr in order. */
+    note?: (line: string) => void;
+}
+/** Search-engine choice and tuning. */
+export interface RecallSearchOpts {
+    usePhysics: boolean;
+    physicsConfig: PhysicsConfig;
+    multihop: boolean;
+    /** Graph-stream rrf fusion over the local store; hop and seed counts fall back to the engine defaults. */
+    graphStream?: RecallGraphStream;
+    mmr: boolean;
+    mmrLambda: number;
+    localBump: number;
+    minResults?: number;
+    /** Score breakdowns for `hippo explain`; explain's physics call also leaves out the bi-temporal flags. */
+    explain: boolean;
+}
+/** `--graph-hops` and `--graph-seeds`. */
+export interface RecallGraphStream {
+    hops?: number;
+    seeds?: number;
+}
+/** `--hops` and `--max-neighbors`. */
+export interface RecallGraphHops {
+    hops: number;
+    maxNeighbors: number;
+}
+/** A reranker from the registry and how many head rows it sees. */
+export interface RecallReranker {
+    fn: RerankerFn;
+    topK: number;
+}
+/** A stage rankRecall can stop before, in pipeline order. */
+export type RankStage = 'expand' | 'rerank' | 'salience' | 'outcome' | 'layer';
+/** Everything that shapes one ranking, already parsed and validated. */
+export interface RankRecallOpts {
+    query: string;
+    /** Tokens the engines may spend, priced by `cost`. */
+    budget: number;
+    /** Price of one result, usually the tokens its printed line takes. */
+    cost: ResultCost;
+    limit: number;
+    /** Record a rerank trace step for each score change. */
+    why?: boolean;
+    includeSuperseded: boolean;
+    asOf?: string;
+    /** `--scope`: unlocks that envelope scope on top of the default-admitted set. */
+    explicitScope: string | null;
+    /** Scope used for boosting only, never for filtering. */
+    activeScope: string | null;
+    search: RecallSearchOpts;
+    graphHops?: RecallGraphHops;
+    evcAdaptive?: boolean;
+    filterConflicts?: boolean;
+    valueAware?: boolean;
+    rerankUtility?: boolean;
+    reranker?: RecallReranker;
+    /** Explicit goal tag; when set, the session goal stack is skipped. */
+    goalTag?: string;
+    /** Session whose active goals boost matching rows. */
+    sessionId?: string;
+    salienceThreshold?: number;
+    outcome?: string;
+    layer?: string;
+    /** The caller rejected a flag this stage reads; ranking stops before it so the notes and goal-log rows
+     *  produced up to there match the CLI's error path. */
+    haltBefore?: RankStage;
+}
+/** Ranked results and what the caller needs to report and persist them. */
+export interface RankRecallResult {
+    results: SearchResult[];
+    /** The candidate pools after the scope and bi-temporal filters. */
+    localEntries: MemoryEntry[];
+    globalEntries: MemoryEntry[];
+    /** Candidates loaded, before any filter. */
+    totalCandidates: number;
+    /** Rows dropped by a named filter (scope, bi-temporal, conflicts, outcome, layer). */
+    droppedPreRank: number;
+    /** Rows graph expansion surfaced that the lexical pool never held. */
+    graphAdded: number;
+    /** goal_recall_log rows the session goal boost earned; the caller writes them. */
+    goalRecallLog: GoalRecallLogRow[];
+    /** True when ranking stopped at `haltBefore`. */
+    halted: boolean;
+}
+/** Ranks memories for a query as `hippo recall` does, through the `limit` slice. Reads stores, embeddings and
+ *  physics state; writes nothing and prints nothing (notes go to `ctx.note`). The caller supplies the cost
+ *  function and reranker in `opts`, and persists the returned goal-log rows. */
+export declare function rankRecall(ctx: RankRecallCtx, opts: RankRecallOpts): Promise<RankRecallResult>;
+//# sourceMappingURL=recall-pipeline.d.ts.map

package/dist/recall-pipeline.js

@@ -0,0 +1,313 @@
+// Ranking core shared by `hippo recall` and `hippo explain`: load, search, expand, re-rank and filter, with no
+// writes and no direct output. Callers own flag parsing, printing, budget fitting and persistence.
+import { evalNow } from './ablation.js';
+import { oneCopyPerMemory } from './api.js';
+import { compareEntryIdentity } from './compare.js';
+import { closeHippoDb, openHippoDb } from './db.js';
+import { isEmbeddingAvailable } from './embeddings.js';
+import { computeGoalStackBoost } from './goals.js';
+import { graphExpandRecall } from './graph-recall.js';
+import { DEFAULT_GRAPH_STREAM_WEIGHT } from './graph-stream.js';
+import { Layer } from './memory.js';
+import { multihopSearch } from './multihop.js';
+import { passesCliRecallScopeFilter } from './recall-scope.js';
+import { hybridSearch, physicsSearch, textOverlap } from './search.js';
+import { searchBothHybrid } from './shared.js';
+import { loadRecallSearchEntries } from './store.js';
+import { tokenize as tokenizeQuery } from './tokenize.js';
+/** Ranks memories for a query as `hippo recall` does, through the `limit` slice. Reads stores, embeddings and
+ *  physics state; writes nothing and prints nothing (notes go to `ctx.note`). The caller supplies the cost
+ *  function and reranker in `opts`, and persists the returned goal-log rows. */
+export async function rankRecall(ctx, opts) {
+    const pool = loadRecallPool(ctx, opts);
+    const state = { results: [], droppedPreRank: pool.dropped, graphAdded: 0, goalRecallLog: [] };
+    const done = (halted) => ({
+        results: state.results,
+        localEntries: pool.local,
+        globalEntries: pool.global,
+        totalCandidates: pool.total,
+        droppedPreRank: state.droppedPreRank,
+        graphAdded: state.graphAdded,
+        goalRecallLog: state.goalRecallLog,
+        halted,
+    });
+    state.results = await searchPool(ctx, opts, pool);
+    if (opts.haltBefore === 'expand')
+        return done(true);
+    if (opts.graphHops)
+        expandGraph(ctx, opts, opts.graphHops, state);
+    applyPfcRerankers(opts, state);
+    if (opts.haltBefore === 'rerank')
+        return done(true);
+    if (opts.reranker)
+        state.results = await applyReranker(opts, opts.reranker, state.results);
+    applyGoalBoosts(ctx, opts, state);
+    if (opts.haltBefore === 'salience')
+        return done(true);
+    if (opts.salienceThreshold !== undefined)
+        state.results = applySalience(opts, opts.salienceThreshold, state.results);
+    if (opts.haltBefore === 'outcome')
+        return done(true);
+    if (opts.outcome)
+        dropUnless(state, (r) => r.entry.layer !== Layer.Trace || r.entry.trace_outcome === opts.outcome);
+    if (opts.haltBefore === 'layer')
+        return done(true);
+    if (opts.layer)
+        dropUnless(state, (r) => r.entry.layer === opts.layer);
+    if (opts.limit < state.results.length)
+        state.results = state.results.slice(0, opts.limit);
+    return done(false);
+}
+function loadRecallPool(ctx, opts) {
+    // An explicit --scope unlocks that envelope scope; the regex-only `<source>:private:*` deny is the JS half below.
+    const requested = opts.explicitScope || undefined;
+    const loadSuperseded = opts.includeSuperseded || Boolean(opts.asOf);
+    let local = loadRecallSearchEntries(ctx.hippoRoot, opts.query, undefined, ctx.tenantId, requested, 'additive', loadSuperseded);
+    let global = ctx.globalRoot
+        ? loadRecallSearchEntries(ctx.globalRoot, opts.query, undefined, ctx.tenantId, requested, 'additive', loadSuperseded)
+        : [];
+    // SQL-excluded rows are pre-candidate, so the total is taken before the JS filters, which normally drop nothing.
+    const total = local.length + global.length;
+    const passes = (e) => passesCliRecallScopeFilter(e.scope ?? null, requested);
+    local = local.filter(passes);
+    global = global.filter(passes);
+    if (opts.asOf) {
+        local = currentAsOf(local, opts.asOf);
+        global = currentAsOf(global, opts.asOf);
+    }
+    else if (!opts.includeSuperseded) {
+        local = local.filter((e) => !e.superseded_by);
+        global = global.filter((e) => !e.superseded_by);
+    }
+    return { local, global, total, dropped: total - (local.length + global.length) };
+}
+/** Rows that were true at `asOf`: valid by then, and not yet replaced by a successor in the same pool. */
+function currentAsOf(entries, asOf) {
+    const asOfDate = new Date(asOf);
+    const successorValidFrom = new Map();
+    for (const e of entries) {
+        if (e.superseded_by) {
+            const successor = entries.find(s => s.id === e.superseded_by);
+            if (successor)
+                successorValidFrom.set(e.id, successor.valid_from);
+        }
+    }
+    return entries.filter(e => {
+        if (new Date(e.valid_from) > asOfDate)
+            return false;
+        if (!e.superseded_by)
+            return true;
+        const succVf = successorValidFrom.get(e.id);
+        return succVf ? new Date(succVf) > asOfDate : true;
+    });
+}
+async function searchPool(ctx, opts, pool) {
+    const { query, budget, cost, includeSuperseded, asOf, activeScope: scope, search } = opts;
+    const { mmr, mmrLambda, minResults, explain } = search;
+    const globalRoot = pool.global.length > 0 ? ctx.globalRoot : undefined;
+    if (search.graphStream) {
+        // Without embeddings hybridSearch falls back to BM25-only and the stream is inert; say so rather than no-op.
+        if (!isEmbeddingAvailable()) {
+            ctx.note?.('[note] --graph-stream needs embeddings (rrf fusion); none available, so the graph stream is inert. Run `hippo embed` first.');
+        }
+        if (globalRoot)
+            ctx.note?.('[note] --graph-stream searches the local store only; global graph fusion is a follow-up.');
+        // With seedCount or fewer candidates every one is a seed and the stream degrades to the 2-list fusion.
+        return hybridSearch(query, pool.local, {
+            budget, cost, hippoRoot: ctx.hippoRoot, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf,
+            scoring: 'rrf',
+            graphStream: { weight: DEFAULT_GRAPH_STREAM_WEIGHT, tenantId: ctx.tenantId, hops: search.graphStream.hops, seedCount: search.graphStream.seeds },
+        });
+    }
+    if (search.multihop) {
+        // Unlike searchBothHybrid below, multihop ranks one pooled list, so a shared memory's two copies both compete.
+        const allEntries = oneCopyPerMemory(pool.local, pool.global, evalNow()).flat();
+        return multihopSearch(query, allEntries, { budget, cost, hippoRoot: ctx.hippoRoot, minResults, includeSuperseded, asOf });
+    }
+    if (search.usePhysics && !globalRoot) {
+        // Explain has never passed the bi-temporal flags to physics; keeping that holds its output steady.
+        const temporal = explain ? {} : { minResults, includeSuperseded, asOf };
+        return physicsSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, physicsConfig: search.physicsConfig, scope, explain, ...temporal });
+    }
+    if (globalRoot) {
+        // searchBothHybrid reloads candidates itself, so the scope rule is passed in rather than inherited from the pool.
+        return searchBothHybrid(query, ctx.hippoRoot, globalRoot, {
+            budget, cost, explain, mmr, mmrLambda, localBump: search.localBump, minResults, scope, tenantId: ctx.tenantId,
+            includeSuperseded, asOf,
+            recallScope: opts.explicitScope ? { requested: opts.explicitScope, additive: true } : {},
+        });
+    }
+    return hybridSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, explain, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf });
+}
+/** Adds memories reached by walking the entity graph out from the lexical seeds. */
+function expandGraph(ctx, opts, graph, state) {
+    if (graph.hops <= 0)
+        return;
+    // Expansion both adds neighbours and evicts weak base rows, so compare id sets: a net count would hide both.
+    const beforeGraphIds = new Set(state.results.map((r) => r.entry.id));
+    state.results = graphExpandRecall(state.results, {
+        hops: graph.hops,
+        maxNeighbors: graph.maxNeighbors,
+        hippoRoot: ctx.hippoRoot,
+        globalRoot: ctx.globalRoot !== ctx.hippoRoot ? ctx.globalRoot : undefined,
+        tenantId: ctx.tenantId,
+        includeSuperseded: opts.includeSuperseded,
+        asOf: opts.asOf,
+        budget: opts.budget,
+        cost: opts.cost,
+        minResults: opts.search.minResults ?? 1,
+        recallScope: opts.explicitScope ? { requested: opts.explicitScope, additive: true } : {},
+    });
+    for (const r of state.results) {
+        if (!beforeGraphIds.has(r.entry.id))
+            state.graphAdded++;
+    }
+}
+/** Appends one rerank step to a re-scored row when `why` is on. */
+function traced(opts, prev, next, step) {
+    if (opts.why)
+        next.rerankTrace = [...(prev.rerankTrace ?? []), step];
+    return next;
+}
+/** Re-sort after a score change. Plain and stable on purpose: ties keep the prior rank, not a content order. */
+function byScore(results) {
+    return results.sort((a, b) => b.score - a.score);
+}
+function applyPfcRerankers(opts, state) {
+    if (opts.evcAdaptive && state.results.length >= 2)
+        state.results = evcAdaptive(opts.query, state.results);
+    if (opts.filterConflicts) {
+        dropUnless(state, (r) => !r.entry.superseded_by);
+        // Recorded conflicts only: a lexical-overlap gate once wrecked benchmark recall. Down-rank, never delete.
+        const presentIds = new Set(state.results.map((r) => r.entry.id));
+        state.results = byScore(state.results.map((r) => {
+            const hasPeerInResults = (r.entry.conflicts_with || []).some((peerId) => presentIds.has(peerId));
+            if (!hasPeerInResults)
+                return r;
+            const next = { ...r, score: r.score * 0.3 };
+            return traced(opts, r, next, { stage: 'interference', multiplier: 0.3, scoreBefore: r.score, scoreAfter: next.score });
+        }));
+    }
+    if (opts.valueAware && state.results.length >= 1) {
+        // Wider clamp than the always-on outcome boost, so outcome history can decide the order.
+        state.results = byScore(state.results.map((r) => {
+            const pos = r.entry.outcome_positive ?? 0;
+            const neg = r.entry.outcome_negative ?? 0;
+            if (pos === 0 && neg === 0)
+                return r;
+            const valueMult = Math.max(0.7, Math.min(1.3, 1 + 0.3 * Math.tanh(pos - neg)));
+            const next = { ...r, score: r.score * valueMult };
+            return traced(opts, r, next, { stage: 'value', multiplier: valueMult, scoreBefore: r.score, scoreAfter: next.score });
+        }));
+    }
+    if (opts.rerankUtility) {
+        // utility = score * (0.5 + 0.5 * strength) * (1 - min(0.3, tokens / 10000)); long evidence-rich rows pay for length.
+        state.results = byScore(state.results.map((r) => {
+            const strength = typeof r.entry.strength === 'number' ? r.entry.strength : 1.0;
+            const utilityMult = (0.5 + 0.5 * strength) * (1 - Math.min(0.3, (r.tokens || 0) / 10000));
+            const utility = r.score * utilityMult;
+            return traced(opts, r, { ...r, score: utility }, { stage: 'utility', multiplier: utilityMult, scoreBefore: r.score, scoreAfter: utility });
+        }));
+    }
+}
+/** When the top hits are near-duplicates (same topic, different facts), surface the newest on-topic row first. */
+function evcAdaptive(query, results) {
+    const slice = results.slice(0, Math.min(3, results.length));
+    let pairs = 0;
+    let overlapSum = 0;
+    for (let i = 0; i < slice.length; i++) {
+        for (let j = i + 1; j < slice.length; j++) {
+            overlapSum += textOverlap(slice[i].entry.content, slice[j].entry.content);
+            pairs++;
+        }
+    }
+    if ((pairs > 0 ? overlapSum / pairs : 0) < 0.4)
+        return results;
+    const poolSize = Math.min(results.length, Math.max(slice.length * 3, 9));
+    const pool = results.slice(0, poolSize);
+    const scoreFloor = pool.reduce((m, r) => Math.max(m, r.score), 0) * 0.5;
+    // Query coverage catches the differently phrased update a score floor alone would miss.
+    const queryTokens = new Set(tokenizeQuery(query));
+    const onTopic = [];
+    const offTopic = [];
+    for (const r of pool) {
+        let hits = 0;
+        if (queryTokens.size > 0) {
+            const candTokens = new Set(tokenizeQuery(r.entry.content));
+            for (const t of queryTokens)
+                if (candTokens.has(t))
+                    hits++;
+        }
+        const queryCoverage = queryTokens.size > 0 ? hits / queryTokens.size : 0;
+        (r.score >= scoreFloor || queryCoverage >= 0.6 ? onTopic : offTopic).push(r);
+    }
+    // Recency is the primary key; identity only breaks exact-timestamp ties.
+    onTopic.sort((a, b) => {
+        const ta = new Date(a.entry.created).getTime();
+        const tb = new Date(b.entry.created).getTime();
+        return tb !== ta ? tb - ta : compareEntryIdentity(a.entry, b.entry);
+    });
+    return [...onTopic, ...offTopic, ...results.slice(poolSize)];
+}
+async function applyReranker(opts, reranker, results) {
+    const { fn, topK } = reranker;
+    const rerankInput = results.slice(0, topK).map((r, i) => ({ ...r, preRerankRank: i + 1 }));
+    const reranked = await fn(opts.query, rerankInput, { topK });
+    // The reranker's score becomes `score` so later stages that sort by score keep its order.
+    const withPostRank = reranked.map((r, i) => traced(opts, r, { ...r, score: r.rerankScore, postRerankRank: i + 1 }, { stage: 'reranker', scoreBefore: r.score, scoreAfter: r.rerankScore }));
+    return [...withPostRank, ...results.slice(topK)];
+}
+function applyGoalBoosts(ctx, opts, state) {
+    const goalTag = opts.goalTag ?? '';
+    if (goalTag) {
+        // Its own trace stage: `goal` is the explicit flag, `goal-boost` the session stack it replaces.
+        state.results = byScore(state.results.map((r) => {
+            if (!r.entry.tags?.includes(goalTag))
+                return r;
+            const boosted = { ...r, score: r.score * 1.5 };
+            return traced(opts, r, boosted, { stage: 'goal', multiplier: 1.5, scoreBefore: r.score, scoreAfter: r.score * 1.5, note: `--goal ${goalTag}` });
+        }));
+        return;
+    }
+    if (!opts.sessionId)
+        return;
+    const db = openHippoDb(ctx.hippoRoot);
+    // The helper re-spreads rows, so its steps come back in a map keyed by entry id.
+    const goalBoostTrace = opts.why ? new Map() : undefined;
+    try {
+        const boost = computeGoalStackBoost(db, state.results, {
+            sessionId: opts.sessionId,
+            tenantId: ctx.tenantId,
+            limit: opts.limit,
+            trace: goalBoostTrace,
+        });
+        state.results = boost.results;
+        state.goalRecallLog = boost.log;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    if (goalBoostTrace && goalBoostTrace.size > 0) {
+        state.results = state.results.map((r) => {
+            const step = goalBoostTrace.get(r.entry.id);
+            return step ? { ...r, rerankTrace: [...(r.rerankTrace ?? []), step] } : r;
+        });
+    }
+}
+/** Soft-demotes rarely recalled rows: score *= max(0.5, retrieval_count / T); never drops one. */
+function applySalience(opts, threshold, results) {
+    return byScore(results.map((r) => {
+        const count = r.entry.retrieval_count ?? 0;
+        if (count >= threshold)
+            return r;
+        const mult = Math.max(0.5, count / threshold);
+        const next = { ...r, score: r.score * mult };
+        return traced(opts, r, next, { stage: 'retrieval-count-downweight', multiplier: mult, scoreBefore: r.score, scoreAfter: next.score });
+    }));
+}
+function dropUnless(state, keep) {
+    const before = state.results.length;
+    state.results = state.results.filter(keep);
+    state.droppedPreRank += before - state.results.length;
+}
+//# sourceMappingURL=recall-pipeline.js.map