oh-my-second-brain 0.3.0 → 0.6.2

package/dist/kernel/engine/retrieval/dispatcher.js

@@ -11,6 +11,23 @@
  *     every async step.
  */
 import { fuseRRF } from "./rrf.js";
+function assertFiniteVector(vector, expectedDimensions) {
+    if (!(vector instanceof Float32Array)) {
+        throw new Error("Embedding provider returned a vector that is not a Float32Array.");
+    }
+    if (vector.length !== expectedDimensions) {
+        throw new Error(`Embedding provider returned ${vector.length} dimensions; expected ${expectedDimensions}.`);
+    }
+    for (let index = 0; index < vector.length; index += 1) {
+        if (!Number.isFinite(vector[index])) {
+            throw new Error(`Embedding provider returned a non-finite vector value at index ${index}.`);
+        }
+    }
+}
+async function embedQuery(provider, text) {
+    const queryProvider = provider;
+    return queryProvider.embedQuery?.(text) ?? provider.embed(text);
+}
 /** Create a new mutable cancel token. */
 export function createCancelToken() {
     let cancelled = false;
@@ -59,6 +76,26 @@ const PROVENANCE_BOOST = {
     curated: 0.01, // deliberately imported / curated references
     "external-raw": 0, // raw external content — no boost
 };
+/**
+ * Apply the provenance signal without putting it on a different scale from
+ * RRF. RRF scores are bounded by the number of lists and `rrfK` (roughly
+ * 0.016 for one rank-1 list with k=60), so adding a raw 0.02 would let a
+ * low-ranked authored hit leap over a stronger multi-list result. A
+ * multiplicative adjustment keeps the signal monotonic and proportional to
+ * the fused score.
+ */
+export function applyProvenanceBoost(score, provenance) {
+    const boost = provenance === undefined ? 0 : PROVENANCE_BOOST[provenance];
+    return score * (1 + boost);
+}
+export const DISPATCHER_POLICIES = Object.freeze([
+    "boost-additive",
+    "boost-k-scale",
+    "boost-per-list",
+    "boost-zero",
+]);
+export const PREREGISTERED_ARM_POLICIES = Object.freeze(["boost-k-scale", "boost-per-list", "boost-zero"]);
+export const DEFAULT_DISPATCHER_POLICY = "boost-additive";
 // ---------------------------------------------------------------------------
 // Per-type dispatch
 // ---------------------------------------------------------------------------
@@ -70,13 +107,15 @@ async function dispatchOne(sub, deps, k, cancel, collection) {
                 : deps.store.queryLex(sub.query, k, collection)), cancel);
         }
         case "vec": {
-            const vec = await withRetry(() => deps.embed.embed(sub.query), cancel);
+            const vec = await withRetry(() => embedQuery(deps.embed, sub.query), cancel);
+            assertFiniteVector(vec, deps.embed.dimensions);
             return withRetry(() => Promise.resolve(collection === undefined ? deps.store.queryVec(vec, k) : deps.store.queryVec(vec, k, collection)), cancel);
         }
         case "hyde": {
             const generator = deps.hydeGenerator ?? defaultHydeGenerator;
             const hypoDoc = await withRetry(() => generator(sub.query), cancel);
-            const vec = await withRetry(() => deps.embed.embed(hypoDoc), cancel);
+            const vec = await withRetry(() => embedQuery(deps.embed, hypoDoc), cancel);
+            assertFiniteVector(vec, deps.embed.dimensions);
             return withRetry(() => Promise.resolve(collection === undefined ? deps.store.queryVec(vec, k) : deps.store.queryVec(vec, k, collection)), cancel);
         }
         case "graph": {
@@ -91,6 +130,22 @@ async function dispatchOne(sub, deps, k, cancel, collection) {
         }
     }
 }
