hippo-memory 1.70.0 → 1.72.0

package/dist/api/prompt-hook.d.ts

@@ -1,9 +1,22 @@
 import { type Context, type ContextResult, type ContextResultEntry } from './index.js';
-import type { DeliveryRecorder } from '../store/delivery-recorder.js';
+import { type DeliveryEventType, type DeliveryRecorder } from '../store/delivery-recorder.js';
+import type { HookRuntime } from '../core/capture-contract.js';
 import { type JsonValue } from '../util/json.js';
 import type { MemoryEntry } from '../core/memory.js';
-import { type PilotArm } from './pilot-arm.js';
+import type { PilotArm } from '../store/pilot-arm.js';
 import type { DeliveryWrite } from '../store/ledger-turn.js';
+/** What a hook's delivery row says about the call it records. */
+export interface DeliveryStart {
+    stdinText: string | undefined;
+    runtime: HookRuntime;
+    eventType?: DeliveryEventType;
+    /** The host's own session id from its environment, used when the payload names none. */
+    envSessionId: string | undefined;
+}
+/** A delivery recorder for a hook on `ctx.hippoRoot` when the ledger store enables one, else null; never throws. */
+export declare function startDeliveryRecorder(ctx: Context, start: DeliveryStart): DeliveryRecorder | null;
+/** A recorder for `hippo capture-error`, only when the failure log and the ledger are one store, so `failure_id` never points into another. */
+export declare function startToolFailureRecorder(ctx: Context, start: Omit<DeliveryStart, 'eventType'>): DeliveryRecorder | null;
 /** With `write`, stores on the token ledger's connection (same store); without it, opens its own. A second flush is a no-op. */
 export declare function flushDeliveryRecorder(rec: DeliveryRecorder | null, write?: DeliveryWrite): void;
 /** What one render needs once api.getContext has answered. */
@@ -58,10 +71,10 @@ interface PromptHookOpts {
 }
 /** The caps on a hook caller's session id and project names, so a caller other than an HTTP route is bounded too. */
 export declare function assertCallerIds(sessionId: string, project: CallerProject): void;
