hippo-memory 1.69.0 → 1.71.0

package/dist/rerankers/cross-encoder.js

@@ -1,12 +1,14 @@
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
-import { log } from '../log.js';
+import { createOutageWarning } from './outage-warning.js';
+import { compareScoresDesc } from '../core/compare.js';
+import { errorMessage, log } from '../util/log.js';
+const DEFAULT_CROSS_ENCODER_TOP_K = 50;
 const MODEL_NAME = 'Xenova/ms-marco-MiniLM-L-6-v2';
 const _require = createRequire(import.meta.url);
 const TRANSFORMERS_PACKAGES = ['@huggingface/transformers', '@xenova/transformers'];
-// Returns the ESM entry URL, the same build src/embeddings.ts imports. A
-// require-style resolve picks the CommonJS build and puts a second copy of
-// the library, with its own ONNX sessions, in the process.
+// Returns the ESM entry URL, the same build src/store/embeddings/index.ts imports; a require-style resolve picks the CommonJS build and
+// puts a second copy of the library, with its own ONNX sessions, in the process.
 function resolveTransformersPackage() {
     for (const name of TRANSFORMERS_PACKAGES) {
         try {
@@ -38,24 +40,14 @@ async function loadTransformersModule() {
         return tok && seq ? { AutoTokenizer: tok, AutoModelForSequenceClassification: seq } : null;
     }
     catch (err) {
-        log.debug(`cross-encoder: transformers import failed: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`cross-encoder: transformers import failed: ${errorMessage(err)}`);
         return null;
     }
 }
 let pipelineLoading = null;
-let warnedOnFallback = false;
-/**
- * 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 async function isCrossEncoderAvailable() {
-    return (await loadTransformersModule()) !== null;
-}
-// NOT the text-classification pipeline: this model is a num_labels=1
-// regression head, and that pipeline softmaxes a length-1 logit vector, which
-// is identically 1.0 for every input. Read the logit, then squash it.
+const outage = createOutageWarning('cross-encoder', 'falling back to identity ordering');
+// NOT the text-classification pipeline: this is a num_labels=1 regression head and that pipeline softmaxes a length-1 logit vector (always 1.0).
+// Read the logit, then squash it.
 async function buildPipeline() {
     try {
         const mod = await loadTransformersModule();
@@ -81,7 +73,7 @@ async function buildPipeline() {
         };
     }
     catch (err) {
-        log.debug(`cross-encoder: model load failed: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`cross-encoder: model load failed: ${errorMessage(err)}`);
         return null;
     }
 }
@@ -97,16 +89,12 @@ function loadPipeline() {
 }
 /** Track 2 reranker: MS-MARCO MiniLM cross-encoder, identity fallback if the model will not load. */
 export const crossEncoderReranker = async (query, results, options) => {
-    const topK = options?.topK ?? 50;
+    const topK = options?.topK ?? DEFAULT_CROSS_ENCODER_TOP_K;
     const head = results.slice(0, topK);
     const pipe = await loadPipeline();
     if (!pipe) {
-        // Warn once per process: a silent identity fallback otherwise reads as a
-        // working reranker.
-        if (!warnedOnFallback) {
-            warnedOnFallback = true;
-            log.warn('cross-encoder reranker unavailable (no Transformers.js backend, or model fetch blocked); falling back to identity ordering. Subsequent calls will not repeat this warning.');
-        }
+        // A silent identity fallback otherwise reads as a working reranker.
+        outage.failed('no Transformers.js backend, or model fetch blocked');
         return head.map((r, i) => ({
             ...r,
             rerankScore: r.score,
@@ -114,13 +102,15 @@ export const crossEncoderReranker = async (query, results, options) => {
             postRerankRank: i + 1,
         }));
     }
+    outage.answered();
     const scored = await Promise.all(head.map(async (r, i) => {
         let ceScore;
         try {
             ceScore = await pipe(query, r.entry.content);
         }
-        catch {
+        catch (err) {
             // One bad inference must not sink the whole pass.
+            log.debug(`cross-encoder inference failed, keeping the base score: ${errorMessage(err)}`);
             ceScore = r.score;
         }
         return {
@@ -132,7 +122,7 @@ export const crossEncoderReranker = async (query, results, options) => {
     }));
     // Plain stable sort on purpose: tied scores MUST fall back to the prior
     // relevance order, never an arbitrary content order.
-    scored.sort((a, b) => b.rerankScore - a.rerankScore);
+    scored.sort((a, b) => compareScoresDesc(a.rerankScore, b.rerankScore));
     scored.forEach((r, i) => (r.postRerankRank = i + 1));
     return scored;
 };

package/dist/rerankers/index.js

@@ -1,13 +1,14 @@
-import { clefFlashReranker, clefReranker } from './clef.js';
+import { createClefReranker } from './clef.js';
 import { crossEncoderReranker } from './cross-encoder.js';
-import { jevReranker } from './jev.js';
-import { llmReranker } from './llm.js';
+import { createJevReranker } from './jev.js';
+import { createLlmReranker } from './llm.js';
+// Each hosted reranker is built once here, so its outage warning lasts the process.
 const REGISTRY = {
-    clef: clefReranker,
-    'clef-flash': clefFlashReranker,
+    clef: createClefReranker('clef'),
+    'clef-flash': createClefReranker('clef-flash'),
     'cross-encoder': crossEncoderReranker,
-    jev: jevReranker,
-    llm: llmReranker,
+    jev: createJevReranker(crossEncoderReranker),
+    llm: createLlmReranker(),
 };
 function isRegisteredRerankerName(name) {
     return Object.hasOwn(REGISTRY, name);

package/dist/rerankers/jev.d.ts

@@ -1,5 +1,5 @@
 import type { RerankerFn, RerankResult } from './types.js';
-import type { SearchResult } from '../search/types.js';
+import type { SearchResult } from '../core/search-types.js';
 export declare const JEV_DEFAULT_TOP_K = 40;
 /** The System One `state` and one `noul` question per candidate (`c1`..`cN`). */
 export interface RelevanceRequest {
@@ -15,7 +15,4 @@ export declare function buildRelevanceRequest(query: string, head: readonly Sear
 export declare function createJevReranker(localFallback: RerankerFn): RerankerFn;
 /** Orders `head` by `scores[i]`, keeping any upstream pre-rerank rank. Shared with CLEF. */
 export declare function rankByScores(head: readonly SearchResult[], scores: readonly number[]): RerankResult[];
-/** Track 4 reranker: hosted TypeSafe Jev, opt-in and paid (TYPESAFE_API_KEY), one batched call per recall.
- *  Any failure warns once and delegates to the local cross-encoder. Scores are not bit-stable run to run. */
-export declare const jevReranker: RerankerFn;
 //# sourceMappingURL=jev.d.ts.map

package/dist/rerankers/jev.js

@@ -1,7 +1,12 @@
-import { envJevModel, envJevTimeoutMs, envTypesafeApiKey } from '../env.js';
-import { crossEncoderReranker } from './cross-encoder.js';
-import { redactSecretsStrict } from '../secret-detect.js';
-import { log } from '../log.js';
+import { envJevModel, envJevTimeoutMs, envTypesafeApiKey } from '../util/env.js';
+import { redactSecretsStrict } from '../util/secret-detect.js';
+import { createOutageWarning } from './outage-warning.js';
+import { rerankerPost, RERANKER_MAX_REPLY_BYTES } from './remote.js';
+import { readCappedJson } from '../util/capped-json.js';
+import { isJsonNumber, isJsonObject } from '../util/json.js';
+import { compareScoresDesc } from '../core/compare.js';
+import { errorMessage } from '../util/log.js';
+const REQUEST_ID_MAX_CHARS = 64;
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 const DEFAULT_TIMEOUT_MS = 5_000;
 const TRUNCATE_CHARS = 1200;
@@ -16,14 +21,16 @@ function truncate(s, n) {
 // Number.isFinite rejects a string or null without coercing it, which the
 // declared type cannot promise about a third-party payload.
 function isProbability(v) {
-    return v !== undefined && Number.isFinite(v) && v >= 0 && v <= 1;
+    return isJsonNumber(v) && Number.isFinite(v) && v >= 0 && v <= 1;
 }
 // A half-scored list ranks worse than the order it would replace, so one bad
 // answer voids the whole response.
-function parseScores(answers, n) {
+function parseScores(body, n) {
+    const answers = isJsonObject(body) ? body.answers : undefined;
     const out = [];
     for (let i = 1; i <= n; i++) {
-        const v = answers?.[`c${i}`]?.noul;
+        const answer = isJsonObject(answers) ? answers[`c${i}`] : undefined;
+        const v = isJsonObject(answer) ? answer.noul : undefined;
         if (!isProbability(v))
             return null;
         out.push(v);
@@ -50,45 +57,28 @@ async function requestScores(query, head) {
     if (!key)
         throw new Error('TYPESAFE_API_KEY not set');
     const { state, questions } = buildRelevanceRequest(query, head);
-    const timeoutMs = envJevTimeoutMs() ?? DEFAULT_TIMEOUT_MS;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const resp = await fetch(ENDPOINT, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
-            body: JSON.stringify({
-                state,
-                model: envJevModel() ?? DEFAULT_MODEL,
-                questions,
-            }),
-            signal: controller.signal,
-        });
-        if (!resp.ok) {
-            // A third-party header ends up on stderr, so keep printable ASCII only.
-            const requestId = resp.headers.get('x-request-id')?.replace(/[^\x20-\x7e]/g, '').slice(0, 64);
-            await resp.body?.cancel();
-            throw new Error(`HTTP ${resp.status}${requestId ? `, request ${requestId}` : ''}`);
-        }
-        const body = await resp.json();
-        const scores = parseScores(body.answers, head.length);
-        if (!scores)
-            throw new Error('incomplete or out-of-range answers');
-        return scores;
-    }
-    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(ENDPOINT, {
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+        body: JSON.stringify({
+            state,
+            model: envJevModel() ?? DEFAULT_MODEL,
+            questions,
+        }),
+    }, envJevTimeoutMs() ?? DEFAULT_TIMEOUT_MS);
+    if (!resp.ok) {
+        // A third-party header ends up on stderr, so keep printable ASCII only.
+        const requestId = resp.headers.get('x-request-id')?.replace(/[^\x20-\x7e]/g, '').slice(0, REQUEST_ID_MAX_CHARS);
+        await resp.body?.cancel();
+        throw new Error(`HTTP ${resp.status}${requestId ? `, request ${requestId}` : ''}`);
     }
+    const scores = parseScores(await readCappedJson(resp, RERANKER_MAX_REPLY_BYTES), head.length);
+    if (!scores)
+        throw new Error('incomplete or out-of-range answers');
+    return scores;
 }
 /** Builds a Jev reranker around the reranker it degrades to. Exported so a test can pass a stand-in. */
 export function createJevReranker(localFallback) {
-    let warned = false;
+    const outage = createOutageWarning('jev', 'falling back to the local cross-encoder');
     return async (query, results, options) => {
         const head = results.slice(0, options?.topK ?? JEV_DEFAULT_TOP_K);
         if (head.length === 0)
@@ -96,15 +86,12 @@ export function createJevReranker(localFallback) {
         let scores;
         try {
             scores = await requestScores(query, head);
+            outage.answered();
         }
         catch (err) {
             // A read path never throws, and never hands back the unranked order
-            // without saying so: warn once, then use the free local reranker.
-            if (!warned) {
-                warned = true;
-                const reason = err instanceof Error ? err.message : 'unknown error';
-                log.warn(`jev reranker unavailable (${reason}); falling back to the local cross-encoder. Subsequent calls will not repeat this warning.`);
-            }
+            // without saying so: warn, then use the free local reranker.
+            outage.failed(errorMessage(err));
             return localFallback(query, head, options);
         }
         return rankByScores(head, scores);
@@ -119,11 +106,8 @@ export function rankByScores(head, scores) {
         postRerankRank: 0,
     }));
     // Stable sort: ties fall back to the prior relevance order.
-    scored.sort((a, b) => b.rerankScore - a.rerankScore);
+    scored.sort((a, b) => compareScoresDesc(a.rerankScore, b.rerankScore));
     scored.forEach((r, i) => (r.postRerankRank = i + 1));
     return scored;
 }
-/** Track 4 reranker: hosted TypeSafe Jev, opt-in and paid (TYPESAFE_API_KEY), one batched call per recall.
- *  Any failure warns once and delegates to the local cross-encoder. Scores are not bit-stable run to run. */
-export const jevReranker = createJevReranker(crossEncoderReranker);
 //# sourceMappingURL=jev.js.map

package/dist/rerankers/llm.d.ts

@@ -1,16 +1,5 @@
 import type { RerankerFn } from './types.js';
-/**
- * Track 3 reranker: listwise LLM rerank. Uses a customer-supplied
- * OpenAI-compatible endpoint. Gated on HIPPO_LLM_RERANKER_URL to prevent
- * accidental cost.
- *
- * Skeleton only; full characterisation is deferred.
- *
- * Timeout: defaults to 30s; overridable via HIPPO_LLM_RERANKER_TIMEOUT_MS.
- * On timeout or any fetch failure, the reranker warns once per process and
- * falls back to identity ordering; recall must not hang on a wedged endpoint.
- */
+/** Track 3 reranker (skeleton): listwise LLM rerank on a customer-supplied OpenAI-compatible endpoint, gated on HIPPO_LLM_RERANKER_URL against accidental cost.
+ * Timeout is 30s for the whole call, retries included (HIPPO_LLM_RERANKER_TIMEOUT_MS); any failure falls back to identity ordering, so recall never hangs. */
 export declare function createLlmReranker(): RerankerFn;
-/** The instance the reranker registry serves; its warn-once flag lasts the process. */
-export declare const llmReranker: RerankerFn;
 //# sourceMappingURL=llm.d.ts.map

package/dist/rerankers/llm.js

@@ -1,37 +1,30 @@
-import { envLlmRerankerKey, envLlmRerankerModel, envLlmRerankerTimeoutMs, envLlmRerankerUrl } from '../env.js';
-import { redactSecretsStrict } from '../secret-detect.js';
-import { log } from '../log.js';
+import { envLlmRerankerKey, envLlmRerankerModel, envLlmRerankerTimeoutMs, envLlmRerankerUrl } from '../util/env.js';
+import { redactSecretsStrict } from '../util/secret-detect.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, isJsonString } from '../util/json.js';
+import { errorMessage } from '../util/log.js';
+const DEFAULT_LLM_RERANK_TOP_K = 20;
 const DEFAULT_TIMEOUT_MS = 30_000;
-/**
- * Track 3 reranker: listwise LLM rerank. Uses a customer-supplied
- * OpenAI-compatible endpoint. Gated on HIPPO_LLM_RERANKER_URL to prevent
- * accidental cost.
- *
- * Skeleton only; full characterisation is deferred.
- *
- * Timeout: defaults to 30s; overridable via HIPPO_LLM_RERANKER_TIMEOUT_MS.
- * On timeout or any fetch failure, the reranker warns once per process and
- * falls back to identity ordering; recall must not hang on a wedged endpoint.
- */
+/** Track 3 reranker (skeleton): listwise LLM rerank on a customer-supplied OpenAI-compatible endpoint, gated on HIPPO_LLM_RERANKER_URL against accidental cost.
+ * Timeout is 30s for the whole call, retries included (HIPPO_LLM_RERANKER_TIMEOUT_MS); any failure falls back to identity ordering, so recall never hangs. */
 export function createLlmReranker() {
-    let warned = false;
+    const outage = createOutageWarning('llm', 'keeping the input order');
     return async (query, results, options) => {
         const url = envLlmRerankerUrl();
         if (!url) {
             throw new Error('HIPPO_LLM_RERANKER_URL not set; refusing to run LLM reranker.');
         }
-        const head = results.slice(0, options?.topK ?? 20);
+        const head = results.slice(0, options?.topK ?? DEFAULT_LLM_RERANK_TOP_K);
         let permutation = null;
         try {
             permutation = await requestPermutation(url, query, head);
+            outage.answered();
         }
         catch (err) {
             // A read path never throws, and never hands back the unranked order without saying so.
-            if (!warned) {
-                warned = true;
-                const reason = err instanceof Error ? err.message : 'unknown error';
-                log.warn(`llm reranker unavailable (${reason}); keeping the input order. Subsequent calls will not repeat this warning.`);
-            }
+            outage.failed(errorMessage(err));
         }
         const ordered = permutation ? permutation.map((idx) => head[idx]) : head;
         return ordered.map((r, i) => ({
@@ -42,8 +35,14 @@ export function createLlmReranker() {
         }));
     };
 }
-/** The instance the reranker registry serves; its warn-once flag lasts the process. */
-export const llmReranker = createLlmReranker();
+/** The first choice's message text, or '' when the reply has none. */
+function replyText(body) {
+    const choices = isJsonObject(body) ? body.choices : undefined;
+    const choice = Array.isArray(choices) ? choices[0] : undefined;
+    const message = isJsonObject(choice) ? choice.message : undefined;
+    const content = isJsonObject(message) ? message.content : undefined;
+    return isJsonString(content) ? content : '';
+}
 /** One chat-completions call; rejects with the reason when the reply holds no usable permutation. */
 async function requestPermutation(url, query, head) {
     const key = envLlmRerankerKey();
@@ -53,48 +52,32 @@ async function requestPermutation(url, query, head) {
         ...head.map((r, i) => `[${i}] ${redactSecretsStrict(r.entry.content)}`),
         `Output format: [<int>, <int>, ...] with all ${head.length} indices.`,
     ].join('\n');
-    const timeoutMs = envLlmRerankerTimeoutMs() ?? DEFAULT_TIMEOUT_MS;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
     const headers = {
         'content-type': 'application/json',
     };
     if (key) {
         headers.authorization = `Bearer ${key}`;
     }
-    try {
-        const resp = await fetch(`${url.replace(/\/$/, '')}/chat/completions`, {
-            method: 'POST',
-            headers: { ...headers },
-            body: JSON.stringify({
-                model: envLlmRerankerModel() ?? 'gpt-4o-mini',
-                messages: [{ role: 'user', content: prompt }],
-                temperature: 0,
-            }),
-            signal: controller.signal,
-        });
-        if (!resp.ok) {
-            await resp.body?.cancel();
-            throw new Error(`HTTP ${resp.status}`);
-        }
-        const j = await resp.json();
-        const txt = j.choices?.[0]?.message?.content ?? '';
-        const m = txt.match(/\[\s*(\d+(?:\s*,\s*\d+)*)\s*\]/);
-        const parsed = m ? m[1].split(',').map((s) => parseInt(s.trim(), 10)) : [];
-        const isPermutation = parsed.length === head.length &&
-            parsed.every((n) => Number.isInteger(n) && n >= 0 && n < head.length) &&
-            new Set(parsed).size === head.length;
-        if (!isPermutation)
-            throw new Error('reply is not a permutation of the candidates');
-        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(`${url.replace(/\/$/, '')}/chat/completions`, {
+        headers: { ...headers },
+        body: JSON.stringify({
+            model: envLlmRerankerModel() ?? 'gpt-4o-mini',
+            messages: [{ role: 'user', content: prompt }],
+            temperature: 0,
+        }),
+    }, envLlmRerankerTimeoutMs() ?? DEFAULT_TIMEOUT_MS);
+    if (!resp.ok) {
+        await resp.body?.cancel();
+        throw new Error(`HTTP ${resp.status}`);
     }
+    const txt = replyText(await readCappedJson(resp, RERANKER_MAX_REPLY_BYTES));
+    const m = txt.match(/\[\s*(\d+(?:\s*,\s*\d+)*)\s*\]/);
+    const parsed = m ? m[1].split(',').map((s) => parseInt(s.trim(), 10)) : [];
+    const isPermutation = parsed.length === head.length &&
+        parsed.every((n) => Number.isInteger(n) && n >= 0 && n < head.length) &&
+        new Set(parsed).size === head.length;
+    if (!isPermutation)
+        throw new Error('reply is not a permutation of the candidates');
+    return parsed;
 }
 //# sourceMappingURL=llm.js.map

package/dist/rerankers/outage-warning.d.ts

@@ -0,0 +1,8 @@
+export interface OutageWarning {
+    failed(reason: string): void;
+    answered(): void;
+}
+/** Warns when `name` starts failing, at most every five minutes while it keeps failing,
+ * and once when it answers again. `fallback` says what recall does meanwhile. */
+export declare function createOutageWarning(name: string, fallback: string): OutageWarning;
+//# sourceMappingURL=outage-warning.d.ts.map

package/dist/rerankers/outage-warning.js

@@ -0,0 +1,32 @@
+// One way for a reranker to report that it stopped working, without a line per recall.
+import { log } from '../util/log.js';
+const REPEAT_MS = 5 * 60_000;
+/** Warns when `name` starts failing, at most every five minutes while it keeps failing,
+ * and once when it answers again. `fallback` says what recall does meanwhile. */
+export function createOutageWarning(name, fallback) {
+    let failures = 0;
+    let unreported = 0;
+    let warnedAt = 0;
+    return {
+        failed(reason) {
+            failures++;
+            if (failures > 1 && Date.now() - warnedAt < REPEAT_MS) {
+                unreported++;
+                return;
+            }
+            const skipped = unreported > 0 ? ` ${unreported} more calls failed since the last warning.` : '';
+            log.warn(`${name} reranker unavailable (${reason}); ${fallback}.${skipped} While it fails this repeats at most every ${REPEAT_MS / 60_000} minutes.`);
+            warnedAt = Date.now();
+            unreported = 0;
+        },
+        answered() {
+            if (failures === 0)
+                return;
+            // At warn so it shows at the default level, next to the outage line it closes.
+            log.warn(`${name} reranker is answering again after ${failures} failed ${failures === 1 ? 'call' : 'calls'}.`);
+            failures = 0;
+            unreported = 0;
+        },
+    };
+}
+//# sourceMappingURL=outage-warning.js.map

package/dist/rerankers/remote.d.ts

@@ -0,0 +1,4 @@
+export declare const RERANKER_MAX_REPLY_BYTES: number;
+/** POST a scoring request. A dropped connection, 429 or 5xx is retried, since scoring changes nothing on the far side. */
+export declare function rerankerPost(url: string, init: RequestInit, budgetMs: number): Promise<Response>;
+//# sourceMappingURL=remote.d.ts.map

package/dist/rerankers/remote.js

@@ -0,0 +1,25 @@
+// The one bounded, retried POST every remote reranker sends.
+import { fetchWithRetry } from '../util/http-retry.js';
+// A Retry-After longer than this would outlast most budgets, so the answer is handed back and the reranker falls back.
+const RETRY_WAIT_CAP_MS = 2_000;
+// Every reranker reads its reply through this cap; the largest honest reply is a few KB, and 1 MiB leaves room for a verbose envelope.
+export const RERANKER_MAX_REPLY_BYTES = 1024 * 1024;
+/** POST a scoring request. A dropped connection, 429 or 5xx is retried, since scoring changes nothing on the far side. */
+export async function rerankerPost(url, init, budgetMs) {
+    // The budget bounds the whole call, retries included, so recall never waits past the configured timeout.
+    const budget = AbortSignal.timeout(budgetMs);
+    try {
+        return await fetchWithRetry(url, { ...init, method: 'POST', signal: budget }, {
+            timeoutMs: budgetMs,
+            retryTransport: true,
+            maxDelayMs: RETRY_WAIT_CAP_MS,
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+            throw new Error(`no answer within ${budgetMs} ms`, { cause: err });
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=remote.js.map

package/dist/rerankers/types.d.ts

@@ -1,18 +1,6 @@
-import type { SearchResult } from '../search/types.js';
-/**
- * A reranker reorders (and optionally rescales) the candidate set produced
- * by hybridSearch's BM25 + cosine + MMR pipeline. Rerankers run AFTER MMR
- * de-duplication and BEFORE token-budget filtering, so the reranker sees
- * the full diversity-balanced candidate pool but does not see candidates
- * already filtered out by score-zero or supersession.
- *
- * Rerankers MUST be deterministic for a given (query, results) input
- * unless explicitly documented as stochastic (the LLM track, and the
- * hosted jev reranker, whose scores move slightly run to run).
- * Determinism is required for paired A/B and for the workload-validity gate.
- *
- * @returns Reordered (and optionally rescaled) results.
- */
+import type { SearchResult } from '../core/search-types.js';
+/** Reorders hybridSearch's candidates AFTER MMR de-duplication and BEFORE token-budget filtering, so it sees the full diverse pool.
+ * MUST be deterministic for a given (query, results) unless documented stochastic (LLM track, hosted jev): paired A/B and the validity gate need it. */
 export type RerankerFn = (query: string, results: SearchResult[], options?: RerankerOptions) => Promise<RerankResult[]>;
 /** JSON-serializable value. Per-track reranker config is opaque to the seam
  *  but must still be a concrete, serializable shape rather than `unknown`. */

package/dist/search/as-of.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 export interface CurrentnessOptions {
     /** Keep only rows current at this ISO date string. */
     asOf?: string;

package/dist/search/bm25-search.d.ts

@@ -1,5 +1,5 @@
-import type { MemoryEntry } from '../memory.js';
-import { type ResultCost, type SearchResult } from './types.js';
+import type { MemoryEntry } from '../core/memory.js';
+import { type ResultCost, type SearchResult } from '../core/search-types.js';
 export interface SearchOptions {
     budget?: number;
     now?: Date;

package/dist/search/bm25-search.js

@@ -1,15 +1,15 @@
-import { estimateTokens } from '../token-ledger.js';
-import { tokenize } from '../tokenize.js';
-import { evalNow } from '../ablation.js';
-import { extractPathTags } from '../path-context.js';
-import { detectScope } from '../scope.js';
-import { compareScoredResults } from '../compare.js';
+import { estimateTokens } from '../util/token-text.js';
+import { tokenize } from '../util/tokenize.js';
+import { evalNow } from '../core/ablation.js';
+import { extractPathTags } from './path-context.js';
+import { detectScope } from '../sharing/scope.js';
+import { compareScoredResults } from '../core/compare.js';
 import { bm25Score, buildCorpus, entryText } from './bm25.js';
 import { currentEntries } from './as-of.js';
 import { applyRankBoosts, strengthRecencyMultipliers, NO_SUMMARY_SCORING } from './boosts.js';
 import { temporalContext } from './temporal.js';
 import { dedupeExtracted, fitBudget, withDagChildren } from './finalize.js';
-import { DEFAULT_RECALL_BUDGET } from './types.js';
+import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 /** Synchronous BM25 search: relevance * strength * recency and the rank boosts, without embeddings or the outcome nudge. */
 export function search(query, entries, options = {}) {
     const now = options.now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)

package/dist/search/bm25.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryEntry } from '../memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 /** Tokenized BM25 corpus; build it once with `buildCorpus` and reuse it across queries on the same entry set. */
 export interface BM25Corpus {
     docs: string[][];

package/dist/search/bm25.js

@@ -1,4 +1,4 @@
-import { tokenize } from '../tokenize.js';
+import { tokenize } from '../util/tokenize.js';
 const BM25_K1 = 1.5;
 const BM25_B = 0.75;
 /** The text BM25 indexes for an entry: its content followed by its tags. */

package/dist/search/boosts.d.ts

@@ -1,8 +1,8 @@
-import { type MemoryEntry } from '../memory.js';
+import { type MemoryEntry } from '../core/memory.js';
 import { type TemporalDirection, type TemporalRange } from './temporal.js';
-export declare const CHURN_STALE_RANK_MULTIPLIER = 0.5;
+export declare const STRENGTH_RANK_FLOOR = 0.5;
+export declare const STRENGTH_RANK_SPAN = 0.5;
 export declare function churnStaleFactor(entry: MemoryEntry): number;
-export declare function recencyBoost(entry: MemoryEntry, now: Date): number;
 /** Retrieval-time outcome nudge in [0.85, 1.15]; the bm25-outcome eval baseline ranks with it too. */
 export declare function outcomeMultiplier(entry: MemoryEntry): number;
 /** A DAG summary is a topic summary (level 2) or an entity profile (level 3); both take the same deboost. */
@@ -27,6 +27,8 @@ export declare function strengthRecencyMultipliers(entry: MemoryEntry, now: Date
     strength: number;
     recency: number;
 };
+/** The rank multiplier for a scopeMatch signal: match, mismatch or neutral. */
+export declare function scopeBoostFor(signal: -1 | 0 | 1): number;
 export interface BoostContext {
     now: Date;
     pathTags: string[];