+/**
+ * Apply the per-list policy before RRF ranking. RRF consumes rank positions,
+ * so the weighted score must be used to establish each list's order rather
+ * than applied after fusion (which would be the k-scale policy).
+ */
+function rankListForPolicy(list, deps, policy) {
+    if (policy !== "boost-per-list")
+        return list;
+    return [...list].sort((left, right) => {
+        const leftScore = applyProvenanceBoost(left.score, deps.provenanceMap?.(left.docPath));
+        const rightScore = applyProvenanceBoost(right.score, deps.provenanceMap?.(right.docPath));
+        return rightScore - leftScore ||
+            left.docPath.localeCompare(right.docPath) ||
+            left.chunkOrdinal - right.chunkOrdinal;
+    });
+}
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -106,16 +161,27 @@ async function dispatchOne(sub, deps, k, cancel, collection) {
 export async function dispatch(subQueries, deps, k = 10, cancel, collection) {
     const token = cancel ?? createCancelToken();
     const rrfK = deps.rrfK ?? 60;
+    const policy = deps.policy ?? DEFAULT_DISPATCHER_POLICY;
+    if (!Number.isSafeInteger(k) || k < 0) {
+        throw new Error("Retrieval candidate count k must be a non-negative safe integer.");
+    }
+    if (!Number.isFinite(rrfK) || rrfK < 0) {
+        throw new Error("RRF smoothing constant k must be a finite non-negative number.");
+    }
+    if (!DISPATCHER_POLICIES.includes(policy)) {
+        throw new Error(`Unknown dispatcher policy: ${String(policy)}`);
+    }
     if (subQueries.length === 0)
         return [];
     // Execute all sub-queries in parallel (each with its own retry envelope)
     const rankedLists = await Promise.all(subQueries.map((sub) => dispatchOne(sub, deps, k, token, collection)));
+    const policyLists = rankedLists.map((list) => rankListForPolicy(list, deps, policy));
     // Build per-type score index for the perTypeScores field
     // key = "docPath\0chunkOrdinal" → type → max raw score from that type
     const typeScores = new Map();
     for (let i = 0; i < subQueries.length; i++) {
         const type = subQueries[i].type;
-        const list = rankedLists[i];
+        const list = policyLists[i];
         for (const hit of list) {
             const key = `${hit.docPath}\x00${hit.chunkOrdinal}`;
             const perType = typeScores.get(key) ?? new Map();
@@ -126,22 +192,32 @@ export async function dispatch(subQueries, deps, k = 10, cancel, collection) {
         }
     }
     // Fuse with RRF
-    const fused = fuseRRF(rankedLists, rrfK);
-    // Build final results with provenance boost and per-type breakdown
-    return fused.map((hit) => {
+    const fused = fuseRRF(policyLists, rrfK, {
+        preserveInputOrder: policy === "boost-per-list",
+    });
+    // Build final results with provenance boost and per-type breakdown.
+    const results = fused.map((hit) => {
         const key = `${hit.docPath}\x00${hit.chunkOrdinal}`;
         const provenance = deps.provenanceMap?.(hit.docPath);
-        const boost = provenance !== undefined ? PROVENANCE_BOOST[provenance] : 0;
+        const boost = provenance === undefined ? 0 : PROVENANCE_BOOST[provenance];
         const perTypeMap = typeScores.get(key);
         const perTypeScores = perTypeMap !== undefined && perTypeMap.size > 0
             ? Object.fromEntries(perTypeMap)
             : undefined;
         return {
             docPath: hit.docPath,
-            score: hit.score + boost,
+            score: policy === "boost-additive"
+                ? hit.score + boost
+                : policy === "boost-k-scale"
+                    ? applyProvenanceBoost(hit.score, provenance)
+                    : hit.score,
             provenance,
             perTypeScores,
         };
     });
+    if (policy === "boost-additive")
+        return results;
+    return results.sort((a, b) => b.score - a.score ||
+        a.docPath.localeCompare(b.docPath));
 }
 //# sourceMappingURL=dispatcher.js.map

package/dist/kernel/engine/retrieval/dispatcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../../../src/kernel/engine/retrieval/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAYnC,yCAAyC;AACzC,MAAM,UAAU,iBAAiB;IAC/B,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,OAAO;QACL,IAAI,SAAS;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM;YACJ,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,gDAAgD;AAChD,8EAA8E;AAE9E;;;;GAIG;AACH,KAAK,UAAU,SAAS,CACtB,EAAoB,EACpB,MAAmB,EACnB,WAAW,GAAG,CAAC;IAEf,IAAI,SAAkB,CAAC;IACvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,MAAM,CAAC,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;QAC7D,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAG,CAAC;YAChB,0DAA0D;YAC1D,IAAI,OAAO,GAAG,WAAW,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBACnD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAChF,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,SAAS,CAAC;AAClB,CAAC;AAiBD,iEAAiE;AACjE,MAAM,oBAAoB,GAAkB,CAAC,KAAa,EAAE,EAAE,CAC5D,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEzB,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,gBAAgB,GAA+B;IACnD,QAAQ,EAAE,IAAI,EAAI,8CAA8C;IAChE,OAAO,EAAE,IAAI,EAAK,6CAA6C;IAC/D,cAAc,EAAE,CAAC,EAAE,kCAAkC;CACtD,CAAC;AAgCF,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,KAAK,UAAU,WAAW,CACxB,GAAkB,EAClB,IAAoB,EACpB,CAAS,EACT,MAAmB,EACnB,UAAmB;IAEnB,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,OAAO,SAAS,CACd,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CACnB,UAAU,KAAK,SAAS;gBACtB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;gBACnC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,CAClD,EACD,MAAM,CACP,CAAC;QACJ,CAAC;QAED,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;YACvE,OAAO,SAAS,CACd,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CACnB,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,UAAU,CAAC,CACjG,EACD,MAAM,CACP,CAAC;QACJ,CAAC;QAED,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,IAAI,oBAAoB,CAAC;YAC7D,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;YACpE,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;YACrE,OAAO,SAAS,CACd,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CACnB,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,UAAU,CAAC,CACjG,EACD,MAAM,CACP,CAAC;QACJ,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,IAAI,CAAC,IAAI,CAAC,aAAa;gBAAE,OAAO,EAAE,CAAC;YACnC,MAAM,QAAQ,GAAa;gBACzB,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,GAAG,CAAC,KAAK;gBACf,KAAK,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC;aAC5B,CAAC;YACF,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,aAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,UAA2B,EAC3B,IAAoB,EACpB,CAAC,GAAG,EAAE,EACN,MAAoB,EACpB,UAAmB;IAEnB,MAAM,KAAK,GAAG,MAAM,IAAI,iBAAiB,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;IAE7B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,yEAAyE;IACzE,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,GAAG,CACnC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CACtE,CAAC;IAEF,yDAAyD;IACzD,sEAAsE;IACtE,MAAM,UAAU,GAAG,IAAI,GAAG,EAA+B,CAAC;IAC1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC;QACjC,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAE,CAAC;QAC7B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,OAAO,OAAO,GAAG,CAAC,YAAY,EAAE,CAAC;YACpD,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,EAAkB,CAAC;YACjE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpC,IAAI,GAAG,CAAC,KAAK,GAAG,IAAI;gBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YACnD,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,gBAAgB;IAChB,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAEzC,mEAAmE;IACnE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACvB,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,OAAO,OAAO,GAAG,CAAC,YAAY,EAAE,CAAC;QACpD,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,KAAK,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE1E,MAAM,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,aAAa,GACjB,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,IAAI,GAAG,CAAC;YAC7C,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC;YAChC,CAAC,CAAC,SAAS,CAAC;QAEhB,OAAO;YACL,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,KAAK;YACxB,UAAU;YACV,aAAa;SACd,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../../../src/kernel/engine/retrieval/dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/kernel/engine/retrieval/index.d.ts

@@ -11,7 +11,8 @@
  */
 export { fuseRRF } from "./rrf.js";
 export type { Reranker } from "./reranker.js";
-export { PassthroughReranker, passthroughReranker } from "./reranker.js";
+export { createLlamaReranker, DEFAULT_RERANKER_CANDIDATE_CAP, LlamaReranker, PassthroughReranker, passthroughReranker, } from "./reranker.js";
+export type { LlamaModelLoader, LlamaRerankerOptions, RankingContext, RankingModel, } from "./reranker.js";
 export { dispatch, createCancelToken, } from "./dispatcher.js";
 export type { CancelToken, DispatcherDeps, HydeGenerator } from "./dispatcher.js";
 import type { RetrievalResult } from "../types.js";

package/dist/kernel/engine/retrieval/index.js

@@ -10,7 +10,7 @@
  *   - DispatcherDeps — dependency-injection bag for backends
  */
 export { fuseRRF } from "./rrf.js";
-export { PassthroughReranker, passthroughReranker } from "./reranker.js";
+export { createLlamaReranker, DEFAULT_RERANKER_CANDIDATE_CAP, LlamaReranker, PassthroughReranker, passthroughReranker, } from "./reranker.js";
 export { dispatch, createCancelToken, } from "./dispatcher.js";
 import { dispatch } from "./dispatcher.js";
 /**

package/dist/kernel/engine/retrieval/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/kernel/engine/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EACL,QAAQ,EACR,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAkC3C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAqB;IAClD,qDAAqD;IACrD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAEjG,2CAA2C;IAC3C,IAAI,CAAC,IAAI,CAAC,QAAQ;QAAE,OAAO,OAAO,CAAC;IAEnC,2EAA2E;IAC3E,MAAM,IAAI,GAAgB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC5C,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,YAAY,EAAE,CAAC;QACf,KAAK,EAAE,CAAC,CAAC,KAAK;KACf,CAAC,CAAC,CAAC;IAEJ,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAE9D,wEAAwE;IACxE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACX,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAA4B,CAAC;IACjE,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAwB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/kernel/engine/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,mBAAmB,EACnB,8BAA8B,EAC9B,aAAa,EACb,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAOvB,OAAO,EACL,QAAQ,EACR,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAkC3C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAqB;IAClD,qDAAqD;IACrD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAEjG,2CAA2C;IAC3C,IAAI,CAAC,IAAI,CAAC,QAAQ;QAAE,OAAO,OAAO,CAAC;IAEnC,2EAA2E;IAC3E,MAAM,IAAI,GAAgB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC5C,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,YAAY,EAAE,CAAC;QACf,KAAK,EAAE,CAAC,CAAC,KAAK;KACf,CAAC,CAAC,CAAC;IAEJ,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAE9D,wEAAwE;IACxE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACX,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAA4B,CAAC;IACjE,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAwB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;AAC1D,CAAC"}

package/dist/kernel/engine/retrieval/reranker.d.ts

@@ -2,8 +2,10 @@
  * Cross-encoder reranker hook.
  *
  * This module defines the Reranker interface and ships a passthrough (no-op)
- * default so the precision-mode pipeline is wired end-to-end in M1 without
- * requiring a loaded reranker model.
+ * default so the precision-mode pipeline is wired end-to-end without
+ * requiring a loaded reranker model. The node-llama-cpp implementation below
+ * is explicitly opt-in and lazy: constructing it never loads a model or
+ * creates a ranking context.
  *
  * Intended production implementations (inject at the integrate phase):
  *   - bge-reranker-v2-m3  (BAAI, Apache-2.0) — strong multilingual reranker,
@@ -13,6 +15,7 @@
  *
  * Wire a real impl by passing it to retrieve() as `opts.reranker`.
  */
+import type { LlamaRankingContextOptions } from "node-llama-cpp";
 import type { ScoredHit } from "../types.js";
 /**
  * Opt-in cross-encoder reranker hook.
@@ -31,8 +34,81 @@ export interface Reranker {
      * @returns A new list sorted descending by the reranker's cross-encoder score.
      *          The returned list may be shorter than `hits` (e.g. top-k precision cut).
      */
-    rerank(query: string, hits: ScoredHit[]): Promise<ScoredHit[]>;
+    rerank(query: string, hits: ScoredHit[], cancel?: {
+        readonly cancelled: boolean;
+    }): Promise<ScoredHit[]>;
 }
+/**
+ * Narrow seam around node-llama-cpp used by the lazy implementation.
+ *
+ * Keeping the seam injectable makes the lifecycle contract testable without
+ * downloading or loading a model. Production uses the default dynamic loader.
+ */
+export interface RankingContext {
+    rankAll(query: string, documents: string[]): Promise<readonly number[]>;
+    dispose(): Promise<void>;
+}
+export interface RankingModel {
+    createRankingContext(options?: LlamaRankingContextOptions): Promise<RankingContext>;
+    dispose(): Promise<void>;
+}
+export type LlamaModelLoader = (modelPath: string) => Promise<RankingModel>;
+/** Conservative candidate budget; reranking is opt-in and default-off. */
+export declare const DEFAULT_RERANKER_CANDIDATE_CAP = 50;
+/**
+ * Options for {@link createLlamaReranker}.
+ *
+ * `idleUnloadMs` is disabled by default (`0`). Enabling it is useful for
+ * memory-constrained hosts, but the model is otherwise retained after its
+ * first requested rerank so repeated opt-in calls do not reload native state.
+ */
+export interface LlamaRerankerOptions {
+    readonly modelPath: string;
+    readonly candidateCap?: number;
+    readonly idleUnloadMs?: number;
+    readonly contextOptions?: LlamaRankingContextOptions;
+    /** Test seam; production callers should omit this. */
+    readonly loadModel?: LlamaModelLoader;
+}
+/**
+ * A lazy node-llama-cpp cross-encoder reranker.
+ *
+ * The model and `LlamaRankingContext` are created only by the first
+ * `rerank()` call. Only the first `candidateCap` fused hits are sent to the
+ * cross-encoder; hits beyond that safety budget are intentionally omitted.
+ * Scores are replaced with the cross-encoder scores and returned descending.
+ */
+export declare class LlamaReranker implements Reranker {
+    private readonly modelPath;
+    private readonly candidateCap;
+    private readonly idleUnloadMs;
+    private readonly contextOptions;
+    private readonly loadModel;
+    private model;
+    private context;
+    private loadPromise;
+    private idleTimer;
+    private activeCalls;
+    private activeDone;
+    private resolveActiveDone;
+    private disposed;
+    private disposePromise;
+    constructor(options: LlamaRerankerOptions);
+    private clearIdleTimer;
+    private scheduleIdleUnload;
+    private ensureContext;
+    private unload;
+    /** Release model/context resources; safe before the first rerank call. */
+    dispose(): Promise<void>;
+    rerank(query: string, hits: ScoredHit[], cancel?: {
+        readonly cancelled: boolean;
+    }): Promise<ScoredHit[]>;
+}
+/**
+ * Construct a lazy reranker. No model import, native load, or context
+ * creation occurs until the returned reranker's `rerank()` is requested.
+ */
+export declare function createLlamaReranker(options: LlamaRerankerOptions): LlamaReranker;
 /**
  * Passthrough (no-op) reranker — returns hits unchanged.
  *
@@ -40,7 +116,9 @@ export interface Reranker {
  * is available or when reranking overhead is not desired.
  */
 export declare class PassthroughReranker implements Reranker {
-    rerank(_query: string, hits: ScoredHit[]): Promise<ScoredHit[]>;
+    rerank(_query: string, hits: ScoredHit[], cancel?: {
+        readonly cancelled: boolean;
+    }): Promise<ScoredHit[]>;
 }
 /** Shared singleton passthrough instance — safe to reuse across calls. */
 export declare const passthroughReranker: Reranker;

package/dist/kernel/engine/retrieval/reranker.js

@@ -2,8 +2,10 @@
  * Cross-encoder reranker hook.
  *
  * This module defines the Reranker interface and ships a passthrough (no-op)
- * default so the precision-mode pipeline is wired end-to-end in M1 without
- * requiring a loaded reranker model.
+ * default so the precision-mode pipeline is wired end-to-end without
+ * requiring a loaded reranker model. The node-llama-cpp implementation below
+ * is explicitly opt-in and lazy: constructing it never loads a model or
+ * creates a ranking context.
  *
  * Intended production implementations (inject at the integrate phase):
  *   - bge-reranker-v2-m3  (BAAI, Apache-2.0) — strong multilingual reranker,
@@ -13,6 +15,177 @@
  *
  * Wire a real impl by passing it to retrieve() as `opts.reranker`.
  */
+/** Conservative candidate budget; reranking is opt-in and default-off. */
+export const DEFAULT_RERANKER_CANDIDATE_CAP = 50;
+async function loadLlamaModel(modelPath) {
+    const { getLlama } = await import("node-llama-cpp");
+    const llama = await getLlama();
+    return llama.loadModel({ modelPath });
+}
+/**
+ * A lazy node-llama-cpp cross-encoder reranker.
+ *
+ * The model and `LlamaRankingContext` are created only by the first
+ * `rerank()` call. Only the first `candidateCap` fused hits are sent to the
+ * cross-encoder; hits beyond that safety budget are intentionally omitted.
+ * Scores are replaced with the cross-encoder scores and returned descending.
+ */
+export class LlamaReranker {
+    modelPath;
+    candidateCap;
+    idleUnloadMs;
+    contextOptions;
+    loadModel;
+    model = null;
+    context = null;
+    loadPromise = null;
+    idleTimer = null;
+    activeCalls = 0;
+    activeDone = null;
+    resolveActiveDone = null;
+    disposed = false;
+    disposePromise = null;
+    constructor(options) {
+        const candidateCap = options.candidateCap ?? DEFAULT_RERANKER_CANDIDATE_CAP;
+        if (!Number.isSafeInteger(candidateCap) || candidateCap < 1) {
+            throw new Error("reranker candidateCap must be a positive safe integer.");
+        }
+        const idleUnloadMs = options.idleUnloadMs ?? 0;
+        if (!Number.isFinite(idleUnloadMs) || idleUnloadMs < 0) {
+            throw new Error("reranker idleUnloadMs must be a non-negative number.");
+        }
+        if (options.modelPath.trim().length === 0) {
+            throw new Error("reranker modelPath must be non-empty.");
+        }
+        this.modelPath = options.modelPath;
+        this.candidateCap = candidateCap;
+        this.idleUnloadMs = idleUnloadMs;
+        this.contextOptions = options.contextOptions;
+        this.loadModel = options.loadModel ?? loadLlamaModel;
+    }
+    clearIdleTimer() {
+        if (this.idleTimer !== null) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+    }
+    scheduleIdleUnload() {
+        this.clearIdleTimer();
+        if (this.disposed || this.idleUnloadMs <= 0 || this.context === null)
+            return;
+        this.idleTimer = setTimeout(() => {
+            this.idleTimer = null;
+            if (this.activeCalls > 0) {
+                this.scheduleIdleUnload();
+                return;
+            }
+            void this.unload().catch(() => undefined);
+        }, this.idleUnloadMs);
+    }
+    async ensureContext() {
+        if (this.disposed)
+            throw new Error("Reranker has been disposed.");
+        if (this.context !== null)
+            return this.context;
+        if (this.loadPromise !== null)
+            return this.loadPromise;
+        this.loadPromise = (async () => {
+            const model = await this.loadModel(this.modelPath);
+            this.model = model;
+            try {
+                const context = await model.createRankingContext(this.contextOptions);
+                this.context = context;
+                return context;
+            }
+            catch (error) {
+                this.model = null;
+                await model.dispose().catch(() => undefined);
+                throw error;
+            }
+        })().finally(() => {
+            this.loadPromise = null;
+        });
+        return this.loadPromise;
+    }
+    async unload() {
+        this.clearIdleTimer();
+        const context = this.context;
+        const model = this.model;
+        this.context = null;
+        this.model = null;
+        if (context !== null)
+            await context.dispose().catch(() => undefined);
+        if (model !== null)
+            await model.dispose().catch(() => undefined);
+    }
+    /** Release model/context resources; safe before the first rerank call. */
+    async dispose() {
+        if (this.disposePromise !== null) {
+            return this.disposePromise;
+        }
+        this.disposed = true;
+        this.clearIdleTimer();
+        this.disposePromise = (async () => {
+            if (this.loadPromise !== null) {
+                await this.loadPromise.catch(() => undefined);
+            }
+            // Context disposal must never race a native rankAll() call. Calls
+            // already admitted before dispose() drain before unloading resources.
+            if (this.activeDone !== null)
+                await this.activeDone;
+            await this.unload();
+        })();
+        return this.disposePromise;
+    }
+    async rerank(query, hits, cancel) {
+        if (hits.length === 0)
+            return [];
+        if (this.disposed)
+            throw new Error("Reranker has been disposed.");
+        if (cancel?.cancelled)
+            throw new Error("Retrieval cancelled");
+        const candidates = hits.slice(0, this.candidateCap);
+        this.activeCalls += 1;
+        if (this.activeCalls === 1) {
+            this.activeDone = new Promise((resolve) => {
+                this.resolveActiveDone = resolve;
+            });
+        }
+        try {
+            const context = await this.ensureContext();
+            if (cancel?.cancelled)
+                throw new Error("Retrieval cancelled");
+            const scores = await context.rankAll(query, candidates.map((hit) => hit.docPath));
+            if (cancel?.cancelled)
+                throw new Error("Retrieval cancelled");
+            if (scores.length !== candidates.length) {
+                throw new Error(`reranker returned ${scores.length} scores for ${candidates.length} candidates.`);
+            }
+            if (scores.some((score) => !Number.isFinite(score))) {
+                throw new Error("reranker returned a non-finite score.");
+            }
+            return candidates
+                .map((hit, index) => ({ ...hit, score: scores[index] }))
+                .sort((left, right) => right.score - left.score);
+        }
+        finally {
+            this.activeCalls -= 1;
+            if (this.activeCalls === 0) {
+                this.resolveActiveDone?.();
+                this.resolveActiveDone = null;
+                this.activeDone = null;
+            }
+            this.scheduleIdleUnload();
+        }
+    }
+}
+/**
+ * Construct a lazy reranker. No model import, native load, or context
+ * creation occurs until the returned reranker's `rerank()` is requested.
+ */
+export function createLlamaReranker(options) {
+    return new LlamaReranker(options);
+}
 /**
  * Passthrough (no-op) reranker — returns hits unchanged.
  *
@@ -20,7 +193,9 @@
  * is available or when reranking overhead is not desired.
  */
 export class PassthroughReranker {
-    async rerank(_query, hits) {
+    async rerank(_query, hits, cancel) {
+        if (cancel?.cancelled)
+            throw new Error("Retrieval cancelled");
         return hits;
     }
 }

package/dist/kernel/engine/retrieval/reranker.js.map

@@ -1 +1 @@
-{"version":3,"file":"reranker.js","sourceRoot":"","sources":["../../../../src/kernel/engine/retrieval/reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAwBH;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IAC9B,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,IAAiB;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,CAAC,MAAM,mBAAmB,GAAa,IAAI,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"reranker.js","sourceRoot":"","sources":["../../../../src/kernel/engine/retrieval/reranker.ts"],"names":[],"mappings":"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"}

package/dist/kernel/engine/retrieval/rrf.d.ts

@@ -14,10 +14,18 @@ import type { ScoredHit } from "../types.js";
  * Fuse multiple ranked lists into a single list using Reciprocal Rank Fusion.
  *
  * @param rankedLists - Per-modality ranked hit lists. Each inner list need not be
- *   pre-sorted; fuseRRF sorts each list descending by score before ranking.
+ *   pre-sorted unless `preserveInputOrder` is enabled.
  * @param k - RRF smoothing constant (default 60). Higher values reduce the impact
  *   of rank position; typical range is 50–70.
+ * @param options - Ranking behavior for each input list.
  * @returns Fused list sorted descending by RRF score. Ties are broken
  *   lexicographically by the composite key `"docPath\0chunkOrdinal"`.
  */
-export declare function fuseRRF(rankedLists: ScoredHit[][], k?: number): ScoredHit[];
+export interface FuseRRFOptions {
+    /**
+     * Treat each list as already ranked and use its supplied order. This is
+     * required when a caller has established rank with a non-score policy.
+     */
+    preserveInputOrder?: boolean;
+}
+export declare function fuseRRF(rankedLists: ScoredHit[][], k?: number, options?: FuseRRFOptions): ScoredHit[];

package/dist/kernel/engine/retrieval/rrf.js

@@ -9,17 +9,38 @@
  * where rank_i(d) is the 1-based position of document d in list i.
  * Documents absent from a list contribute 0 for that list.
  */
-/**
- * Fuse multiple ranked lists into a single list using Reciprocal Rank Fusion.
- *
- * @param rankedLists - Per-modality ranked hit lists. Each inner list need not be
- *   pre-sorted; fuseRRF sorts each list descending by score before ranking.
- * @param k - RRF smoothing constant (default 60). Higher values reduce the impact
- *   of rank position; typical range is 50–70.
- * @returns Fused list sorted descending by RRF score. Ties are broken
- *   lexicographically by the composite key `"docPath\0chunkOrdinal"`.
- */
-export function fuseRRF(rankedLists, k = 60) {
+function validateRrfInputs(rankedLists, k, options) {
+    if (!Array.isArray(rankedLists)) {
+        throw new Error("RRF ranked lists must be an array.");
+    }
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new Error("RRF options must be an object.");
+    }
+    if (!Number.isFinite(k) || k < 0) {
+        throw new Error("RRF smoothing constant k must be a finite non-negative number.");
+    }
+    if (typeof options.preserveInputOrder !== "undefined" && typeof options.preserveInputOrder !== "boolean") {
+        throw new Error("RRF preserveInputOrder must be a boolean.");
+    }
+    for (const list of rankedLists) {
+        if (!Array.isArray(list)) {
+            throw new Error("RRF ranked lists must be arrays of scored hits.");
+        }
+        for (const hit of list) {
+            if (hit === null ||
+                typeof hit !== "object" ||
+                typeof hit.docPath !== "string" ||
+                hit.docPath.trim().length === 0 ||
+                !Number.isSafeInteger(hit.chunkOrdinal) ||
+                hit.chunkOrdinal < 0 ||
+                !Number.isFinite(hit.score)) {
+                throw new Error("RRF scored hits must have a non-empty path, non-negative ordinal, and finite score.");
+            }
+        }
+    }
+}
+export function fuseRRF(rankedLists, k = 60, options = {}) {
+    validateRrfInputs(rankedLists, k, options);
     if (rankedLists.length === 0)
         return [];
     // key → { accumulated RRF score, original hit metadata }
@@ -27,11 +48,13 @@ export function fuseRRF(rankedLists, k = 60) {
     for (const list of rankedLists) {
         if (list.length === 0)
             continue;
-        // Sort descending by score; secondary lex sort ensures deterministic ranking
-        // when two hits in the same list have the same score.
-        const sorted = [...list].sort((a, b) => b.score - a.score ||
-            a.docPath.localeCompare(b.docPath) ||
-            a.chunkOrdinal - b.chunkOrdinal);
+        // Dispatch policies may establish rank independently of raw score. In that
+        // case, preserve the caller's order rather than replacing it here.
+        const sorted = options.preserveInputOrder
+            ? list
+            : [...list].sort((a, b) => b.score - a.score ||
+                a.docPath.localeCompare(b.docPath) ||
+                a.chunkOrdinal - b.chunkOrdinal);
         for (let idx = 0; idx < sorted.length; idx++) {
             const hit = sorted[idx];
             const key = `${hit.docPath}\x00${hit.chunkOrdinal}`;