hippo-memory 1.58.0 → 1.60.0

package/dist/project-merge.js

@@ -0,0 +1,168 @@
+// `hippo projects`: list the project names a store holds, fold one into another, and re-tag sleep's old user-global merges.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { setAsideRow } from './agent-memories/apply.js';
+import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TOOLS } from './agent-memories/tools.js';
+import { appendAuditEvent } from './audit.js';
+import { insertDormantRow, listDormantSnapshots, replaceDormantEntry } from './dormant.js';
+import { calculateStrength } from './memory.js';
+import { deleteEntryRowInTx, removeEntryMirrors, selectAllEntries, writeEntryMirrors } from './store.js';
+const ACTOR = 'cli';
+function isImport(entry) {
+    return entry.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX);
+}
+function toolTag(source) {
+    const id = source.slice(AGENT_MEMORY_SOURCE_PREFIX.length).split(':')[0];
+    return AGENT_MEMORY_TOOLS.find((t) => t.id === id)?.tag ?? null;
+}
+/** Live rows per project name, newest write first, with how many of its imported notes are copies held elsewhere. */
+export function listProjects(db, tenantId) {
+    const live = selectAllEntries(db, tenantId).filter((e) => !e.superseded_by);
+    const byOrigin = new Map();
+    const holders = new Map();
+    for (const e of live) {
+        const origin = e.origin_project ?? null;
+        byOrigin.set(origin, [...(byOrigin.get(origin) ?? []), e]);
+        if (isImport(e))
+            holders.set(e.content, (holders.get(e.content) ?? new Set()).add(origin));
+    }
+    return [...byOrigin].map(([origin, rows]) => {
+        const imports = rows.filter(isImport);
+        return {
+            origin,
+            live: rows.length,
+            imported: imports.length,
+            newest: rows.reduce((max, e) => (e.created > max ? e.created : max), ''),
+            copiesElsewhere: imports.filter((e) => (holders.get(e.content)?.size ?? 0) > 1).length,
+        };
+    }).sort((a, b) => b.newest.localeCompare(a.newest));
+}
+/** Copies the database before a repair writes, so the audit ids plus this file are the way back. */
+export function backupStore(db, hippoRoot, label, now = new Date()) {
+    const dir = path.join(hippoRoot, 'backups');
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `hippo-${label}-${now.toISOString().replace(/[:.]/g, '-')}.db`);
+    db.prepare('VACUUM INTO ?').run(file);
+    return file;
+}
+function inTransaction(db, dryRun, body) {
+    db.exec(dryRun ? 'BEGIN' : 'BEGIN IMMEDIATE');
+    try {
+        const out = body();
+        db.exec(dryRun ? 'ROLLBACK' : 'COMMIT');
+        return out;
+    }
+    catch (err) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { /* already rolled back; keep the original error */ }
+        throw err;
+    }
+}
+/** Refuses user-global and unknown: they are not projects, and folding them would leak or hide every row. */
+export function validateMergeNames(from, into) {
+    if (from.trim() === '' || into.trim() === '')
+        return 'both project names are required; user-global and unknown rows cannot be merged';
+    if (from === into)
+        return `${from} is already ${into}`;
+    return null;
+}
+/** Folds project `from` into `into` for one tenant in one transaction; a dry run rolls back and writes nothing, mirrors included. */
+export function mergeProjects(db, hippoRoot, opts) {
+    const refusal = validateMergeNames(opts.from, opts.into);
+    if (refusal)
+        throw new Error(refusal);
+    const { tenantId, from, into, dryRun } = opts;
+    const backup = dryRun ? null : backupStore(db, hippoRoot, 'before-merge');
+    const result = inTransaction(db, dryRun, () => {
+        const rows = selectAllEntries(db, tenantId).filter((e) => e.origin_project === from);
+        const setAside = [];
+        for (const row of rows) {
+            const tag = toolTag(row.source);
+            if (!isImport(row) || row.superseded_by || row.kind === 'raw' || tag === null)
+                continue;
+            if (setAsideRow(db, tag, { ...row, origin_project: into }, 'project-merge').kind === 'dormant')
+                setAside.push(row.id);
+        }
+        const gone = new Set(setAside);
+        const restamped = rows.filter((e) => !gone.has(e.id)).map((e) => e.id);
+        db.prepare(`UPDATE memories SET origin_project = ?, updated_at = datetime('now') WHERE tenant_id = ? AND origin_project = ?`)
+            .run(into, tenantId, from);
+        const dormantRestamped = [];
+        for (const snap of listDormantSnapshots(db, tenantId)) {
+            if (snap.entry.origin_project !== from || gone.has(snap.entry.id))
+                continue;
+            replaceDormantEntry(db, tenantId, snap.entry.id, { ...snap.entry, origin_project: into });
+            dormantRestamped.push(snap.entry.id);
+        }
+        const compactions = Number(db.prepare(`UPDATE compactions SET origin_project = ? WHERE tenant_id = ? AND origin_project = ?`)
+            .run(into, tenantId, from).changes ?? 0);
+        appendAuditEvent(db, {
+            tenantId, actor: ACTOR, op: 'project_merge',
+            metadata: { from, into, backup, setAside, restamped, dormantRestamped, compactions },
+        });
+        return { from, into, setAside, restamped, dormantRestamped, compactions, backup };
+    });
+    if (!dryRun)
+        refreshMirrors(db, hippoRoot, tenantId, result.restamped, result.setAside);
+    return result;
+}
+/** Reads only, so doctor can call it on a read-only handle: what the repair would do to each user-global merged row. */
+export function planUserGlobalRepair(db, tenantId) {
+    const all = selectAllEntries(db, tenantId);
+    const origins = new Map(listDormantSnapshots(db, tenantId).map((s) => [s.entry.id, s.entry.origin_project ?? null]));
+    for (const e of all)
+        origins.set(e.id, e.origin_project ?? null);
+    const toProject = [];
+    const setAside = [];
+    const untraced = [];
+    for (const row of all) {
+        if (row.source !== 'consolidation' || row.origin_project !== '' || row.superseded_by)
+            continue;
+        const parents = new Set(row.parents.filter((id) => origins.has(id)).map((id) => origins.get(id) ?? null));
+        const [only] = parents;
+        if (parents.size === 1 && only === '')
+            continue;
+        if (parents.size === 1 && only)
+            toProject.push({ id: row.id, origin: only });
+        else if (parents.size > 1 && !row.pinned && row.kind !== 'raw')
+            setAside.push(row.id);
+        else
+            untraced.push(row.id);
+    }
+    return { toProject, setAside, untraced };
+}
+/** Re-tags sleep's merged rows saved as user-global before the fix, by the projects of their parents. */
+export function repairUserGlobalMerges(db, hippoRoot, opts) {
+    const { tenantId, dryRun } = opts;
+    if (dryRun)
+        return { ...planUserGlobalRepair(db, tenantId), backup: null };
+    const backup = backupStore(db, hippoRoot, 'before-repair');
+    const result = inTransaction(db, false, () => {
+        const plan = planUserGlobalRepair(db, tenantId);
+        const stamp = db.prepare(`UPDATE memories SET origin_project = ?, updated_at = datetime('now') WHERE tenant_id = ? AND id = ?`);
+        for (const { id, origin } of plan.toProject)
+            stamp.run(origin, tenantId, id);
+        const aside = new Set(plan.setAside);
+        const now = new Date();
+        for (const row of selectAllEntries(db, tenantId).filter((e) => aside.has(e.id))) {
+            insertDormantRow(db, { entry: row, strength: calculateStrength(row, now), reason: 'project-repair', dormantAt: now.toISOString() });
+            deleteEntryRowInTx(db, row, ACTOR);
+        }
+        appendAuditEvent(db, { tenantId, actor: ACTOR, op: 'project_repair', metadata: { backup, ...plan } });
+        return { ...plan, backup };
+    });
+    refreshMirrors(db, hippoRoot, tenantId, result.toProject.map((r) => r.id), result.setAside);
+    return result;
+}
+/** After commit, as the agent memory sync does: a stale mirror would bring the old tag back on the next rebuild. */
+function refreshMirrors(db, hippoRoot, tenantId, rewrite, purge) {
+    const ids = new Set(rewrite);
+    for (const entry of selectAllEntries(db, tenantId))
+        if (ids.has(entry.id))
+            writeEntryMirrors(hippoRoot, entry);
+    for (const id of purge)
+        removeEntryMirrors(hippoRoot, id);
+}
+//# sourceMappingURL=project-merge.js.map

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-scope.d.ts

