hippo-memory 1.58.0 → 1.59.0

package/dist/consolidate.js

@@ -689,7 +689,7 @@ export async function consolidate(hippoRoot, options = {}) {
         // before this fix — byte-identical behavior there.
         const mergeCandidatesByTenant = new Map();
         for (const entry of mergeCandidates) {
-            const key = derivationPartitionKey(entry.tenantId, entry.scope);
+            const key = derivationPartitionKey(entry.tenantId, entry.scope, entry.origin_project);
             const bucket = mergeCandidatesByTenant.get(key);
             if (bucket)
                 bucket.push(entry);
@@ -708,6 +708,7 @@ export async function consolidate(hippoRoot, options = {}) {
         for (const [, tenantCandidates] of mergeCandidatesByTenant) {
             const mergeTenant = tenantCandidates[0].tenantId;
             const mergeScope = derivationScope(tenantCandidates[0].scope);
+            const mergeOrigin = tenantCandidates[0].origin_project;
             const partnersOf = mergePartners(tenantCandidates.map((e) => e.content));
             for (let i = 0; i < tenantCandidates.length; i++) {
                 if (used.has(tenantCandidates[i].id) || tenantCandidates[i].content.length > MERGE_MAX_CHARS)
@@ -752,6 +753,7 @@ export async function consolidate(hippoRoot, options = {}) {
                             scope: mergeScope,
                             baseHalfLifeDays: config.defaultHalfLifeDays,
                         }),
+                        origin_project: mergeOrigin,
                         parents: cluster.map((e) => e.id),
                     };
                 }
@@ -994,6 +996,8 @@ rescuedIds = new Set()) {
                 continue;
             if (survivors[i].superseded_by || survivors[j].superseded_by)
                 continue;
+            if (!recalledTogether(survivors[i], survivors[j]))
+                continue;
             if ([survivors[i], survivors[j]].some((e) => e.tags.includes('extracted') || e.tags.includes('session-digest')))
                 continue;
             const reasonAndScore = describeConflict(profiles[i], profiles[j]);
@@ -1009,6 +1013,13 @@ rescuedIds = new Set()) {
     }
     return detected;
 }
