hippo-memory 1.69.0 → 1.70.0

package/dist/objects/skills.js

@@ -0,0 +1,156 @@
+/**
+ * Skills as a first-class, versioned object.
+ *
+ * A `skill` is a reusable, agent-followable capability: an `instructions` body
+ * plus an optional `trigger` ("when to apply"), evolving via the supersede delta
+ * lifecycle. "Executable" is scoped to an agent-followable INSTRUCTION that, once
+ * exported into the agent's in-force rules (AGENTS.md / CLAUDE.md) via
+ * `exportSkills`, is executed by the agent reading it. Literal code/command
+ * execution is deferred (security; a future sandbox). The distinguishing
+ * capability is therefore the EXPORT renderer, not a runtime.
+ *
+ * Reuses the process/decision supersede machinery verbatim (superseded_by self-FK
+ * + CAS + INSERT-preflight + server-derived version + change_summary + supersede
+ * tenant-match trigger). It DROPS process's `steps` (a skill's content is a single
+ * `instructions` body) and ADDS `trigger` (stored in the `trigger_text` column -
+ * `trigger` is a SQLite reserved keyword).
+ *
+ * The `skills` table is the source of truth (survives memory decay); the memory
+ * mirror is for recall. memory_id is NULLABLE with ON DELETE SET NULL.
+ *
+ * Lifecycle: active -> superseded (a newer version replaces it) or active ->
+ * closed (retired). Export renders ACTIVE skills only.
+ */
+import { BadRequestError } from '../core/api-errors.js';
+import { assertTenantId } from '../store/tenant.js';
+import { checkText, requireLine } from './fields.js';
+import { closeObjectAt, listObjectsAt, objectByIdAt, saveObjectAt } from './lifecycle.js';
+import { sqliteObjects } from '../store/sqlite/objects-group.js';
+// ---------------------------------------------------------------------------
+// Domain types
+// ---------------------------------------------------------------------------
+export const VALID_SKILL_STATES = new Set([
+    'active',
+    'superseded',
+    'closed',
+]);
+/** Field caps (untrusted at the HTTP/SDK boundary). instructions is a body, so a
+ *  larger cap than the 4096 short-field convention. */
+export const MAX_SKILL_NAME_LEN = 256;
+export const MAX_SKILL_INSTRUCTIONS_LEN = 8192;
+export const MAX_SKILL_TRIGGER_LEN = 1024;
+/** Aggregate bound on a single export render so the export body is never unbounded.
+ *  Realistic active-skill counts are tens; 1000 is a generous bound. */
+export const MAX_EXPORT_SKILLS = 1000;
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/** The trigger as stored, or null for none. One line, because a newline would forge a heading inside the exported **When:** line. */
+function checkTrigger(trigger) {
+    if (trigger === undefined || trigger === null || trigger.trim().length === 0)
+        return null;
+    if (trigger.length > MAX_SKILL_TRIGGER_LEN) {
+        throw new BadRequestError(`saveSkill: trigger exceeds the ${MAX_SKILL_TRIGGER_LEN}-char cap`);
+    }
+    if (/[\r\n]/.test(trigger)) {
+        throw new BadRequestError('saveSkill: trigger must be a single line (no newlines)');
+    }
+    return trigger;
+}
+/** Recall-surface content for the memory mirror: name + optional trigger +
+ *  instructions. Named (mirrors buildProcessContent) so the recall surface is
+ *  deterministic + unit-testable. */
+function buildSkillContent(skillName, instructions, trigger) {
+    let content = skillName;
+    if (trigger)
+        content += `\n\nWhen: ${trigger}`;
+    content += `\n\n${instructions}`;
+    return content;
+}
+export const SKILL = {
+    kind: 'skill',
+    label: 'skill',
+    plural: 'skills',
+    fn: { get: 'loadSkillById', close: 'closeSkill', list: 'loadSkills', save: 'saveSkill' },
+    states: VALID_SKILL_STATES,
+    closableFrom: ['active'],
+    draft(opts) {
+        // The name becomes an H2 header in the export, so it must be one line.
+        const name = requireLine(opts.skillName, MAX_SKILL_NAME_LEN, {
+            required: 'saveSkill: skillName is required',
+            singleLine: 'saveSkill: skillName must be a single line (no newlines)',
+            tooLong: `saveSkill: skillName exceeds the ${MAX_SKILL_NAME_LEN}-char cap`,
+        });
+        checkText(opts.instructions, MAX_SKILL_INSTRUCTIONS_LEN, {
+            required: 'saveSkill: instructions are required',
+            tooLong: `saveSkill: instructions exceed the ${MAX_SKILL_INSTRUCTIONS_LEN}-char cap`,
+        });
+        const trigger = checkTrigger(opts.trigger);
+        return {
+            fields: { name, instructions: opts.instructions, trigger },
+            content: buildSkillContent(name, opts.instructions, trigger),
+            tags: opts.extraTags ?? [],
+            supersedesId: opts.supersedesSkillId,
+            changeSummary: opts.changeSummary,
+            at: new Date().toISOString(),
+        };
+    },
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Create a skill (or a new version that supersedes an existing one). Writes the
+ * memory mirror + the skills row in the `objects` store group's one transaction. When
+ * supersedesSkillId is given, the referenced ACTIVE row is preflighted (status +
+ * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same transaction;
+ * the new version = predecessor.version + 1 (server-derived).
+ */
+export function saveSkill(hippoRoot, tenantId, opts, actor = 'cli') {
+    return saveObjectAt(SKILL, { hippoRoot, tenantId, actor }, opts);
+}
+/**
+ * Close (retire) an active skill. A superseded row is terminal.
+ */
+export function closeSkill(hippoRoot, tenantId, id, actor = 'cli') {
+    return closeObjectAt(hippoRoot, SKILL, tenantId, id, actor);
+}
+export function loadSkillById(hippoRoot, tenantId, id) {
+    return objectByIdAt(hippoRoot, SKILL, tenantId, id);
+}
+export function loadSkills(hippoRoot, tenantId, opts = {}) {
+    return listObjectsAt(hippoRoot, SKILL, tenantId, opts);
+}
+export function loadActiveSkills(hippoRoot, tenantId, opts = {}) {
+    return loadSkills(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
+}
+/**
+ * Render the tenant's ACTIVE skills into ONE AGENTS.md / CLAUDE.md-style markdown
+ * block (one H2 per skill, ordered by skill_name ASC for determinism), and RETURN
+ * the string. Does NOT write any file. Returns '' when there are no active skills.
+ *
+ * skill_name is single-line (validated on save) so it cannot break the H2 header;
+ * instructions are emitted verbatim (operator content). Bounded by MAX_EXPORT_SKILLS
+ * active rows; each field is capped on save, so the rendered string is bounded.
+ */
+export function exportSkills(hippoRoot, tenantId) {
+    assertTenantId('exportSkills', tenantId);
+    return skillsBlock(sqliteObjects(hippoRoot).activeSkillsByName(tenantId, MAX_EXPORT_SKILLS));
+}
+/** `exportSkills` over a served store's group. */
+export async function skillsMarkdown(objects, tenantId) {
+    assertTenantId('exportSkills', tenantId);
+    return skillsBlock(await objects.activeSkillsByName(tenantId, MAX_EXPORT_SKILLS));
+}
+function skillsBlock(skills) {
+    return skills
+        .map((s) => {
+        let block = `## ${s.skillName}`;
+        if (s.trigger)
+            block += `\n\n**When:** ${s.trigger}`;
+        block += `\n\n${s.instructions}`;
+        return block;
+    })
+        .join('\n\n');
+}
+//# sourceMappingURL=skills.js.map

package/dist/postinstall.js

@@ -1,9 +1,10 @@
-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;
@@ -13,8 +14,9 @@ function main() {
         // 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();

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

@@ -1,6 +1,6 @@
-import { type AppendAuditOpts } from '../audit.js';
-import { type ForwardClaimMatch } from '../forward-claim-detector.js';
-import { type PredictionBaserate } from './store.js';
+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 an
  * agent's recall query carries a forward-prediction phrase AND the closest
@@ -47,8 +47,7 @@ export interface PlanningFallacyWatching {
     suggestion: string;
 }
 /**
- * Richer return type for
- * `computePlanningFallacyOutput`. Carries EITHER `hint` (baserate
+ * What `decidePlanningFallacy` hands to recall. 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.
  */
@@ -63,85 +62,14 @@ export interface ComputePlanningFallacyHintOpts {
      *  reload). 'off' short-circuits to null BEFORE the regex gate so the
      *  AUTODEBIAS=off path pays zero work. */
     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,7 +1,10 @@
-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 } from './remote.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;
@@ -73,12 +76,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 +89,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,
@@ -143,35 +146,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);
+    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 +170,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 +184,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 +201,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