@@ -113,7 +113,7 @@ export declare function commonDerivationScope(scopes: readonly (string | null |
 } | {
     ok: false;
 };
-/** Map-partition key for consolidate/dag producers: tenant + derivation scope,
- *  so a derived row never blends two restricted scopes or a mixed pair. */
-export declare function derivationPartitionKey(tenantId: string, scope: string | null | undefined): string;
+/** Map-partition key for consolidate/dag/dedup producers: tenant + derivation scope + origin project,
+ *  so a derived row never blends two restricted scopes, a mixed pair, or two projects. */
+export declare function derivationPartitionKey(tenantId: string, scope: string | null | undefined, origin: string | null | undefined): string;
 //# sourceMappingURL=recall-scope.d.ts.map

package/dist/recall-scope.js

@@ -164,9 +164,10 @@ export function commonDerivationScope(scopes) {
     }
     return { ok: true, scope: common };
 }
-/** Map-partition key for consolidate/dag producers: tenant + derivation scope,
- *  so a derived row never blends two restricted scopes or a mixed pair. */
-export function derivationPartitionKey(tenantId, scope) {
-    return `${tenantId}\u0000${derivationScope(scope) ?? ''}`;
+/** Map-partition key for consolidate/dag/dedup producers: tenant + derivation scope + origin project,
+ *  so a derived row never blends two restricted scopes, a mixed pair, or two projects. */
+export function derivationPartitionKey(tenantId, scope, origin) {
+    const project = origin === undefined ? '\u0002' : origin ?? '\u0001'; // unstamped, unknown and named never share a bucket
+    return `${tenantId}\u0000${derivationScope(scope) ?? ''}\u0000${project}`;
 }
 //# sourceMappingURL=recall-scope.js.map

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

@@ -0,0 +1,29 @@
+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';
+/** True when `name` is one of the CLEF reranker names. */
+export declare function isClefModel(name: string): name is ClefModel;
+interface ClefRoute {
+    url: string;
+    token: string | undefined;
+    backend: Exclude<RerankProvenance['backend'], 'native'>;
+}
+interface ClefScores {
+    scores: number[];
+    actualModel?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+/** Transport from trusted local env, never call arguments: HIPPO_CLEF_ENDPOINT wins over hosted Workers AI. */
+export declare function resolveClefRoute(model: ClefModel): ClefRoute;
+/** Unwraps a Workers AI `{ result }` envelope or a bare System One reply and checks model and `c1..cN`; a string is the rejection reason. */
+export declare function parseClefReply(body: JsonValue, n: number, model: ClefModel, requireModel: boolean): ClefScores | string;
+/** A CLEF reranker for one model: Jev's request shape and pool; any failure keeps the native order (never paid Jev), warning once. */
+export declare function createClefReranker(model: ClefModel): RerankerFn;
+/** Opt-in CLEF-flash reranker (Cloudflare Workers AI or HIPPO_CLEF_ENDPOINT); off unless named, so defaults stay native. */
+export declare const clefFlashReranker: RerankerFn;
+/** Opt-in CLEF reranker, the larger model. Same transport and fallback as clef-flash. */
+export declare const clefReranker: RerankerFn;
+export {};
+//# sourceMappingURL=clef.d.ts.map

package/dist/rerankers/clef.js

@@ -0,0 +1,223 @@
+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;
+/** True when `name` is one of the CLEF reranker names. */
+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);
+}
+function isString(v) {
+    return v !== undefined && v !== null && v.constructor === String;
+}
+function isRejection(v) {
+    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();
+    if (endpoint) {
+        let parsed;
+        try {
+            parsed = new URL(endpoint);
+        }
+        catch {
+            throw new Error('HIPPO_CLEF_ENDPOINT is not a valid URL');
+        }
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+            throw new Error('HIPPO_CLEF_ENDPOINT must be an http or https URL');
+        }
+        // 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() ?? '';
+    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,
+        backend: 'cloudflare',
+    };
+}
+/** Unwraps a Workers AI `{ result }` envelope or a bare System One reply and checks model and `c1..cN`; a string is the rejection reason. */
+export function parseClefReply(body, n, model, requireModel) {
+    if (!isJsonObjectRecord(body))
+        return 'reply is not a JSON object';
+    if (body.success === false)
+        return 'provider reported failure';
+    const reply = body.result === undefined ? body : body.result;
+    if (!isJsonObjectRecord(reply))
+        return 'reply has no result object';
+    const actual = reply.model;
+    if (actual !== undefined && (!isString(actual) || actual.trim() !== model))
+        return 'reply names a different model';
+    if (actual === undefined && requireModel)
+        return 'reply does not name its model';
+    const answers = reply.answers;
+    if (!isJsonObjectRecord(answers))
+        return 'reply has no answers';
+    if (Object.keys(answers).length !== n)
+        return 'incomplete or out-of-range answers';
+    const scores = [];
+    for (let i = 1; i <= n; i++) {
+        const a = answers[`c${i}`];
+        if (!isJsonObjectRecord(a) || (a.type !== undefined && a.type !== 'noul'))
+            return 'incomplete or out-of-range answers';
+        const v = a.noul;
+        if (!isNumber(v) || v < 0 || v > 1)
+            return 'incomplete or out-of-range answers';
+        scores.push(v);
+    }
+    const usage = isJsonObjectRecord(reply.usage) ? reply.usage : {};
+    return {
+        scores,
+        actualModel: isString(actual) ? actual.trim() : undefined,
+        inputTokens: isNumber(usage.input_tokens) ? usage.input_tokens : undefined,
+        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);
+    // 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',
+            headers,
+            body: JSON.stringify({ state, model, questions }),
+            signal: controller.signal,
+        });
+        if (!resp.ok) {
+            // A third-party header ends up on stderr, so keep printable ASCII only.
+            const ray = resp.headers.get('cf-ray')?.replace(/[^\x20-\x7e]/g, '').slice(0, 64);
+            await resp.body?.cancel();
+            throw new Error(`HTTP ${resp.status}${ray ? `, ray ${ray}` : ''}`);
+        }
+        const body = await readCappedJson(resp);
+        const parsed = parseClefReply(body, head.length, model, route.backend === 'cloudflare');
+        if (isRejection(parsed))
+            throw new Error(parsed);
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError')
+            throw new Error(`no answer within ${timeoutMs} ms`);
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The input order, unchanged, with the reason recorded. Never a partial reorder. */
+function nativeOrder(head, provenance) {
+    return head.map((r, i) => ({
+        ...r,
+        rerankScore: r.score,
+        preRerankRank: r.preRerankRank ?? i + 1,
+        postRerankRank: i + 1,
+        // 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. */
+export function createClefReranker(model) {
+    let warned = false;
+    return async (query, results, options) => {
+        const head = results.slice(0, options?.topK ?? JEV_DEFAULT_TOP_K);
+        if (head.length === 0)
+            return [];
+        let route;
+        let got;
+        try {
+            if (head.length > MAX_CANDIDATES)
+                throw new Error(`more than ${MAX_CANDIDATES} candidates`);
+            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;
+                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 rerankProvenance = {
+            backend: route.backend,
+            requestedModel: model,
+            actualModel: got.actualModel,
+            inputTokens: got.inputTokens,
+            outputTokens: got.outputTokens,
+        };
+        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. */
+export const clefFlashReranker = createClefReranker('clef-flash');
+/** Opt-in CLEF reranker, the larger model. Same transport and fallback as clef-flash. */
+export const clefReranker = createClefReranker('clef');
+//# sourceMappingURL=clef.js.map

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,