-/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for the caller's project, leaving out an unchanged static block only when `printedHash` matches it.
- *  `arm` is the raw ledger arm (`hippo` or `holdout`), null at rate 0; a holdout session gets an empty stdout. `staticHash` is the hash to echo back: null with no static block, for a sub-agent or a holdout.
- *  Scope detection (HIPPO_SCOPE and skill env vars) and delivery-ledger events are CLI-only.
- *  Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
+/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for its project.
+ * Omits an unchanged static block only when `printedHash` matches; `arm` is the ledger arm (`hippo` or `holdout`, null at rate 0); a holdout gets empty stdout.
+ * `staticHash` is the hash to echo back (null with no static block, a sub-agent or a holdout). Scope detection and delivery-ledger events are CLI-only.
+ * Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
 export declare function promptHookContext(ctx: Context, req: PromptHookRequest, opts?: PromptHookOpts): Promise<{
     arm: PilotArm | null;
     stdout: string;

package/dist/api/prompt-hook.js

@@ -1,18 +1,60 @@
 // The per-prompt hook's block and ledger rows, rendered here for `hippo context` and for promptHookContext (a remote hook route's call).
-// promptHookContext keeps the server-side copy of the CLI's getContext flags (cli/context.ts); the CLI parity case in tests/prompt-hook-context.test.ts is all that ties the two.
+// promptHookContext keeps the server-side copy of the CLI's getContext flags (cli/context.ts);
+// the CLI parity case in tests/prompt-hook-context.test.ts is all that ties the two.
 import { getContext } from './index.js';
 import { BadRequestError } from '../core/api-errors.js';
 import { isSharedStore, loadConfig } from '../core/config.js';
 import { contextBlockLines, contextCost, crossProjectLines, handoffText, sessionTrailText, settleTokens, snapshotText } from './context-render.js';
-import { MAX_ID_LEN } from '../util/http-util.js';
+import { createDeliveryRecorder } from '../store/delivery-recorder.js';
+import { realpathOrResolve } from '../util/real-path.js';
+import { MAX_ID_LEN } from '../util/limits.js';
 import { isJsonString } from '../util/json.js';
-import { bookLedgerTurn, ledgerLastSent, noteLedgerRowSkipped } from './ledger-db.js';
+import { bookLedgerTurn, ledgerLastSent, ledgerRoot } from './ledger-db.js';
+import { noteLedgerRowSkipped } from '../store/ledger-turn.js';
 import { sessionPilotArm } from './pilot-arm.js';
-import { assertCallerProject, MAX_PROJECT_ALIASES } from '../core/project-identity.js';
+import { assertCallerProject, isGlobalStoreRoot, MAX_PROJECT_ALIASES } from '../core/project-identity.js';
 import { writeDeliveryEventAtRoot } from '../store/recall-trace.js';
-import { hookPayloadString, isSubagentPayload, shouldSkipUnchanged, } from '../store/token-ledger.js';
+import { shouldSkipUnchanged } from '../store/token-ledger.js';
+import { hookPayloadString, isSubagentPayload } from '../util/hook-payload.js';
 import { blockHash, estimateTokens } from '../util/token-text.js';
-import { errorMessage } from '../util/log.js';
+import { errorMessage, log } from '../util/log.js';
+import { DEFAULT_CONTEXT_BUDGET } from './context.js';
+/** A delivery recorder for a hook on `ctx.hippoRoot` when the ledger store enables one, else null; never throws. */
+export function startDeliveryRecorder(ctx, start) {
+    try {
+        // The same store the token ledger writes to, so its config governs both.
+        const root = ledgerRoot(ctx.hippoRoot);
+        if (root === null || !loadConfig(root).deliveryLedger.enabled)
+            return null;
+        return createDeliveryRecorder({
+            root,
+            storeHash: blockHash(realpathOrResolve(root)),
+            writeStore: isGlobalStoreRoot(root) ? 'global' : 'local',
+            tenantId: ctx.tenantId,
+            stdinText: start.stdinText,
+            envSessionId: start.envSessionId,
+            runtime: start.runtime === 'copilot' ? 'copilot' : undefined,
+            eventType: start.eventType,
+        });
+    }
+    catch (error) {
+        log.warn(`delivery ledger skipped: ${errorMessage(error)}`);
+        return null;
+    }
+}
+/** A recorder for `hippo capture-error`, only when the failure log and the ledger are one store, so `failure_id` never points into another. */
+export function startToolFailureRecorder(ctx, start) {
+    try {
+        const root = ledgerRoot(ctx.hippoRoot);
+        if (root === null || realpathOrResolve(root) !== realpathOrResolve(ctx.hippoRoot))
+            return null;
+        return startDeliveryRecorder(ctx, { ...start, eventType: 'tool-failure' });
+    }
+    catch (error) {
+        log.warn(`delivery ledger skipped: ${errorMessage(error)}`);
+        return null;
+    }
+}
 /** With `write`, stores on the token ledger's connection (same store); without it, opens its own. A second flush is a no-op. */
 export function flushDeliveryRecorder(rec, write) {
     if (rec === null)
@@ -21,8 +63,7 @@ export function flushDeliveryRecorder(rec, write) {
         rec.flush(write ?? ((input) => writeDeliveryEventAtRoot(rec.root, input)));
     }
     catch (error) {
-        // The hook's one-line stderr contract pins this exact text, so it bypasses the leveled logger.
-        console.error(`[hippo] delivery ledger write failed:${errorMessage(error)}`);
+        log.error(`delivery ledger write failed: ${errorMessage(error)}`);
     }
 }
 /** A Copilot sessionStart reply's wrapper, picked by the sender's casing: stdin.ts keeps a camelCase `sessionId`, which only the Copilot harness sends. */
@@ -143,7 +184,7 @@ function recordAdditionalContextRows(view, surface, staticPart, recallPart) {
 }
 // The flags HIPPO_PINNED_INJECT_COMMAND gives the local hook; the CLI parity test fails if the two drift.
 const HOOK_INCLUDE_RECENT = 5;
-const HOOK_BUDGET = 1500;
+const HOOK_BUDGET = DEFAULT_CONTEXT_BUDGET;
 const HOOK_FRAMING = 'observe';
 // blockHash's shape (token-ledger.ts).
 const BLOCK_HASH_RE = /^[0-9a-f]{16}$/;
@@ -162,10 +203,10 @@ function assertPromptHookRequest(req) {
         throw new BadRequestError('printed hash: 16 lowercase hex characters');
     }
 }
