hippo-memory 1.57.0 → 1.59.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.js

@@ -1,5 +1,6 @@
+import { BadRequestError, NotFoundError } from './api-errors.js';
 import { isFtsAvailable } from './db.js';
-import { appendAuditEvent } from './audit.js';
+import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { markSummaryDirtyInTx } from './store.js';
 export function archiveRawMemory(db, id, opts) {
     // SAFETY: SELECT * FROM memories returns every column of the memories table; only
@@ -7,9 +8,9 @@ export function archiveRawMemory(db, id, opts) {
     // null) by the memories schema.
     const row = db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id);
     if (!row)
-        throw new Error(`memory not found: ${id}`);
+        throw new NotFoundError(`memory not found: ${id}`);
     if (row.kind !== 'raw') {
-        throw new Error(`memory ${id} is not raw (kind=${String(row.kind)})`);
+        throw new BadRequestError(`memory ${id} is not raw (kind=${String(row.kind)})`);
     }
     // SAVEPOINT (not BEGIN) so this works whether or not we're already inside a
     // transaction. SQLite refuses BEGIN within a transaction; SAVEPOINT nests safely.
@@ -58,9 +59,9 @@ export function archiveRawMemory(db, id, opts) {
                 metadata: { reason: opts.reason },
             });
         }
-        catch {
-            // Audit must not crash the archive. Failures here mean the audit table
-            // is unwritable; the archive itself has already succeeded.
+        catch (error) {
+            // The archive itself has already succeeded; an unwritable audit table must not undo it.
+            reportAuditWriteFailure('archive_raw', String(error), id);
         }
         // v0.30 / E2 — DAG live-coupling: archive of a child under a level-2
         // summary marks parent dirty. Inside the SAVEPOINT so the dirty-mark

package/dist/recall-scope.d.ts

@@ -6,6 +6,7 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
+import { ForbiddenError } from './api-errors.js';
 /**
  * Literal scopes excluded from recall by default-deny when the
  * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
@@ -83,7 +84,7 @@ export declare function passesCliRecallScopeFilter(scope: string | null, request
  * Thrown when a caller requests a scope its role may not read. The HTTP layer
  * maps it to 403.
  */
-export declare class ScopeForbiddenError extends Error {
+export declare class ScopeForbiddenError extends ForbiddenError {
     readonly scope: string;
     constructor(scope: string);
 }
@@ -112,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

@@ -6,6 +6,7 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
+import { ForbiddenError } from './api-errors.js';
 /**
  * Literal scopes excluded from recall by default-deny when the
  * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
@@ -105,7 +106,7 @@ export function passesCliRecallScopeFilter(scope, requested) {
  * Thrown when a caller requests a scope its role may not read. The HTTP layer
  * maps it to 403.
  */
-export class ScopeForbiddenError extends Error {
+export class ScopeForbiddenError extends ForbiddenError {
     scope;
     constructor(scope) {
         super(`scope ${scope} requires admin role`);
@@ -163,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/refine-llm.js

@@ -15,6 +15,7 @@
 import { Layer } from './memory.js';
 import { loadAllEntries, readEntry, writeEntry } from './store.js';
 import { redactSecrets } from './secret-detect.js';
+import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
 const REFINED_TAG = 'llm-refined';
 const CONSOLIDATED_MARKERS = [
     '[Consolidated from',
@@ -48,7 +49,7 @@ Source memories (up to 8 shown):
 ${sourceBlock}`;
     let res;
     try {
-        res = await fetchFn('https://api.anthropic.com/v1/messages', {
+        res = await fetchWithRetry('https://api.anthropic.com/v1/messages', {
             method: 'POST',
             headers: {
                 'content-type': 'application/json',
@@ -60,7 +61,7 @@ ${sourceBlock}`;
                 max_tokens: 800,
                 messages: [{ role: 'user', content: prompt }],
             }),
-        });
+        }, { timeoutMs: llmTimeoutMs(), fetchFn });
     }
     catch {
         return null;

package/dist/reject-flow.js

@@ -12,7 +12,7 @@
  * cli.ts and api.ts, so it introduces no cycle.
  */
 import { closeHippoDb } from './db.js';
-import { appendAuditEvent } from './audit.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';
@@ -144,12 +144,9 @@ export function rejectValue(opts) {
                     metadata: { digest, removedIds, count: removedIds.length },
                 });
             }
