hippo-memory 1.55.0 → 1.57.0

package/dist/memory.js

@@ -471,4 +471,42 @@ function inferValence(tags) {
         return 'positive';
     return 'neutral';
 }
+/**
+ * Update retrieval metadata on entries that were returned by a search.
+ * Returns the mutated copies (caller must persist to disk).
+ *
+ * EVAL-ONLY ablation (see ablation.ts): with HIPPO_ABLATE_RECALL_BOOST set,
+ * this returns the entries UNMUTATED - neutralizing all three strengthening
+ * sub-effects (clock reset, retrieval_count, half-life increment) at the
+ * single shared write site. The entries (not an empty array) must be
+ * returned because callers derive `last_retrieval_ids` from the return
+ * value, and a later `hippo outcome --good/--bad` targets those ids - an
+ * empty return would silently co-ablate the outcome channel in the
+ * strengthen-off arm. PERSISTENCE is gated separately at
+ * each persisting caller (CLI recall, api context, MCP recall/context,
+ * consolidation replay): writeEntry on identical rows still refreshes
+ * updated_at, rewrites mirrors, and marks DAG parents dirty,
+ * so those write loops skip under the flag.
+ * The default `now` honors HIPPO_FAKE_NOW (simulated-time protocols).
+ */
+// Confidence is deliberately absent below: it is an epistemic tier, not a
+// recency signal, and a stored 'stale' is always a deliberate mark.
+export function markRetrieved(entries, now = evalNow()) {
+    if (isRecallBoostAblated())
+        return entries;
+    return entries.map((e) => {
+        if (e.superseded_by)
+            return e;
+        const wrong = netWrong(e) > 0;
+        const updated = {
+            ...e,
+            retrieval_count: e.retrieval_count + 1,
+            last_retrieved: wrong ? e.last_retrieved : now.toISOString(),
+            // +2 days half-life per retrieval (PLAN.md); a wrong memory keeps both, since last_retrieved is the decay anchor
+            half_life_days: wrong ? e.half_life_days : e.half_life_days + 2,
+        };
+        updated.strength = calculateStrength(updated, now);
+        return updated;
+    });
+}
 //# sourceMappingURL=memory.js.map

package/dist/policies.js

@@ -37,7 +37,8 @@
  * supersede, the predecessor's UPDATE) inside writeEntry's SAVEPOINT.
  */
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, assertTenantId } from './store.js';
+import { writeEntry } from './store.js';
+import { assertTenantId } from './tenant.js';
 import { markGraphDirty, removeGraphEntitiesForObject } from './graph.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';

package/dist/predictions.js

@@ -25,7 +25,8 @@
  * this module ships the data layer.
  */
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, assertTenantId } from './store.js';
+import { writeEntry } from './store.js';
+import { assertTenantId } from './tenant.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
 import { loadConfig } from './config.js';

package/dist/processes.js

@@ -31,7 +31,8 @@
  * them back. Pattern matches saveDecision (decisions.ts).
  */
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, assertTenantId } from './store.js';
+import { writeEntry } from './store.js';
+import { assertTenantId } from './tenant.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
 import { objectHalfLifeDays } from './half-life-migration.js';

package/dist/project-briefs.js

@@ -22,7 +22,9 @@
  * closed (retired).
  */
 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';

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/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

package/dist/recall-scope.d.ts

@@ -6,6 +6,28 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
+/**
+ * Literal scopes excluded from recall by default-deny when the
+ * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
+ * helper `passesScopeFilterForRecall` (src/api.ts) both read from this
+ * constant. Adding a deny scope is a one-place change.
+ *
+ * Regex-based denies (e.g. `<source>:private:*`) stay in
+ * `passesScopeFilterForRecall` as a separate JS step — they don't translate
+ * cleanly to SQL.
+ *
+ * Invariant: never empty. An empty array would silently allow quarantine
+ * scopes through both paths (SQL clause omitted, JS check vacuous). The
+ * module-load assertion below pins this loudly.
+ */
+export declare const RECALL_DEFAULT_DENY_SCOPES: readonly ["unknown:legacy"];
+/**
+ * @internal Runtime guard against a future maintainer blanking a
+ * load-bearing literal array. Extracted from the inline guard so the throw
+ * path is directly testable. `as const` arrays widen via `readonly T[]` at
+ * the call site so the empty case is reachable at runtime.
+ */
+export declare function assertNonEmpty<T>(arr: readonly T[], name: string): void;
 /**
  * v1.2.1: source-agnostic private-scope detector. A scope string is treated
  * as private when it has the shape `<lowercase-source>:private:<rest>`.

package/dist/recall-scope.js

@@ -6,7 +6,33 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
-import { RECALL_DEFAULT_DENY_SCOPES } from './store.js';
+/**
+ * Literal scopes excluded from recall by default-deny when the
+ * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
+ * helper `passesScopeFilterForRecall` (src/api.ts) both read from this
+ * constant. Adding a deny scope is a one-place change.
+ *
+ * Regex-based denies (e.g. `<source>:private:*`) stay in
+ * `passesScopeFilterForRecall` as a separate JS step — they don't translate
+ * cleanly to SQL.
+ *
+ * Invariant: never empty. An empty array would silently allow quarantine
+ * scopes through both paths (SQL clause omitted, JS check vacuous). The
+ * module-load assertion below pins this loudly.
+ */
+export const RECALL_DEFAULT_DENY_SCOPES = ['unknown:legacy'];
+/**
+ * @internal Runtime guard against a future maintainer blanking a
+ * load-bearing literal array. Extracted from the inline guard so the throw
+ * path is directly testable. `as const` arrays widen via `readonly T[]` at
+ * the call site so the empty case is reachable at runtime.
+ */
+export function assertNonEmpty(arr, name) {
+    if (arr.length === 0) {
+        throw new Error(`${name} cannot be empty — would silently allow quarantine scopes`);
+    }
+}
+assertNonEmpty(RECALL_DEFAULT_DENY_SCOPES, 'RECALL_DEFAULT_DENY_SCOPES');
 /**
  * v1.2.1: source-agnostic private-scope detector. A scope string is treated
  * as private when it has the shape `<lowercase-source>:private:<rest>`.