+/** One project's ambient context can show both: same tenant, and the same project or a user-global row beside a project's. */
+function recalledTogether(a, b) {
+    if (a.tenantId !== b.tenantId)
+        return false;
+    const [x, y] = [a.origin_project ?? null, b.origin_project ?? null];
+    return x === y || (x === '' && y !== null) || (y === '' && x !== null);
+}
 function conflictProfile(text) {
     const opening = openingWindow(text);
     // Polarity is measured only in the first POLARITY_WINDOW_WORDS, so a stray

package/dist/dag.js

@@ -98,7 +98,7 @@ export async function buildDag(hippoRoot, facts, opts) {
     // behavior there.
     const unparentedByTenant = new Map();
     for (const fact of unparented) {
-        const key = derivationPartitionKey(fact.tenantId, fact.scope);
+        const key = derivationPartitionKey(fact.tenantId, fact.scope, fact.origin_project);
         const bucket = unparentedByTenant.get(key);
         if (bucket)
             bucket.push(fact);
@@ -129,6 +129,7 @@ export async function buildDag(hippoRoot, facts, opts) {
                 scope: factScope,
                 baseHalfLifeDays,
             });
+            summaryEntry.origin_project = tenantFacts[0].origin_project;
             // Schema v25: cache descendant_count + earliest/latest_at on the summary
             // row so DAG-aware recall (docs/plans/2026-05-05-dag-recall.md Task 2)
             // can reason about scope without walking the children.
@@ -310,7 +311,7 @@ export async function buildEntityProfiles(hippoRoot, l2Summaries, opts) {
     const byTenant = new Map();
     for (const l2 of unparented) {
         const tid = l2.tenantId ?? 'default';
-        const key = derivationPartitionKey(tid, l2.scope);
+        const key = derivationPartitionKey(tid, l2.scope, l2.origin_project);
         const list = byTenant.get(key) ?? [];
         list.push(l2);
         byTenant.set(key, list);
@@ -338,6 +339,7 @@ export async function buildEntityProfiles(hippoRoot, l2Summaries, opts) {
                 scope,
                 baseHalfLifeDays,
             });
+            profileEntry.origin_project = tenantL2s[0].origin_project;
             profileEntry.descendant_count = cluster.members.length;
             profileEntry.earliest_at = memberCreatedAts[0];
             profileEntry.latest_at = memberCreatedAts[memberCreatedAts.length - 1];

package/dist/dedupe.js

@@ -78,7 +78,7 @@ export function deduplicateStore(hippoRoot, options = {}) {
     const entriesByTenant = new Map();
     for (const entry of entries) {
         // EI2: also split by restricted scope, else a private copy can delete the readable one.
-        const key = derivationPartitionKey(entry.tenantId, entry.scope);
+        const key = derivationPartitionKey(entry.tenantId, entry.scope, entry.origin_project);
         const bucket = entriesByTenant.get(key);
         if (bucket)
             bucket.push(entry);

package/dist/doctor.js

@@ -15,6 +15,8 @@ import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVe
 import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './compaction-record.js';
 import { isEmbeddingAvailable } from './embeddings.js';
 import { CODEX_TRUST_LINE, codexHomeDir, isCodexPresent, isJsonObject } from './hooks.js';
+import { planUserGlobalRepair } from './project-merge.js';
+import { resolveTenantId } from './tenant.js';
 /** Minimum Node.js version hippo supports (package.json engines). */
 export const MIN_NODE = '22.16.0';
 function versionAtLeast(actual, min) {
@@ -128,6 +130,25 @@ function compactionsCheck(db, now) {
             : { id: 'compactions', status: 'warn', detail: `cannot read the compaction records: ${message}` };
     }
 }
+/** Merged rows older sleep saved as user-global, counted by the repair's own dry run so a truly user-global merge never warns. */
+function projectsCheck(globalRoot) {
+    let db = null;
+    try {
+        db = openHippoDbReadOnly(globalRoot);
+        const r = planUserGlobalRepair(db, resolveTenantId({}));
+        const n = r.toProject.length + r.setAside.length;
+        return n === 0
+            ? { id: 'projects', status: 'pass', detail: 'no merged memories in the global store are tagged user-global by mistake' }
+            : { id: 'projects', status: 'warn', detail: `${n} merged memories in the global store are tagged user-global, so every project's context can show them`, fix: 'hippo projects repair --global   (dry run; add --apply to write)' };
+    }
+    catch (err) {
+        return { id: 'projects', status: 'info', detail: `project tags not checked (${err instanceof Error ? err.message : String(err)})` };
+    }
+    finally {
+        if (db !== null)
+            closeHippoDb(db);
+    }
+}
 /** Run every check. Never throws for a broken install; broken parts become failed checks. */
 export function runDoctor(opts) {
     const cwd = opts.cwd ?? process.cwd();
@@ -213,6 +234,8 @@ export function runDoctor(opts) {
     if (holdoutRateBp > 0) {
         checks.push({ id: 'pilot', status: 'info', detail: `pilot holdout on: about ${holdoutRateBp / 100}% of sessions get no memories pushed by hippo (pilot.holdoutRateBp=${holdoutRateBp})` });
     }
+    if (hasGlobal)
+        checks.push(projectsCheck(globalRoot));
     const claudeDir = path.join(home, '.claude');
     if (fs.existsSync(claudeDir)) {
         const settings = readJson(path.join(claudeDir, 'settings.json'));

package/dist/dormant.d.ts

@@ -19,8 +19,8 @@
  */
 import type { DatabaseSyncLike } from './db.js';
 import type { MemoryEntry } from './memory.js';
-/** Why a memory went dormant: sleep's decay pass, or an imported agent memory whose note was deleted. */
-export type DormantReason = 'decay' | 'source-deleted';
+/** Why a memory went dormant: sleep's decay pass, an imported agent memory whose note was deleted, or `hippo projects repair` splitting a two-project merge. */
+export type DormantReason = 'decay' | 'source-deleted' | 'project-repair';
 /** One memory that sleep is moving out of active memory into the dormant store. */
 export interface DormantMove {
     /** The memory as it stood when it faded; restored verbatim apart from its recall clock. */

package/dist/extract.js

@@ -92,22 +92,22 @@ export function storeExtractedFacts(hippoRoot, source, facts) {
     const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
     for (const fact of facts) {
         const tags = ['extracted', ...inheritedTags, ...fact.tags];
-        const entry = createMemory(fact.content, {
-            layer: Layer.Semantic,
-            tags,
-            emotional_valence: fact.valence,
-            confidence: 'inferred',
-            source: source.source,
-            extracted_from: source.id,
-            scope: source.scope,
-            // T1 executor check (2026-08-15 hardening pass): same defect as the
-            // consolidate.ts merge/trace passes — createMemory with no tenantId
-            // option stamps 'default' (memory.ts:535) regardless of the source
-            // entry's own tenant. Thread it through so extracted facts land in
-            // the same tenant as the episodic memory they were extracted from.
-            tenantId: source.tenantId,
-            baseHalfLifeDays,
-        });
+        const entry = { ...createMemory(fact.content, {
+                layer: Layer.Semantic,
+                tags,
+                emotional_valence: fact.valence,
+                confidence: 'inferred',
+                source: source.source,
+                extracted_from: source.id,
+                scope: source.scope,
+                // T1 executor check (2026-08-15 hardening pass): same defect as the
+                // consolidate.ts merge/trace passes — createMemory with no tenantId
+                // option stamps 'default' (memory.ts:535) regardless of the source
+                // entry's own tenant. Thread it through so extracted facts land in
+                // the same tenant as the episodic memory they were extracted from.
+                tenantId: source.tenantId,
+                baseHalfLifeDays,
+            }), origin_project: source.origin_project };
         // AT1 containment: a refusal is per-VALUE — one rejected fact must not
         // drop the rest of this batch. writeEntry has already audited the
         // refusal (reject_refusal) before rethrowing, so skip-and-count here.

package/dist/project-merge.d.ts

@@ -0,0 +1,52 @@
+import type { DatabaseSyncLike } from './db.js';
+export interface ProjectSummary {
+    /** '' is user-global, null is unknown; neither can be merged. */
+    readonly origin: string | null;
+    readonly live: number;
+    readonly imported: number;
+    readonly newest: string;
+    /** Imported notes whose text another project name also holds: evidence of a duplicate import, never a merge target. */
+    readonly copiesElsewhere: number;
+}
+export interface MergeResult {
+    readonly from: string;
+    readonly into: string;
+    /** Imported note copies moved to dormant storage; the next sync under `into` imports the notes still on disk. */
+    readonly setAside: readonly string[];
+    readonly restamped: readonly string[];
+    readonly dormantRestamped: readonly string[];
+    readonly compactions: number;
+    readonly backup: string | null;
+}
+export interface RepairResult {
+    readonly toProject: ReadonlyArray<{
+        readonly id: string;
+        readonly origin: string;
+    }>;
+    /** Parents in two projects: the merged text blends them, so it goes dormant and the parents re-merge per project. */
+    readonly setAside: readonly string[];
+    /** No parent left to say which project, or pinned: left as they are, since hiding them would rest on no evidence. */
+    readonly untraced: readonly string[];
+    readonly backup: string | null;
+}
+/** Live rows per project name, newest write first, with how many of its imported notes are copies held elsewhere. */
+export declare function listProjects(db: DatabaseSyncLike, tenantId: string): ProjectSummary[];
+/** Copies the database before a repair writes, so the audit ids plus this file are the way back. */
+export declare function backupStore(db: DatabaseSyncLike, hippoRoot: string, label: string, now?: Date): string;
+/** Refuses user-global and unknown: they are not projects, and folding them would leak or hide every row. */
+export declare function validateMergeNames(from: string, into: string): string | null;
+/** Folds project `from` into `into` for one tenant in one transaction; a dry run rolls back and writes nothing, mirrors included. */
+export declare function mergeProjects(db: DatabaseSyncLike, hippoRoot: string, opts: {
+    tenantId: string;
+    from: string;
+    into: string;
+    dryRun: boolean;
+}): MergeResult;
+/** Reads only, so doctor can call it on a read-only handle: what the repair would do to each user-global merged row. */
+export declare function planUserGlobalRepair(db: DatabaseSyncLike, tenantId: string): Omit<RepairResult, 'backup'>;
+/** Re-tags sleep's merged rows saved as user-global before the fix, by the projects of their parents. */
+export declare function repairUserGlobalMerges(db: DatabaseSyncLike, hippoRoot: string, opts: {
+    tenantId: string;
+    dryRun: boolean;
+}): RepairResult;
+//# sourceMappingURL=project-merge.d.ts.map

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

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

package/dist/recall-scope.js

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

package/dist/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,