@equationalapplications/core-llm-wiki 4.1.0 → 4.3.0

package/dist/index.d.mts

@@ -52,6 +52,20 @@ interface ReadOptions {
      */
     preFilterLimit?: number | null;
     hybridWeight?: number;
+    /**
+     * 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>;
+    /**
+     * 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;
 }
 interface WikiFact {
     id: string;
@@ -274,6 +288,12 @@ interface MemoryBundle {
     facts: WikiFact[];
     tasks: WikiTask[];
     events: WikiEvent[];
+    factScores?: Record<string, number>;
+    metadata?: {
+        query: string;
+        entityIds: string[];
+        tierWeights?: Record<string, number>;
+    };
 }
 interface MemoryDump {
     generatedAt: number;
@@ -405,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.
      */
@@ -415,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

@@ -52,6 +52,20 @@ interface ReadOptions {
      */
     preFilterLimit?: number | null;
     hybridWeight?: number;
+    /**
+     * 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>;
+    /**
+     * 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;
 }
 interface WikiFact {
     id: string;
@@ -274,6 +288,12 @@ interface MemoryBundle {
     facts: WikiFact[];
     tasks: WikiTask[];
     events: WikiEvent[];
+    factScores?: Record<string, number>;
+    metadata?: {
+        query: string;
+        entityIds: string[];
+        tierWeights?: Record<string, number>;
+    };
 }
 interface MemoryDump {
     generatedAt: number;
@@ -405,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.
      */
@@ -415,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.