-            catch {
-                // Best-effort — mirrors store.ts's private audit() semantics. This
-                // runs INSIDE the still-open transaction (COMMIT is the next
-                // statement): a swallowed audit failure lets the tombstone +
-                // removals commit without the trail row, rather than rolling the
-                // whole reject back over bookkeeping.
+            catch (error) {
+                // Inside the open transaction: the reject commits without its trail row rather than rolling back over bookkeeping.
+                reportAuditWriteFailure('reject_value', String(error), opts.memoryId);
             }
             db.exec('COMMIT');
         }
@@ -217,8 +214,8 @@ export function unrejectValue(hippoRoot, tenantId, digestOrPrefix, actor) {
                 metadata: { digest: target.digest, reason: target.reason },
             });
         }
-        catch {
-            // Best-effort, same as reject's audit call above.
+        catch (error) {
+            reportAuditWriteFailure('unreject_value', String(error), target.sourceMemoryId);
         }
         return { status: 'ok', digest: target.digest, reason: target.reason };
     }

package/dist/rejection.d.ts

@@ -12,6 +12,7 @@
  * be a cycle.
  */
 import type { DatabaseSyncLike } from './db.js';
+import { BadRequestError } from './api-errors.js';
 /**
  * Normalize content for rejection-digest comparisons: Unicode NFC →
  * lowercase → collapse whitespace runs to a single space → trim. No
@@ -33,7 +34,7 @@ export declare function rejectionDigest(content: string): string;
  * blocks (writeEntry, api.supersede) to write a post-rollback
  * `reject_refusal` audit row via `auditRejectionRefusal` (plan §3).
  */
