hippo-memory 1.69.0 → 1.71.0

package/dist/postinstall.js

@@ -1,20 +1,21 @@
-import { envSkipPostinstall } from './env.js';
+import { envSkipPostinstall } from './util/env.js';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { detectRealCodexPath, isCodexWrapperInstalled, repairCodexWrapperIfInstalled } from './hooks/codex-wrapper.js';
 import { claudeConfigDir } from './hooks/shared.js';
+import { errorMessage, log } from './util/log.js';
 function main() {
     if (envSkipPostinstall())
         return;
     try {
-        // Repair-only, for users who opted in (a Codex update can restore the real binary over our shim).
-        // Swapping the binary from postinstall is a consent violation that supply-chain scanners read as
-        // hijacking, so first install is `hippo hook install codex` only.
+        // Repair-only, for users who opted in (a Codex update can restore the real binary over our shim): swapping the binary from postinstall
+        // is a consent violation that supply-chain scanners read as hijacking, so first install is `hippo hook install codex` only.
         repairCodexWrapperIfInstalled();
     }
-    catch {
+    catch (err) {
         // Never fail package install because auto-integration could not be applied.
+        log.debug(`postinstall: codex wrapper not repaired: ${errorMessage(err)}`);
     }
     try {
         printClaudeCodeNudge();
@@ -29,16 +30,8 @@ function main() {
         // Never fail package install because the install hint could not be printed.
     }
 }
-/**
- * Read-only nudge: if Claude Code is detected on the machine and the Hippo
- * UserPromptSubmit hook is NOT yet installed, print a short message pointing
- * the user at `hippo init`. No config writes. Silent otherwise.
- *
- * We avoid aggressively auto-patching ~/.claude/settings.json from a package
- * postinstall — that's surprising, breaks the principle of least authority,
- * and trips security scanners. A one-line visible prompt is the friendly
- * middle ground.
- */
+/** Read-only nudge: if Claude Code is detected and the Hippo UserPromptSubmit hook is not installed, point the user at `hippo init`.
+ * It never patches ~/.claude/settings.json from a package postinstall: surprising, against least authority, and trips security scanners. */
 function printClaudeCodeNudge() {
     const claudeDir = claudeConfigDir(os.homedir());
     if (!fs.existsSync(claudeDir))
@@ -74,12 +67,8 @@ function printClaudeCodeNudge() {
     line('To skip this message on future installs: export HIPPO_SKIP_POSTINSTALL=1');
     line('');
 }
-/**
- * Read-only nudge: if the Codex CLI is on PATH and the Hippo session-capture
- * wrapper is NOT installed, print the opt-in command. Mirrors the Claude Code
- * nudge above — same least-authority reasoning: we tell the user what to run,
- * we never swap their binary for them.
- */
+/** Read-only nudge: if the Codex CLI is on PATH and the session-capture wrapper is not installed, print the opt-in command;
+ * same least-authority reasoning as the Claude Code nudge, we never swap the user's binary. */
 function printCodexNudge() {
     if (isCodexWrapperInstalled())
         return;

package/dist/predictions/planning-fallacy.d.ts

@@ -1,15 +1,8 @@
-import { type AppendAuditOpts } from '../audit.js';
-import { type ForwardClaimMatch } from '../forward-claim-detector.js';
-import { type PredictionBaserate } from './store.js';
-/**
- * Surface delivered on `RecallResult.planningFallacyHint` when an
- * agent's recall query carries a forward-prediction phrase AND the closest
- * matching prediction class has closed historical data.
- *
- * The agent sees its track record at the moment of forecasting, anchoring
- * on the outside view (Lovallo-Kahneman 2003) rather than the inside-view
- * inside the planning fallacy.
- */
+import type { AppendAuditOpts } from '../store/audit.js';
+import { type ForwardClaimMatch } from '../learn/forward-claim-detector.js';
+import type { PlanningFallacyEvidence } from '../store/planning-fallacy-evidence.js';
+/** Surface delivered on `RecallResult.planningFallacyHint` when a recall query carries a forward-prediction phrase and the closest class has closed history,
+ *  so the agent sees its own track record at the moment of forecasting. */
 export interface PlanningFallacyHint {
     classTag: string;
     /** Verbatim PredictionBaserate.summary, e.g.
@@ -17,131 +10,43 @@ export interface PlanningFallacyHint {
     baserateSummary: string;
     /** Discriminator vs hypothetical future manual-override hints. */
     source: 'j3.2-auto';
-    /** The regex match snippet that triggered detection. Lets the agent
-     *  see WHY the hint appeared and self-correct if detection misfires
-     *  (e.g. "I wasn't predicting; ignore"). */
+    /** The regex match snippet that triggered detection, so the agent sees WHY the hint appeared and can self-correct if detection misfired. */
     detectedPhrase: string;
     nClosed: number;
     /** Null only when every closed-row had estimate_value=0 (ratio undefined). */
     meanRatio: number | null;
 }
-/**
- * "Watching" variant emitted when the forward-claim regex matched but no
- * PlanningFallacyHint baserate was returned. Silence was the most common
- * real-world failure: a natural-language query carries a
- * forward-claim phrase but its non-stopword tokens don't overlap with
- * any prediction class tag, so hippo emitted nothing despite
- * the regex match. The watching variant surfaces the detection event
- * + a one-line suggestion so the agent can either re-tag the prediction
- * or pass the suggestion through to the user.
- */
+/** "Watching" variant emitted when the forward-claim regex matched but no baserate hint was returned (no prediction class tag overlaps the query's tokens).
+ *  It surfaces the detection plus a one-line suggestion so the agent can re-tag the prediction or pass the suggestion to the user. */
 export interface PlanningFallacyWatching {
     /** The forward-claim phrase the detector matched (verbatim regex match snippet). */
     detectedPhrase: string;
-    /** Why hippo couldn't produce a baserate hint despite the match.
-     *  - 'no_class_match': no class scored >=1 on token overlap.
-     *  - 'tiebreak': >=2 classes tied at the same best score (silent on ambiguity). */
+    /** Why hippo could not produce a baserate hint despite the match: 'no_class_match' (no class scored >=1 on token overlap)
+     *  or 'tiebreak' (>=2 classes tied at the best score; silent on ambiguity). */
     reason: 'no_class_match' | 'tiebreak';
     /** One-line agent-facing suggestion for how the user can give hippo
      *  enough signal to produce a baserate next time. */
     suggestion: string;
 }
-/**
- * Richer return type for
- * `computePlanningFallacyOutput`. Carries EITHER `hint` (baserate
- * available) OR `watching` (regex fired, no baserate), or NEITHER (mode=off,
- * no queryText, no regex match, or nClosed=0 silent path). Never both.
- */
+/** What `decidePlanningFallacy` hands to recall: EITHER `hint` (baserate available) OR `watching` (regex fired, no baserate), or NEITHER (mode=off,
+ *  no queryText, no regex match, or nClosed=0). Never both. */
 export interface PlanningFallacyOutput {
     hint?: PlanningFallacyHint;
     watching?: PlanningFallacyWatching;
 }
 export type AutodebiasMode = 'off' | 'regex';
 export interface ComputePlanningFallacyHintOpts {
-    /** Override env. When undefined, reads process.env.HIPPO_AUTODEBIAS at
-     *  call time (per-call to allow test-time env toggling without module
-     *  reload). 'off' short-circuits to null BEFORE the regex gate so the
-     *  AUTODEBIAS=off path pays zero work. */
+    /** Override env; undefined reads process.env.HIPPO_AUTODEBIAS per call (so tests can toggle it).
+     *  'off' short-circuits to null before the regex gate. */
     mode?: AutodebiasMode;
-    /** Actor for any audit emissions. Defaults to 'recall' (caller didn't
-     *  specify). MUST thread through to the inner computePredictionBaserate
-     *  call (passed as its `actor` arg) so MCP/HTTP-originated auto-hints
-     *  carry the right attribution instead of the 'cli' default. */
-    actor?: string;
-}
-export interface ClassResolution {
-    classTag: string | null;
-    /** True when ≥2 classes tied at the best overlap score AND best ≥ 1.
-     *  Caller emits `recall_autodebias_hint_tiebreak` audit and returns
-     *  null hint (silent — prevents the "show wrong class half the time"
-     *  failure mode the alphabetical-tiebreak alternative would create). */
-    tiebreak: boolean;
-}
-/** The prediction class a forward claim resolves to, and that class's closed-prediction stats when one resolved. */
-export interface PlanningFallacyEvidence extends ClassResolution {
-    readonly baserate: PredictionBaserate | null;
 }
 /** The output a claim earns from its evidence, and the audit row that records the decision when there is one. */
 export interface PlanningFallacyDecision {
     output: PlanningFallacyOutput;
     audit?: AppendAuditOpts;
 }
-/**
- * Resolve a query-token set to a unique best-matching class_tag for the
- * tenant. Scores by lower-cased token overlap; requires best score ≥ 1
- * AND strictly greater than the 2nd-best score.
- *
- * Indexed via idx_predictions_tenant_class (db.ts:1015) → O(log n) seek
- * plus a small DISTINCT scan over the per-tenant class-tag set.
- *
- * Scope behaviour (deliberate): class_tag selection is TENANT-GLOBAL,
- * NOT scope-filtered against
- * the recall's opts.scope. The class_tag is an aggregator label across
- * historical predictions in the class, not a per-memory scope-bound
- * property. A no-scope recall CAN surface a class_tag from a privately-
- * scoped prediction's class in PlanningFallacyHint.classTag — by design,
- * because base-rate reasoning needs the full historical sample.
- * Implications:
- *   - The hint payload itself carries no memory content (only the aggregate
- *     summary string + numeric stats), so memory bodies do not leak.
- *   - The class_tag NAME is the side-channel. If sensitive labels are a
- *     concern, callers should either use opaque class names (e.g. hashes
- *     or numeric tokens) or set HIPPO_AUTODEBIAS=off.
- *   - tests/api-recall-autodebias.test.ts locks this with an explicit
- *     test asserting that scope-set predictions surface via no-scope
- *     recalls (so future "fix" attempts that scope-filter trip CI).
- */
-export declare function resolveClassFromTokens(hippoRoot: string, tenantId: string, queryTokens: readonly string[]): ClassResolution;
-/**
- * Planning-fallacy orchestrator.
- *
- * Composes the forward-claim detector + class resolver + baserate compute,
- * with telemetry-grade audit emission at every decision point (success,
- * no-class-match, tiebreak).
- *
- * Returns `{}` (neither hint nor watching) on:
- *   - mode === 'off' (env-disabled; pays only the env read, skips regex)
- *   - empty queryText
- *   - no forward-claim regex match
- *   - resolved class has nClosed=0 (no historical data yet; silent)
- *
- * Returns `{ watching: ... }` on:
- *   - resolver returns no class (no overlap ≥ 1; emits no_class_match audit)
- *   - resolver returns tiebreak (≥2 classes tied at best; emits tiebreak audit)
- *
- * Returns `{ hint: ... }` on success: calls computePredictionBaserate(...,
- * emitAudit=false) so the predict_baserate audit channel stays scoped to
- * deliberate predict-baserate calls (the orchestrator's own recall_autodebias_hint
- * audit carries n_closed + mean_ratio in metadata so no telemetry is lost),
- * then emits recall_autodebias_hint audit + returns the hint.
- *
- * Latency budget: well under 50ms; a miss pays only the regex.
- */
-export declare function computePlanningFallacyOutput(hippoRoot: string, tenantId: string, queryText: string, opts?: ComputePlanningFallacyHintOpts): PlanningFallacyOutput;
 /** The forward claim in a recall query; null when HIPPO_AUTODEBIAS=off, the query is empty or no claim matches. */
 export declare function detectPlanningClaim(queryText: string, opts?: ComputePlanningFallacyHintOpts): ForwardClaimMatch | null;
-/** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
-export declare function planningFallacyEvidenceAt(hippoRoot: string, tenantId: string, classQueryTokens: readonly string[]): PlanningFallacyEvidence;
 /** The hint, the watching variant or nothing for a claim and its class evidence; reads and writes nothing itself. */
 export declare function decidePlanningFallacy(match: ForwardClaimMatch, evidence: PlanningFallacyEvidence, tenantId: string, actor: string): PlanningFallacyDecision;
 //# sourceMappingURL=planning-fallacy.d.ts.map

package/dist/predictions/planning-fallacy.js

@@ -1,114 +1,6 @@
-import { envAutodebiasOff } from '../env.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { appendAuditEvent } from '../audit.js';
-import { detectForwardClaim } from '../forward-claim-detector.js';
-import { computePredictionBaserate } from './store.js';
-/**
- * Resolve a query-token set to a unique best-matching class_tag for the
- * tenant. Scores by lower-cased token overlap; requires best score ≥ 1
- * AND strictly greater than the 2nd-best score.
- *
- * Indexed via idx_predictions_tenant_class (db.ts:1015) → O(log n) seek
- * plus a small DISTINCT scan over the per-tenant class-tag set.
- *
- * Scope behaviour (deliberate): class_tag selection is TENANT-GLOBAL,
- * NOT scope-filtered against
- * the recall's opts.scope. The class_tag is an aggregator label across
- * historical predictions in the class, not a per-memory scope-bound
- * property. A no-scope recall CAN surface a class_tag from a privately-
- * scoped prediction's class in PlanningFallacyHint.classTag — by design,
- * because base-rate reasoning needs the full historical sample.
- * Implications:
- *   - The hint payload itself carries no memory content (only the aggregate
- *     summary string + numeric stats), so memory bodies do not leak.
- *   - The class_tag NAME is the side-channel. If sensitive labels are a
- *     concern, callers should either use opaque class names (e.g. hashes
- *     or numeric tokens) or set HIPPO_AUTODEBIAS=off.
- *   - tests/api-recall-autodebias.test.ts locks this with an explicit
- *     test asserting that scope-set predictions surface via no-scope
- *     recalls (so future "fix" attempts that scope-filter trip CI).
- */
-export function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
-    if (queryTokens.length === 0)
-        return { classTag: null, tiebreak: false };
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: rows' shape matches the single `class_tag` column named in the SELECT above.
-        const rows = db.prepare(`SELECT DISTINCT class_tag FROM predictions WHERE tenant_id = ?`).all(tenantId);
-        const querySet = new Set(queryTokens);
-        let bestScore = 0;
-        let bestClass = null;
-        let secondBest = 0;
-        for (const { class_tag } of rows) {
-            const classTokens = class_tag
-                .toLowerCase()
-                .split(/[-_\s]+/)
-                .filter((t) => t.length >= 3);
-            let score = 0;
-            for (const t of classTokens)
-                if (querySet.has(t))
-                    score++;
-            if (score > bestScore) {
-                secondBest = bestScore;
-                bestScore = score;
-                bestClass = class_tag;
-            }
-            else if (score === bestScore && score > 0) {
-                // Tie at current best — bump secondBest. Do NOT update bestClass
-                // (alphabetical tiebreak would pick wrong class on ambiguous query
-                // like "migration will take 3 days" between migration-effort vs
-                // migration-risk; silent on tie instead).
-                secondBest = score;
-            }
-            else if (score > secondBest) {
-                secondBest = score;
-            }
-        }
-        if (bestScore < 1)
-            return { classTag: null, tiebreak: false };
-        if (bestScore === secondBest)
-            return { classTag: null, tiebreak: true };
-        return { classTag: bestClass, tiebreak: false };
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Planning-fallacy orchestrator.
- *
- * Composes the forward-claim detector + class resolver + baserate compute,
- * with telemetry-grade audit emission at every decision point (success,
- * no-class-match, tiebreak).
- *
- * Returns `{}` (neither hint nor watching) on:
- *   - mode === 'off' (env-disabled; pays only the env read, skips regex)
- *   - empty queryText
- *   - no forward-claim regex match
- *   - resolved class has nClosed=0 (no historical data yet; silent)
- *
- * Returns `{ watching: ... }` on:
- *   - resolver returns no class (no overlap ≥ 1; emits no_class_match audit)
- *   - resolver returns tiebreak (≥2 classes tied at best; emits tiebreak audit)
- *
- * Returns `{ hint: ... }` on success: calls computePredictionBaserate(...,
- * emitAudit=false) so the predict_baserate audit channel stays scoped to
- * deliberate predict-baserate calls (the orchestrator's own recall_autodebias_hint
- * audit carries n_closed + mean_ratio in metadata so no telemetry is lost),
- * then emits recall_autodebias_hint audit + returns the hint.
- *
- * Latency budget: well under 50ms; a miss pays only the regex.
- */
-export function computePlanningFallacyOutput(hippoRoot, tenantId, queryText, opts = {}) {
-    const match = detectPlanningClaim(queryText, opts);
-    if (!match)
-        return {};
-    const actor = opts.actor ?? 'recall';
-    const { output, audit } = decidePlanningFallacy(match, planningFallacyEvidenceAt(hippoRoot, tenantId, match.classQueryTokens), tenantId, actor);
-    if (audit)
-        appendAuditEventOnce(hippoRoot, audit);
-    return output;
-}
+import { envAutodebiasOff } from '../util/env.js';
+import { detectForwardClaim } from '../learn/forward-claim-detector.js';
+const TARGET_ID_CHARS = 100;
 /** The forward claim in a recall query; null when HIPPO_AUTODEBIAS=off, the query is empty or no claim matches. */
 export function detectPlanningClaim(queryText, opts = {}) {
     // Env read FIRST so AUTODEBIAS=off pays zero regex cost; read per call so tests can toggle it without a module reload.
@@ -119,13 +11,6 @@ export function detectPlanningClaim(queryText, opts = {}) {
         return null;
     return detectForwardClaim(queryText);
 }
-/** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
-export function planningFallacyEvidenceAt(hippoRoot, tenantId, classQueryTokens) {
-    const resolution = resolveClassFromTokens(hippoRoot, tenantId, classQueryTokens);
-    // emitAudit=false: the recall_autodebias_hint row carries n_closed and mean_ratio, so predict_baserate stays off.
-    const baserate = resolution.classTag ? computePredictionBaserate(hippoRoot, tenantId, resolution.classTag, 'recall', false) : null;
-    return { ...resolution, baserate };
-}
 /** The hint, the watching variant or nothing for a claim and its class evidence; reads and writes nothing itself. */
 export function decidePlanningFallacy(match, evidence, tenantId, actor) {
     if (evidence.tiebreak) {
@@ -168,16 +53,6 @@ export function decidePlanningFallacy(match, evidence, tenantId, actor) {
 }
 const TIEBREAK_SUGGESTION = 'Multiple prediction classes tied on this query. Refine the query or rename overlapping classes to break the tie.';
 const NO_CLASS_MATCH_SUGGESTION = 'No matching prediction class for this forward-claim. Tag your prediction with `hippo predict --class <name>` to start tracking this class.';
-/** One audit row on its own short-lived connection. */
-function appendAuditEventOnce(hippoRoot, event) {
-    const db = openHippoDb(hippoRoot);
-    try {
-        appendAuditEvent(db, event);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 function watchingWithAudit(tenantId, actor, match, reason, suggestion) {
     return {
         output: {
@@ -191,7 +66,7 @@ function watchingWithAudit(tenantId, actor, match, reason, suggestion) {
             tenantId,
             actor,
             op: reason === 'tiebreak' ? 'recall_autodebias_hint_tiebreak' : 'recall_autodebias_hint_no_class_match',
-            targetId: match.phrase.slice(0, 100),
+            targetId: match.phrase.slice(0, TARGET_ID_CHARS),
             metadata: { detected_phrase: match.phrase, token_count: match.classQueryTokens.length },
         },
     };

package/dist/rerankers/clef.d.ts

@@ -1,5 +1,5 @@
 import type { RerankerFn, RerankProvenance } from './types.js';
-import type { JsonValue } from '../json.js';
+import { type JsonValue } from '../util/json.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. */
@@ -19,11 +19,7 @@ interface ClefScores {
 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. */
+/** A CLEF reranker for one model: Jev's request shape and pool; any failure keeps the native order (never paid Jev) and warns. */
 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

@@ -1,12 +1,14 @@
-import { envClefEndpoint, envClefEndpointToken, envClefTimeoutMs, envCloudflareAccountId, envCloudflareApiToken } from '../env.js';
+import { envClefEndpoint, envClefEndpointToken, envClefTimeoutMs, envCloudflareAccountId, envCloudflareApiToken } from '../util/env.js';
 import { buildRelevanceRequest, JEV_DEFAULT_TOP_K, rankByScores } from './jev.js';
-import { isJsonObjectRecord } from '../http-util.js';
-import { log } from '../log.js';
+import { createOutageWarning } from './outage-warning.js';
+import { rerankerPost, RERANKER_MAX_REPLY_BYTES } from './remote.js';
+import { readCappedJson } from '../util/capped-json.js';
+import { isJsonObject } from '../util/json.js';
+import { errorMessage } from '../util/log.js';
+const RAY_ID_MAX_CHARS = 64;
 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;
@@ -73,12 +75,12 @@ export function resolveClefRoute(model) {
 }
 /** 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))
+    if (!isJsonObject(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))
+    if (!isJsonObject(reply))
         return 'reply has no result object';
     const actual = reply.model;
     if (actual !== undefined && (!isString(actual) || actual.trim() !== model))
@@ -86,21 +88,21 @@ export function parseClefReply(body, n, model, requireModel) {
     if (actual === undefined && requireModel)
         return 'reply does not name its model';
     const answers = reply.answers;
-    if (!isJsonObjectRecord(answers))
+    if (!isJsonObject(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'))
+        if (!isJsonObject(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 : {};
+    const usage = isJsonObject(reply.usage) ? reply.usage : {};
     return {
         scores,
         actualModel: isString(actual) ? actual.trim() : undefined,
@@ -108,33 +110,6 @@ 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);
     // Strict parse: parseInt would read "15s" as 15 ms, and Node clamps a delay past 2^31-1 to 1 ms.
@@ -143,35 +118,18 @@ async function requestScores(model, query, head, route) {
     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);
+    const resp = await rerankerPost(route.url, { headers, body: JSON.stringify({ state, model, questions }) }, timeoutMs);
+    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, RAY_ID_MAX_CHARS);
+        await resp.body?.cancel();
+        throw new Error(`HTTP ${resp.status}${ray ? `, ray ${ray}` : ''}`);
     }
+    const body = await readCappedJson(resp, RERANKER_MAX_REPLY_BYTES);
+    const parsed = parseClefReply(body, head.length, model, route.backend === 'cloudflare');
+    if (isRejection(parsed))
+        throw new Error(parsed);
+    return parsed;
 }
 /** The input order, unchanged, with the reason recorded. Never a partial reorder. */
 function nativeOrder(head, provenance) {
@@ -184,9 +142,9 @@ function nativeOrder(head, 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. */
+/** A CLEF reranker for one model: Jev's request shape and pool; any failure keeps the native order (never paid Jev) and warns. */
 export function createClefReranker(model) {
-    let warned = false;
+    const outage = createOutageWarning(model, 'keeping the native order');
     return async (query, results, options) => {
         const head = results.slice(0, options?.topK ?? JEV_DEFAULT_TOP_K);
         if (head.length === 0)
@@ -198,13 +156,11 @@ export function createClefReranker(model) {
                 throw new Error(`more than ${MAX_CANDIDATES} candidates`);
             route = resolveClefRoute(model);
             got = await requestScores(model, query, head, route);
+            outage.answered();
         }
         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.`);
-            }
+            const reason = errorMessage(err);
+            outage.failed(reason);
             return nativeOrder(head, { backend: 'native', requestedModel: model, fallbackReason: reason });
         }
         const rerankProvenance = {
@@ -217,8 +173,4 @@ export function createClefReranker(model) {
         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.d.ts

@@ -1,11 +1,4 @@
 import type { RerankerFn } from './types.js';
-/**
- * True if a Transformers.js backend is importable. Note: this does NOT confirm
- * that the model is downloadable from Hugging Face CDN — in sandboxed
- * environments the package may import but the model fetch may be blocked.
- * The reranker silently falls back to identity ordering in that case.
- */
-export declare function isCrossEncoderAvailable(): Promise<boolean>;
 /** Track 2 reranker: MS-MARCO MiniLM cross-encoder, identity fallback if the model will not load. */
 export declare const crossEncoderReranker: RerankerFn;
 //# sourceMappingURL=cross-encoder.d.ts.map