hippo-memory 1.64.0 → 1.65.0

package/dist/predictions/planning-fallacy.js

@@ -28,7 +28,7 @@ import { computePredictionBaserate } from './store.js';
  *     test asserting that scope-set predictions surface via no-scope
  *     recalls (so future "fix" attempts that scope-filter trip CI).
  */
-function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
+export function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
     if (queryTokens.length === 0)
         return { classTag: null, tiebreak: false };
     const db = openHippoDb(hippoRoot);
@@ -100,56 +100,69 @@ function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
  * Latency budget: well under 50ms; a miss pays only the regex.
  */
 export function computePlanningFallacyOutput(hippoRoot, tenantId, queryText, opts = {}) {
-    // Env read FIRST so AUTODEBIAS=off pays zero regex cost. Per-call read
-    // (rather than module-load cache) is deliberate: tests env-toggle this
-    // via process.env mutation without module reload.
-    const mode = opts.mode ?? (envAutodebiasOff() ? 'off' : 'regex');
-    if (mode === 'off')
-        return {};
-    if (!queryText)
-        return {};
-    const match = detectForwardClaim(queryText);
+    const match = detectPlanningClaim(queryText, opts);
     if (!match)
         return {};
     const actor = opts.actor ?? 'recall';
-    const resolution = resolveClassFromTokens(hippoRoot, tenantId, match.classQueryTokens);
-    if (resolution.tiebreak) {
+    const { output, audit } = decidePlanningFallacy(match, planningFallacyEvidenceAt(hippoRoot, tenantId, match.classQueryTokens), tenantId, actor);
+    if (audit)
+        appendAuditEventOnce(hippoRoot, audit);
+    return output;
+}
+/** The forward claim in a recall query; null when HIPPO_AUTODEBIAS=off, the query is empty or no claim matches. */
+export function detectPlanningClaim(queryText, opts = {}) {
+    // Env read FIRST so AUTODEBIAS=off pays zero regex cost; read per call so tests can toggle it without a module reload.
+    const mode = opts.mode ?? (envAutodebiasOff() ? 'off' : 'regex');
+    if (mode === 'off')
+        return null;
+    if (!queryText)
+        return null;
+    return detectForwardClaim(queryText);
+}
+/** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
+export function planningFallacyEvidenceAt(hippoRoot, tenantId, classQueryTokens) {
+    const resolution = resolveClassFromTokens(hippoRoot, tenantId, classQueryTokens);
+    // emitAudit=false: the recall_autodebias_hint row carries n_closed and mean_ratio, so predict_baserate stays off.
+    const baserate = resolution.classTag ? computePredictionBaserate(hippoRoot, tenantId, resolution.classTag, 'recall', false) : null;
+    return { ...resolution, baserate };
+}
+/** The hint, the watching variant or nothing for a claim and its class evidence; reads and writes nothing itself. */
+export function decidePlanningFallacy(match, evidence, tenantId, actor) {
+    if (evidence.tiebreak) {
         // Telemetry: forward-claim detected, ≥2 classes tied at best overlap. The watching variant lets the
         // caller render "watching but no baserate (tiebreak)"; the audit channel stays the source of truth.
-        return watchingWithAudit(hippoRoot, tenantId, actor, match, 'tiebreak', TIEBREAK_SUGGESTION);
+        return watchingWithAudit(tenantId, actor, match, 'tiebreak', TIEBREAK_SUGGESTION);
     }
-    if (!resolution.classTag) {
-        // Telemetry: forward-claim detected, no class scored ≥ 1. High volume here means regex+token-overlap
-        // misses real forward-claims with no class signal, the case for an embedding fallback.
-        // The watching variant lets the caller render "watching but no baserate (no class match)".
-        return watchingWithAudit(hippoRoot, tenantId, actor, match, 'no_class_match', NO_CLASS_MATCH_SUGGESTION);
+    if (!evidence.classTag) {
+        // Telemetry: no class scored ≥ 1. High volume here means regex+token-overlap misses real forward-claims
+        // with no class signal, the case for an embedding fallback.
+        return watchingWithAudit(tenantId, actor, match, 'no_class_match', NO_CLASS_MATCH_SUGGESTION);
     }
-    // emitAudit=false: avoid double-write to predict_baserate channel.
-    // The recall_autodebias_hint audit below carries n_closed + mean_ratio.
-    const baserate = computePredictionBaserate(hippoRoot, tenantId, resolution.classTag, actor, 
-    /*emitAudit=*/ false);
-    if (baserate.nClosed === 0)
-        return {}; // Silent — wait for closed data.
-    appendAuditEventOnce(hippoRoot, {
-        tenantId,
-        actor,
-        op: 'recall_autodebias_hint',
-        targetId: resolution.classTag,
-        metadata: {
-            class_tag: resolution.classTag,
-            detected_phrase: match.phrase,
-            n_closed: baserate.nClosed,
-            mean_ratio: baserate.meanRatio,
-        },
-    });
+    const baserate = evidence.baserate;
+    if (!baserate || baserate.nClosed === 0)
+        return { output: {} }; // Silent — wait for closed data.
     return {
-        hint: {
-            classTag: resolution.classTag,
-            baserateSummary: baserate.summary,
-            source: 'j3.2-auto',
-            detectedPhrase: match.phrase,
-            nClosed: baserate.nClosed,
-            meanRatio: baserate.meanRatio,
+        output: {
+            hint: {
+                classTag: evidence.classTag,
+                baserateSummary: baserate.summary,
+                source: 'j3.2-auto',
+                detectedPhrase: match.phrase,
+                nClosed: baserate.nClosed,
+                meanRatio: baserate.meanRatio,
+            },
+        },
+        audit: {
+            tenantId,
+            actor,
+            op: 'recall_autodebias_hint',
+            targetId: evidence.classTag,
+            metadata: {
+                class_tag: evidence.classTag,
+                detected_phrase: match.phrase,
+                n_closed: baserate.nClosed,
+                mean_ratio: baserate.meanRatio,
+            },
         },
     };
 }
@@ -165,19 +178,21 @@ function appendAuditEventOnce(hippoRoot, event) {
         closeHippoDb(db);
     }
 }
-function watchingWithAudit(hippoRoot, tenantId, actor, match, reason, suggestion) {
-    appendAuditEventOnce(hippoRoot, {
-        tenantId,
-        actor,
-        op: reason === 'tiebreak' ? 'recall_autodebias_hint_tiebreak' : 'recall_autodebias_hint_no_class_match',
-        targetId: match.phrase.slice(0, 100),
-        metadata: { detected_phrase: match.phrase, token_count: match.classQueryTokens.length },
-    });
+function watchingWithAudit(tenantId, actor, match, reason, suggestion) {
     return {
-        watching: {
-            detectedPhrase: match.phrase,
-            reason,
-            suggestion,
+        output: {
+            watching: {
+                detectedPhrase: match.phrase,
+                reason,
+                suggestion,
+            },
+        },
+        audit: {
+            tenantId,
+            actor,
+            op: reason === 'tiebreak' ? 'recall_autodebias_hint_tiebreak' : 'recall_autodebias_hint_no_class_match',
+            targetId: match.phrase.slice(0, 100),
+            metadata: { detected_phrase: match.phrase, token_count: match.classQueryTokens.length },
         },
     };
 }

package/dist/recall-trace.d.ts

@@ -173,7 +173,7 @@ export interface DeliveryEventRow {
 }
 /** One event plus its candidates in one write transaction, then prune; fail-soft. The caller must not hold a transaction on `db`. */
 export declare function writeDeliveryEvent(db: DatabaseSyncLike, input: DeliveryEventInput): number | null;
-/** Write on a short-lived connection that waits at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
+/** Write on the request's handle, or a short-lived one, waiting at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
 export declare function writeDeliveryEventAtRoot(root: string, input: DeliveryEventInput): number | null;
 /** On a caller's open handle, which saves a second open and close per turn; the handle's own lock wait comes back after. */
 export declare function writeDeliveryEventOnHandle(db: DatabaseSyncLike, input: DeliveryEventInput): number | null;

package/dist/recall-trace.js

@@ -15,7 +15,7 @@
  * new debug env var).
  */
 import { createHash } from 'node:crypto';
-import { openHippoDb, closeHippoDb } from './db.js';
+import { openHippoDb, closeHippoDb, rethrowIfSqliteBlocked } from './db.js';
 import { DELIVERY_LEDGER_VERSION } from './delivery-recorder.js';
 import { log } from './log.js';
 /**
@@ -109,6 +109,7 @@ export function writeRecallTraceAtRoot(root, input) {
         db = openHippoDb(root);
     }
     catch (error) {
+        rethrowIfSqliteBlocked(error);
         log.error(`recall trace connection failed: ${error instanceof Error ? error.message : String(error)}`);
         return null;
     }
@@ -267,11 +268,11 @@ export function writeDeliveryEvent(db, input) {
         return null;
     }
 }
-/** Write on a short-lived connection that waits at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
+/** Write on the request's handle, or a short-lived one, waiting at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
 export function writeDeliveryEventAtRoot(root, input) {
     let db;
     try {
-        db = openHippoDb(root, { busyWaitMs: DELIVERY_LEDGER_WAIT_MS });
+        db = openHippoDb(root);
     }
     catch (error) {
         // Same hook stderr line as writeDeliveryEvent above.
@@ -279,7 +280,7 @@ export function writeDeliveryEventAtRoot(root, input) {
         return null;
     }
     try {
-        return writeDeliveryEvent(db, input);
+        return writeDeliveryEventOnHandle(db, input);
     }
     finally {
         closeHippoDb(db);

package/dist/search/physics-search.js

@@ -6,7 +6,7 @@ import { resolveEmbeddingProvider } from '../embedding-provider.js';
 import { physicsScore as computePhysicsScores, computeMass } from '../physics.js';
 import { DEFAULT_PHYSICS_CONFIG } from '../physics-config.js';
 import { loadPhysicsState } from '../physics-state.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
+import { openHippoDb, closeHippoDb, rethrowIfSqliteBlocked } from '../db.js';
 import { compareScoredResults } from '../compare.js';
 import { log } from '../log.js';
 import { churnStaleFactor, summaryMultipliers, summaryScoring } from './boosts.js';
@@ -57,6 +57,7 @@ async function physicsQueryVector(query, root, given) {
         return vec && vec.length > 0 ? vec : null;
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         log.debug(`physics search: query embed failed, using hybrid: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
@@ -68,6 +69,7 @@ function withVectorCandidates(root, entries, queryVector, spec) {
         return [...entries, ...vectorCandidatesOutside(root, entries, queryVector, spec)];
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         log.warn(`physics search ranked the lexical pool only; the vector lookup failed: ${err instanceof Error ? err.message : String(err)}`);
         return entries;
     }
@@ -84,6 +86,7 @@ function loadCandidateParticles(root, pool) {
         }
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         log.debug(`physics search: state load failed, using hybrid: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }

package/dist/search/vector.js

@@ -1,6 +1,7 @@
 import { cosineSimilarity, embeddingModelRequiresReindex, hasEmbeddings, loadStoredVectors } from '../embeddings.js';
 import { loadVectorCandidateEntries } from '../store/search-rows.js';
 import { resolveEmbeddingProvider } from '../embedding-provider.js';
+import { rethrowIfSqliteBlocked } from '../db.js';
 import { log } from '../log.js';
 import { redactSecretsStrict } from '../secret-detect.js';
 import { currentEntries } from './as-of.js';
@@ -22,6 +23,7 @@ export async function resolveVectorArm(query, entries, options) {
         await fillVectorArm(arm, query, options.hippoRoot, options);
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         warnBm25Fallback('error', err instanceof Error ? err.message : String(err));
     }
     return arm;

package/dist/server/routes/recall.d.ts

@@ -1,5 +1,5 @@
 import type { RouteRequest } from '../types.js';
-/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+/** Test-only: reset the HTTP recall rings. Call from beforeEach. */
 export declare function __resetSessionRecallHistoryHttp(): void;
 export declare function handleRecallMemories({ req, res, opts, query }: RouteRequest): Promise<void>;
 export declare function handleAssembleSession({ req, res, opts, query }: RouteRequest, assembleMatch: Record<string, string>): Promise<void>;

package/dist/server/routes/recall.js

@@ -3,185 +3,47 @@ import { dirname, resolve } from 'node:path';
 import { assertCallerProject, resolveProjectIdentity } from '../../project-identity.js';
 import { isSharedStore } from '../../config.js';
 import { assembleCost, contextCost, drillCost } from '../../context-render.js';
-import { closeHippoDb, openHippoDb } from '../../db.js';
-import { updateStats } from '../../store/index-and-stats.js';
-import { appendRecall, biasHintEnabled, buildSessionKey, getOrCreateRing, hashQueryText, snapshotRing } from '../../recall-history.js';
-import { appendAuditEvent, auditQueryFields } from '../../audit.js';
+import { storeFor } from '../../store-port.js';
+import { biasHintEnabled } from '../../recall-history.js';
 import { assemble, drillDown, getContext, recordTokens, retrieve } from '../../api.js';
-import { HttpError, MAX_ID_LEN, sendJson } from '../../http-util.js';
+import { httpParams, parseContextRequest, parseRecallRequest } from '../../api/recall-request.js';
+import { anchorSkippedRows, noteRecall, peekSessionRing, resetSessionRings, sessionRing } from '../../api/recall-record.js';
+import { HttpError, sendJson } from '../../http-util.js';
 import { buildContextWithAuth } from '../auth.js';
-import { parseListLimit, validateIdSegment } from '../validation.js';
-// Module-level per-(tenant, session) recall-history ring map
-// for the HTTP pipeline. Separate from CLI/MCP rings (per-
-// pipeline rings; no IPC). HTTP is the only caller that threads its
-// snapshot through opts.recallHistory to api.recall — api.recall's
-// anchoringHint on the returned RecallResult IS the user-visible hint
-// here (no separate compute needed).
-const sessionRecallHistoryHttp = new Map();
-/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+import { validateIdSegment } from '../validation.js';
+/** Test-only: reset the HTTP recall rings. Call from beforeEach. */
 export function __resetSessionRecallHistoryHttp() {
-    sessionRecallHistoryHttp.clear();
+    resetSessionRings('http');
 }
-function parseFreshTail(query) {
-    // Surface the fresh-tail RecallOpts to HTTP callers so session-scoped
-    // fresh-tail and summary substitution are not JS-only.
-    const freshTailCountRaw = query.get('fresh_tail_count');
-    const freshTailCount = freshTailCountRaw === null ? undefined : Number(freshTailCountRaw);
-    if (freshTailCount !== undefined && (!Number.isFinite(freshTailCount) || freshTailCount < 0)) {
-        throw new HttpError(400, 'fresh_tail_count must be a non-negative number');
-    }
-    // Cap session_id length consistent with the
-    // rest of the API. Untrimmed strings round-trip through the SQL layer
-    // and through any downstream metric/log; 256 is generous for a session
-    // id and matches the rest of this file's id-shaped param parsers.
-    const freshTailSessionIdRaw = query.get('fresh_tail_session_id');
-    if (freshTailSessionIdRaw !== null && freshTailSessionIdRaw.length > MAX_ID_LEN) {
-        throw new HttpError(400, `fresh_tail_session_id exceeds ${MAX_ID_LEN}-character cap`);
-    }
-    const freshTailSessionId = freshTailSessionIdRaw && freshTailSessionIdRaw.length > 0
-        ? freshTailSessionIdRaw
-        : undefined;
-    return { freshTailCount, freshTailSessionId };
-}
-function parseSessionId(query) {
-    // session_id for the dlPFC goal-stack boost. 256-char cap mirrors
-    // fresh_tail_session_id (above). Trim then drop if empty so api.recall
-    // sees undefined when the param is omitted or whitespace-only.
-    const sessionIdRaw = query.get('session_id');
-    if (sessionIdRaw !== null && sessionIdRaw.length > MAX_ID_LEN) {
-        throw new HttpError(400, `session_id exceeds ${MAX_ID_LEN}-character cap`);
-    }
-    return sessionIdRaw && sessionIdRaw.trim().length > 0
-        ? sessionIdRaw.trim()
-        : undefined;
-}
-function parseRecallQuery(query) {
-    const q = query.get('q');
-    if (!q) {
-        throw new HttpError(400, 'q is required');
-    }
-    const limitRaw = query.get('limit');
-    const limit = limitRaw === null ? undefined : parseListLimit(limitRaw);
-    const mode = query.get('mode');
-    if (mode !== null && mode !== 'bm25' && mode !== 'hybrid' && mode !== 'physics') {
-        throw new HttpError(400, "mode must be 'bm25', 'hybrid', or 'physics'");
-    }
-    const scope = query.get('scope');
-    const includeContinuityRaw = query.get('include_continuity');
-    const includeContinuity = includeContinuityRaw === '1'
-        || includeContinuityRaw === 'true';
-    const { freshTailCount, freshTailSessionId } = parseFreshTail(query);
-    // Strict parse matching the includeContinuity convention, so values
-    // like `?summarize_overflow=banana` or an empty value do not turn it on.
-    const summarizeOverflowRaw = query.get('summarize_overflow');
-    const summarizeOverflow = summarizeOverflowRaw === null
-        ? undefined
-        : (summarizeOverflowRaw === '1' || summarizeOverflowRaw === 'true');
-    // recall() owns the shape rule (NaN, 0 and negatives throw invalid_scorer_window); the transport caps remote cost.
-    const scorerWindowRaw = query.get('scorer_window');
-    const scorerWindow = scorerWindowRaw === null ? undefined : Number(scorerWindowRaw);
-    if (scorerWindow !== undefined && scorerWindow > 1000) {
-        throw new HttpError(400, 'scorer_window must be <= 1000');
-    }
-    const sessionId = parseSessionId(query);
-    // Recall-trace: opt-in explain flag. When set, api.recall attaches the
-    // lifecycle re-ranking trace (goal-boost step on the api pipeline) +
-    // rerankPipeline:'api' to each result item; the field then rides on the
-    // serialized RecallResult. Mirrors the include_continuity convention.
-    const explainRaw = query.get('explain');
-    const explain = explainRaw === '1' || explainRaw === 'true';
-    return { q, limit, mode, scope, includeContinuity, freshTailCount, freshTailSessionId, summarizeOverflow, scorerWindow, sessionId, explain };
-}
-// HTTP per-pipeline anchoring detector. HTTP threads its
-// ring snapshot via opts.recallHistory so api.recall's own
-// anchoringHint compute path activates. Unlike CLI (which computes
-// its own hint separately because cmdRecall runs its own physics/
-// hybrid pipeline outside api.recall), HTTP's /v1/memories response
-// body IS api.recall's result directly. So the api.recall-computed
-// hint flows through. HIPPO_ANCHORING=off short-circuits.
-function snapshotSessionRing(ctx, hippoRoot, q, sessionId) {
-    let httpRecallHistory;
-    let httpRingKey;
-    if (biasHintEnabled('anchoring')) {
-        if (sessionId) {
-            // Do NOT mutate sessionRecallHistoryHttp before recall() preflight: a request
-            // that 400s would otherwise create-or-touch a ring and LRU-evict valid sessions.
-            httpRingKey = buildSessionKey(ctx.tenantId, sessionId);
-            const existingRing = sessionRecallHistoryHttp.get(httpRingKey);
-            httpRecallHistory = existingRing ? snapshotRing(existingRing) : [];
-        }
-        else {
-            // Telemetry: caller had no session_id so ring tracking skipped.
-            // Per the normal recall-audit convention (api.ts:854 stores
-            // SHA-256/16 hash of the query, NOT raw text), avoid retaining
-            // prompts in audit_log here too — query content can contain
-            // secrets, PII, or RTBF-restricted material. hashQueryText is a 32-bit
-            // FNV-1a, NOT a privacy hash, so use the recall audit's SHA-256/16 truncation.
-            const dbForAudit = openHippoDb(hippoRoot);
-            try {
-                appendAuditEvent(dbForAudit, {
-                    tenantId: ctx.tenantId,
-                    actor: ctx.actor.subject,
-                    op: 'recall_anchor_skipped_no_session',
-                    targetId: undefined,
-                    metadata: auditQueryFields(q),
-                });
-            }
-            finally {
-                closeHippoDb(dbForAudit);
-            }
-        }
-    }
-    return { httpRecallHistory, httpRingKey };
-}
-function recallExtraOpts(parsed, httpRecallHistory) {
-    const recallExtra = {};
-    if (parsed.freshTailCount !== undefined)
-        recallExtra.freshTailCount = parsed.freshTailCount;
-    if (parsed.freshTailSessionId !== undefined)
-        recallExtra.freshTailSessionId = parsed.freshTailSessionId;
-    if (parsed.summarizeOverflow !== undefined)
-        recallExtra.summarizeOverflow = parsed.summarizeOverflow;
-    if (parsed.scorerWindow !== undefined)
-        recallExtra.scorerWindow = parsed.scorerWindow;
-    if (parsed.sessionId !== undefined)
-        recallExtra.sessionId = parsed.sessionId;
-    if (httpRecallHistory !== undefined)
-        recallExtra.recallHistory = httpRecallHistory;
-    if (parsed.explain)
-        recallExtra.explain = parsed.explain;
-    return recallExtra;
+// HTTP threads the ring through opts.recallHistory, so the hint retrieve() returns is the one the caller sees.
+async function recallHistoryFor(ctx, q, sessionId) {
+    if (!biasHintEnabled('anchoring'))
+        return undefined;
+    if (sessionId)
+        return peekSessionRing('http', ctx.tenantId, sessionId);
+    await storeFor(ctx).appendAuditEvents(anchorSkippedRows({ tenantId: ctx.tenantId, actor: ctx.actor.subject }, q));
+    return undefined;
 }
 // GET /v1/memories?q=...&limit=...&mode=...&scope=...&include_continuity=1
 export async function handleRecallMemories({ req, res, opts, query }) {
-    const parsed = parseRecallQuery(query);
-    const { q, includeContinuity, sessionId } = parsed;
+    const { opts: recallOpts, limit, mode, explain } = parseRecallRequest(httpParams(query));
+    const { query: q, includeContinuity, sessionId } = recallOpts;
     const ctx = await buildContextWithAuth(req, opts);
-    const { httpRecallHistory, httpRingKey } = snapshotSessionRing(ctx, opts.hippoRoot, q, sessionId);
-    const result = await retrieve(ctx, {
-        query: q,
-        limit: parsed.limit,
-        mode: parsed.mode ?? undefined,
-        scope: parsed.scope ?? undefined,
-        includeContinuity,
-        ...recallExtraOpts(parsed, httpRecallHistory),
-    });
-    // Append only after recall succeeds, so a 400 cannot LRU-evict valid sessions;
-    // anchoredOn feeds the cooldown logic for the NEXT recall on this session.
-    if (httpRingKey) {
-        const httpRing = getOrCreateRing(sessionRecallHistoryHttp, httpRingKey);
-        const topId = result.results[0]?.id ?? null;
-        appendRecall(httpRing, hashQueryText(q), topId, result.anchoringHint?.memoryId);
-    }
+    const recallHistory = await recallHistoryFor(ctx, q, sessionId);
+    const result = await retrieve(ctx, { ...recallOpts, limit, mode, explain, recallHistory });
+    // The ring is created only after recall succeeds, so a 400 cannot LRU-evict a live session.
+    const ring = sessionRing('http', ctx.tenantId, sessionId);
+    if (ring)
+        noteRecall(ring, q, result.results[0]?.id ?? null, result.anchoringHint?.memoryId);
     // Each recall surface counts its own hits; api.recall is no chokepoint,
     // since the CLI never calls it and MCP shows the user a different band.
-    updateStats(opts.hippoRoot, { recalled: result.results.length });
+    await storeFor(ctx).bumpRecallStats(result.results.length);
     // Continuity payloads should never be cached. The caller is asking for
     // session-state-aware data; intermediaries must not reuse it across users.
     if (includeContinuity) {
         res.setHeader('Cache-Control', 'no-store');
     }
-    recordTokens(ctx, 'http_recall', { items: result.results.length, tokens: result.tokens + (result.continuityTokens ?? 0), sessionId: sessionId ?? null });
+    await recordTokens(ctx, 'http_recall', { items: result.results.length, tokens: result.tokens + (result.continuityTokens ?? 0), sessionId: sessionId ?? null });
     sendJson(res, 200, result);
     return;
 }
@@ -220,7 +82,7 @@ export async function handleAssembleSession({ req, res, opts, query }, assembleM
     if (scope !== undefined)
         assembleExtra.scope = scope;
     const result = assemble(ctx, assembleMatch.id, { ...assembleExtra, cost: assembleCost(assembleMatch.id) });
-    recordTokens(ctx, 'http_assemble', { items: result.items.length, tokens: result.tokens, sessionId: assembleMatch.id });
+    await recordTokens(ctx, 'http_assemble', { items: result.items.length, tokens: result.tokens, sessionId: assembleMatch.id });
     sendJson(res, 200, result);
     return;
 }
@@ -290,64 +152,14 @@ function contextReader(hippoRoot, query) {
 // via the Bearer. Pinned-only + '*' fallback skip the recall audit emit
 // (matches cmdContext); real-query hybrid search emits one 'recall' row.
 export async function handleGetContext({ req, res, opts, query }) {
-    const q = query.get('q') ?? undefined;
-    // DoS cap on q-param length. 1024 covers real multi-clause queries
-    // (pasted error messages, multi-stem searches) while bounding BM25
-    // tokenisation cost (~150 tokens worst case at 1024 chars).
-    if (q !== undefined && q.length > 1024) {
-        throw new HttpError(400, 'q exceeds 1024-character cap');
-    }
-    const budgetRaw = query.get('budget');
-    let budget;
-    if (budgetRaw !== null) {
-        budget = Number(budgetRaw);
-        if (!Number.isFinite(budget) || budget < 0) {
-            throw new HttpError(400, 'budget must be a non-negative number');
-        }
-    }
-    const limitRaw = query.get('limit');
-    let limit;
-    if (limitRaw !== null) {
-        limit = Number(limitRaw);
-        if (!Number.isFinite(limit) || limit <= 0) {
-            throw new HttpError(400, 'limit must be a positive number');
-        }
-    }
-    const pinnedOnlyRaw = query.get('pinned_only');
-    const pinnedOnly = pinnedOnlyRaw === '1' || pinnedOnlyRaw === 'true';
-    const scopeRaw = query.get('scope');
-    if (scopeRaw !== null && scopeRaw.length > MAX_ID_LEN) {
-        throw new HttpError(400, `scope exceeds ${MAX_ID_LEN}-character cap`);
-    }
-    const scope = scopeRaw === null ? undefined : scopeRaw;
-    const includeRecentRaw = query.get('include_recent');
-    let includeRecent;
-    if (includeRecentRaw !== null) {
-        includeRecent = Number(includeRecentRaw);
-        if (!Number.isFinite(includeRecent) || includeRecent < 0) {
-            throw new HttpError(400, 'include_recent must be a non-negative number');
-        }
-    }
-    // v39 memory scope isolation: cross_project=1|true re-includes
-    // other-project rows (tagged category 'cross-project' in the response).
-    // The partition identity comes from the SERVED STORE's location, not the
-    // daemon's process cwd - a daemon started from anywhere still isolates
-    // the project it serves.
-    const crossProjectRaw = query.get('cross_project');
-    const crossProject = crossProjectRaw === '1' || crossProjectRaw === 'true';
+    const parsed = parseContextRequest(httpParams(query));
     const ctx = await buildContextWithAuth(req, opts);
     const result = await getContext(ctx, {
-        q,
-        budget,
-        limit,
-        pinnedOnly,
-        scope,
-        includeRecent,
-        crossProject,
+        ...parsed,
         currentProject: contextReader(opts.hippoRoot, query),
         cost: contextCost('markdown', 'observe'), // clients render; the budget prices the block `hippo context` would print
     });
-    recordTokens(ctx, 'http_context', { items: result.entries.length, tokens: result.tokens });
+    await recordTokens(ctx, 'http_context', { items: result.entries.length, tokens: result.tokens });
     sendJson(res, 200, result);
     return;
 }

package/dist/server.d.ts

@@ -11,8 +11,19 @@ export { HttpError } from './http-util.js';
 export { promptHookContext, type CallerProject } from './prompt-hook.js';
 export type { JsonValue } from './json.js';
 export { captureSessionTexts, type SessionCaptureRequest, type SessionCaptureResult } from './capture/session-texts.js';
-export { sqliteStore, type HippoStore } from './store-port.js';
+export { sqliteStore, type HippoStore, type RecallSearchArgs, type RecallWrites } from './store-port.js';
 export type { ApiKeyRecord } from './auth.js';
+export type { AppendAuditOpts } from './audit.js';
+export type { ContinuityBlock } from './api/recall-types.js';
+export type { ActiveGoals, GetActiveGoalsOpts, Goal, GoalRecallLogRow, RetrievalPolicy } from './goals.js';
+export type { MemoryEntry } from './memory.js';
+export type { ClassResolution, PlanningFallacyEvidence } from './predictions/planning-fallacy.js';
+export type { PredictionBaserate } from './predictions/store.js';
+export type { RecallTraceInput } from './recall-trace.js';
+export type { StrengthenOptions } from './store/entry-writes.js';
+export type { OriginFilter } from './store/search-rows.js';
+export type { ContinuityKey } from './store/sessions.js';
+export type { TokenUse } from './token-ledger.js';
 export { StoreBusyError } from './db.js';
 export { authCreate, type AuthCreateOpts, type AuthCreateResult } from './api.js';
 export { isSharedStore } from './config.js';