-export declare class RejectedValueError extends Error {
+export declare class RejectedValueError extends BadRequestError {
     readonly digest: string;
     readonly tenantId: string;
     readonly entryId: string;

package/dist/rejection.js

@@ -12,6 +12,7 @@
  * be a cycle.
  */
 import { createHash } from 'node:crypto';
+import { BadRequestError } from './api-errors.js';
 /**
  * Normalize content for rejection-digest comparisons: Unicode NFC →
  * lowercase → collapse whitespace runs to a single space → trim. No
@@ -37,7 +38,7 @@ export function rejectionDigest(content) {
  * blocks (writeEntry, api.supersede) to write a post-rollback
  * `reject_refusal` audit row via `auditRejectionRefusal` (plan §3).
  */
-export class RejectedValueError extends Error {
+export class RejectedValueError extends BadRequestError {
     digest;
     tenantId;
     entryId;

package/dist/rerankers/clef.d.ts

@@ -0,0 +1,29 @@
+import type { RerankerFn } 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: 'cloudflare' | 'private-endpoint';
+}
+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,182 @@
+import { buildRelevanceRequest, JEV_DEFAULT_TOP_K } from './jev.js';
+import { isJsonObjectRecord } from '../http-util.js';
+const CLEF_MODELS = ['clef-flash', 'clef'];
+const DEFAULT_TIMEOUT_MS = 15_000;
+// 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);
+}
+function isNumber(v) {
+    return Number.isFinite(v);
+}
+function isString(v) {
+    return v !== undefined && v !== null && v.constructor === String;
+}
+function isRejection(v) {
+    return typeof v === 'string';
+}
+/** 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');
+        }
+        return { url: parsed.href, token: process.env.HIPPO_CLEF_ENDPOINT_TOKEN?.trim() || undefined, 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');
+    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,
+    };
+}
+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);
+    const headers = new Headers({ 'content-type': 'application/json' });
+    if (route.token)
+        headers.set('authorization', `Bearer ${route.token}`);
+    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 resp.json();
+        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,
+        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 backend = 'native';
+        let got;
+        try {
+            if (head.length > MAX_CANDIDATES)
+                throw new Error(`more than ${MAX_CANDIDATES} candidates`);
+            const route = resolveClefRoute(model);
+            backend = route.backend;
+            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.`);
+            }
+            return nativeOrder(head, { backend: 'native', requestedModel: model, fallbackReason: reason });
+        }
+        const provenance = {
+            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;
+    };
+}
+/** 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/index.js

@@ -1,7 +1,10 @@
+import { clefFlashReranker, clefReranker } from './clef.js';
 import { crossEncoderReranker } from './cross-encoder.js';
 import { jevReranker } from './jev.js';
 import { llmReranker } from './llm.js';
 const REGISTRY = {
+    clef: clefReranker,
+    'clef-flash': clefFlashReranker,
     'cross-encoder': crossEncoderReranker,
     jev: jevReranker,
     llm: llmReranker,

package/dist/rerankers/jev.d.ts

@@ -1,5 +1,16 @@
 import type { RerankerFn } from './types.js';
+import type { SearchResult } from '../search.js';
 export declare const JEV_DEFAULT_TOP_K = 40;
+/** The System One `state` and one `noul` question per candidate (`c1`..`cN`). */
+export interface RelevanceRequest {
+    state: string;
+    questions: Record<string, {
+        type: 'noul';
+        instructions: string;
+    }>;
+}
+/** Redacted query plus numbered, redacted, truncated candidates. Shared with CLEF so both arms see matched input. */
+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;
 /** Track 4 reranker: hosted TypeSafe Jev, opt-in and paid (TYPESAFE_API_KEY), one batched call per recall.

package/dist/rerankers/jev.js

@@ -28,11 +28,8 @@ function parseScores(answers, n) {
     }
     return out;
 }
-/** One batched request for the whole candidate list. Rejects with the reason when there are no usable scores. */
-async function requestScores(query, head) {
-    const key = process.env.TYPESAFE_API_KEY;
-    if (!key)
-        throw new Error('TYPESAFE_API_KEY not set');
+/** Redacted query plus numbered, redacted, truncated candidates. Shared with CLEF so both arms see matched input. */
+export function buildRelevanceRequest(query, head) {
     const lines = head.map((r, i) => `[${i + 1}] ${truncate(redactSecrets(r.entry.content), TRUNCATE_CHARS)}`);
     const state = `Query: ${redactSecrets(query)}\n\nNumbered candidate memories from an AI coding agent's project store:\n\n${lines.join('\n\n')}`;
     const questions = {};
@@ -42,6 +39,14 @@ async function requestScores(query, head) {
             instructions: `Probability that candidate ${i} (numbered in the state above) helps answer the query.`,
         };
     }
+    return { state, questions };
+}
+/** One batched request for the whole candidate list. Rejects with the reason when there are no usable scores. */
+async function requestScores(query, head) {
+    const key = process.env.TYPESAFE_API_KEY;
+    if (!key)
+        throw new Error('TYPESAFE_API_KEY not set');
+    const { state, questions } = buildRelevanceRequest(query, head);
     const parsed = Number.parseInt(process.env.HIPPO_JEV_TIMEOUT_MS ?? '', 10);
     const timeoutMs = parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS;
     const controller = new AbortController();

package/dist/rerankers/types.d.ts

@@ -26,6 +26,20 @@ export interface RerankerOptions {
     /** Per-track config blob; opaque to the seam. */
     config?: Record<string, RerankerConfigValue>;
 }
+/** Which backend and model produced a rerank, or why it fell back. */
+export interface RerankProvenance {
+    /** `cloudflare`, `private-endpoint`, or `native` when the input order was kept. */
+    backend: 'cloudflare' | 'private-endpoint' | 'native';
+    /** Model the caller asked for. */
+    requestedModel: string;
+    /** Model the provider says scored the request, when it reports one. */
+    actualModel?: string;
+    /** Set when the input order was kept instead of a model ranking. */
+    fallbackReason?: string;
+    /** Provider-reported token usage, when sent. */
+    inputTokens?: number;
+    outputTokens?: number;
+}
 export interface RerankResult extends SearchResult {
     /** Score assigned by the reranker. Replaces `score` for downstream
      *  ordering; original `score` preserved on the SearchResult. */
@@ -34,5 +48,7 @@ export interface RerankResult extends SearchResult {
     preRerankRank: number;
     /** 1-indexed rank in the reranker output. */
     postRerankRank: number;
+    /** Recorded by rerankers that track model identity (the CLEF rerankers). */
+    rerankProvenance?: RerankProvenance;
 }
 //# sourceMappingURL=types.d.ts.map