hippo-memory 1.72.0 → 2.1.0

package/dist/api/prompt-hook.js

@@ -1,61 +1,65 @@
-// 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.
+// 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.
 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 { createDeliveryRecorder } from '../store/delivery-recorder.js';
+import { contextBlockLines, contextCost, crossProjectLines, handoffText, sessionTrailText, settleTokens, snapshotText, } from './context-render.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, ledgerRoot } from './ledger-db.js';
+import { bookLedgerTurn, ledgerLastSent, ledgerReachOf, ledgerRoot } from './ledger-db.js';
 import { noteLedgerRowSkipped } from '../store/ledger-turn.js';
 import { sessionPilotArm } from './pilot-arm.js';
-import { assertCallerProject, isGlobalStoreRoot, MAX_PROJECT_ALIASES } from '../core/project-identity.js';
+import { assertCallerProject, MAX_PROJECT_ALIASES } from '../core/project-identity.js';
 import { writeDeliveryEventAtRoot } from '../store/recall-trace.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, log } from '../util/log.js';
+import { errorMessage, log, errorFields } 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);
+        const root = ledgerRoot(ctx.hippoRoot, ledgerReachOf(ctx));
         if (root === null || !loadConfig(root).deliveryLedger.enabled)
             return null;
         return createDeliveryRecorder({
             root,
             storeHash: blockHash(realpathOrResolve(root)),
-            writeStore: isGlobalStoreRoot(root) ? 'global' : 'local',
+            // ledgerRoot falls back to the global root only when the primary is not initialized.
+            writeStore: root !== ctx.hippoRoot || ctx.reach?.isGlobal === true ? 'global' : 'local',
             tenantId: ctx.tenantId,
             stdinText: start.stdinText,
             envSessionId: start.envSessionId,
             runtime: start.runtime === 'copilot' ? 'copilot' : undefined,
             eventType: start.eventType,
+            fault: start.fault,
         });
     }
     catch (error) {
-        log.warn(`delivery ledger skipped: ${errorMessage(error)}`);
+        log.warn(`delivery ledger skipped: ${errorMessage(error)}`, errorFields(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. */
+/** 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);
+        const root = ledgerRoot(ctx.hippoRoot, ledgerReachOf(ctx));
         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)}`);
+        log.warn(`delivery ledger skipped: ${errorMessage(error)}`, errorFields(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. */
+/** 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)
         return;
@@ -63,10 +67,11 @@ export function flushDeliveryRecorder(rec, write) {
         rec.flush(write ?? ((input) => writeDeliveryEventAtRoot(rec.root, input)));
     }
     catch (error) {
-        log.error(`delivery ledger write failed: ${errorMessage(error)}`);
+        log.error(`delivery ledger write failed: ${errorMessage(error)}`, errorFields(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. */
+/** A Copilot sessionStart reply's wrapper, picked by the sender's casing: stdin.ts keeps a camelCase `sessionId`, which
+ * only the Copilot harness sends. */
 export function sessionStartEnvelope(stdinText) {
     return hookPayloadString(stdinText, 'sessionId') !== null ? 'copilot-session-start' : 'vscode-session-start';
 }
@@ -86,17 +91,14 @@ export function hasContextData(result) {
 export function toRenderItems(entries) {
     return entries.map((r) => ({ entry: r.entry, score: r.score, tokens: r.tokens, isGlobal: r.isGlobal ?? false }));
 }
-/** The hook format's stdout, '' when nothing is sent: a skippable static block (snapshot, handoff, events, pins, recent-N) and a never-skipped recall block. */
+/** The hook format's stdout, '' when nothing is sent: a skippable static block (snapshot, handoff, events, pins,
+ * recent-N) and a never-skipped recall block. */
 export function additionalContextOutput(view) {
     return renderAdditionalContext(view).stdout;
 }
-function renderAdditionalContext(view) {
-    const { result, rec, framing } = view;
-    const staticEntries = result.entries.filter((r) => r.category !== 'cross-project' && !r.promptRecall);
-    const staticCrossEntries = result.entries.filter((r) => r.category === 'cross-project' && !r.promptRecall);
-    const staticItems = toRenderItems(staticEntries);
-    const recallItems = toRenderItems(result.entries.filter((r) => r.promptRecall));
-    const staticBlock = settleTokens((t) => [
+function renderStaticBlock(view, staticItems, staticCrossEntries) {
+    const { result, framing } = view;
+    return settleTokens((t) => [
         ...(result.activeSnapshot ? [snapshotText(result.activeSnapshot)] : []),
         ...(result.sessionHandoff ? [handoffText(result.sessionHandoff)] : []),
         ...(result.recentEvents && result.recentEvents.length > 0 ? [sessionTrailText(result.recentEvents)] : []),
@@ -104,9 +106,20 @@ function renderAdditionalContext(view) {
         ...(staticItems.length > 0 ? contextBlockLines(staticItems, t, framing, { showStrength: false }) : []),
         ...crossProjectLines(staticCrossEntries),
     ].join('\n'));
-    const recallBlock = recallItems.length > 0
-        ? settleTokens((t) => contextBlockLines(recallItems, t, framing, { showStrength: false, heading: 'Prompt-Relevant Memory' }).join('\n'))
-        : '';
+}
+function renderRecallBlock(recallItems, framing) {
+    if (recallItems.length === 0)
+        return '';
+    return settleTokens((t) => contextBlockLines(recallItems, t, framing, { showStrength: false, heading: 'Prompt-Relevant Memory' }).join('\n'));
+}
+function renderAdditionalContext(view) {
+    const { result, rec, framing } = view;
+    const staticEntries = result.entries.filter((r) => r.category !== 'cross-project' && !r.promptRecall);
+    const staticCrossEntries = result.entries.filter((r) => r.category === 'cross-project' && !r.promptRecall);
+    const staticItems = toRenderItems(staticEntries);
+    const recallItems = toRenderItems(result.entries.filter((r) => r.promptRecall));
+    const staticBlock = renderStaticBlock(view, staticItems, staticCrossEntries);
+    const recallBlock = renderRecallBlock(recallItems, framing);
     if (!staticBlock.trim() && !recallBlock.trim()) {
         rec?.delivered({ state: 'empty' });
         return NOTHING_RENDERED;
@@ -138,13 +151,12 @@ function renderAdditionalContext(view) {
 /** True, after booking the skip row, when the hook may omit a static block this session already holds. */
 function skipUnchangedStatic(view, surface, staticBlock, recallBlock, staticCount) {
     const { hippoRoot, payloadSessionId, rec } = view;
-    const ledgerOpts = { sharedStore: view.sharedStore };
     if (!view.pinnedOnly || payloadSessionId === undefined)
         return false;
     // Session start is the only injection Copilot gets, so a resumed session needs the whole block again.
     if (view.envelope === 'copilot-session-start' || view.envelope === 'vscode-session-start')
         return false;
-    const injectCfg = loadConfig(hippoRoot).pinnedInject;
+    const injectCfg = (view.config ?? loadConfig(hippoRoot)).pinnedInject;
     if (injectCfg.skipUnchanged === false)
         return false;
     const refreshTurns = Number.isFinite(injectCfg.refreshTurns) && injectCfg.refreshTurns >= 0
@@ -155,7 +167,7 @@ function skipUnchangedStatic(view, surface, staticBlock, recallBlock, staticCoun
     // Before the ledger read, so a caller that did not print this block books no skip row.
     if (view.printedHash !== undefined && view.printedHash !== staticHash)
         return false;
-    const last = ledgerLastSent(hippoRoot, view.tenantId, payloadSessionId, surface, ledgerOpts);
+    const last = ledgerLastSent(hippoRoot, view.tenantId, payloadSessionId, surface, view.reach);
     if (!shouldSkipUnchanged(last ?? null, staticHash, refreshTurns))
         return false;
     bookLedgerTurn(hippoRoot, {
@@ -167,20 +179,24 @@ function skipUnchangedStatic(view, surface, staticBlock, recallBlock, staticCoun
             rec?.delivered({ state: 'reused', staticHash, staticReused: true });
             flushDeliveryRecorder(rec, write);
         },
-    }, ledgerOpts);
+    }, view.reach);
     return true;
 }
-/** One connection for both rows; a failed row is logged and the other still lands, because a ledger failure must not break the hook. */
+/** One connection for both rows; a failed row is logged and the other still lands, because a ledger failure must not
+ * break the hook. */
 function recordAdditionalContextRows(view, surface, staticPart, recallPart) {
     const row = (part, on) => ({
         tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface: on, event: 'inject',
         items: part.items, tokens: estimateTokens(part.text), hash: blockHash(part.text),
     });
     bookLedgerTurn(view.hippoRoot, {
-        uses: [...(staticPart.text ? [row(staticPart, surface)] : []), ...(recallPart.text ? [row(recallPart, 'hook_recall')] : [])],
+        uses: [
+            ...(staticPart.text ? [row(staticPart, surface)] : []),
+            ...(recallPart.text ? [row(recallPart, 'hook_recall')] : []),
+        ],
         onRowError: noteLedgerRowSkipped,
         delivery: (write) => flushDeliveryRecorder(view.rec, write),
-    }, { sharedStore: view.sharedStore });
+    }, view.reach);
 }
 // The flags HIPPO_PINNED_INJECT_COMMAND gives the local hook; the CLI parity test fails if the two drift.
 const HOOK_INCLUDE_RECENT = 5;
@@ -191,8 +207,9 @@ const BLOCK_HASH_RE = /^[0-9a-f]{16}$/;
 /** The caps on a hook caller's session id and project names, so a caller other than an HTTP route is bounded too. */
 export function assertCallerIds(sessionId, project) {
     const { name, legacyName, aliases = [] } = project;
-    if (aliases.length > MAX_PROJECT_ALIASES)
+    if (aliases.length > MAX_PROJECT_ALIASES) {
         throw new BadRequestError(`project aliases: at most ${MAX_PROJECT_ALIASES}`);
+    }
     if ([sessionId, name, legacyName, ...aliases].some((v) => v.length > MAX_ID_LEN)) {
         throw new BadRequestError(`session id and project names: at most ${MAX_ID_LEN} characters each`);
     }
@@ -203,20 +220,24 @@ 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 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. */
+/** 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;
     const { sharedStore } = opts;
-    if (sharedStore || isSharedStore(ctx.hippoRoot))
+    const sharedByReach = ctx.reach ? ctx.reach.shared : isSharedStore(ctx.hippoRoot);
+    if (sharedStore || sharedByReach)
         assertCallerProject(req.project);
     // The test the local hook runs on its stdin, so a sub-agent books no arm and no session rows here either.
     const subagent = payload !== undefined && isSubagentPayload(JSON.stringify(payload));
     const ledgerSessionId = subagent ? undefined : sessionId;
-    const arm = sessionPilotArm(ctx.hippoRoot, ctx.tenantId, sessionId, !subagent, { sharedStore, ownTenantOnly: true });
+    const reach = ledgerReachOf(ctx, sharedStore);
+    const arm = sessionPilotArm(ctx.hippoRoot, ctx.tenantId, sessionId, !subagent, { reach, ownTenantOnly: true });
     if (arm === 'holdout')
         return { arm, ...NOTHING_RENDERED };
     const prompt = payload?.prompt;
@@ -233,8 +254,9 @@ export async function promptHookContext(ctx, req, opts = {}) {
     });
     const rendered = hasContextData(result)
         ? renderAdditionalContext({
-            hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, ledgerSessionId, payloadSessionId: ledgerSessionId,
-            pinnedOnly: true, framing: HOOK_FRAMING, rec: null, result, sharedStore, printedHash: req.printedHash ?? null,
+            hippoRoot: ctx.hippoRoot, config: ctx.config, tenantId: ctx.tenantId, ledgerSessionId,
+            payloadSessionId: ledgerSessionId, pinnedOnly: true, framing: HOOK_FRAMING, rec: null, result, reach,
+            printedHash: req.printedHash ?? null,
         })
         : NOTHING_RENDERED;
     // A sub-agent's output is not the session's, so its caller must not record it as printed.

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

@@ -8,7 +8,9 @@ export interface ProvenanceCoverage {
         missing: ('owner' | 'artifact_ref')[];
     }>;
 }
-/** Provenance coverage gate: every `kind='raw'` row must carry `owner` and `artifact_ref`; derivative or terminal rows are excluded.
+/**
+ * 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/api/provenance-coverage.js

@@ -1,4 +1,6 @@
-/** Provenance coverage gate: every `kind='raw'` row must carry `owner` and `artifact_ref`; derivative or terminal rows are excluded.
+/**
+ * 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');

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

@@ -0,0 +1,185 @@
+import { type AppendAuditOpts, type AuditOp } from '../../store/audit.js';
+import type { HippoStore, RecallWrites } from '../../store/index.js';
+import type { TokenSurface } from '../../store/token-ledger.js';
+import type { AvailabilityHint } from '../availability.js';
+import type { Context, StoreContext } from '../types.js';
+/**
+ * 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;
+    /** The memory ID that is anchoring the agent's reasoning. */
+    memoryId: string;
+    /** For 'memory_dominance': how many distinct queries in the recent window
+     *  had this memory as their top-1 result. Always >= 3 when emitted. */
+    queryCount?: number;
+    /** Human-readable summary surfaced to the agent. */
+    summary: string;
+    /** Discriminator for hint origin; reserved for future variants. */
+    source: 'j1-recurrence';
+}
+export interface RecallHistoryEntry {
+    /** Hash of the queryText that produced this entry (see hashQueryText). */
+    queryHash: number;
+    /** Top-1 memory id this recall surfaced; null if zero results. */
+    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; the caller writes it after detectAnchoring
+     * returns, and the cooldown reads it next
+     * time. */
+    anchoredOn?: string;
+}
+export type RecallHistorySnapshot = readonly RecallHistoryEntry[];
+export interface DetectAnchoringOpts {
+    /** memory_dominance threshold: number of distinct queryHashes that must have returned
+     *  the same topMemoryId. Default 3. */
+    minDominance?: number;
+    /** query_repeat window: how many recent history entries to scan for query repeat.
+     *  Default 5. */
+    recentRepeatWindow?: number;
+    /**
+     * Cooldown: suppress when the prior fire (per `anchoredOn`) was for the same topMemoryId within this many history
+     * entries. Default 3.
+     */
+    cooldown?: number;
+}
+/**
+ * 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;
+/**
+ * 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 (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;
+}
+/** 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 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;
+/**
+ * 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 env at call time, so `HIPPO_ANCHORING=off` or `HIPPO_AVAILABILITY=off`
+ * disables only that kind.
+ */
+export declare function biasHintEnabled(kind: 'anchoring' | 'availability'): boolean;
+/** The ids among `ids` that a tenant's rows in `store` hold. */
+export declare function heldIds(store: HippoStore, ids: readonly string[], tenantId: string): Promise<Set<string>>;
+export type RecallSurface = 'cli' | 'mcp' | 'http';
+/** The session's ring, created on first use; null when anchoring is off or the call has no session. */
+export declare function sessionRing(surface: RecallSurface, tenantId: string, sessionId: string | undefined): RingBuffer | null;
+/** Records this recall's top row and hint, which the next recall's cooldown reads. */
+export declare function noteRecall(ring: RingBuffer, query: string, topId: string | null, anchoredOn: string | undefined): void;
+export declare function resetSessionRings(surface: RecallSurface): void;
+/** Whom a recall audit row names. */
+export interface RecallAuditCaller {
+    readonly tenantId: string;
+    readonly actor: string;
+}
+export declare function callerOf(ctx: Context): RecallAuditCaller;
+/** The strengthen every ranker of `retrieve` hands to the recall's write: the shown ids, in the caller's tenant. */
+export declare function strengthenOf(ctx: Context, ids: readonly string[]): NonNullable<RecallWrites['strengthen']>;
+type RecallAuditMetadata = Readonly<Record<string, string | number | null>>;
+export declare function recallAuditRow(who: RecallAuditCaller, op: AuditOp, targetId?: string, metadata?: RecallAuditMetadata): AppendAuditOpts;
+export declare function recallAuditMetadata(query: string, results: number): {
+    results: number;
+    query_hash: string;
+    query_length: number;
+};
+/**
+ * No session means no ring; the row hashes with SHA-256/16, since hashQueryText is FNV-1a and easy to reverse on short
+ * queries.
+ */
+export declare function anchorSkippedRows(who: RecallAuditCaller, query: string): AppendAuditOpts[];
+export declare function anchoringRows(who: RecallAuditCaller, hint: AnchoringHint | null): AppendAuditOpts[];
+export declare function availabilityRows(who: RecallAuditCaller, hint: AvailabilityHint | null): AppendAuditOpts[];
+export interface ShownRecall {
+    readonly query: string;
+    readonly ring: RingBuffer | null;
+    readonly topId: string | null;
+    readonly anchoring: AnchoringHint | null;
+    readonly availability: AvailabilityHint | null;
+}
+/**
+ * The hint rows for a list a surface showed, so a surface on the store port can hand them to the recall's one write.
+ */
+export declare function shownRecallRows(who: RecallAuditCaller, shown: ShownRecall): AppendAuditOpts[];
+/** 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: StoreContext, store: HippoStore, how: RecallRecording, shown: ShownList): Promise<void>;
+export {};
+//# sourceMappingURL=finish.d.ts.map