@equationalapplications/core-llm-wiki 4.0.0 → 4.2.0

package/README.md

@@ -302,6 +302,41 @@ wikiMemory.clearVectorCache();
 
 The cache is also automatically invalidated on any mutation (`runLibrarian`, `runHeal`, `runPrune`, `runReembed`, `ingestDocument`, `importDump`, `forget`).
 
+## Entity Status
+
+`WikiMemory` exposes the in-flight job state for a single entity through two complementary APIs.
+
+### `getEntityStatus(entityId)`
+
+Synchronous point-in-time snapshot:
+
+```typescript
+const status = wikiMemory.getEntityStatus('user-42');
+// { ingesting: boolean, librarian: boolean, heal: boolean }
+```
+
+Use this when you only need the current value (e.g. inside a request handler).
+
+### `subscribeEntityStatus(entityId, callback)`
+
+Push-based change notification — the callback fires synchronously once with the current status, then again on every transition where any of the three booleans flips. There is no polling and no duplicate snapshots.
+
+```typescript
+const unsubscribe = wikiMemory.subscribeEntityStatus('user-42', (status) => {
+  console.log(status); // { ingesting, librarian, heal }
+});
+
+// Later:
+unsubscribe(); // idempotent — safe to call more than once
+```
+
+Notes:
+
+- The first invocation happens **before** `subscribeEntityStatus` returns. Treat it as the initial render value.
+- Each emission may be a fresh object literal. Do not rely on referential equality between callbacks; equality of the three booleans is the contract.
+- A throwing callback is caught (logged via `console.error`) and does not block other subscribers or the underlying job.
+- Subscriptions are scoped to a single `entityId`. There is no wildcard or "all entities" form.
+
 ## Security
 
 `@equationalapplications/core-llm-wiki` enforces multiple security layers:

package/dist/index.d.mts

@@ -52,6 +52,19 @@ 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.
+     */
+    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.
+     */
+    includeZeroWeightEntities?: boolean;
 }
 interface WikiFact {
     id: string;
@@ -274,6 +287,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;
@@ -337,6 +356,7 @@ declare class WikiMemory {
     private options;
     private activeMaintenanceJobs;
     private activeIngestJobs;
+    private statusSubscribers;
     private miniSearch;
     private miniSearchEntryIdsByEntity;
     /**
@@ -392,6 +412,8 @@ declare class WikiMemory {
     private _isAnyMaintenanceActiveWithSuffix;
     /** Returns true if any ingest job is active for the given entity. */
     private _isIngestActiveFor;
+    private _copyEntityStatus;
+    private _notifyStatusSubscribers;
     private _validatePruneDuration;
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
@@ -445,6 +467,17 @@ declare class WikiMemory {
         failed: number;
     }>;
     getEntityStatus(entityId: string): EntityStatus;
+    /**
+     * Subscribe to {@link EntityStatus} changes for a single entity. The callback
+     * is invoked synchronously once with the current status before this method
+     * returns, then again on every transition where any of `ingesting`,
+     * `librarian`, or `heal` flips. No polling, no duplicate snapshots.
+     *
+     * Returns an idempotent unsubscribe function.
+     *
+     * See also {@link getEntityStatus} for a synchronous point-in-time read.
+     */
+    subscribeEntityStatus(entityId: string, callback: (status: EntityStatus) => void): () => void;
     clearVectorCache(): void;
     private _getFullBundle;
     exportDump(entityIds?: string[]): Promise<MemoryDump>;

package/dist/index.d.ts

@@ -52,6 +52,19 @@ 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.
+     */
+    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.
+     */
+    includeZeroWeightEntities?: boolean;
 }
 interface WikiFact {
     id: string;
@@ -274,6 +287,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;
@@ -337,6 +356,7 @@ declare class WikiMemory {
     private options;
     private activeMaintenanceJobs;
     private activeIngestJobs;
+    private statusSubscribers;
     private miniSearch;
     private miniSearchEntryIdsByEntity;
     /**
@@ -392,6 +412,8 @@ declare class WikiMemory {
     private _isAnyMaintenanceActiveWithSuffix;
     /** Returns true if any ingest job is active for the given entity. */
     private _isIngestActiveFor;
+    private _copyEntityStatus;
+    private _notifyStatusSubscribers;
     private _validatePruneDuration;
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
@@ -445,6 +467,17 @@ declare class WikiMemory {
         failed: number;
     }>;
     getEntityStatus(entityId: string): EntityStatus;
+    /**
+     * Subscribe to {@link EntityStatus} changes for a single entity. The callback
+     * is invoked synchronously once with the current status before this method
+     * returns, then again on every transition where any of `ingesting`,
+     * `librarian`, or `heal` flips. No polling, no duplicate snapshots.
+     *
+     * Returns an idempotent unsubscribe function.
+     *
+     * See also {@link getEntityStatus} for a synchronous point-in-time read.
+     */
+    subscribeEntityStatus(entityId: string, callback: (status: EntityStatus) => void): () => void;
     clearVectorCache(): void;
     private _getFullBundle;
     exportDump(entityIds?: string[]): Promise<MemoryDump>;

package/dist/index.js

@@ -418,6 +418,7 @@ var _WikiMemory = class _WikiMemory {
   constructor(db, options) {
     this.activeMaintenanceJobs = /* @__PURE__ */ new Set();
     this.activeIngestJobs = /* @__PURE__ */ new Set();
+    this.statusSubscribers = /* @__PURE__ */ new Map();
     this.miniSearch = new MiniSearch__default.default({
       fields: ["title", "body", "tags"],
       storeFields: ["entity_id"],
@@ -822,6 +823,24 @@ After running the migration SQL, restart your application.`
     }
     return false;
   }
+  _copyEntityStatus(s) {
+    return { ingesting: s.ingesting, librarian: s.librarian, heal: s.heal };
+  }
+  _notifyStatusSubscribers(entityId) {
+    const set = this.statusSubscribers.get(entityId);
+    if (!set || set.size === 0) return;
+    for (const entry of Array.from(set)) {
+      if (!set.has(entry)) continue;
+      const next = this.getEntityStatus(entityId);
+      if (entry.last.ingesting === next.ingesting && entry.last.librarian === next.librarian && entry.last.heal === next.heal) continue;
+      entry.last = this._copyEntityStatus(next);
+      try {
+        entry.callback(this._copyEntityStatus(next));
+      } catch (err) {
+        console.error(`[WikiMemory.subscribeEntityStatus] callback error for entityId="${entityId}" during transition emission`, err);
+      }
+    }
+  }
   _validatePruneDuration(value, name) {
     if (value !== null && value !== void 0 && (typeof value !== "number" || !isFinite(value) || value < 0)) {
       throw new Error(`Invalid ${name}: must be a non-negative finite number or null`);
@@ -1564,7 +1583,11 @@ After running the migration SQL, restart your application.`
       const jobKey = this._librarianKey(entityId);
       if (!this.activeMaintenanceJobs.has(jobKey) && !this.activeMaintenanceJobs.has(this._pruneKey(entityId)) && !this._isReembedActive(entityId) && !this._isImportActiveFor(entityId) && !this._isForgetActiveFor(entityId)) {
         this.activeMaintenanceJobs.add(jobKey);
-        this.runLibrarianThenMaybeHeal(entityId, count).catch(console.error).finally(() => this.activeMaintenanceJobs.delete(jobKey));
+        this._notifyStatusSubscribers(entityId);
+        this.runLibrarianThenMaybeHeal(entityId, count).catch(console.error).finally(() => {
+          this.activeMaintenanceJobs.delete(jobKey);
+          this._notifyStatusSubscribers(entityId);
+        });
       }
     }
   }
@@ -1583,6 +1606,7 @@ After running the migration SQL, restart your application.`
       const healKey = this._healKey(entityId);
       if (!this.activeMaintenanceJobs.has(healKey)) {
         this.activeMaintenanceJobs.add(healKey);
+        this._notifyStatusSubscribers(entityId);
         try {
           await this._doRunHeal(entityId);
           await this.db.runAsync(`
@@ -1592,6 +1616,7 @@ After running the migration SQL, restart your application.`
           `, [entityId, currentEventCount, currentEventCount]);
         } finally {
           this.activeMaintenanceJobs.delete(healKey);
+          this._notifyStatusSubscribers(entityId);
         }
       }
     }
@@ -1783,10 +1808,12 @@ The following document anchors are provided for contradiction detection only. Do
       throw new WikiBusyError("forget", entityId);
     }
     this.activeMaintenanceJobs.add(jobKey);
