@equationalapplications/core-llm-wiki 4.2.0 → 4.4.0

package/dist/index.d.mts

@@ -53,16 +53,17 @@ interface ReadOptions {
     preFilterLimit?: number | null;
     hybridWeight?: number;
     /**
-     * (Reserved for Phase 2+ multi-entity weighted retrieval)
-     * entity_id -> score multiplier. Missing entries default to 1.0.
-     * Currently ignored by WikiMemory.read(); planned for implementation in Phase 2.
+     * Per-entity score multiplier for multi-entity reads. Missing entries default to 1.0.
+     * Entities with weight 0 are skipped during scored retrieval unless
+     * `includeZeroWeightEntities` is true; in that case they rank below all finite scores.
+     * Only meaningful when `entityId` is an array; ignored for single-string calls.
      */
     tierWeights?: Record<string, number>;
     /**
-     * (Reserved for Phase 2+ multi-entity weighted retrieval)
-     * false/default -> skip zero-weight entities during scored retrieval.
-     * true -> retrieve zero-weight entities and let them fill only if the pool is small.
-     * Currently ignored by WikiMemory.read(); planned for implementation in Phase 2.
+     * When true, entities with a tier weight of 0 are included in scored retrieval
+     * as bottom fillers (ranked below every finite-scored candidate).
+     * When false (default), zero-weight entities are skipped entirely.
+     * Only meaningful when `entityId` is an array; ignored for single-string calls.
      */
     includeZeroWeightEntities?: boolean;
 }
@@ -424,7 +425,12 @@ declare class WikiMemory {
         tasks: number;
         events: number;
     }>;
-    read(entityId: string, query: string, options?: ReadOptions): Promise<MemoryBundle>;
+    read(entityId: string | string[], query: string, options?: ReadOptions): Promise<MemoryBundle>;
+    /**
+     * Returns entity IDs that will participate in scored retrieval.
+     * Excludes zero-weight entities unless includeZeroWeightEntities is true.
+     */
+    private _filterScoredEntities;
     /**
      * Stable tie-break sort: score desc → access_count desc → updated_at desc → id asc.
      */
@@ -434,6 +440,15 @@ declare class WikiMemory {
      * Negative return means "a ranks ahead of b" for descending score order.
      */
     private _compareScoredRows;
+    /**
+     * Build SQL IN clause with placeholders for multiple entity IDs.
+     */
+    private _entityInClause;
+    /**
+     * 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).
+     */
+    private _hydrateFactsByIds;
     /**
      * 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.

package/dist/index.d.ts

@@ -53,16 +53,17 @@ interface ReadOptions {
     preFilterLimit?: number | null;
     hybridWeight?: number;
     /**
-     * (Reserved for Phase 2+ multi-entity weighted retrieval)
-     * entity_id -> score multiplier. Missing entries default to 1.0.
-     * Currently ignored by WikiMemory.read(); planned for implementation in Phase 2.
+     * Per-entity score multiplier for multi-entity reads. Missing entries default to 1.0.
+     * Entities with weight 0 are skipped during scored retrieval unless
+     * `includeZeroWeightEntities` is true; in that case they rank below all finite scores.
+     * Only meaningful when `entityId` is an array; ignored for single-string calls.
      */
     tierWeights?: Record<string, number>;
     /**
-     * (Reserved for Phase 2+ multi-entity weighted retrieval)
-     * false/default -> skip zero-weight entities during scored retrieval.
-     * true -> retrieve zero-weight entities and let them fill only if the pool is small.
-     * Currently ignored by WikiMemory.read(); planned for implementation in Phase 2.
+     * When true, entities with a tier weight of 0 are included in scored retrieval
+     * as bottom fillers (ranked below every finite-scored candidate).
+     * When false (default), zero-weight entities are skipped entirely.
+     * Only meaningful when `entityId` is an array; ignored for single-string calls.
      */
     includeZeroWeightEntities?: boolean;
 }
@@ -424,7 +425,12 @@ declare class WikiMemory {
         tasks: number;
         events: number;
     }>;
-    read(entityId: string, query: string, options?: ReadOptions): Promise<MemoryBundle>;
+    read(entityId: string | string[], query: string, options?: ReadOptions): Promise<MemoryBundle>;
+    /**
+     * Returns entity IDs that will participate in scored retrieval.
+     * Excludes zero-weight entities unless includeZeroWeightEntities is true.
+     */
+    private _filterScoredEntities;
     /**
      * Stable tie-break sort: score desc → access_count desc → updated_at desc → id asc.
      */
@@ -434,6 +440,15 @@ declare class WikiMemory {
      * Negative return means "a ranks ahead of b" for descending score order.
      */
     private _compareScoredRows;
+    /**
+     * Build SQL IN clause with placeholders for multiple entity IDs.
+     */
+    private _entityInClause;
+    /**
+     * 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).
+     */
+    private _hydrateFactsByIds;
     /**
      * 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.