hippo-memory 1.59.0 → 1.61.0

package/dist/quarantine.js

@@ -1,5 +1,6 @@
 /** Quarantine tier (CD5, AT3): pending/approved/rejected record for a memory `remember` flagged as untrusted. */
 import { appendAuditEvent } from './audit.js';
+import { keysetAfter } from './keyset.js';
 export const QUARANTINE_SCOPE_PREFIX = 'quarantine:private:';
 /** Scope a quarantined memory is stored under; matches PRIVATE_SCOPE_RE so every default-deny site hides it. */
 export function quarantineScopeFor(original) {
@@ -39,16 +40,18 @@ export function getQuarantineRow(db, tenantId, memoryId) {
         .get(tenantId, memoryId);
     return row ? fromDbRow(row) : null;
 }
-export function listQuarantineRows(db, tenantId, status = 'pending', limit = 100) {
+export function listQuarantineRows(db, tenantId, status = 'pending', limit = 100, afterRow) {
     // A pending row whose memory was deleted (e.g. Slack message_deleted) is dead; keep its history, drop it from the queue.
     const live = status === 'pending'
         ? ' AND EXISTS (SELECT 1 FROM memories m WHERE m.id = memory_quarantine.memory_id AND m.tenant_id = memory_quarantine.tenant_id)'
         : '';
+    const after = keysetAfter('quarantined_at', 'memory_id', afterRow);
+    const order = 'ORDER BY quarantined_at DESC, memory_id DESC LIMIT ?';
     const rows = status === 'all'
-        ? db.prepare(`SELECT ${SELECT_COLUMNS} FROM memory_quarantine WHERE tenant_id = ? ORDER BY quarantined_at DESC LIMIT ?`)
-            .all(tenantId, limit)
-        : db.prepare(`SELECT ${SELECT_COLUMNS} FROM memory_quarantine WHERE tenant_id = ? AND status = ?${live} ORDER BY quarantined_at DESC LIMIT ?`)
-            .all(tenantId, status, limit);
+        ? db.prepare(`SELECT ${SELECT_COLUMNS} FROM memory_quarantine WHERE tenant_id = ?${after.sql} ${order}`)
+            .all(tenantId, ...after.params, limit)
+        : db.prepare(`SELECT ${SELECT_COLUMNS} FROM memory_quarantine WHERE tenant_id = ? AND status = ?${live}${after.sql} ${order}`)
+            .all(tenantId, status, ...after.params, limit);
     // SAFETY: both branches select SELECT_COLUMNS, matching QuarantineDbRow's field set.
     return rows.map(fromDbRow);
 }

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/raw-archive.js

@@ -1,7 +1,7 @@
 import { BadRequestError, NotFoundError } from './api-errors.js';
 import { isFtsAvailable } from './db.js';
 import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
-import { markSummaryDirtyInTx } from './store.js';
+import { markSummaryDirtyInTx } from './summary-dirty.js';
 export function archiveRawMemory(db, id, opts) {
     // SAFETY: SELECT * FROM memories returns every column of the memories table; only
     // kind, tenant_id, and dag_parent_id are read below, all guaranteed present (possibly

package/dist/recall-history.js

@@ -18,6 +18,7 @@
  * Composes with J3.2: AnchoringHint + PlanningFallacyHint are independent
  * signals; both can fire on the same recall.
  */
+import { envAnchoringOff, envAvailabilityOff } from './env.js';
 const DEFAULT_MIN_DOMINANCE = 3;
 const DEFAULT_RECENT_REPEAT_WINDOW = 5;
 const DEFAULT_COOLDOWN = 3;
@@ -238,7 +239,7 @@ export function snapshotRing(ring) {
  */
 export function biasHintEnabled(kind) {
     return kind === 'anchoring'
-        ? process.env.HIPPO_ANCHORING !== 'off'
-        : process.env.HIPPO_AVAILABILITY !== 'off';
+        ? !envAnchoringOff()
+        : !envAvailabilityOff();
 }
 //# sourceMappingURL=recall-history.js.map

package/dist/recall-pipeline.d.ts

@@ -2,7 +2,7 @@ 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, type SearchResult } from './search.js';
+import type { ResultCost, SearchResult } from './search/types.js';
 /** Stores rankRecall reads and where it sends operator notes. */
 export interface RankRecallCtx {
     hippoRoot: string;
@@ -23,7 +23,7 @@ export interface RecallSearchOpts {
     mmrLambda: number;
     localBump: number;
     minResults?: number;
-    /** Score breakdowns for `hippo explain`; explain's physics call also leaves out the bi-temporal flags. */
+    /** Score breakdowns for `hippo explain`; explain's physics call also leaves out minResults and includeSuperseded. */
     explain: boolean;
 }
 /** `--graph-hops` and `--graph-seeds`. */

package/dist/recall-pipeline.js

@@ -4,17 +4,18 @@ import { evalNow } from './ablation.js';
 import { oneCopyPerMemory } from './api.js';
 import { compareEntryIdentity } from './compare.js';
 import { closeHippoDb, openHippoDb } from './db.js';
-import { isEmbeddingAvailable } from './embeddings.js';
+import { isEmbeddingAvailable } from './local-embedding.js';
 import { computeGoalStackBoost } from './goals.js';
 import { graphExpandRecall } from './graph-recall.js';
 import { DEFAULT_GRAPH_STREAM_WEIGHT } from './graph-stream.js';
 import { Layer } from './memory.js';
 import { multihopSearch } from './multihop.js';
 import { passesCliRecallScopeFilter } from './recall-scope.js';
-import { hybridSearch, physicsSearch, textOverlap } from './search.js';
+import { hybridSearch } from './search/hybrid.js';
+import { physicsSearch } from './search/physics-search.js';
 import { searchBothHybrid } from './shared.js';
-import { loadRecallSearchEntries } from './store.js';
-import { tokenize as tokenizeQuery } from './tokenize.js';
+import { loadRecallSearchEntries, recallScopeFilter } from './store/search-rows.js';
+import { textOverlap, tokenize as tokenizeQuery } from './tokenize.js';
 /** Ranks memories for a query as `hippo recall` does, through the `limit` slice. Reads stores, embeddings and
  *  physics state; writes nothing and prints nothing (notes go to `ctx.note`). The caller supplies the cost
  *  function and reranker in `opts`, and persists the returned goal-log rows. */
@@ -124,10 +125,17 @@ async function searchPool(ctx, opts, pool) {
         const allEntries = oneCopyPerMemory(pool.local, pool.global, evalNow()).flat();
         return multihopSearch(query, allEntries, { budget, cost, hippoRoot: ctx.hippoRoot, minResults, includeSuperseded, asOf });
     }
+    const requested = opts.explicitScope || undefined;
+    const vectorCandidates = {
+        tenantId: ctx.tenantId,
+        scope: recallScopeFilter(requested, 'additive'),
+        includeSuperseded: includeSuperseded || Boolean(asOf),
+        admit: (e) => passesCliRecallScopeFilter(e.scope ?? null, requested),
+    };
     if (search.usePhysics && !globalRoot) {
-        // Explain has never passed the bi-temporal flags to physics; keeping that holds its output steady.
-        const temporal = explain ? {} : { minResults, includeSuperseded, asOf };
-        return physicsSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, physicsConfig: search.physicsConfig, scope, explain, ...temporal });
+        // Explain leaves minResults and includeSuperseded out to hold its output steady; asOf must reach physics or later rows leak.
+        const temporal = explain ? { asOf } : { minResults, includeSuperseded, asOf };
+        return physicsSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, physicsConfig: search.physicsConfig, scope, explain, vectorCandidates, ...temporal });
     }
     if (globalRoot) {
         // searchBothHybrid reloads candidates itself, so the scope rule is passed in rather than inherited from the pool.
@@ -137,7 +145,7 @@ async function searchPool(ctx, opts, pool) {
             recallScope: opts.explicitScope ? { requested: opts.explicitScope, additive: true } : {},
         });
     }
