@equationalapplications/core-llm-wiki 4.2.0 → 4.4.0

package/dist/index.js

@@ -209,6 +209,40 @@ function parseEmbedding(blob, text) {
   return null;
 }
 
+// src/readOptions.ts
+function normalizeEntityIds(entityId) {
+  const input = Array.isArray(entityId) ? entityId : [entityId];
+  const seen = /* @__PURE__ */ new Set();
+  const normalized = [];
+  for (const id of input) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    normalized.push(id);
+  }
+  return normalized;
+}
+function sanitizeTierWeights(entityIds, tierWeights) {
+  if (tierWeights === void 0) return void 0;
+  const sanitized = /* @__PURE__ */ Object.create(null);
+  for (const entityId of entityIds) {
+    const raw = tierWeights[entityId];
+    if (raw === void 0 || !Number.isFinite(raw)) {
+      sanitized[entityId] = 1;
+    } else {
+      sanitized[entityId] = Math.max(0, raw);
+    }
+  }
+  return sanitized;
+}
+function applyTierWeight(score, entityId, sanitizedTierWeights) {
+  const weight = sanitizedTierWeights?.[entityId] ?? 1;
+  if (weight === 0) return -Infinity;
+  return score * weight;
+}
+function shouldExposeReadMetadata(entityId) {
+  return Array.isArray(entityId);
+}
+
 // src/WikiMemory.ts
 var HOOK_TIMEOUT_MARKER = /* @__PURE__ */ Symbol("WikiMemoryHookTimeout");
 function parseJsonResponse(text) {
@@ -974,6 +1008,25 @@ After running the migration SQL, restart your application.`
   }
   async read(entityId, query, options) {
     const config = this.options.config;
+    const entityIds = normalizeEntityIds(entityId);
+    const sanitizedTierWeights = sanitizeTierWeights(entityIds, options?.tierWeights);
+    const exposeMetadata = shouldExposeReadMetadata(entityId);
+    if (entityIds.length === 0) {
+      const empty = { facts: [], tasks: [], events: [] };
+      if (exposeMetadata) {
+        empty.metadata = { query, entityIds: [] };
+        if (sanitizedTierWeights && Object.keys(sanitizedTierWeights).length > 0) empty.metadata.tierWeights = sanitizedTierWeights;
+      }
+      return empty;
+    }
+    const MAX_ENTITY_IDS = 100;
+    if (entityIds.length > MAX_ENTITY_IDS) {
+      throw new RangeError(`read() accepts at most ${MAX_ENTITY_IDS} entity IDs; received ${entityIds.length}`);
+    }
+    const nullByteId = entityIds.find((id) => id.includes("\0"));
+    if (nullByteId !== void 0) {
+      throw new TypeError(`entity_id values must not contain the null byte (\\x00); got "${nullByteId}"`);
+    }
     const rawMaxResults = options?.maxResults ?? config?.maxResults ?? config?.maxFtsResults ?? 10;
     const maxResults = Number.isFinite(rawMaxResults) ? Math.max(0, Math.trunc(rawMaxResults)) : 10;
     const rawPreFilterLimit = options?.preFilterLimit === null ? void 0 : options?.preFilterLimit ?? config?.preFilterLimit;
@@ -984,13 +1037,15 @@ After running the migration SQL, restart your application.`
     const embedFn = this.options.llmProvider.embed;
     const trimmedQuery = query.trim();
     let facts = [];
+    let scoreByFactId;
     if (maxResults === 0) ; else if (trimmedQuery) {
       let usedEmbed = false;
-      if (!skipEmbed && embedFn) {
+      const scoredEntityIds = this._filterScoredEntities(entityIds, sanitizedTierWeights, options?.includeZeroWeightEntities);
+      if (scoredEntityIds.length === 0) {
+        usedEmbed = true;
+      } else if (!skipEmbed && embedFn) {
         let rankerShouldRethrow = false;
         let pendingRankerFallbackError;
-        let usedKeywordFallback = false;
-        let scoredAlreadySortedAndLimited = false;
         try {
           const queryVec = await embedFn(trimmedQuery);
           if (queryVec.length === 0 || !queryVec.every((v) => typeof v === "number" && isFinite(v))) {
@@ -1009,13 +1064,14 @@ After running the migration SQL, restart your application.`
               );
             }
           }
+          const mismatchScope = this._entityInClause(entityIds);
           const mismatchedCount = await this.db.getFirstAsync(
             `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
-             WHERE entity_id = ? AND deleted_at IS NULL
+             WHERE ${mismatchScope.clause} AND deleted_at IS NULL
                AND embedding_blob IS NOT NULL
                AND (CAST(length(embedding_blob) AS INTEGER) % 4 = 0)
                AND (CAST(length(embedding_blob) AS INTEGER) / 4) != ?`,
-            [entityId, queryVec.length]
+            [...mismatchScope.params, queryVec.length]
           );
           if (mismatchedCount && mismatchedCount.cnt > 0) {
             throw new Error(
@@ -1024,12 +1080,13 @@ After running the migration SQL, restart your application.`
           }
           const useRanker = Boolean(this.options.vectorRanker);
           let candidateRows;
-          let populateCache = true;
+          let populateCache = entityIds.length === 1;
           let miniSearchScores;
           if (effectivePreFilterLimit !== void 0) {
             populateCache = false;
+            const entityIdSet = new Set(scoredEntityIds);
             const preResults = this.miniSearch.search(trimmedQuery, {
-              filter: (r) => r.entity_id === entityId,
+              filter: (r) => entityIdSet.has(r.entity_id),
               combineWith: "OR"
             });
             if (preResults.length === 0) {
@@ -1047,7 +1104,7 @@ After running the migration SQL, restart your application.`
                     const idChunk = topKIds.slice(i, i + inClauseChunkSize);
                     const placeholders = idChunk.map(() => "?").join(",");
                     const chunkRows = await this.db.getAllAsync(
-                      `SELECT id, updated_at, access_count FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
+                      `SELECT id, entity_id, updated_at, access_count FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
                       idChunk
                     );
                     rows.push(...chunkRows);
@@ -1059,7 +1116,7 @@ After running the migration SQL, restart your application.`
                     const idChunk = topKIds.slice(i, i + inClauseChunkSize);
                     const placeholders = idChunk.map(() => "?").join(",");
                     const chunkRows = await this.db.getAllAsync(
-                      `SELECT id, embedding_blob, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
+                      `SELECT id, entity_id, embedding_blob, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
                       idChunk
                     );
                     rows.push(...chunkRows);
@@ -1074,19 +1131,22 @@ After running the migration SQL, restart your application.`
             }
           } else {
             if (useRanker) {
+              const entityScope = this._entityInClause(scoredEntityIds);
               candidateRows = await this.db.getAllAsync(
-                `SELECT id, updated_at, access_count FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
-                [entityId]
+                `SELECT id, entity_id, updated_at, access_count FROM ${this.prefix}entries WHERE ${entityScope.clause} AND deleted_at IS NULL`,
+                entityScope.params
               );
             } else {
+              const entityScope = this._entityInClause(scoredEntityIds);
               candidateRows = await this.db.getAllAsync(
-                `SELECT id, embedding_blob, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
-                [entityId]
+                `SELECT id, entity_id, embedding_blob, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE ${entityScope.clause} AND deleted_at IS NULL`,
+                entityScope.params
               );
             }
             if (weight !== void 0 && weight < 1) {
+              const entityIdSet = new Set(scoredEntityIds);
               const msResults = this.miniSearch.search(trimmedQuery, {
-                filter: (r) => r.entity_id === entityId,
+                filter: (r) => entityIdSet.has(r.entity_id),
                 combineWith: "OR"
               });
               const maxMsScore = Math.max(1, msResults[0]?.score ?? 1);
@@ -1096,33 +1156,45 @@ After running the migration SQL, restart your application.`
           if (candidateRows === null) {
             usedEmbed = true;
           } else {
+            const entityCacheKey = entityIds.length === 1 ? entityIds[0] : entityIds.join("\0");
             let scored;
             if (useRanker) {
-              const candidateIds = effectivePreFilterLimit !== void 0 ? candidateRows.map((r) => r.id) : void 0;
+              const candidateRowsByEntity = /* @__PURE__ */ new Map();
+              for (const row of candidateRows) {
+                const rows = candidateRowsByEntity.get(row.entity_id) ?? [];
+                rows.push(row);
+                candidateRowsByEntity.set(row.entity_id, rows);
+              }
               try {
-                const oversampledLimit = Math.max(maxResults * 2, maxResults + 50);
-                scored = await this._rankWithVectorRanker({
-                  entityId,
-                  queryVec,
-                  candidateIds,
-                  weight,
-                  miniSearchScores,
-                  limit: oversampledLimit
-                });
-                if (scored.length > 0) {
-                  const scoredIds2 = new Set(scored.map((s) => s.id));
-                  const metaMap = /* @__PURE__ */ new Map();
-                  for (const r of candidateRows) {
-                    if (scoredIds2.has(r.id)) {
-                      metaMap.set(r.id, { updated_at: r.updated_at, access_count: r.access_count });
-                    }
-                  }
-                  scored = scored.map((s) => {
-                    const meta = metaMap.get(s.id);
-                    return { ...s, updated_at: meta?.updated_at ?? null, access_count: meta?.access_count ?? null };
-                  });
-                }
+                const rankerResultsByEntity = await Promise.all(
+                  scoredEntityIds.filter((id) => (candidateRowsByEntity.get(id)?.length ?? 0) > 0).map(async (scopedEntityId) => {
+                    const rowsForEntity = candidateRowsByEntity.get(scopedEntityId) ?? [];
+                    const candidateIds = effectivePreFilterLimit !== void 0 ? rowsForEntity.map((row) => row.id) : void 0;
+                    const ranked = await this._rankWithVectorRanker({
+                      entityId: scopedEntityId,
+                      queryVec,
+                      candidateIds,
+                      candidateRows: rowsForEntity,
+                      weight,
+                      miniSearchScores,
+                      limit: Math.max(maxResults * 2, maxResults + 50)
+                    });
+                    return ranked.map((row) => ({ ...row, entity_id: scopedEntityId }));
+                  })
+                );
+                scored = rankerResultsByEntity.flat();
                 const scoredIds = new Set(scored.map((s) => s.id));
+                const metadataById = new Map(
+                  candidateRows.filter((row) => scoredIds.has(row.id)).map((row) => [row.id, row])
+                );
+                scored = scored.map((row) => {
+                  const metadata = metadataById.get(row.id);
+                  return {
+                    ...row,
+                    updated_at: metadata?.updated_at ?? null,
+                    access_count: metadata?.access_count ?? null
+                  };
+                });
                 const isHybrid = weight !== void 0 && weight < 1;
                 const maxBackfill = isHybrid ? maxResults : Math.max(0, maxResults - scored.length);
                 if (maxBackfill > 0) {
@@ -1200,6 +1272,7 @@ After running the migration SQL, restart your application.`
                     for (const { row, kwScore } of topK) {
                       scored.push({
                         id: row.id,
+                        entity_id: row.entity_id,
                         score: (1 - weight) * kwScore,
                         updated_at: row.updated_at,
                         access_count: row.access_count
@@ -1209,7 +1282,7 @@ After running the migration SQL, restart your application.`
                     const omitted = [];
                     for (const row of candidateRows) {
                       if (scoredIds.has(row.id)) continue;
-                      omitted.push({ id: row.id, score: -2, updated_at: row.updated_at, access_count: row.access_count });
+                      omitted.push({ id: row.id, entity_id: row.entity_id, score: -2, updated_at: row.updated_at, access_count: row.access_count });
                     }
                     if (omitted.length > 0) {
                       this._tieBreakSort(omitted);
@@ -1237,8 +1310,8 @@ After running the migration SQL, restart your application.`
                       const idChunk = rowIds.slice(i, i + chunkSize);
                       const placeholders = idChunk.map(() => "?").join(",");
                       const embeddingRows = await this.db.getAllAsync(
-                        `SELECT id, embedding_blob, embedding FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND entity_id = ? AND deleted_at IS NULL`,
-                        [...idChunk, entityId]
+                        `SELECT id, embedding_blob, embedding FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
+                        idChunk
                       );
                       for (const row of embeddingRows) {
                         embeddingsMap.set(row.id, { embedding_blob: row.embedding_blob, embedding: row.embedding });
@@ -1251,38 +1324,37 @@ After running the migration SQL, restart your application.`
                     }));
                   }
                   scored = await this._rankWithJsCosine({
-                    entityId,
+                    entityId: entityCacheKey,
                     queryVec,
                     candidateRows: fallbackRows,
                     weight,
                     miniSearchScores,
                     populateCache,
-                    limit: maxResults
+                    limit: fallbackRows.length,
+                    skipSort: true
+                    // read() re-sorts after applying tier weights
                   });
-                  scoredAlreadySortedAndLimited = true;
                 } else if (policy === "keyword") {
+                  const scoredEntityIdSet = new Set(scoredEntityIds);
                   const msResults = this.miniSearch.search(trimmedQuery, {
-                    filter: (r) => r.entity_id === entityId,
+                    filter: (r) => scoredEntityIdSet.has(r.entity_id),
                     combineWith: "OR"
                   });
-                  const topResults = msResults.slice(0, maxResults);
-                  const resultIds = new Set(topResults.map((r) => r.id));
-                  const candidateMap = /* @__PURE__ */ new Map();
-                  for (const r of candidateRows) {
-                    if (resultIds.has(r.id)) {
-                      candidateMap.set(r.id, { updated_at: r.updated_at, access_count: r.access_count });
-                    }
-                  }
-                  scored = topResults.map((r) => {
-                    const meta = candidateMap.get(r.id);
+                  const keywordOversampledLimit = Math.max(maxResults * 2, maxResults + 50);
+                  const topResults = msResults.slice(0, keywordOversampledLimit);
+                  const topResultIds = new Set(topResults.map((r) => r.id));
+                  const candidateMap = new Map(candidateRows.filter((r) => topResultIds.has(r.id)).map((row) => [row.id, row]));
+                  scored = topResults.map((result) => {
+                    const metadata = candidateMap.get(result.id);
+                    const entityForScore = metadata?.entity_id ?? result.entity_id ?? "";
                     return {
-                      id: r.id,
-                      score: r.score ?? 0,
-                      access_count: meta?.access_count ?? null,
-                      updated_at: meta?.updated_at ?? null
+                      id: result.id,
+                      entity_id: entityForScore,
+                      score: result.score ?? 0,
+                      access_count: metadata?.access_count ?? null,
+                      updated_at: metadata?.updated_at ?? null
                     };
                   });
-                  usedKeywordFallback = true;
                 } else {
                   scored = [];
                 }
@@ -1294,46 +1366,44 @@ After running the migration SQL, restart your application.`
                 }
               }
             } else {
+              const jsCosineNeedsTierSort = sanitizedTierWeights !== void 0 && Object.values(sanitizedTierWeights).some((w) => w !== 1);
               scored = await this._rankWithJsCosine({
-                entityId,
+                entityId: entityCacheKey,
                 queryVec,
                 candidateRows,
                 weight,
                 miniSearchScores,
                 populateCache,
-                limit: maxResults
+                limit: jsCosineNeedsTierSort ? candidateRows.length : maxResults,
+                skipSort: jsCosineNeedsTierSort
+                // read() re-sorts after applying tier weights
               });
-              scoredAlreadySortedAndLimited = true;
             }
             if (scored.length > 0) {
-              if (!usedKeywordFallback && !scoredAlreadySortedAndLimited) {
-                this._tieBreakSort(scored);
+              scored = scored.map((row) => ({
+                ...row,
+                score: applyTierWeight(row.score, row.entity_id, sanitizedTierWeights)
+              }));
+              this._tieBreakSort(scored);
+              const selectedScored = scored.slice(0, maxResults);
+              const topIds = selectedScored.map((s) => s.id);
+              if (exposeMetadata && trimmedQuery) {
+                scoreByFactId = new Map(selectedScored.map((s) => [s.id, Number.isFinite(s.score) ? s.score : 0]));
               }
-              const topIds = (scoredAlreadySortedAndLimited ? scored : scored.slice(0, maxResults)).map((s) => s.id);
               if (topIds.length > 0) {
-                const fullRows = [];
-                const phase2ChunkSize = 500;
-                for (let i = 0; i < topIds.length; i += phase2ChunkSize) {
-                  const idChunk = topIds.slice(i, i + phase2ChunkSize);
-                  const placeholders = idChunk.map(() => "?").join(",");
-                  const chunkRows = await this.db.getAllAsync(
-                    `SELECT * FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND entity_id = ? AND deleted_at IS NULL`,
-                    [...idChunk, entityId]
-                  );
-                  fullRows.push(...chunkRows);
-                }
-                const byId = new Map(fullRows.map((r) => [r.id, r]));
-                facts = topIds.map((id) => byId.get(id)).filter((f) => f !== void 0);
-                if (facts.length < topIds.length) {
-                  const missingIds = topIds.filter((id) => !byId.has(id));
+                const facts2 = await this._hydrateFactsByIds(topIds, entityIds);
+                if (facts2.length < topIds.length) {
+                  const hydrationById = new Set(facts2.map((f) => f.id));
+                  const missingIds = topIds.filter((id) => !hydrationById.has(id));
                   const missingCount = missingIds.length;
                   const sample = missingIds.slice(0, 5);
                   const sampleSuffix = sample.length > 0 ? ` Missing ID sample: ${sample.join(", ")}${missingIds.length > sample.length ? ", ..." : ""}.` : "";
                   const error = new Error(
-                    `Phase 2 fact hydration returned ${missingCount} fewer row(s) than ranked IDs for entity ${entityId}. Rows may have been concurrently soft-deleted or filtered by deleted_at during hydration, or vector ranker output may include IDs that do not exist for this entity.` + sampleSuffix
+                    `Phase 2 fact hydration returned ${missingCount} fewer row(s) than ranked IDs. Rows may have been concurrently soft-deleted or filtered by deleted_at during hydration, or vector ranker output may include IDs that do not exist in requested entities.` + sampleSuffix
                   );
                   this.options.onRetrievalFallback?.(error);
                 }
+                facts = facts2;
               }
               if (pendingRankerFallbackError) {
                 this.options.onRetrievalFallback?.(pendingRankerFallbackError);
@@ -1360,26 +1430,28 @@ After running the migration SQL, restart your application.`
           this.options.onRetrievalFallback?.(error);
         }
       }
-      if (!usedEmbed) {
+      if (!usedEmbed && scoredEntityIds.length > 0) {
+        const fallbackEntityIdSet = new Set(scoredEntityIds);
+        const fallbackOversampledLimit = Math.max(maxResults * 2, maxResults + 50);
         const results = this.miniSearch.search(trimmedQuery, {
-          filter: (r) => r.entity_id === entityId,
+          filter: (r) => fallbackEntityIdSet.has(r.entity_id),
           combineWith: "OR"
         });
-        const topIds = results.slice(0, maxResults).map((r) => r.id);
+        const candidates = results.slice(0, fallbackOversampledLimit).map((r) => ({
+          id: r.id,
+          entity_id: r.entity_id,
+          score: applyTierWeight(r.score ?? 0, r.entity_id, sanitizedTierWeights),
+          updated_at: null,
+          access_count: null
+        }));
+        this._tieBreakSort(candidates);
+        const topCandidates = candidates.slice(0, maxResults);
+        const topIds = topCandidates.map((c) => c.id);
         if (topIds.length > 0) {
-          const kwRows = [];
-          const kwChunkSize = 500;
-          for (let i = 0; i < topIds.length; i += kwChunkSize) {
-            const idChunk = topIds.slice(i, i + kwChunkSize);
-            const placeholders = idChunk.map(() => "?").join(",");
-            const chunkRows = await this.db.getAllAsync(
-              `SELECT * FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND entity_id = ? AND deleted_at IS NULL`,
-              [...idChunk, entityId]
-            );
-            kwRows.push(...chunkRows);
+          facts = await this._hydrateFactsByIds(topIds, entityIds);
+          if (exposeMetadata) {
+            scoreByFactId = new Map(topCandidates.map((c) => [c.id, Number.isFinite(c.score) ? c.score : 0]));
           }
-          const byId = new Map(kwRows.map((r) => [r.id, r]));
-          facts = topIds.map((id) => byId.get(id)).filter((f) => f !== void 0);
         }
       }
       if (facts.length > 0) {
@@ -1398,37 +1470,66 @@ After running the migration SQL, restart your application.`
         }
       }
     } else {
-      facts = await this.db.getAllAsync(
+      const entityScope = this._entityInClause(entityIds);
+      const rawFacts = await this.db.getAllAsync(
         `SELECT * FROM ${this.prefix}entries
-         WHERE entity_id = ? AND deleted_at IS NULL
+         WHERE ${entityScope.clause} AND deleted_at IS NULL
          ORDER BY updated_at DESC
          LIMIT ?`,
-        [entityId, maxResults]
+        [...entityScope.params, maxResults]
       );
+      facts = rawFacts.map((f) => {
+        const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
+        return {
+          ...rest,
+          tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
+        };
+      });
     }
     const [tasks, events] = await Promise.all([
-      this.db.getAllAsync(
-        `SELECT * FROM ${this.prefix}tasks
-         WHERE entity_id = ? AND status IN ('pending', 'in_progress') AND deleted_at IS NULL
-         ORDER BY priority DESC, created_at ASC`,
-        [entityId]
-      ),
-      this.db.getAllAsync(
-        `SELECT * FROM ${this.prefix}events
-         WHERE entity_id = ?
-         ORDER BY created_at DESC
-         LIMIT 10`,
-        [entityId]
-      )
+      (async () => {
+        const entityScope = this._entityInClause(entityIds);
+        const tasksLimit = entityIds.length === 1 ? void 0 : Math.min(20 * entityIds.length, 200);
+        return this.db.getAllAsync(
+          `SELECT * FROM ${this.prefix}tasks
+           WHERE ${entityScope.clause} AND status IN ('pending', 'in_progress') AND deleted_at IS NULL
+           ORDER BY priority DESC, created_at ASC${tasksLimit !== void 0 ? "\n           LIMIT ?" : ""}`,
+          tasksLimit !== void 0 ? [...entityScope.params, tasksLimit] : entityScope.params
+        );
+      })(),
+      (async () => {
+        const entityScope = this._entityInClause(entityIds);
+        const eventsLimit = Math.min(10 * entityIds.length, 100);
+        return this.db.getAllAsync(
+          `SELECT * FROM ${this.prefix}events
+           WHERE ${entityScope.clause}
+           ORDER BY created_at DESC
+           LIMIT ?`,
+          [...entityScope.params, eventsLimit]
+        );
+      })()
     ]);
-    const parsedFacts = facts.map((f) => {
-      const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
-      return {
-        ...rest,
-        tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
-      };
+    let factScores;
+    if (exposeMetadata && trimmedQuery && scoreByFactId) {
+      factScores = Object.fromEntries(facts.map((fact) => [fact.id, scoreByFactId.get(fact.id) ?? 0]));
+    }
+    const bundle = { facts, tasks, events: events.reverse() };
+    if (exposeMetadata) {
+      bundle.metadata = { query, entityIds };
+      if (sanitizedTierWeights && Object.keys(sanitizedTierWeights).length > 0) bundle.metadata.tierWeights = sanitizedTierWeights;
+      if (factScores && Object.keys(factScores).length > 0) bundle.factScores = factScores;
+    }
+    return bundle;
+  }
+  /**
+   * Returns entity IDs that will participate in scored retrieval.
+   * Excludes zero-weight entities unless includeZeroWeightEntities is true.
+   */
+  _filterScoredEntities(entityIds, sanitizedTierWeights, includeZeroWeightEntities) {
+    return entityIds.filter((id) => {
+      const w = sanitizedTierWeights?.[id] ?? 1;
+      return includeZeroWeightEntities === true || w !== 0;
     });
-    return { facts: parsedFacts, tasks, events: events.reverse() };
   }
   /**
    * Stable tie-break sort: score desc → access_count desc → updated_at desc → id asc.
@@ -1442,13 +1543,48 @@ After running the migration SQL, restart your application.`
    */
   _compareScoredRows(a, b) {
     const scoreDiff = b.score - a.score;
-    if (scoreDiff !== 0) return scoreDiff;
+    if (!Number.isNaN(scoreDiff) && scoreDiff !== 0) return scoreDiff;
     const accessCountDiff = (b.access_count ?? 0) - (a.access_count ?? 0);
     if (accessCountDiff !== 0) return accessCountDiff;
     const updatedAtDiff = (b.updated_at ?? 0) - (a.updated_at ?? 0);
     if (updatedAtDiff !== 0) return updatedAtDiff;
     return a.id.localeCompare(b.id);
   }
+  /**
+   * Build SQL IN clause with placeholders for multiple entity IDs.
+   */
+  _entityInClause(entityIds) {
+    if (entityIds.length === 0) return { clause: "1=0", params: [] };
+    const placeholders = entityIds.map(() => "?").join(",");
+    return { clause: `entity_id IN (${placeholders})`, params: [...entityIds] };
+  }
+  /**
+   * Hydrate full facts by ID. Pass scopedEntityIds to restrict to requested namespaces in SQL
+   * (defense-in-depth against a rogue VectorRanker returning cross-entity IDs).
+   */
+  async _hydrateFactsByIds(ids, scopedEntityIds) {
+    const fullRows = [];
+    const chunkSize = 500;
+    const entityClause = scopedEntityIds && scopedEntityIds.length > 0 ? ` AND entity_id IN (${scopedEntityIds.map(() => "?").join(",")})` : "";
+    const entityParams = scopedEntityIds && scopedEntityIds.length > 0 ? [...scopedEntityIds] : [];
+    for (let i = 0; i < ids.length; i += chunkSize) {
+      const idChunk = ids.slice(i, i + chunkSize);
+      const placeholders = idChunk.map(() => "?").join(",");
+      const chunkRows = await this.db.getAllAsync(
+        `SELECT * FROM ${this.prefix}entries WHERE id IN (${placeholders})${entityClause} AND deleted_at IS NULL`,
+        [...idChunk, ...entityParams]
+      );
+      fullRows.push(...chunkRows);
+    }
+    const byId = new Map(fullRows.map((row) => [row.id, row]));
+    return ids.map((id) => byId.get(id)).filter((fact) => fact !== void 0).map((fact) => {
+      const { embedding: _embedding, embedding_blob: _blob, ...rest } = fact;
+      return {
+        ...rest,
+        tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
+      };
+    });
+  }
   /**
    * Strip potentially sensitive data from ranker errors before exposing to host callbacks.
    * Preserves error type for debugging but removes message/stack that may contain credentials.
@@ -1473,7 +1609,7 @@ After running the migration SQL, restart your application.`
    */
   async _rankWithJsCosine(args) {
     const queryVec = args.queryVec instanceof Float32Array ? args.queryVec.slice() : Array.from(args.queryVec);
-    const { entityId, candidateRows, weight, miniSearchScores, populateCache, limit } = args;
+    const { entityId, candidateRows, weight, miniSearchScores, populateCache, limit, skipSort } = args;
     let entityCache = this.vectorCache.get(entityId);
     const tooLarge = populateCache && candidateRows.length > _WikiMemory.MAX_VECTOR_CACHE_FACTS_PER_ENTITY;
     if (tooLarge && entityCache) {
@@ -1504,7 +1640,13 @@ After running the migration SQL, restart your application.`
       } else {
         score = -2;
       }
-      return { id: row.id, score, updated_at: row.updated_at, access_count: row.access_count };
+      return {
+        id: row.id,
+        entity_id: row.entity_id,
+        score,
+        updated_at: row.updated_at,
+        access_count: row.access_count
+      };
     });
     if (canCache && entityCache && entityCache.size > 0) {
       if (!this.vectorCache.has(entityId)) {
@@ -1515,7 +1657,7 @@ After running the migration SQL, restart your application.`
         this.vectorCache.set(entityId, entityCache);
       }
     }
-    this._tieBreakSort(scored);
+    if (!skipSort) this._tieBreakSort(scored);
     return scored.slice(0, limit);
   }
   /**
@@ -1524,7 +1666,7 @@ After running the migration SQL, restart your application.`
    * Returns scored results ready for hybrid blending and tie-break sorting.
    */
   async _rankWithVectorRanker(args) {
-    const { entityId, candidateIds, weight, miniSearchScores, limit } = args;
+    const { entityId, candidateIds, candidateRows, weight, miniSearchScores, limit } = args;
     const ranker = this.options.vectorRanker;
     if (!ranker) {
       throw new Error("vectorRanker not configured");
@@ -1536,7 +1678,7 @@ After running the migration SQL, restart your application.`
       candidateIds,
       limit
     });
-    const allowedIds = candidateIds ? new Set(candidateIds) : void 0;
+    const allowedIds = new Set(candidateRows.map((row) => row.id));
     const seen = /* @__PURE__ */ new Set();
     const normalized = [];
     for (const r of rankerResults) {
@@ -1547,13 +1689,19 @@ After running the migration SQL, restart your application.`
       seen.add(r.id);
       normalized.push(r);
     }
+    const entityIdByCandidateId = new Map(candidateRows.map((row) => [row.id, row.entity_id]));
     const scored = normalized.map((r) => {
       let score = r.semanticScore;
       if (weight !== void 0) {
         const kwScore = miniSearchScores?.get(r.id) ?? 0;
         score = weight * Math.max(0, r.semanticScore) + (1 - weight) * kwScore;
       }
-      return { id: r.id, score };
+      return {
+        id: r.id,
+        entity_id: entityIdByCandidateId.get(r.id),
+        // allowedIds filter above guarantees membership
+        score
+      };
     });
     return scored;
   }