-/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for the caller's project, leaving out an unchanged static block only when `printedHash` matches it.
- *  `arm` is the raw ledger arm (`hippo` or `holdout`), null at rate 0; a holdout session gets an empty stdout. `staticHash` is the hash to echo back: null with no static block, for a sub-agent or a holdout.
- *  Scope detection (HIPPO_SCOPE and skill env vars) and delivery-ledger events are CLI-only.
- *  Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
+/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for its project.
+ * Omits an unchanged static block only when `printedHash` matches; `arm` is the ledger arm (`hippo` or `holdout`, null at rate 0); a holdout gets empty stdout.
+ * `staticHash` is the hash to echo back (null with no static block, a sub-agent or a holdout). Scope detection and delivery-ledger events are CLI-only.
+ * Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
 export async function promptHookContext(ctx, req, opts = {}) {
     assertPromptHookRequest(req);
     const { sessionId, payload } = req;

package/dist/api/provenance-coverage.d.ts

@@ -0,0 +1,14 @@
+import { MemoryEntry } from '../core/memory.js';
+export interface ProvenanceCoverage {
+    rawTotal: number;
+    rawWithEnvelope: number;
+    coverage: number;
+    gaps: Array<{
+        id: string;
+        missing: ('owner' | 'artifact_ref')[];
+    }>;
+}
+/** Provenance coverage gate: every `kind='raw'` row must carry `owner` and `artifact_ref`; derivative or terminal rows are excluded.
+ * Coverage 1.0 on a non-empty raw set is the ship gate. */
+export declare function buildProvenanceCoverage(entries: MemoryEntry[]): ProvenanceCoverage;
+//# sourceMappingURL=provenance-coverage.d.ts.map

package/dist/{cli → api}/provenance-coverage.js

@@ -1,9 +1,5 @@
-/**
- * Provenance coverage gate: every `kind='raw'` row must carry both `owner`
- * and `artifact_ref`. Distilled / superseded / archived rows are excluded —
- * those are derivative or terminal, not source receipts. Coverage of 1.0 on
- * a non-empty raw set is the ship gate from the Company Brain scorecard.
- */
+/** Provenance coverage gate: every `kind='raw'` row must carry `owner` and `artifact_ref`; derivative or terminal rows are excluded.
+ * Coverage 1.0 on a non-empty raw set is the ship gate. */
 export function buildProvenanceCoverage(entries) {
     const raws = entries.filter((e) => e.kind === 'raw');
     const gaps = [];

package/dist/api/recall-cli.d.ts

@@ -0,0 +1,58 @@
+import { confidenceFacets } from '../core/memory.js';
+import type { ResultCost, SearchResult } from '../core/search-types.js';
+import type { RerankerFn } from '../rerankers/types.js';
+import { explainMatch } from '../search/explain.js';
+import type { ContinuityBlock } from '../store/port.js';
+import type { Context } from './types.js';
+export { DEFAULT_MAX_NEIGHBORS, MAX_HOPS } from '../graph/recall.js';
+/** The global store beside this one, whether this one is it, and the scope that boosts rows. */
+export interface CliRecallSetting {
+    readonly globalRoot: string;
+    readonly primaryIsGlobal: boolean;
+    readonly activeScope: string | null;
+}
+/** The active scope merges `--scope` with the detected one, which only boosts. */
+export declare function cliRecallSetting(ctx: Context, explicitScope: string | null): CliRecallSetting;
+export interface CliRecallOrigin {
+    readonly globalOn: boolean;
+    /** True when a ranked row came from the global store: this store is it, or the global store is on and this one lacks the id. */
+    readonly isGlobal: (id: string) => boolean;
+}
+export declare function cliRecallOrigin(ctx: Context, setting: CliRecallSetting): CliRecallOrigin;
+/** How many of `query`'s search candidates the scope rule hides from a recall asking for `requested`; the read is
+ *  window-capped, so this is a floor on a large store. */
+export declare function scopeHiddenCount(ctx: Context, query: string, globalRoot: string | undefined, requested: string | undefined): number;
+/** The active snapshot, its session's latest handoff and last five events, each kept only when its scope passes. */
+export declare function loadCliRecallContinuity(ctx: Context, setting: CliRecallSetting, wanted: boolean): ContinuityBlock;
+export interface CliRecallRerankerPick {
+    readonly fn: RerankerFn;
+    readonly defaultTopK: number;
+}
+/** The reranker a `--reranker` name picks and the top-k it takes by default; an unknown name throws, a blank one picks none. */
+export declare function cliRecallReranker(name: string): CliRecallRerankerPick | null;
+/** The ranked rows a print budget holds, best first; the first `floor` stay whatever they cost. */
+export declare function fitRecallRows(ranked: SearchResult[], budget: number, floor: number, cost: ResultCost): SearchResult[];
+/** One result row; the optional keys are set in the order the JSON prints them. */
+export interface RecallJsonRow {
+    id: string;
+    score: number;
+    strength: SearchResult['entry']['strength'];
+    tokens: number;
+    tags: SearchResult['entry']['tags'];
+    content: string;
+    layer: SearchResult['entry']['layer'];
+    trace_outcome?: SearchResult['entry']['trace_outcome'];
+    superseded?: boolean;
+    superseded_by?: SearchResult['entry']['superseded_by'];
+    graphVia?: SearchResult['graphVia'];
+    confidence?: ReturnType<typeof confidenceFacets>['tier'];
+    aged_out?: ReturnType<typeof confidenceFacets>['agedOut'];
+    source?: 'global' | 'local';
+    reason?: ReturnType<typeof explainMatch>['reason'];
+    bm25?: SearchResult['bm25'];
+    cosine?: SearchResult['cosine'];
+    envelope?: ReturnType<typeof explainMatch>['envelope'];
+    rerankTrace?: SearchResult['rerankTrace'];
+}
+export declare function recallJsonRow(r: SearchResult, query: string, showWhy: boolean, isGlobal: boolean): RecallJsonRow;
+//# sourceMappingURL=recall-cli.d.ts.map

package/dist/api/recall-cli.js

@@ -0,0 +1,103 @@
+// What the `hippo recall` verb reads beside its ranking core: the stores it searches, the resume packet and the JSON rows.
+import { confidenceFacets, Layer } from '../core/memory.js';
+import { isGlobalStoreRoot, isInitialized } from '../core/project-identity.js';
+import { getReranker } from '../rerankers/index.js';
+import { isClefModel } from '../rerankers/clef.js';
+import { JEV_DEFAULT_TOP_K } from '../rerankers/jev.js';
+import { explainMatch } from '../search/explain.js';
+import { fitBudget } from '../search/finalize.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { detectScope } from '../core/active-scope.js';
+import { loadLatestHandoff } from '../store/handoffs.js';
+import { loadIndex } from '../store/index-and-stats.js';
+import { passesCliRecallScopeFilter, passesScopeFilterForRecall } from '../core/recall-scope.js';
+import { loadSearchEntries } from '../store/search-rows.js';
+import { listSessionEvents, loadActiveTaskSnapshot } from '../store/sessions.js';
+export { DEFAULT_MAX_NEIGHBORS, MAX_HOPS } from '../graph/recall.js';
+/** The active scope merges `--scope` with the detected one, which only boosts. */
+export function cliRecallSetting(ctx, explicitScope) {
+    return { globalRoot: getGlobalRoot(), primaryIsGlobal: isGlobalStoreRoot(ctx.hippoRoot), activeScope: explicitScope || detectScope() };
+}
+export function cliRecallOrigin(ctx, setting) {
+    const localIndex = loadIndex(ctx.hippoRoot);
+    const globalOn = isInitialized(setting.globalRoot);
+    return { globalOn, isGlobal: (id) => setting.primaryIsGlobal || (globalOn && !localIndex.entries[id]) };
+}
+/** How many of `query`'s search candidates the scope rule hides from a recall asking for `requested`; the read is
+ *  window-capped, so this is a floor on a large store. */
+export function scopeHiddenCount(ctx, query, globalRoot, requested) {
+    const probe = [
+        ...loadSearchEntries(ctx.hippoRoot, query, undefined, ctx.tenantId),
+        ...(globalRoot ? loadSearchEntries(globalRoot, query, undefined, ctx.tenantId) : []),
+    ];
+    return probe.filter((e) => !passesCliRecallScopeFilter(e.scope ?? null, requested)).length;
+}
+/** The active snapshot, its session's latest handoff and last five events, each kept only when its scope passes. */
+export function loadCliRecallContinuity(ctx, setting, wanted) {
+    if (!wanted || setting.primaryIsGlobal)
+        return { activeSnapshot: null, sessionHandoff: null, recentSessionEvents: [] };
+    const { hippoRoot, tenantId } = ctx;
+    const rawSnapshot = loadActiveTaskSnapshot(hippoRoot, tenantId);
+    const sessionId = rawSnapshot?.session_id ?? undefined;
+    const rawHandoff = sessionId ? loadLatestHandoff(hippoRoot, tenantId, sessionId) : null;
+    const rawEvents = sessionId ? listSessionEvents(hippoRoot, tenantId, { session_id: sessionId, limit: 5 }) : [];
+    // The same shared scope rule as api.recall; the active scope merges --scope and detectScope().
+    const effectiveScope = setting.activeScope || undefined;
+    const passes = (r) => passesScopeFilterForRecall(r.scope ?? null, effectiveScope);
+    return {
+        activeSnapshot: rawSnapshot && passes(rawSnapshot) ? rawSnapshot : null,
+        sessionHandoff: rawHandoff && passes(rawHandoff) ? rawHandoff : null,
+        recentSessionEvents: rawEvents.filter(passes),
+    };
+}
+/** The reranker a `--reranker` name picks and the top-k it takes by default; an unknown name throws, a blank one picks none. */
+export function cliRecallReranker(name) {
+    const fn = getReranker(name);
+    if (!fn)
+        return null;
+    return { fn, defaultTopK: name === 'jev' || isClefModel(name) ? JEV_DEFAULT_TOP_K : 50 };
+}
+/** The ranked rows a print budget holds, best first; the first `floor` stay whatever they cost. */
+export function fitRecallRows(ranked, budget, floor, cost) {
+    return fitBudget(ranked, budget, floor, cost);
+}
+export function recallJsonRow(r, query, showWhy, isGlobal) {
+    const base = {
+        id: r.entry.id,
+        score: r.score,
+        strength: r.entry.strength,
+        tokens: r.tokens,
+        tags: r.entry.tags,
+        content: r.entry.content,
+        layer: r.entry.layer,
+    };
+    if (r.entry.layer === Layer.Trace) {
+        base.trace_outcome = r.entry.trace_outcome;
+    }
+    if (r.entry.superseded_by) {
+        base.superseded = true;
+        base.superseded_by = r.entry.superseded_by;
+    }
+    if (r.graphVia) {
+        base.graphVia = r.graphVia;
+    }
+    if (showWhy) {
+        const explanation = explainMatch(query, r);
+        const facets = confidenceFacets(r.entry);
+        base.confidence = facets.tier;
+        base.aged_out = facets.agedOut;
+        base.source = isGlobal ? 'global' : 'local';
+        base.reason = explanation.reason;
+        base.bm25 = r.bm25;
+        base.cosine = r.cosine;
+        if (explanation.envelope) {
+            base.envelope = explanation.envelope;
+        }
+        // The ordered lifecycle re-ranking steps, so a caller can see why a row moved.
+        if (r.rerankTrace && r.rerankTrace.length > 0) {
+            base.rerankTrace = r.rerankTrace;
+        }
+    }
+    return base;
+}
+//# sourceMappingURL=recall-cli.js.map

package/dist/api/recall-core.js

@@ -5,10 +5,10 @@ import { decidePlanningFallacy, detectPlanningClaim } from '../predictions/plann
 import { rankRecall } from './recall-pipeline.js';
 import { writeRecallTraceAtRoot } from '../store/recall-trace.js';
 import { saveIndex } from '../store/index-and-stats.js';
-import { sqliteStore } from '../store/index.js';
+import { sqliteStore, storeFor } from '../store/index.js';
 import { estimateTokens } from '../util/token-text.js';
 import { callerOf, recallAuditMetadata, recallAuditRow, strengthenOf } from './recall-record.js';
-import { recordTokens } from './tokens.js';
+import { RECALL_RECORDING, recordShownRecall } from './recall-finish.js';
 // entriesByIds reads at most this many ids a call.
 const ID_READ_CHUNK = 500;
 export async function retrieveWithCliCore(ctx, opts, core) {
@@ -16,8 +16,8 @@ export async function retrieveWithCliCore(ctx, opts, core) {
     if (!ctx.actor.hostAdmin)
         throw new ForbiddenError('The CLI ranking core serves the host admin only');
     const globalRoot = core.sources?.globalRoot;
-    // The ranking core reads hippo.db itself, so its writes go to the same file whatever store the context names.
-    const store = sqliteStore(ctx.hippoRoot);
+    // The ranking core reads hippo.db under hippoRoot, yet writes through the caller's store, whose finishRecall skips any id it does not hold.
+    const store = storeFor(ctx);
     const ranking = await rankRecall({ hippoRoot: ctx.hippoRoot, globalRoot, tenantId: ctx.tenantId, note: core.note }, { ...core.rank, query: opts.query, sessionId: opts.sessionId, goalTag: opts.goalTag });
     if (ranking.halted) {
         // The stages that ran earned these rows, so the caller's flag error does not drop them.
@@ -69,10 +69,19 @@ async function recordShown(ctx, store, opts, core, done) {
         // The second store logs that it was searched, and strengthens only the rows the first does not hold.
         if (second !== undefined)
             await finishOrReport(sqliteStore(second), { goalLog: [], audit: [recallRow], strengthen: strengthenOf(ctx, heldElsewhere) });
-        await traceAndMark(ctx, store, opts, core, shown.results);
+        traceAndMark(ctx, opts, core, shown.results);
     }
-    // The ledger books the text the caller prints, and it prints whether or not the record was written.
-    await recordTokens(ctx, 'recall', { items: ids.length, tokens: shown.tokens, sessionId: core.hostSessionId ?? null });
+    // The caller prints whether or not the record was written, so the ring and the ledger still take this list; `written` holds back the count.
+    await recordShownRecall(ctx, store, RECALL_RECORDING.cli, {
+        query: opts.query,
+        sessionId: opts.sessionId,
+        topId: ids[0] ?? null,
+        anchoredOn: shown.anchoredOn,
+        items: ids.length,
+        tokens: shown.tokens,
+        ledgerSessionId: core.hostSessionId ?? null,
+        written: audited,
+    });
 }
 // The caller has ranked and is about to print, so a failed audit write is logged and counted, never thrown.
 async function finishOrReport(store, writes) {
@@ -93,7 +102,7 @@ async function idsNotHeld(store, ids, tenantId) {
     }
     return ids.filter((id) => !held.has(id));
 }
-async function traceAndMark(ctx, store, opts, core, shown) {
+function traceAndMark(ctx, opts, core, shown) {
     // An empty list is traced too, so a coverage gap still reaches the training corpus.
     const traceId = writeRecallTraceAtRoot(ctx.hippoRoot, {
         tenantId: ctx.tenantId,
@@ -107,6 +116,5 @@ async function traceAndMark(ctx, store, opts, core, shown) {
         return;
     // One write for both markers, so `hippo outcome` never pairs these ids with an older trace.
     saveIndex(ctx.hippoRoot, { last_retrieval_ids: shown.map((r) => r.entry.id), last_trace_id: traceId !== null ? String(traceId) : null });
-    await store.bumpRecallStats(shown.length);
 }
 //# sourceMappingURL=recall-core.js.map

package/dist/api/recall-finish.d.ts

@@ -0,0 +1,53 @@
+import type { AppendAuditOpts } from '../store/audit.js';
+import type { HippoStore } from '../store/index.js';
+import type { TokenSurface } from '../store/token-ledger.js';
+import { type RecallHistorySnapshot } from './recall-history.js';
+import { type RecallSurface } from './recall-record.js';
+import type { Context } from './types.js';
+/** How one surface's recall is recorded. The surfaces differ in these three values and in the list they hand over, nowhere else. */
+export interface RecallRecording {
+    /** Whose session rings the recall reads and feeds. */
+    readonly ring: RecallSurface;
+    /** The label of its token ledger row. */
+    readonly ledger: TokenSurface;
+    /** 'every': an empty list still reaches the stats write, which then only rewrites stats.json; 'shown': an empty list skips it. */
+    readonly stats: 'every' | 'shown';
+}
+/** The surfaces `retrieve` records in full. MCP is pending: src/mcp still feeds its own ring and books its own ledger row, and counts no stats. */
+export declare const RECALL_RECORDING: {
+    readonly http: {
+        readonly ring: "http";
+        readonly ledger: "http_recall";
+        readonly stats: "every";
+    };
+    readonly cli: {
+        readonly ring: "cli";
+        readonly ledger: "recall";
+        readonly stats: "shown";
+    };
+};
+/** What a recorded recall takes into ranking. */
+export interface RecallLead {
+    readonly recallHistory: RecallHistorySnapshot | undefined;
+    readonly leadingAudit: readonly AppendAuditOpts[];
+}
+/** For a surface whose hint `retrieve` judges: the session's history, or the row saying the recall named no session. */
+export declare function recallLead(ctx: Context, how: RecallRecording, query: string, sessionId: string | undefined): RecallLead;
+/** The list a recall showed, as its ranker counted and priced it. */
+export interface ShownList {
+    readonly query: string;
+    /** The recall's session, which keys the ring. */
+    readonly sessionId: string | undefined;
+    readonly topId: string | null;
+    /** The memory this recall's anchoring hint named; the next recall's cooldown reads it. */
+    readonly anchoredOn: string | undefined;
+    readonly items: number;
+    readonly tokens: number;
+    /** The session the ledger row names: the recall's own on HTTP, the host agent's on the CLI. */
+    readonly ledgerSessionId: string | null;
+    /** False when the audit rows could not be written and the caller answers anyway. */
+    readonly written: boolean;
+}
+/** Runs after the recall's own write, in this order: the ring, then the counter, then the ledger. */
+export declare function recordShownRecall(ctx: Context, store: HippoStore, how: RecallRecording, shown: ShownList): Promise<void>;
+//# sourceMappingURL=recall-finish.d.ts.map

package/dist/api/recall-finish.js

@@ -0,0 +1,30 @@
+import { biasHintEnabled } from './recall-history.js';
+import { anchorSkippedRows, callerOf, noteRecall, peekSessionRing, sessionRing } from './recall-record.js';
+import { recordTokens } from './tokens.js';
+/** The surfaces `retrieve` records in full. MCP is pending: src/mcp still feeds its own ring and books its own ledger row, and counts no stats. */
+export const RECALL_RECORDING = {
+    http: { ring: 'http', ledger: 'http_recall', stats: 'every' },
+    cli: { ring: 'cli', ledger: 'recall', stats: 'shown' },
+};
+/** For a surface whose hint `retrieve` judges: the session's history, or the row saying the recall named no session. */
+export function recallLead(ctx, how, query, sessionId) {
+    return {
+        // Peeked, never created: a recall that then fails must not LRU-evict a live session.
+        recallHistory: sessionId && biasHintEnabled('anchoring') ? peekSessionRing(how.ring, ctx.tenantId, sessionId) : undefined,
+        // Written first in the recall's own write, so a recall that fails leaves no row.
+        leadingAudit: sessionId ? [] : anchorSkippedRows(callerOf(ctx), query),
+    };
+}
+/** Runs after the recall's own write, in this order: the ring, then the counter, then the ledger. */
+export async function recordShownRecall(ctx, store, how, shown) {
+    // A surface that only peeked has its ring created here, after the write, so a recall that fails cannot LRU-evict a live session.
+    const ring = sessionRing(how.ring, ctx.tenantId, shown.sessionId);
+    if (ring)
+        noteRecall(ring, shown.query, shown.topId, shown.anchoredOn);
+    // A recall with no audit row counts nothing, as it strengthens and traces nothing.
+    if (shown.written && (how.stats === 'every' || shown.items > 0))
+        await store.bumpRecallStats(shown.items);
+    // The ledger books text that was sent, so its row does not wait on the audit write.
+    await recordTokens(ctx, how.ledger, { items: shown.items, tokens: shown.tokens, sessionId: shown.ledgerSessionId });
+}
+//# sourceMappingURL=recall-finish.js.map

package/dist/api/recall-history.d.ts

@@ -1,22 +1,6 @@
-/**
- * Anchoring detector (recall-recurrence), pure module.
- *
- * Implements two detection rules:
- *   query_repeat: same queryHash within recentRepeatWindow returned
- *     same topMemoryId (caller is re-asking the same question).
- *   memory_dominance: same topMemoryId across >= minDominance distinct
- *     queryHashes (memory acts as a fixed-point anchor regardless of what
- *     the agent asks).
- *
- * Each pipeline (api.recall via
- * HTTP, cmdRecall, MCP hippo_recall) owns its OWN ring buffer Map keyed
- * by (tenant, session). No cross-pipeline sharing (the typical multi-
- * process deployment makes IPC ring-sharing impractical; per-pipeline
- * is correct because each pipeline has its own top-1 ranking anyway).
- *
- * AnchoringHint + PlanningFallacyHint are independent
- * signals; both can fire on the same recall.
- */
+/** Anchoring detector (recall-recurrence), pure module: `query_repeat` (a queryHash re-asked within the window returns the same topMemoryId) and
+ * `memory_dominance` (the same topMemoryId across >= minDominance distinct queryHashes). Each pipeline keeps its OWN ring Map keyed by (tenant, session),
+ * because its top-1 ranking differs. AnchoringHint and PlanningFallacyHint are independent signals. */
 export type AnchoringReason = 'query_repeat' | 'memory_dominance';
 export interface AnchoringHint {
     reason: AnchoringReason;
@@ -37,10 +21,8 @@ export interface RecallHistoryEntry {
     topMemoryId: string | null;
     /** ISO-8601 timestamp; advisory, not used by the detection rules. */
     ts: string;
-    /** Memory id of the AnchoringHint that fired on this recall, if any.
-     *  Used by the cooldown logic to prevent re-emitting the same hint on
-     *  consecutive recalls within the dominance window. Caller-written
-     *  AFTER detectAnchoring returns; reads next time detectAnchoring runs. */
+    /** Memory id of the AnchoringHint that fired on this recall, if any; the caller writes it after detectAnchoring returns, and the cooldown reads it next
+     * time. */
     anchoredOn?: string;
 }
 export type RecallHistorySnapshot = readonly RecallHistoryEntry[];
@@ -51,81 +33,32 @@ export interface DetectAnchoringOpts {
     /** query_repeat window: how many recent history entries to scan for query repeat.
      *  Default 5. */
     recentRepeatWindow?: number;
-    /** Cooldown: if the immediately-prior fire (per `anchoredOn`) was for
-     *  the same topMemoryId within this many history entries, suppress.
-     *  Default 3. */
+    /** Cooldown: suppress when the prior fire (per `anchoredOn`) was for the same topMemoryId within this many history entries. Default 3. */
     cooldown?: number;
 }
-/**
- * Normalize + hash a query text into a 32-bit integer.
- * Lowercase → strip non-alphanumeric → split → drop empty + short tokens →
- * sort tokens → join → FNV-1a 32-bit.
- *
- * Token sort + dedup means semantically-equivalent queries with reordered
- * words collide intentionally ("semantically-distinct" is approximated by
- * textual normalization, not embeddings).
- *
- * Deterministic across processes; stable across Node + V8 versions.
- */
+/** Normalizes a query (lowercase, strip non-alphanumerics, drop short tokens, sort, dedup, join) and hashes it with 32-bit FNV-1a.
+ * Reordered words collide intentionally; deterministic across processes and V8 versions. */
 export declare function hashQueryText(query: string): number;
-/**
- * Detect anchoring patterns in the recall history against the current
- * recall's (queryHash, topMemoryId).
- *
- * Rule precedence: memory_dominance wins on tie. When both rules fire on the
- * same recall, return only memory_dominance, the stronger signal (a memory
- * dominating multiple DIFFERENT queries is a fixed-point anchor; query_repeat
- * alone is just a literal re-ask).
- *
- * Cooldown: if the immediately-prior recall fired a hint on the SAME
- * topMemoryId within `cooldown=3` history entries, suppress. Prevents
- * spam when the agent repeatedly recalls within the dominance window.
- * Cooldown is per-memory, not per-rule: if memory_dominance fired on M
- * (cooldown engaged for M), and the next recall has top=N + repeated query,
- * query_repeat fires on N (different memory, not in cooldown).
- *
- * @returns AnchoringHint when a pattern fires; null otherwise.
- */
+/** Detects anchoring against the current (queryHash, topMemoryId); memory_dominance wins when both rules fire, since it spans DIFFERENT queries.
+ * Cooldown is per memory: a hint on the SAME topMemoryId within `cooldown=3` history entries is suppressed. Returns an AnchoringHint or null. */
 export declare function detectAnchoring(history: RecallHistorySnapshot, currentQueryHash: number, currentTopMemoryId: string | null, opts?: DetectAnchoringOpts): AnchoringHint | null;
-/**
- * Bounded FIFO ring of RecallHistoryEntry. Newest entries pushed via
- * append; oldest evicted when the ring is full. The class is intentionally
- * a thin wrapper around an array so snapshotRing returns a readonly view
- * without copying on the hot path.
- */
+/** Bounded FIFO ring of RecallHistoryEntry (oldest evicted when full); a thin array wrapper so snapshotRing returns a readonly view without copying. */
 export declare class RingBuffer {
     private entries;
     append(entry: RecallHistoryEntry): void;
     snapshot(): RecallHistorySnapshot;
     size(): number;
 }
-/**
- * Build the (tenant, session) key for a per-session ring Map. Uses a NUL
- * (`\x00`) byte as delimiter because tenant ids and session ids are
- * validated elsewhere to reject NUL chars — guarantees collision-free
- * concatenation regardless of what `:` or other delimiters might appear
- * inside either field (notably API-key-derived subjects can contain `:`).
- */
+/** Builds the (tenant, session) key with a NUL delimiter: tenant and session ids are validated elsewhere to reject NUL,
+ * so concatenation cannot collide even though API-key-derived subjects can contain `:`. */
 export declare function buildSessionKey(tenantId: string, sessionId: string): string;
-/**
- * Get-or-create a RingBuffer for a session key. Caps total tracked keys
- * at `maxSessions` (default 1000) with LRU eviction — when the cap is
- * hit, deletes the oldest-inserted key before inserting the new one.
- * Map iteration order preserves insertion order per ECMA-262 spec, so
- * "oldest" = first key returned by Map.prototype.keys().
- */
+/** Get-or-create a RingBuffer per session key, capped at `maxSessions` (default 1000); at the cap the oldest-inserted key (first from Map.keys()) is
+ * evicted. */
 export declare function getOrCreateRing(map: Map<string, RingBuffer>, key: string, maxSessions?: number): RingBuffer;
-/**
- * Append a recall to a ring. The `anchoredOn` argument carries the
- * memoryId of the AnchoringHint that fired on THIS recall (or undefined
- * if no hint). detectAnchoring reads it next time for cooldown gating.
- */
+/** Appends a recall to a ring; `anchoredOn` is the memoryId of the hint that fired on THIS recall (or undefined), read by detectAnchoring for cooldown. */
 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.
- */
+/** Whether a recall bias hint is enabled; reads 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