-    return hybridSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, explain, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf });
+    return hybridSearch(query, pool.local, { budget, cost, hippoRoot: ctx.hippoRoot, explain, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf, vectorCandidates });
 }
 /** Adds memories reached by walking the entity graph out from the lexical seeds. */
 function expandGraph(ctx, opts, graph, state) {

package/dist/recall-scope.js

@@ -124,7 +124,7 @@ export function isRestrictedScope(scope) {
         return false;
     // SAFETY: RECALL_DEFAULT_DENY_SCOPES is a readonly tuple of string
     // literals; widening the array (not the input) lets .includes() take any scope.
-    // `:private:` anywhere, any case, matches the store's SQL default-deny (store.ts:894) so JS never admits what SQL hides.
+    // `:private:` anywhere, any case, matches the store's SQL default-deny (store/search-rows.ts) so JS never admits what SQL hides.
     return isPrivateScope(scope) || /:private:/i.test(scope) || RECALL_DEFAULT_DENY_SCOPES.includes(scope);
 }
 /** True when `actor` may read `scope`: admin always; member needs an exact grant on a restricted scope. */

package/dist/recall-trace.d.ts

@@ -16,7 +16,7 @@
  * new debug env var).
  */
 import { type DatabaseSyncLike } from './db.js';
-import type { RerankStep } from './search.js';
+import type { RerankStep } from './search/types.js';
 import { type DeliveryEventInput } from './delivery-recorder.js';
 /** One ranked result to persist alongside its trace row. */
 export interface RecallTraceResultInput {
@@ -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

@@ -13,9 +13,11 @@
  * - On failure (API error, bad response), the original memory is untouched.
  */
 import { Layer } from './memory.js';
-import { loadAllEntries, readEntry, writeEntry } from './store.js';
-import { redactSecrets } from './secret-detect.js';
+import { writeEntry } from './store/entry-writes.js';
+import { loadAllEntries, readEntry } from './store/entry-reads.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 +33,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 +45,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 +65,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/reject-flow.js

@@ -15,7 +15,12 @@ import { closeHippoDb } from './db.js';
 import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { deleteDormantRow, listDormantSnapshots, purgeDormantByDigest, replaceDormantEntry } from './dormant.js';
-import { openStore, deleteEntryCore, purgeMirrorBestEffort, selectAllEntries, stampOriginProject, writeEntryDbOnly, writeEntryMirrors, } from './store.js';
+import { stampOriginProject } from './store/entry-row.js';
+import { purgeMirrorBestEffort } from './store/mirrors.js';
+import { openStore } from './store/open.js';
+import { writeEntryDbOnly, writeEntryMirrors } from './store/entry-writes.js';
+import { selectAllEntries } from './store/entry-reads.js';
+import { deleteEntryCore } from './store/delete-and-batch.js';
 import { heldTexts } from './same-text.js';
 import { mergedSuccessor } from './merged-row.js';
 import { rejectionDigest, normalizeValueForRejection, insertRejectedValue, deleteRejectedValue, listRejectedValues, } from './rejection.js';

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,12 @@
-import { buildRelevanceRequest, JEV_DEFAULT_TOP_K } from './jev.js';
+import { envClefEndpoint, envClefEndpointToken, envClefTimeoutMs, envCloudflareAccountId, envCloudflareApiToken } from '../env.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 +14,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,11 +25,16 @@ 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) {
-    const endpoint = process.env.HIPPO_CLEF_ENDPOINT?.trim();
+    const endpoint = envClefEndpoint();
     if (endpoint) {
         let parsed;
         try {
@@ -32,14 +46,25 @@ 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 = envClefEndpointToken();
+        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() ?? '';
+    const account = envCloudflareAccountId();
+    const token = envCloudflareApiToken();
     if (!account || !token)
         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 +108,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(envClefTimeoutMs());
+    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 +158,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 +180,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 +191,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,

package/dist/rerankers/jev.d.ts

@@ -1,5 +1,5 @@
-import type { RerankerFn } from './types.js';
-import type { SearchResult } from '../search.js';
+import type { RerankerFn, RerankResult } from './types.js';
+import type { SearchResult } from '../search/types.js';
 export declare const JEV_DEFAULT_TOP_K = 40;
 /** The System One `state` and one `noul` question per candidate (`c1`..`cN`). */
 export interface RelevanceRequest {
@@ -13,6 +13,8 @@ export interface RelevanceRequest {
 export declare function buildRelevanceRequest(query: string, head: readonly SearchResult[]): RelevanceRequest;
 /** Builds a Jev reranker around the reranker it degrades to. Exported so a test can pass a stand-in. */
 export declare function createJevReranker(localFallback: RerankerFn): RerankerFn;
+/** Orders `head` by `scores[i]`, keeping any upstream pre-rerank rank. Shared with CLEF. */
+export declare function rankByScores(head: readonly SearchResult[], scores: readonly number[]): RerankResult[];
 /** Track 4 reranker: hosted TypeSafe Jev, opt-in and paid (TYPESAFE_API_KEY), one batched call per recall.
  *  Any failure warns once and delegates to the local cross-encoder. Scores are not bit-stable run to run.
  *  Cost, env vars, evidence and limits: docs/evals/2026-09-19-jev-reranker.md. */