+    this._notifyStatusSubscribers(entityId);
     try {
       await this._doRunLibrarian(entityId);
     } finally {
       this.activeMaintenanceJobs.delete(jobKey);
+      this._notifyStatusSubscribers(entityId);
     }
   }
   async runHeal(entityId) {
@@ -1807,10 +1834,12 @@ The following document anchors are provided for contradiction detection only. Do
       throw new WikiBusyError("forget", entityId);
     }
     this.activeMaintenanceJobs.add(jobKey);
+    this._notifyStatusSubscribers(entityId);
     try {
       await this._doRunHeal(entityId);
     } finally {
       this.activeMaintenanceJobs.delete(jobKey);
+      this._notifyStatusSubscribers(entityId);
     }
   }
   async runReembed(entityId, opts) {
@@ -1950,6 +1979,40 @@ The following document anchors are provided for contradiction detection only. Do
       heal: this.activeMaintenanceJobs.has(this._healKey(entityId))
     };
   }
+  /**
+   * Subscribe to {@link EntityStatus} changes for a single entity. The callback
+   * is invoked synchronously once with the current status before this method
+   * returns, then again on every transition where any of `ingesting`,
+   * `librarian`, or `heal` flips. No polling, no duplicate snapshots.
+   *
+   * Returns an idempotent unsubscribe function.
+   *
+   * See also {@link getEntityStatus} for a synchronous point-in-time read.
+   */
+  subscribeEntityStatus(entityId, callback) {
+    const initial = this.getEntityStatus(entityId);
+    let set = this.statusSubscribers.get(entityId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.statusSubscribers.set(entityId, set);
+    }
+    const entry = { callback, last: this._copyEntityStatus(initial) };
+    set.add(entry);
+    try {
+      callback(this._copyEntityStatus(initial));
+    } catch (err) {
+      console.error(`[WikiMemory.subscribeEntityStatus] callback error for entityId="${entityId}" during initial emission`, err);
+    }
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const s = this.statusSubscribers.get(entityId);
+      if (!s) return;
+      s.delete(entry);
+      if (s.size === 0) this.statusSubscribers.delete(entityId);
+    };
+  }
   clearVectorCache() {
     this.vectorCache.clear();
   }
@@ -2475,6 +2538,7 @@ The following document anchors are provided for contradiction detection only. Do
       throw new WikiBusyError("forget", entityId);
     }
     this.activeIngestJobs.add(jobKey);
+    this._notifyStatusSubscribers(entityId);
     try {
       const { chunks, truncated } = chunkText(params.documentChunk, maxChunkLength, chunkOverlap);
       if (chunks.length === 0) {
@@ -2546,6 +2610,7 @@ ${chunk}`;
       return { truncated, chunks: chunks.length };
     } finally {
       this.activeIngestJobs.delete(jobKey);
+      this._notifyStatusSubscribers(entityId);
     }
   }
 };