hippo-memory 1.59.0 → 1.60.0

package/dist/mcp/server.d.ts

@@ -25,8 +25,13 @@ interface McpResponse {
     error?: {
         code: number;
         message: string;
+        data?: {
+            requestId: string;
+        };
     };
 }
+/** JSON-RPC reply for a request that threw: typed API errors keep their text; anything else is logged and answered generically. */
+export declare function mcpErrorResponse<E>(id: McpResponse['id'], err: E, requestId?: string): McpResponse;
 export type { McpRequest, McpResponse };
 /**
  * Optional execution context threaded from a non-stdio transport. When the

package/dist/mcp/server.js

@@ -9,14 +9,17 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { randomUUID } from 'node:crypto';
+import { INTERNAL_ERROR_MESSAGE, mapApiError } from '../http-util.js';
+import { log } from '../log.js';
 import { createMemory, Layer, calculateStrength, } from '../memory.js';
 import { fitBudget, estimateTokens } from '../search.js';
 import { evalNow } from '../ablation.js';
-import { loadAllEntries, writeEntry, readEntry, listMemoryConflicts, resolveConflict, countCreatedSinceLastSleep } from '../store.js';
+import { loadStrengthRows, loadTextsHoldingWords, writeEntry, readEntry, listMemoryConflicts, resolveConflict, countCreatedSinceLastSleep } from '../store.js';
 import { shareMemory, listPeers, getGlobalRoot, initGlobal } from '../shared.js';
 import { consolidate } from '../consolidate.js';
 import { fetchGitLog, extractLessons, partitionLessons, isGitRepo } from '../autolearn.js';
-import { dropHeldCopies, duplicateKey, storedTextKeys } from '../same-text.js';
+import { dropHeldCopies, duplicateKey, longestWord, storedTextKeys } from '../same-text.js';
 import { loadConfig } from '../config.js';
 import { confidenceLabel } from '../memory.js';
 import { resolveTenantId } from '../tenant.js';
@@ -50,6 +53,18 @@ export function findHippoRoot(cwd = process.cwd(), opts) {
     const global = getGlobalRoot();
     return fs.existsSync(global) ? global : null;
 }
+/** JSON-RPC reply for a request that threw: typed API errors keep their text; anything else is logged and answered generically. */
+export function mcpErrorResponse(id, err, requestId = randomUUID()) {
+    const { status, message } = mapApiError(err);
+    if (status !== 500)
+        return { jsonrpc: '2.0', id, error: { code: -32603, message } };
+    log.error(`mcp request failed: ${err instanceof Error ? err.message : String(err)}`, { requestId });
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32603, message: `${INTERNAL_ERROR_MESSAGE} (request id ${requestId})`, data: { requestId } },
+    };
+}
 /**
  * The api-layer actor for a tool call. Stdio (no ctx) is the local operator
  * and runs as admin; over HTTP the transport's authenticated role is used, so
@@ -477,7 +492,7 @@ function resolveClientKey(ctx) {
 function createGlobalStoreOnFirstRun() {
     initGlobal();
     const root = getGlobalRoot();
-    console.error(`hippo: no memory store found; created the global store at ${root}. Run \`hippo init\` in a project for a project store.`);
+    log.warn(`no memory store found; created the global store at ${root}. Run \`hippo init\` in a project for a project store.`);
     return root;
 }
 // ── Token ledger (ROADMAP TE0) ──
@@ -524,7 +539,7 @@ async function executeTool(name, args, ctx) {
     // resolve tenant from HIPPO_TENANT.
     const hippoRoot = ctx?.hippoRoot ?? findHippoRoot() ?? createGlobalStoreOnFirstRun();
     const config = loadConfig(hippoRoot);
-    // A5: every loadAllEntries() in this server returns to the caller and is
+    // A5: every store read in this server returns to the caller and is
     // tenant-isolated. Resolved once per tool call: prefer the transport's
     // ctx.tenantId so an HTTP Bearer for tenant B doesn't drop to HIPPO_TENANT.
     const tenantId = ctx?.tenantId ?? resolveTenantId({});
@@ -866,7 +881,7 @@ async function executeTool(name, args, ctx) {
                 // Fire-and-forget (never block the response); an unhandled rejection would kill the server, so log it.
                 consolidate(hippoRoot)
                     .catch((err) => {
-                    console.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${err instanceof Error ? err.message : err}`);
+                    log.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${err instanceof Error ? err.message : String(err)}`);
                 })
                     .finally(() => autoSleepInFlight.delete(hippoRoot));
             }
@@ -922,7 +937,8 @@ async function executeTool(name, args, ctx) {
                 + formatMemories(result.entries);
         }
         case 'hippo_status': {
-            const entries = loadAllEntries(hippoRoot, tenantId);
+            // Every row counts toward the averages, so this scans the store, but without its text.
+            const entries = loadStrengthRows(hippoRoot, tenantId);
             const now = evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
             let atRisk = 0;
             let totalStrength = 0;
@@ -965,7 +981,7 @@ async function executeTool(name, args, ctx) {
             let added = 0;
             let skipped = 0;
             let rejected = 0;
-            const keys = storedTextKeys(loadAllEntries(hippoRoot, tenantId));
+            const keys = storedTextKeys(loadTextsHoldingWords(hippoRoot, tenantId, lessons.map(longestWord)));
             for (const lesson of lessons) {
                 if (keys.has(duplicateKey(lesson))) {
                     skipped++;
@@ -1138,17 +1154,20 @@ function dispatch(body) {
         req = JSON.parse(body);
     }
     catch {
-        return; // skip malformed
+        log.debug('mcp: skipped a frame that is not valid JSON');
+        return;
     }
     if (!req.method)
         return;
     if (req.method.startsWith('notifications/')) {
-        handleMcpRequest(req).catch(() => { });
+        handleMcpRequest(req).catch((err) => {
+            log.error(`mcp notification ${req.method} failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
         return;
     }
     handleMcpRequest(req).then((resp) => { if (resp)
         send(resp); }).catch((err) => {
-        send({ jsonrpc: '2.0', id: req.id, error: { code: -32603, message: err?.message ?? 'Internal error' } });
+        send(mcpErrorResponse(req.id, err));
     });
 }
 /**
@@ -1171,10 +1190,10 @@ export function startStdioLoop() {
     });
     process.stdin.on('end', () => process.exit(0));
     process.on('uncaughtException', (err) => {
-        process.stderr.write(`hippo-mcp uncaught: ${err?.message ?? err}\n`);
+        log.error(`mcp uncaught: ${err instanceof Error ? err.message : String(err)}`);
     });
     process.on('unhandledRejection', (err) => {
-        process.stderr.write(`hippo-mcp unhandled: ${err instanceof Error ? err.message : String(err)}\n`);
+        log.error(`mcp unhandled: ${err instanceof Error ? err.message : String(err)}`);
     });
 }
 // Auto-start when invoked as the main module (node dist/mcp/server.js or via
@@ -1196,7 +1215,7 @@ const isMainModule = (() => {
         return import.meta.url === mainUrl || import.meta.url === `file:///${argv1.replace(/\\/g, '/')}`;
     }
     catch {
-        return false;
+        return false; // an unreadable argv means this file was imported, not run; never start the stdio loop then
     }
 })();
 if (isMainModule) {

package/dist/memory.d.ts

@@ -135,19 +135,21 @@ export declare function _resetLossAversionRatioCacheForTests(): void;
  * Modulates effective half-life: memories with consistent positive outcomes
  * decay slower; consistent negative outcomes decay faster.
  */
