hippo-memory 1.68.0 → 1.70.0

package/dist/{prompt-hook.js → api/prompt-hook.js}

@@ -1,27 +1,28 @@
 // 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 './api.js';
-import { BadRequestError } from './api-errors.js';
-import { isSharedStore, loadConfig } from './config.js';
+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 { isSqliteBusy, noteStoreBusy } from './db.js';
-import { MAX_ID_LEN } from './http-util.js';
-import { isJsonString } from './json.js';
-import { withLedgerDb } from './ledger-db.js';
+import { MAX_ID_LEN } from '../util/http-util.js';
+import { isJsonString } from '../util/json.js';
+import { bookLedgerTurn, ledgerLastSent, noteLedgerRowSkipped } from './ledger-db.js';
 import { sessionPilotArm } from './pilot-arm.js';
-import { assertCallerProject, MAX_PROJECT_ALIASES } from './project-identity.js';
-import { writeDeliveryEventAtRoot, writeDeliveryEventOnHandle } from './recall-trace.js';
-import { blockHash, estimateTokens, hookPayloadString, isSubagentPayload, lastSentState, recordTokenUse, shouldSkipUnchanged, } from './token-ledger.js';
-/** With `db`, writes on the token ledger's handle (same store); without it, opens its own. A second flush is a no-op. */
-export function flushDeliveryRecorder(rec, db) {
+import { assertCallerProject, 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 { blockHash, estimateTokens } from '../util/token-text.js';
+import { errorMessage } from '../util/log.js';
+/** 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;
     try {
-        rec.flush((input) => (db ? writeDeliveryEventOnHandle(db, input) : writeDeliveryEventAtRoot(rec.root, input)));
+        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:${error instanceof Error ? error.message : String(error)}`);
+        console.error(`[hippo] 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. */
@@ -113,51 +114,31 @@ 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 = withLedgerDb(hippoRoot, (db) => lastSentState(db, view.tenantId, payloadSessionId, surface), ledgerOpts);
+    const last = ledgerLastSent(hippoRoot, view.tenantId, payloadSessionId, surface, ledgerOpts);
     if (!shouldSkipUnchanged(last ?? null, staticHash, refreshTurns))
         return false;
-    withLedgerDb(hippoRoot, (db) => {
-        recordTokenUse(db, {
-            tenantId: view.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
-            items: staticCount, tokens: estimateTokens(staticBlock), hash: staticHash,
-        });
-        if (recallBlock.trim())
-            return;
-        rec?.delivered({ state: 'reused', staticHash, staticReused: true });
-        flushDeliveryRecorder(rec, db);
+    bookLedgerTurn(hippoRoot, {
+        uses: [{
+                tenantId: view.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
+                items: staticCount, tokens: estimateTokens(staticBlock), hash: staticHash,
+            }],
+        delivery: recallBlock.trim() ? undefined : (write) => {
+            rec?.delivered({ state: 'reused', staticHash, staticReused: true });
+            flushDeliveryRecorder(rec, write);
+        },
     }, ledgerOpts);
     return true;
 }
-/** One connection for both rows; each insert in its own try so one failing doesn't skip the other. */
+/** 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) {
-    withLedgerDb(view.hippoRoot, (db) => {
-        if (staticPart.text) {
-            try {
-                recordTokenUse(db, {
-                    tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface, event: 'inject',
-                    items: staticPart.items, tokens: estimateTokens(staticPart.text), hash: blockHash(staticPart.text),
-                });
-                // Best-effort row: only a busy store is actionable, and a ledger failure must not break the hook.
-            }
-            catch (error) {
-                if (isSqliteBusy(error))
-                    noteStoreBusy('token ledger row skipped');
-            }
-        }
-        if (recallPart.text) {
-            try {
-                recordTokenUse(db, {
-                    tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface: 'hook_recall', event: 'inject',
-                    items: recallPart.items, tokens: estimateTokens(recallPart.text), hash: blockHash(recallPart.text),
-                });
-                // Same best-effort rule as the inject row above.
-            }
-            catch (error) {
-                if (isSqliteBusy(error))
-                    noteStoreBusy('token ledger row skipped');
-            }
-        }
-        flushDeliveryRecorder(view.rec, db);
+    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')] : [])],
+        onRowError: noteLedgerRowSkipped,
+        delivery: (write) => flushDeliveryRecorder(view.rec, write),
     }, { sharedStore: view.sharedStore });
 }
 // The flags HIPPO_PINNED_INJECT_COMMAND gives the local hook; the CLI parity test fails if the two drift.

package/dist/api/quarantine.d.ts

@@ -1,5 +1,5 @@
-import { type QuarantineStatus } from '../quarantine.js';
-import type { KeysetPosition } from '../keyset.js';
+import type { QuarantineStatus } from '../store/quarantine.js';
+import type { KeysetPosition } from '../util/keyset.js';
 import type { Context } from './types.js';
 export interface QuarantineListItem {
     id: string;
@@ -16,9 +16,9 @@ export declare function quarantineList(ctx: Context, opts?: {
     status?: QuarantineStatus | 'all';
     limit?: number;
     after?: KeysetPosition;
-}): QuarantineListItem[];
+}): Promise<QuarantineListItem[]>;
 /** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
-export declare function quarantineApprove(ctx: Context, id: string): void;
+export declare function quarantineApprove(ctx: Context, id: string): Promise<void>;
 /** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
-export declare function quarantineReject(ctx: Context, id: string): void;
+export declare function quarantineReject(ctx: Context, id: string): Promise<void>;
 //# sourceMappingURL=quarantine.d.ts.map

package/dist/api/quarantine.js

@@ -1,122 +1,46 @@
 // Quarantine review: list, approve and reject held memories.
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { ConflictError, ForbiddenError, NotFoundError } from '../api-errors.js';
-import { writeEntryMirrors } from '../store/entry-writes.js';
-import { readEntry, selectEntriesByIds } from '../store/entry-reads.js';
-import { quarantineScopeFor, getQuarantineRow, listQuarantineRows, approveQuarantineRow, rejectQuarantineRow, } from '../quarantine.js';
-import { log } from '../log.js';
-import { appendAuditEvent } from '../audit.js';
+import { ConflictError, ForbiddenError, NotFoundError } from '../core/api-errors.js';
+import { requireGroup, storeFor } from '../store/index.js';
 const QUARANTINE_PREVIEW_CHARS = 200;
 /** A tenant's quarantined memories, newest first. Default `status` is 'pending' (the review queue). */
-export function quarantineList(ctx, opts = {}) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        const rows = listQuarantineRows(db, ctx.tenantId, opts.status ?? 'pending', opts.limit, opts.after);
-        const entries = selectEntriesByIds(db, rows.map((row) => row.memoryId), ctx.tenantId);
-        return rows.map((row) => {
-            const entry = entries.get(row.memoryId);
-            return {
-                id: row.memoryId,
-                originalScope: row.originalScope,
-                reason: row.reason,
-                status: row.status,
-                quarantinedAt: row.quarantinedAt,
-                decidedAt: row.decidedAt,
-                decidedBy: row.decidedBy,
-                contentPreview: entry ? entry.content.slice(0, QUARANTINE_PREVIEW_CHARS) : '',
-            };
-        });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+export async function quarantineList(ctx, opts = {}) {
+    const rows = await requireGroup(storeFor(ctx), 'quarantine')
+        .listQuarantined(ctx.tenantId, { status: opts.status ?? 'pending', limit: opts.limit, after: opts.after });
+    return rows.map((row) => ({
+        id: row.memoryId,
+        originalScope: row.originalScope,
+        reason: row.reason,
+        status: row.status,
+        quarantinedAt: row.quarantinedAt,
+        decidedAt: row.decidedAt,
+        decidedBy: row.decidedBy,
+        contentPreview: (row.content ?? '').slice(0, QUARANTINE_PREVIEW_CHARS),
+    }));
 }
-function loadPendingQuarantineRow(db, tenantId, id) {
-    const row = getQuarantineRow(db, tenantId, id);
-    if (!row)
-        throw new NotFoundError(`not quarantined: ${id}`);
-    if (row.status !== 'pending')
-        throw new ConflictError(`${id} is already ${row.status}`);
-    return row;
+function refusalError(id, refusal) {
+    if (refusal.outcome === 'not_quarantined')
+        return new NotFoundError(`not quarantined: ${id}`);
+    return new ConflictError(`${id} is already ${refusal.status}`);
 }
 /** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
-export function quarantineApprove(ctx, id) {
+export async function quarantineApprove(ctx, id) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can approve a quarantined memory');
     }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const row = loadPendingQuarantineRow(db, ctx.tenantId, id);
-            const quarantineScope = quarantineScopeFor(row.originalScope);
-            const updated = db
-                .prepare(`UPDATE memories SET scope = ? WHERE id = ? AND tenant_id = ? AND scope = ?`)
-                .run(row.originalScope, id, ctx.tenantId, quarantineScope);
-            if (Number(updated.changes ?? 0) !== 1) {
-                throw new ConflictError(`memory ${id} scope changed since quarantine; refusing to approve`);
-            }
-            approveQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'quarantine_approve',
-                targetId: id,
-                metadata: { originalScope: row.originalScope },
-            });
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back */ }
-            throw err;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    // Post-commit, best-effort: a failed rewrite leaves the mirror showing the quarantine scope (fail-closed).
-    try {
-        const restored = readEntry(ctx.hippoRoot, id, ctx.tenantId);
-        if (restored)
-            writeEntryMirrors(ctx.hippoRoot, restored);
-    }
-    catch (err) {
-        log.error(`quarantine: mirror rewrite failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const result = await requireGroup(storeFor(ctx), 'quarantine').approveQuarantined(ctx.tenantId, id, ctx.actor.subject);
+    if (result.outcome === 'approved')
+        return;
+    if (result.outcome === 'scope_moved')
+        throw new ConflictError(`memory ${id} scope changed since quarantine; refusing to approve`);
+    throw refusalError(id, result);
 }
 /** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
-export function quarantineReject(ctx, id) {
+export async function quarantineReject(ctx, id) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can reject a quarantined memory');
     }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            loadPendingQuarantineRow(db, ctx.tenantId, id);
-            rejectQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'quarantine_reject',
-                targetId: id,
-                metadata: {},
-            });
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back */ }
-            throw err;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    const result = await requireGroup(storeFor(ctx), 'quarantine').rejectQuarantined(ctx.tenantId, id, ctx.actor.subject);
+    if (result.outcome !== 'rejected')
+        throw refusalError(id, result);
 }
 //# sourceMappingURL=quarantine.js.map

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

@@ -0,0 +1,4 @@
+import type { CliCoreRanker, RecallOpts, RecallResult } from './recall-types.js';
+import type { Context } from './types.js';
+export declare function retrieveWithCliCore(ctx: Context, opts: RecallOpts, core: CliCoreRanker): Promise<RecallResult>;
+//# sourceMappingURL=recall-core.d.ts.map

package/dist/api/recall-core.js

@@ -0,0 +1,112 @@
+// The CLI ranking core as a ranker of retrieve(): rank, let the caller pick the list it shows, then record that list once.
+import { ForbiddenError } from '../core/api-errors.js';
+import { reportAuditWriteFailure } from '../store/audit.js';
+import { decidePlanningFallacy, detectPlanningClaim } from '../predictions/planning-fallacy.js';
+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 { estimateTokens } from '../util/token-text.js';
+import { callerOf, recallAuditMetadata, recallAuditRow, strengthenOf } from './recall-record.js';
+import { recordTokens } from './tokens.js';
+// entriesByIds reads at most this many ids a call.
+const ID_READ_CHUNK = 500;
+export async function retrieveWithCliCore(ctx, opts, core) {
+    // This ranker applies the operator's scope rule and may search a second store, so no bearer client may reach it.
+    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);
+    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.
+        if (ranking.goalRecallLog.length > 0)
+            await store.finishRecall({ goalLog: ranking.goalRecallLog, audit: [] });
+        return resultOf(ranking, []);
+    }
+    if ('inspect' in core) {
+        core.inspect(ranking);
+        return resultOf(ranking, ranking.results);
+    }
+    const planning = await planningFor(ctx, store, opts.query);
+    const shown = core.show(ranking, planning?.output ?? {});
+    await recordShown(ctx, store, opts, core, { ranking, shown, planningAudit: planning?.audit });
+    const result = resultOf(ranking, shown.results);
+    if (planning?.output.hint)
+        result.planningFallacyHint = planning.output.hint;
+    if (planning?.output.watching)
+        result.planningFallacyWatching = planning.output.watching;
+    return result;
+}
+async function planningFor(ctx, store, query) {
+    const claim = detectPlanningClaim(query);
+    if (!claim)
+        return null;
+    return decidePlanningFallacy(claim, await store.planningFallacyEvidence(ctx.tenantId, claim.classQueryTokens), ctx.tenantId, ctx.actor.subject);
+}
+function resultOf(ranking, shown) {
+    const results = shown.map((r) => ({ id: r.entry.id, content: r.entry.content, score: r.score, layer: r.entry.layer, strength: r.entry.strength }));
+    return {
+        results,
+        total: ranking.totalCandidates + ranking.graphAdded,
+        tokens: results.reduce((sum, r) => sum + estimateTokens(r.content), 0),
+    };
+}
+/** Audit rows first: a recall they cannot be written for leaves no strengthen, trace, marker or count, as under the other rankers. */
+async function recordShown(ctx, store, opts, core, done) {
+    const { ranking, shown, planningAudit } = done;
+    const ids = shown.results.map((r) => r.entry.id);
+    const recallRow = recallAuditRow(callerOf(ctx), 'recall', undefined, recallAuditMetadata(opts.query, ids.length));
+    const second = core.sources?.globalRoot !== undefined && core.sources.globalRoot !== ctx.hippoRoot ? core.sources.globalRoot : undefined;
+    const heldElsewhere = second !== undefined ? await idsNotHeld(store, ids, ctx.tenantId) : [];
+    const audited = await finishOrReport(store, {
+        goalLog: ranking.goalRecallLog,
+        audit: [...(planningAudit ? [planningAudit] : []), ...shown.audit, recallRow],
+        strengthen: strengthenOf(ctx, ids),
+    });
+    if (audited) {
+        // 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);
+    }
+    // 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 has ranked and is about to print, so a failed audit write is logged and counted, never thrown.
+async function finishOrReport(store, writes) {
+    try {
+        await store.finishRecall(writes);
+        return true;
+    }
+    catch (err) {
+        reportAuditWriteFailure('recall', String(err));
+        return false;
+    }
+}
+async function idsNotHeld(store, ids, tenantId) {
+    const held = new Set();
+    for (let i = 0; i < ids.length; i += ID_READ_CHUNK) {
+        for (const entry of await store.entriesByIds(ids.slice(i, i + ID_READ_CHUNK), tenantId))
+            held.add(entry.id);
+    }
+    return ids.filter((id) => !held.has(id));
+}
+async function traceAndMark(ctx, store, 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,
+        sessionId: opts.sessionId || core.hostSessionId || null,
+        pipeline: 'cli',
+        query: opts.query,
+        explainMode: core.rank.why === true,
+        results: shown.map((r) => ({ memoryId: r.entry.id, score: r.score, rerankSteps: r.rerankTrace })),
+    });
+    if (shown.length === 0)
+        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/{recall-history.js → api/recall-history.js}

@@ -17,7 +17,7 @@
  * AnchoringHint + PlanningFallacyHint are independent
  * signals; both can fire on the same recall.
  */
-import { envAnchoringOff, envAvailabilityOff } from './env.js';
+import { envAnchoringOff, envAvailabilityOff } from '../util/env.js';
 const DEFAULT_MIN_DOMINANCE = 3;
 const DEFAULT_RECENT_REPEAT_WINDOW = 5;
 const DEFAULT_COOLDOWN = 3;
@@ -47,7 +47,7 @@ export function hashQueryText(query) {
         .split(/\s+/)
         .filter((t) => t.length > 0);
     // Drop tokens under 3 chars (filler words) so `a login bug` and `login bug` hash
-    // alike; matches the >=3 filter in src/forward-claim-detector.ts.
+    // alike; matches the >=3 filter in src/learn/forward-claim-detector.ts.
     const filtered = normalized.filter((t) => t.length >= 3);
     // Fall back to all tokens when the filter empties the query (CJK 2-char words,
     // acronyms like `AI`) so distinct short queries do not all hash to fnv1a32('').
@@ -101,17 +101,8 @@ export function detectAnchoring(history, currentQueryHash, currentTopMemoryId, o
             return null;
         }
     }
-    // memory_dominance check FIRST (wins on tie). Count distinct queryHashes in history
-    // where topMemoryId === currentTopMemoryId (excluding null tops).
-    const matchingQueryHashes = new Set();
-    for (const entry of history) {
-        if (entry.topMemoryId === currentTopMemoryId) {
-            matchingQueryHashes.add(entry.queryHash);
-        }
-    }
-    // Include current query in the count.
-    matchingQueryHashes.add(currentQueryHash);
-    const queryCount = matchingQueryHashes.size;
+    // memory_dominance check FIRST (wins on tie).
+    const queryCount = countDistinctQueries(history, currentQueryHash, currentTopMemoryId);
     if (queryCount >= minDominance) {
         return {
             reason: 'memory_dominance',
@@ -121,21 +112,35 @@ export function detectAnchoring(history, currentQueryHash, currentTopMemoryId, o
             source: 'j1-recurrence',
         };
     }
-    // query_repeat check: is currentQueryHash present in the last `recentRepeatWindow`
-    // entries AND was that entry's topMemoryId === currentTopMemoryId?
-    const r1Slice = history.slice(-recentRepeatWindow);
-    for (const entry of r1Slice) {
-        if (entry.queryHash === currentQueryHash && entry.topMemoryId === currentTopMemoryId) {
-            return {
-                reason: 'query_repeat',
-                memoryId: currentTopMemoryId,
-                summary: `Same query phrasing as a recent recall returned the same top result (${currentTopMemoryId}); you may be re-asking the same question.`,
-                source: 'j1-recurrence',
-            };
-        }
+    if (isRecentRepeat(history, recentRepeatWindow, currentQueryHash, currentTopMemoryId)) {
+        return {
+            reason: 'query_repeat',
+            memoryId: currentTopMemoryId,
+            summary: `Same query phrasing as a recent recall returned the same top result (${currentTopMemoryId}); you may be re-asking the same question.`,
+            source: 'j1-recurrence',
+        };
     }
     return null;
 }
+// Count distinct queryHashes in history where topMemoryId === the current top
+// (excluding null tops), plus the current query itself.
+function countDistinctQueries(history, currentQueryHash, currentTopMemoryId) {
+    const matchingQueryHashes = new Set();
+    for (const entry of history) {
+        if (entry.topMemoryId === currentTopMemoryId) {
+            matchingQueryHashes.add(entry.queryHash);
+        }
+    }
+    matchingQueryHashes.add(currentQueryHash);
+    return matchingQueryHashes.size;
+}
+// query_repeat check: is currentQueryHash present in the last `recentRepeatWindow`
+// entries AND was that entry's topMemoryId === currentTopMemoryId?
+function isRecentRepeat(history, recentRepeatWindow, currentQueryHash, currentTopMemoryId) {
+    return history
+        .slice(-recentRepeatWindow)
+        .some((entry) => entry.queryHash === currentQueryHash && entry.topMemoryId === currentTopMemoryId);
+}
 // ---------------------------------------------------------------------------
 // RingBuffer + caller-side state helpers
 // ---------------------------------------------------------------------------

package/dist/{recall-pipeline.d.ts → api/recall-pipeline.d.ts}

@@ -1,8 +1,8 @@
-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, SearchResult } from './search/types.js';
+import { type GoalRecallLogRow } from '../store/goals.js';
+import { type MemoryEntry } from '../core/memory.js';
+import type { PhysicsConfig } from '../core/physics-config.js';
+import type { RerankerFn } from '../rerankers/types.js';
+import type { ResultCost, SearchResult } from '../core/search-types.js';
 /** Stores rankRecall reads and where it sends operator notes. */
 export interface RankRecallCtx {
     hippoRoot: string;