hippo-memory 1.69.0 → 1.70.0

package/dist/rerankers/cross-encoder.js

@@ -1,10 +1,13 @@
 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
+// 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() {
@@ -38,21 +41,12 @@ 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;
-}
+const outage = createOutageWarning('cross-encoder', 'falling back to identity ordering');
 // 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.
@@ -81,7 +75,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 +91,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 +104,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 +124,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,10 @@
-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 } from './remote.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;
@@ -50,45 +53,29 @@ 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 body = await resp.json();
+    const scores = parseScores(body.answers, 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 +83,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 +103,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

@@ -6,11 +6,9 @@ import type { RerankerFn } from './types.js';
  *
  * 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
+ * Timeout: defaults to 30s for the whole call, retries included; overridable
+ * via HIPPO_LLM_RERANKER_TIMEOUT_MS. On timeout or any failure the reranker
  * falls back to identity ordering; recall must not hang on a wedged endpoint.
  */
 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,6 +1,9 @@
-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 } from './remote.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
@@ -9,29 +12,26 @@ const DEFAULT_TIMEOUT_MS = 30_000;
  *
  * 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
+ * Timeout: defaults to 30s for the whole call, retries included; overridable
+ * via HIPPO_LLM_RERANKER_TIMEOUT_MS. On timeout or any failure the reranker
  * falls back to identity ordering; recall must not hang on a wedged endpoint.
  */
 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 +42,6 @@ export function createLlmReranker() {
         }));
     };
 }
-/** The instance the reranker registry serves; its warn-once flag lasts the process. */
-export const llmReranker = createLlmReranker();
 /** 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 +51,33 @@ 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 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;
 }
 //# sourceMappingURL=llm.js.map

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

@@ -0,0 +1,7 @@
+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,31 @@
+// 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,3 @@
+/** 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,23 @@
+// 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;
+/** 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,4 +1,4 @@
-import type { SearchResult } from '../search/types.js';
+import type { SearchResult } from '../core/search-types.js';
 /**
  * A reranker reorders (and optionally rescales) the candidate set produced
  * by hybridSearch's BM25 + cosine + MMR pipeline. Rerankers run AFTER MMR

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,6 +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. */
@@ -27,6 +29,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[];

package/dist/search/boosts.js

@@ -1,14 +1,29 @@
-import { envSummaryDeboost } from '../env.js';
-import { calculateStrength, CHURN_STALE_TAG } from '../memory.js';
-import { isOutcomeFastAblated, isRecencyAblated, evalRecencyScaleDays } from '../ablation.js';
-import { pathBoostMultiplier } from '../path-context.js';
-import { scopeMatch } from '../scope.js';
+import { envSummaryDeboost } from '../util/env.js';
+import { calculateStrength, CHURN_STALE_TAG } from '../core/memory.js';
+import { isOutcomeFastAblated, isRecencyAblated, evalRecencyScaleDays } from '../core/ablation.js';
+import { pathBoostMultiplier } from './path-context.js';
+import { scopeMatch } from '../sharing/scope.js';
 import { temporalBoost } from './temporal.js';
+import { DAY_MS } from '../util/time.js';
 export const CHURN_STALE_RANK_MULTIPLIER = 0.5; // SHORTCUT: untuned; measure on real recall before any default.
 const DECISION_TAG_BOOST = 1.2;
+// A memory tagged for the active scope outranks a neutral one; one tagged for another scope is demoted.
+const SCOPE_MATCH_BOOST = 1.5;
+const SCOPE_MISMATCH_BOOST = 0.5;
+const EXTRACTION_TAG_BOOST = 1.3;
+// The outcome nudge is 1 + slope * tanh(net / 2), clamped so one outcome streak cannot swamp lexical rank.
+const OUTCOME_NUDGE_SLOPE = 0.15;
+const OUTCOME_NUDGE_MIN = 0.85;
+const OUTCOME_NUDGE_MAX = 1.15;
+// Strength and recency enter the rank as floor + span * signal, so a weak or old memory keeps most of its lexical score.
+export const STRENGTH_RANK_FLOOR = 0.5;
+export const STRENGTH_RANK_SPAN = 0.5;
+const RECENCY_RANK_FLOOR = 0.8;
+const RECENCY_RANK_SPAN = 0.2;
+const RECENCY_SCALE_DAYS = 30;
 const DEFAULT_SUMMARY_DEBOOST = 0.85;
 const DEFAULT_FRESHNESS_BOOST = 1.05;
-const FRESHNESS_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const FRESHNESS_WINDOW_MS = 7 * DAY_MS;
 export function churnStaleFactor(entry) {
     return entry.tags.includes(CHURN_STALE_TAG) ? CHURN_STALE_RANK_MULTIPLIER : 1.0;
 }