-export declare function calculateRewardFactor(entry: MemoryEntry): number;
+export declare function calculateRewardFactor(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>): number;
 /**
  * Net wrongness: bad outcome marks past good ones, never below zero.
  * Strength halves per unit (capped at 3) and recall stops strengthening
  * the memory, so a correction outranks pinning, error tags and heavy recall.
  */
-export declare function netWrong(entry: MemoryEntry): number;
+export declare function netWrong(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>): number;
 /**
  * Options for decay basis.
  * - clock: wall-clock time (default pre-v0.15)
  * - session: decay by sleep cycle count (for intermittent agents)
  * - adaptive: auto-scale half-life by session frequency (default v0.15+)
  */
+/** What calculateStrength reads, so a caller can score a row without loading its text. */
+export type StrengthInputs = Pick<MemoryEntry, 'pinned' | 'created' | 'last_retrieved' | 'half_life_days' | 'retrieval_count' | 'emotional_valence' | 'outcome_positive' | 'outcome_negative'>;
 export interface DecayOptions {
     decayBasis?: 'clock' | 'session' | 'adaptive';
     /** Average interval between sleep cycles, in days. Used by 'adaptive' and 'session' modes. */
@@ -166,7 +168,7 @@ export interface DecayOptions {
  *
  * Pinned memories skip time decay; being marked wrong still fades them (netWrong).
  */
-export declare function calculateStrength(entry: MemoryEntry, now?: Date, options?: DecayOptions): number;
+export declare function calculateStrength(entry: StrengthInputs, now?: Date, options?: DecayOptions): number;
 /**
  * Derive half-life based on signals, as per PLAN.md table.
  */

package/dist/processes.js

@@ -91,6 +91,7 @@ function parseSteps(raw) {
         return [];
     }
     catch {
+        // Legacy garbage reads back as no steps, per the docblock.
         return [];
     }
 }

package/dist/project-identity.d.ts

@@ -7,7 +7,7 @@
  *   directory is the project root; if none exists, the nearest ancestor
  *   containing `.git` (directory or worktree file).
  * - The user home directory is NEVER a project, even though it contains the
- *   global store at `~/.hippo`. Reaching home ends the walk.
+ *   global store at `~/.hippo`. Reaching home or the temp root (inside home on Windows) ends the walk.
  * - A directory with no marker anywhere up the walk is NOT a project: it
  *   resolves to the user-global identity (empty name), so memories written
  *   there stay injectable everywhere (matches pre-isolation behavior).

package/dist/project-identity.js

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { log } from './log.js';
 const MAX_WALK_DEPTH = 64;
 const identityCache = new Map();
 /** Clear the per-process identity cache (test seam). */
@@ -15,7 +16,8 @@ export function realpathOrResolve(p) {
     try {
         return fs.realpathSync.native(p);
     }
-    catch {
+    catch (err) {
+        log.debug(`project identity: realpath fell back to resolve for ${p}: ${err instanceof Error ? err.message : String(err)}`);
         return path.resolve(p);
     }
 }
@@ -43,7 +45,8 @@ function isDirectoryAt(p) {
     try {
         return fs.statSync(p).isDirectory();
     }
-    catch {
+    catch (err) {
+        log.debug(`project identity: no marker at ${p}: ${err instanceof Error ? err.message : String(err)}`);
         return false;
     }
 }
@@ -60,9 +63,11 @@ export function resolveProjectIdentity(cwd, opts) {
             return cached;
     }
     const home = realpathOrResolve(opts?.homeDir ?? os.homedir());
-    const stopDir = opts?.stopDir ? realpathOrResolve(opts.stopDir) : null;
+    const stops = [realpathOrResolve(os.tmpdir())];
+    if (opts?.stopDir)
+        stops.push(realpathOrResolve(opts.stopDir));
     const start = realpathOrResolve(startInput);
-    const { hippoRoot, gitRoot, reachedHome } = walkProjectMarkers(start, home, stopDir === null ? [] : [stopDir]);
+    const { hippoRoot, gitRoot, reachedHome } = walkProjectMarkers(start, home, stops);
     let identity;
     const root = hippoRoot ?? gitRoot;
     if (root !== null) {

package/dist/raw-archive-mirror-cleanup.js

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { log } from './log.js';
 const LAYERS = ['episodic', 'buffer', 'semantic'];
 const MAX_WARN_LOGS = 5;
 /**
@@ -42,7 +43,7 @@ export function cleanupArchivedMirrors(hippoRoot, db) {
             catch (err) {
                 allOk = false;
                 if (warnCount < MAX_WARN_LOGS) {
-                    console.warn(`cleanupArchivedMirrors: unlink failed for ${filePath} (will retry on next DB open):`, err);
+                    log.warn(`cleanupArchivedMirrors: unlink failed for ${filePath} (will retry on next DB open): ${err instanceof Error ? err.message : String(err)}`);
                     warnCount += 1;
                 }
             }

package/dist/recall-trace.d.ts

@@ -102,8 +102,8 @@ export interface RecordTraceOutcomeInput {
  * this function from caller-side state (`last_trace_id` / applied outcome
  * ids) that can go stale relative to the trace it names — a forgotten
  * memory, a tenant switch mid-session, or a race between two callers. Two
- * checks run before the insert, both skip silently (console.error one
- * line) rather than throw:
+ * checks run before the insert, both skip with one log.warn line
+ * rather than throw:
  *   1. The named trace must exist and belong to `input.tenantId` — a
  *      tenant mismatch or a dangling id (deleted trace) skips.
  *   2. `input.memoryIds` is intersected against the trace's OWN

package/dist/recall-trace.js

@@ -18,6 +18,7 @@
 import { createHash } from 'node:crypto';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { DELIVERY_LEDGER_VERSION } from './delivery-recorder.js';
+import { log } from './log.js';
 /**
  * Strip a RerankStep down to {stage, multiplier, scoreBefore, scoreAfter}
  * before persisting (F3 privacy fix, codex cross-model finding). `note` is
@@ -76,8 +77,7 @@ export function writeRecallTrace(db, input) {
         }
     }
     catch (error) {
-        // eslint-disable-next-line no-console
-        console.error(`[hippo] recall trace write failed: ${error instanceof Error ? error.message : String(error)}`);
+        log.error(`recall trace write failed: ${error instanceof Error ? error.message : String(error)}`);
         return null;
     }
 }
@@ -113,8 +113,7 @@ export function writeRecallTraceAtRoot(root, input) {
         db = openHippoDb(root);
     }
     catch (error) {
-        // eslint-disable-next-line no-console
-        console.error(`[hippo] recall trace connection failed: ${error instanceof Error ? error.message : String(error)}`);
+        log.error(`recall trace connection failed: ${error instanceof Error ? error.message : String(error)}`);
         return null;
     }
     try {
@@ -140,8 +139,8 @@ export function writeRecallTraceAtRoot(root, input) {
  * this function from caller-side state (`last_trace_id` / applied outcome
  * ids) that can go stale relative to the trace it names — a forgotten
  * memory, a tenant switch mid-session, or a race between two callers. Two
- * checks run before the insert, both skip silently (console.error one
- * line) rather than throw:
+ * checks run before the insert, both skip with one log.warn line
+ * rather than throw:
  *   1. The named trace must exist and belong to `input.tenantId` — a
  *      tenant mismatch or a dangling id (deleted trace) skips.
  *   2. `input.memoryIds` is intersected against the trace's OWN
@@ -158,8 +157,7 @@ export function recordTraceOutcome(db, input) {
         // SELECT above; sqlite returns undefined when no row matches.
         const trace = db.prepare(`SELECT tenant_id FROM recall_traces WHERE id = ?`).get(input.traceId);
         if (!trace || trace.tenant_id !== input.tenantId) {
-            // eslint-disable-next-line no-console
-            console.error(`[hippo] recall trace outcome skipped: trace ${input.traceId} missing or tenant mismatch`);
+            log.warn(`recall trace outcome skipped: trace ${input.traceId} missing or tenant mismatch`);
             return;
         }
         // SAFETY: row shape matches the single `memory_id` column named in the
@@ -170,8 +168,7 @@ export function recordTraceOutcome(db, input) {
         const members = new Set(memberRows.map((r) => r.memory_id));
         const credited = input.memoryIds.filter((id) => members.has(id));
         if (credited.length === 0) {
-            // eslint-disable-next-line no-console
-            console.error(`[hippo] recall trace outcome skipped: no credited ids intersect trace ${input.traceId}'s results`);
+            log.warn(`recall trace outcome skipped: no credited ids intersect trace ${input.traceId}'s results`);
             return;
         }
         db.prepare(`
@@ -180,8 +177,7 @@ export function recordTraceOutcome(db, input) {
     `).run(input.traceId, new Date().toISOString(), input.tenantId, input.outcome, JSON.stringify(credited));
     }
     catch (error) {
-        // eslint-disable-next-line no-console
-        console.error(`[hippo] recall trace outcome write failed: ${error instanceof Error ? error.message : String(error)}`);
+        log.error(`recall trace outcome write failed: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 /** Pruned on write, counted back from the event's ts capped at the real clock, so a far-future fake time spares real rows. */
@@ -270,7 +266,7 @@ export function writeDeliveryEvent(db, input) {
         }
     }
     catch (error) {
-        // eslint-disable-next-line no-console
+        // The prompt hook's stderr shows this exact `[hippo] delivery ledger` line, so it stays off the logger's format.
         console.error(`[hippo] delivery ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
         return null;
     }
@@ -282,7 +278,7 @@ export function writeDeliveryEventAtRoot(root, input) {
         db = openHippoDb(root, { busyWaitMs: DELIVERY_LEDGER_WAIT_MS });
     }
     catch (error) {
-        // eslint-disable-next-line no-console
+        // Same hook stderr line as writeDeliveryEvent above.
         console.error(`[hippo] delivery ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
         return null;
     }

package/dist/refine-llm.js

@@ -14,8 +14,9 @@
  */
 import { Layer } from './memory.js';
 import { loadAllEntries, readEntry, writeEntry } from './store.js';
-import { redactSecrets } from './secret-detect.js';
+import { redactSecretsStrict } from './secret-detect.js';
 import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
+import { log } from './log.js';
 const REFINED_TAG = 'llm-refined';
 const CONSOLIDATED_MARKERS = [
     '[Consolidated from',
@@ -31,7 +32,7 @@ export async function refineSemanticMemory(merged, sources, opts) {
     const fetchFn = opts.fetcher ?? fetch;
     const sourceBlock = sources
         .slice(0, 8)
-        .map((s, i) => `[source ${i + 1}] ${redactSecrets(s.content).slice(0, 400)}`)
+        .map((s, i) => `[source ${i + 1}] ${redactSecretsStrict(s.content).slice(0, 400)}`)
         .join('\n\n');
     const prompt = `You are refining a semantic memory in an agent's memory store. The rule-based consolidator merged several related episodic memories into one, but the output is clumsy. Produce a single coherent semantic memory that captures the underlying principle.
 
@@ -43,7 +44,7 @@ Rules:
 - Do NOT include the "[Consolidated from N ...]" marker.
 
 Current merged content:
-${redactSecrets(merged)}
+${redactSecretsStrict(merged)}
 
 Source memories (up to 8 shown):
 ${sourceBlock}`;
@@ -63,24 +64,31 @@ ${sourceBlock}`;
             }),
         }, { timeoutMs: llmTimeoutMs(), fetchFn });
     }
-    catch {
+    catch (err) {
+        log.warn(`refine: request failed: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
-    if (!res.ok)
+    if (!res.ok) {
+        log.warn(`refine: API answered HTTP ${res.status}`);
         return null;
+    }
+    let text;
     try {
         // SAFETY: data is the Anthropic Messages API response body; the
         // documented response shape is `{ content: [{ type, text, ... }] }`
         // for a text-generating request like this one.
         const data = await res.json();
-        const text = data.content?.[0]?.text?.trim() ?? '';
-        if (text.length < 10)
-            return null;
-        return text;
+        text = data.content?.[0]?.text?.trim() ?? '';
+    }
+    catch (err) {
+        log.warn(`refine: unreadable response: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
     }
-    catch {
+    if (text.length < 10) {
+        log.warn('refine: response was empty or too short to use');
         return null;
     }
+    return text;
 }
 function isConsolidated(entry) {
     if (entry.layer !== Layer.Semantic)

package/dist/rerankers/clef.d.ts

@@ -1,4 +1,4 @@
-import type { RerankerFn } from './types.js';
+import type { RerankerFn, RerankProvenance } from './types.js';
 import { type JsonValue } from '../http-util.js';
 /** The two pretrained CLEF decision models served by Cloudflare Workers AI. */
 export type ClefModel = 'clef-flash' | 'clef';
@@ -7,7 +7,7 @@ export declare function isClefModel(name: string): name is ClefModel;
 interface ClefRoute {
     url: string;
     token: string | undefined;
-    backend: 'cloudflare' | 'private-endpoint';
+    backend: Exclude<RerankProvenance['backend'], 'native'>;
 }
 interface ClefScores {
     scores: number[];

package/dist/rerankers/clef.js

@@ -1,7 +1,11 @@
-import { buildRelevanceRequest, JEV_DEFAULT_TOP_K } from './jev.js';
+import { buildRelevanceRequest, JEV_DEFAULT_TOP_K, rankByScores } from './jev.js';
 import { isJsonObjectRecord } from '../http-util.js';
+import { log } from '../log.js';
 const CLEF_MODELS = ['clef-flash', 'clef'];
 const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_TIMEOUT_MS = 120_000;
+// 64 answers fit in a few KB; 1 MiB leaves room for a verbose envelope.
+const MAX_REPLY_BYTES = 1024 * 1024;
 // Workers AI rejects a request with more than 64 questions, one per candidate here.
 const MAX_CANDIDATES = 64;
 const ACCOUNT_ID = /^[0-9a-f]{32}$/i;
@@ -9,6 +13,10 @@ const ACCOUNT_ID = /^[0-9a-f]{32}$/i;
 export function isClefModel(name) {
     return CLEF_MODELS.some((m) => m === name);
 }
+// Plain http would put the token and the memory text on the wire, so only the local machine may use it.
+function isLoopback(hostname) {
+    return hostname === 'localhost' || hostname === '[::1]' || /^127(\.\d{1,3}){3}$/.test(hostname);
+}
 function isNumber(v) {
     return Number.isFinite(v);
 }
@@ -16,7 +24,12 @@ function isString(v) {
     return v !== undefined && v !== null && v.constructor === String;
 }
 function isRejection(v) {
-    return typeof v === 'string';
+    return v.constructor === String;
+}
+// fetch quotes a rejected header value in its error, so a token it would reject must never reach it.
+function checkHeaderSafe(name, token) {
+    if (!/^[\x21-\x7e]+$/.test(token))
+        throw new Error(`${name} has characters a header cannot carry`);
 }
 /** Transport from trusted local env, never call arguments: HIPPO_CLEF_ENDPOINT wins over hosted Workers AI. */
 export function resolveClefRoute(model) {
@@ -32,7 +45,17 @@ export function resolveClefRoute(model) {
         if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
             throw new Error('HIPPO_CLEF_ENDPOINT must be an http or https URL');
         }
-        return { url: parsed.href, token: process.env.HIPPO_CLEF_ENDPOINT_TOKEN?.trim() || undefined, backend: 'private-endpoint' };
+        // fetch echoes a URL with credentials in its error text, which reaches stderr.
+        if (parsed.username || parsed.password) {
+            throw new Error('HIPPO_CLEF_ENDPOINT must not embed credentials; set HIPPO_CLEF_ENDPOINT_TOKEN');
+        }
+        if (parsed.protocol === 'http:' && !isLoopback(parsed.hostname)) {
+            throw new Error('HIPPO_CLEF_ENDPOINT must use https unless it is on this machine');
+        }
+        const endpointToken = process.env.HIPPO_CLEF_ENDPOINT_TOKEN?.trim() || undefined;
+        if (endpointToken)
+            checkHeaderSafe('HIPPO_CLEF_ENDPOINT_TOKEN', endpointToken);
+        return { url: parsed.href, token: endpointToken, backend: 'private-endpoint' };
     }
     const account = process.env.CLOUDFLARE_ACCOUNT_ID?.trim() ?? '';
     const token = process.env.CLOUDFLARE_API_TOKEN?.trim() ?? '';
@@ -40,6 +63,7 @@ export function resolveClefRoute(model) {
         throw new Error('CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN not set');
     if (!ACCOUNT_ID.test(account))
         throw new Error('CLOUDFLARE_ACCOUNT_ID is not a 32-character hex id');
+    checkHeaderSafe('CLOUDFLARE_API_TOKEN', token);
     return {
         url: `https://api.cloudflare.com/client/v4/accounts/${account}/ai/run/@cf/cloudflare/${model}`,
         token,
@@ -83,15 +107,43 @@ export function parseClefReply(body, n, model, requireModel) {
         outputTokens: isNumber(usage.output_tokens) ? usage.output_tokens : undefined,
     };
 }
+// The timeout bounds time, not bytes: a hostile endpoint could stream a huge 2xx body into memory.
+async function readCappedJson(resp) {
+    if (!resp.body)
+        throw new Error('reply has no body');
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let raw = '';
+    let received = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        if (received > MAX_REPLY_BYTES) {
+            await reader.cancel();
+            throw new Error(`reply over ${MAX_REPLY_BYTES} bytes`);
+        }
+        raw += decoder.decode(value, { stream: true });
+    }
+    raw += decoder.decode();
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error('reply is not JSON');
+    }
+}
 async function requestScores(model, query, head, route) {
     const { state, questions } = buildRelevanceRequest(query, head);
-    const parsedTimeout = Number.parseInt(process.env.HIPPO_CLEF_TIMEOUT_MS ?? '', 10);
-    const timeoutMs = parsedTimeout > 0 ? parsedTimeout : DEFAULT_TIMEOUT_MS;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    // Strict parse: parseInt would read "15s" as 15 ms, and Node clamps a delay past 2^31-1 to 1 ms.
+    const requested = Number(process.env.HIPPO_CLEF_TIMEOUT_MS);
+    const timeoutMs = Number.isInteger(requested) && requested > 0 && requested <= MAX_TIMEOUT_MS ? requested : DEFAULT_TIMEOUT_MS;
     const headers = new Headers({ 'content-type': 'application/json' });
     if (route.token)
         headers.set('authorization', `Bearer ${route.token}`);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
         const resp = await fetch(route.url, {
             method: 'POST',
@@ -105,7 +157,7 @@ async function requestScores(model, query, head, route) {
             await resp.body?.cancel();
             throw new Error(`HTTP ${resp.status}${ray ? `, ray ${ray}` : ''}`);
         }
-        const body = await resp.json();
+        const body = await readCappedJson(resp);
         const parsed = parseClefReply(body, head.length, model, route.backend === 'cloudflare');
         if (isRejection(parsed))
             throw new Error(parsed);
@@ -127,7 +179,8 @@ function nativeOrder(head, provenance) {
         rerankScore: r.score,
         preRerankRank: r.preRerankRank ?? i + 1,
         postRerankRank: i + 1,
-        rerankProvenance: provenance,
+        // A copy per row, so a caller editing one result cannot change another's provenance.
+        rerankProvenance: { ...provenance },
     }));
 }
 /** A CLEF reranker for one model: Jev's request shape and pool; any failure keeps the native order (never paid Jev), warning once. */
@@ -137,42 +190,30 @@ export function createClefReranker(model) {
         const head = results.slice(0, options?.topK ?? JEV_DEFAULT_TOP_K);
         if (head.length === 0)
             return [];
-        let backend = 'native';
+        let route;
         let got;
         try {
             if (head.length > MAX_CANDIDATES)
                 throw new Error(`more than ${MAX_CANDIDATES} candidates`);
-            const route = resolveClefRoute(model);
-            backend = route.backend;
+            route = resolveClefRoute(model);
             got = await requestScores(model, query, head, route);
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : 'unknown error';
             if (!warned) {
                 warned = true;
-                // eslint-disable-next-line no-console
-                console.warn(`[hippo] ${model} reranker unavailable (${reason}); keeping the native order. Subsequent calls will not repeat this warning.`);
+                log.warn(`${model} reranker unavailable (${reason}); keeping the native order. Subsequent calls will not repeat this warning.`);
             }
             return nativeOrder(head, { backend: 'native', requestedModel: model, fallbackReason: reason });
         }
-        const provenance = {
-            backend,
+        const rerankProvenance = {
+            backend: route.backend,
             requestedModel: model,
             actualModel: got.actualModel,
             inputTokens: got.inputTokens,
             outputTokens: got.outputTokens,
         };
-        const scored = head.map((r, i) => ({
-            ...r,
-            rerankScore: got.scores[i],
-            preRerankRank: r.preRerankRank ?? i + 1,
-            postRerankRank: 0,
-            rerankProvenance: provenance,
-        }));
-        // Stable sort: ties fall back to the prior relevance order.
-        scored.sort((a, b) => b.rerankScore - a.rerankScore);
-        scored.forEach((r, i) => (r.postRerankRank = i + 1));
-        return scored;
+        return rankByScores(head, got.scores).map((r) => ({ ...r, rerankProvenance: { ...rerankProvenance } }));
     };
 }
 /** Opt-in CLEF-flash reranker (Cloudflare Workers AI or HIPPO_CLEF_ENDPOINT); off unless named, so defaults stay native. */

package/dist/rerankers/cross-encoder.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
+import { log } from '../log.js';
 const MODEL_NAME = 'Xenova/ms-marco-MiniLM-L-6-v2';
 const _require = createRequire(import.meta.url);
 const TRANSFORMERS_PACKAGES = ['@huggingface/transformers', '@xenova/transformers'];
@@ -36,7 +37,8 @@ async function loadTransformersModule() {
         const seq = mod.AutoModelForSequenceClassification ?? mod.default?.AutoModelForSequenceClassification;
         return tok && seq ? { AutoTokenizer: tok, AutoModelForSequenceClassification: seq } : null;
     }
-    catch {
+    catch (err) {
+        log.debug(`cross-encoder: transformers import failed: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
 }
@@ -78,7 +80,8 @@ async function buildPipeline() {
             return score;
         };
     }
-    catch {
+    catch (err) {
+        log.debug(`cross-encoder: model load failed: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
 }
@@ -102,8 +105,7 @@ export const crossEncoderReranker = async (query, results, options) => {
         // working reranker.
         if (!warnedOnFallback) {
             warnedOnFallback = true;
-            // eslint-disable-next-line no-console
-            console.warn('[hippo] cross-encoder reranker unavailable (no Transformers.js backend, or model fetch blocked); falling back to identity ordering. Subsequent calls will not repeat this warning.');
+            log.warn('cross-encoder reranker unavailable (no Transformers.js backend, or model fetch blocked); falling back to identity ordering. Subsequent calls will not repeat this warning.');
         }
         return head.map((r, i) => ({
             ...r,