@@ -16,8 +31,8 @@ export function recencyBoost(entry, now) {
     if (isRecencyAblated())
         return 1; // EVAL-ONLY ablation (see ablation.ts)
     const created = new Date(entry.created);
-    const ageDays = (now.getTime() - created.getTime()) / (1000 * 60 * 60 * 24);
-    return Math.exp(-ageDays / (evalRecencyScaleDays() ?? 30));
+    const ageDays = (now.getTime() - created.getTime()) / DAY_MS;
+    return Math.exp(-ageDays / (evalRecencyScaleDays() ?? RECENCY_SCALE_DAYS));
 }
 /** Retrieval-time outcome nudge in [0.85, 1.15]; the bm25-outcome eval baseline ranks with it too. */
 export function outcomeMultiplier(entry) {
@@ -25,7 +40,7 @@ export function outcomeMultiplier(entry) {
     const neg = entry.outcome_negative ?? 0;
     if (isOutcomeFastAblated() || (pos === 0 && neg === 0))
         return 1.0; // EVAL-ONLY ablation (see ablation.ts)
-    return Math.max(0.85, Math.min(1.15, 1 + 0.15 * Math.tanh((pos - neg) / 2)));
+    return Math.max(OUTCOME_NUDGE_MIN, Math.min(OUTCOME_NUDGE_MAX, 1 + OUTCOME_NUDGE_SLOPE * Math.tanh((pos - neg) / 2)));
 }
 /** A DAG summary is a topic summary (level 2) or an entity profile (level 3); both take the same deboost. */
 export function isDagSummary(entry) {
@@ -66,7 +81,14 @@ export function summaryMultipliers(entry, now, s) {
     return { deboost: s.deboost, freshness: s.freshness ? summaryFreshnessMultiplier(entry, now) : 1.0 };
 }
 export function strengthRecencyMultipliers(entry, now) {
-    return { strength: 0.5 + 0.5 * calculateStrength(entry, now), recency: 0.8 + 0.2 * recencyBoost(entry, now) };
+    return {
+        strength: STRENGTH_RANK_FLOOR + STRENGTH_RANK_SPAN * calculateStrength(entry, now),
+        recency: RECENCY_RANK_FLOOR + RECENCY_RANK_SPAN * recencyBoost(entry, now),
+    };
+}
+/** The rank multiplier for a scopeMatch signal: match, mismatch or neutral. */
+export function scopeBoostFor(signal) {
+    return signal === 1 ? SCOPE_MATCH_BOOST : signal === -1 ? SCOPE_MISMATCH_BOOST : 1.0;
 }
 /** Applies every rank multiplier one at a time, in a fixed order, so float rounding matches across paths. */
 export function applyRankBoosts(score, entry, ctx) {
@@ -74,9 +96,8 @@ export function applyRankBoosts(score, entry, ctx) {
     const churnStaleMultiplier = churnStaleFactor(entry);
     const pathBoost = pathBoostMultiplier(entry.tags, ctx.pathTags);
     const outcomeBoost = ctx.outcome ? outcomeMultiplier(entry) : 1.0;
-    const scopeSignal = scopeMatch(entry.tags, ctx.scope);
-    const scopeBoost = scopeSignal === 1 ? 1.5 : scopeSignal === -1 ? 0.5 : 1.0;
-    const extractionBoost = entry.tags.includes('extracted') ? 1.3 : 1.0;
+    const scopeBoost = scopeBoostFor(scopeMatch(entry.tags, ctx.scope));
+    const extractionBoost = entry.tags.includes('extracted') ? EXTRACTION_TAG_BOOST : 1.0;
     const summary = summaryMultipliers(entry, ctx.now, ctx.summary);
     let s = score;
     s *= decisionBoost;

package/dist/search/breakdown.d.ts

@@ -1,5 +1,5 @@
-import type { MemoryEntry } from '../memory.js';
-import type { ScoreBreakdown } from './types.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { ScoreBreakdown } from '../core/search-types.js';
 /** Whole days since the entry was created, never negative. */
 export declare function ageInDays(entry: MemoryEntry, now: Date): number;
 /** Copies the entry's DAG metadata, and for summaries the multipliers applied, onto an explain breakdown. */

package/dist/search/breakdown.js

@@ -1,7 +1,8 @@
 import { isDagSummary } from './boosts.js';
+import { DAY_MS } from '../util/time.js';
 /** Whole days since the entry was created, never negative. */
 export function ageInDays(entry, now) {
-    return Math.max(0, Math.floor((now.getTime() - new Date(entry.created).getTime()) / 86_400_000));
+    return Math.max(0, Math.floor((now.getTime() - new Date(entry.created).getTime()) / DAY_MS));
 }
 /** Copies the entry's DAG metadata, and for summaries the multipliers applied, onto an explain breakdown. */
 export function addDagFields(breakdown, entry, deboost, freshness) {