@equationalapplications/core-llm-wiki 3.2.0 → 4.1.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

@@ -60,7 +60,15 @@ interface WikiFact {
     body: string;
     tags: string[];
     confidence: 'certain' | 'inferred' | 'tentative';
-    source_type: 'user_stated' | 'agent_inferred' | 'user_confirmed' | 'user_document';
+    /**
+     * Source type of this fact.
+     * - 'immutable_document': From ingestDocument(), cannot be modified by system (librarian/heal).
+     *   Only removable via forget() or replaced via re-ingest.
+     * - 'librarian_inferred': Created by runLibrarian() from events, or by runHeal() when synthesizing new inferred facts.
+     * - 'user_stated': Direct user statement.
+     * - 'user_confirmed': User-confirmed fact.
+     */
+    source_type: 'user_stated' | 'librarian_inferred' | 'user_confirmed' | 'immutable_document';
     source_hash: string | null;
     source_ref: string | null;
     created_at: number;
@@ -329,6 +337,7 @@ declare class WikiMemory {
     private options;
     private activeMaintenanceJobs;
     private activeIngestJobs;
+    private statusSubscribers;
     private miniSearch;
     private miniSearchEntryIdsByEntity;
     /**
@@ -358,6 +367,9 @@ declare class WikiMemory {
     private _librarianKey;
     private _healKey;
     private _warnCrossEntityCollision;
+    /** Maps pre-rename enum strings from older dumps to current source_type values. */
+    private _normalizeImportedSourceType;
+    private assertNoLegacySourceTypes;
     private _notifyEmbeddingPersisted;
     /**
      * GDPR-critical variant: awaits the hook with a timeout and rethrows failures.
@@ -381,6 +393,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;
@@ -434,6 +448,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>;
@@ -470,6 +495,8 @@ declare function formatContext(bundle: MemoryBundle, options?: FormatContextOpti
 
 declare function formatMemoryDump(dump: MemoryDump): FormattedMemoryDump;
 
+declare function parseEmbedding(blob: Uint8Array | null | undefined, text: string | null | undefined): Float32Array | null;
+
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { type EntityStatus, type ExtractedFact, type ExtractedTask, type FormatContextOptions, type FormattedMemoryDump, type LLMProvider, type MemoryBundle, type MemoryDump, PrunePartialFailureError, type ReadOptions, type SQLiteAdapter, type VectorRanker, type VectorRankerFallback, type VectorRankerRankArgs, type VectorRankerSemanticResult, WikiBusyError, type WikiBusyOperation, type WikiCheckpoint, type WikiConfig, type WikiEvent, type WikiFact, WikiMemory, type WikiOptions, type WikiTask, createWiki, formatContext, formatMemoryDump };
+export { type EntityStatus, type ExtractedFact, type ExtractedTask, type FormatContextOptions, type FormattedMemoryDump, type LLMProvider, type MemoryBundle, type MemoryDump, PrunePartialFailureError, type ReadOptions, type SQLiteAdapter, type VectorRanker, type VectorRankerFallback, type VectorRankerRankArgs, type VectorRankerSemanticResult, WikiBusyError, type WikiBusyOperation, type WikiCheckpoint, type WikiConfig, type WikiEvent, type WikiFact, WikiMemory, type WikiOptions, type WikiTask, createWiki, formatContext, formatMemoryDump, parseEmbedding };

package/dist/index.d.ts

@@ -60,7 +60,15 @@ interface WikiFact {
     body: string;
     tags: string[];
     confidence: 'certain' | 'inferred' | 'tentative';
-    source_type: 'user_stated' | 'agent_inferred' | 'user_confirmed' | 'user_document';
+    /**
+     * Source type of this fact.
+     * - 'immutable_document': From ingestDocument(), cannot be modified by system (librarian/heal).
+     *   Only removable via forget() or replaced via re-ingest.
+     * - 'librarian_inferred': Created by runLibrarian() from events, or by runHeal() when synthesizing new inferred facts.
+     * - 'user_stated': Direct user statement.
+     * - 'user_confirmed': User-confirmed fact.
+     */
+    source_type: 'user_stated' | 'librarian_inferred' | 'user_confirmed' | 'immutable_document';
     source_hash: string | null;
     source_ref: string | null;
     created_at: number;
@@ -329,6 +337,7 @@ declare class WikiMemory {
     private options;
     private activeMaintenanceJobs;
     private activeIngestJobs;
+    private statusSubscribers;
     private miniSearch;
     private miniSearchEntryIdsByEntity;
     /**
@@ -358,6 +367,9 @@ declare class WikiMemory {
     private _librarianKey;
     private _healKey;
     private _warnCrossEntityCollision;
+    /** Maps pre-rename enum strings from older dumps to current source_type values. */
+    private _normalizeImportedSourceType;
+    private assertNoLegacySourceTypes;
     private _notifyEmbeddingPersisted;
     /**
      * GDPR-critical variant: awaits the hook with a timeout and rethrows failures.
@@ -381,6 +393,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;
@@ -434,6 +448,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>;
@@ -470,6 +495,8 @@ declare function formatContext(bundle: MemoryBundle, options?: FormatContextOpti
 
 declare function formatMemoryDump(dump: MemoryDump): FormattedMemoryDump;
 
+declare function parseEmbedding(blob: Uint8Array | null | undefined, text: string | null | undefined): Float32Array | null;
+
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { type EntityStatus, type ExtractedFact, type ExtractedTask, type FormatContextOptions, type FormattedMemoryDump, type LLMProvider, type MemoryBundle, type MemoryDump, PrunePartialFailureError, type ReadOptions, type SQLiteAdapter, type VectorRanker, type VectorRankerFallback, type VectorRankerRankArgs, type VectorRankerSemanticResult, WikiBusyError, type WikiBusyOperation, type WikiCheckpoint, type WikiConfig, type WikiEvent, type WikiFact, WikiMemory, type WikiOptions, type WikiTask, createWiki, formatContext, formatMemoryDump };
+export { type EntityStatus, type ExtractedFact, type ExtractedTask, type FormatContextOptions, type FormattedMemoryDump, type LLMProvider, type MemoryBundle, type MemoryDump, PrunePartialFailureError, type ReadOptions, type SQLiteAdapter, type VectorRanker, type VectorRankerFallback, type VectorRankerRankArgs, type VectorRankerSemanticResult, WikiBusyError, type WikiBusyOperation, type WikiCheckpoint, type WikiConfig, type WikiEvent, type WikiFact, WikiMemory, type WikiOptions, type WikiTask, createWiki, formatContext, formatMemoryDump, parseEmbedding };

package/dist/index.js

@@ -16,7 +16,7 @@ async function setupDatabase(db, prefix) {
       body TEXT NOT NULL,
       tags TEXT NOT NULL DEFAULT '[]',
       confidence TEXT NOT NULL DEFAULT 'inferred',
-      source_type TEXT NOT NULL DEFAULT 'agent_inferred',
+      source_type TEXT NOT NULL DEFAULT 'librarian_inferred',
       source_hash TEXT,
       source_ref TEXT,
       created_at INTEGER NOT NULL,
@@ -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"],
@@ -593,6 +594,44 @@ var _WikiMemory = class _WikiMemory {
   _warnCrossEntityCollision(type, id, existingEntityId, targetEntityId) {
     console.warn(`[WikiMemory] importDump: ${type} id "${id}" already belongs to entity "${existingEntityId}"; skipping for entity "${targetEntityId}"`);
   }
+  /** Maps pre-rename enum strings from older dumps to current source_type values. */
+  _normalizeImportedSourceType(raw, ctx) {
+    if (raw === "user_document") return "immutable_document";
+    if (raw === "agent_inferred") return "librarian_inferred";
+    const allowed = ["user_stated", "librarian_inferred", "user_confirmed", "immutable_document"];
+    if (allowed.includes(raw)) return raw;
+    const where = ctx !== void 0 ? ` for entity "${ctx.entityId}" fact "${ctx.factId}"` : "";
+    throw new Error(
+      `importDump: invalid source_type "${raw}"${where} (expected one of: ${allowed.join(", ")}, or legacy aliases user_document / agent_inferred)`
+    );
+  }
+  async assertNoLegacySourceTypes() {
+    const legacyProbe = await this.db.getFirstAsync(
+      `SELECT 1 AS one FROM ${this.prefix}entries
+       WHERE source_type IN ('user_document', 'agent_inferred')
+       LIMIT 1`,
+      []
+    );
+    if (!legacyProbe) return;
+    const legacyCount = await this.db.getFirstAsync(
+      `SELECT COUNT(*) as count FROM ${this.prefix}entries
+       WHERE source_type IN ('user_document', 'agent_inferred')`,
+      []
+    );
+    const count = legacyCount?.count ?? 0;
+    const migrationSQL = `
+-- Migrate legacy source_type values (targets your WikiMemory prefix: ${this.prefix})
+UPDATE ${this.prefix}entries SET source_type = 'immutable_document' WHERE source_type = 'user_document';
+UPDATE ${this.prefix}entries SET source_type = 'librarian_inferred' WHERE source_type = 'agent_inferred';
+    `.trim();
+    throw new Error(
+      `Database contains ${count} entries with legacy source_type values ('user_document' or 'agent_inferred'). These enum values were renamed in this release. Running without migration would allow legacy 'user_document' facts to bypass immutability guards, causing data corruption.
+
+${migrationSQL}
+
+After running the migration SQL, restart your application.`
+    );
+  }
   async _notifyEmbeddingPersisted(entityId, factId, vector) {
     if (!this.options.vectorRanker?.onEmbeddingPersisted) return;
     const vectorCopy = vector ? vector.slice() : null;
@@ -694,6 +733,9 @@ var _WikiMemory = class _WikiMemory {
         );
       }
     }
+    if (entriesExistedBeforeSetup) {
+      await this.assertNoLegacySourceTypes();
+    }
     const rows = await this.db.getAllAsync(`
       SELECT rowid, source_ref FROM ${this.prefix}entries
       WHERE source_ref IS NOT NULL
@@ -781,6 +823,24 @@ var _WikiMemory = class _WikiMemory {
     }
     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`);
@@ -830,7 +890,7 @@ var _WikiMemory = class _WikiMemory {
         const cutoff = now - retainSoftDeletedFor * 864e5;
         const entriesToDelete = await this.db.getAllAsync(
           `SELECT id, entity_id FROM ${this.prefix}entries
-           WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at < ?`,
+           WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at <= ?`,
           [entityId, cutoff]
         );
         const succeeded = [];
@@ -850,7 +910,7 @@ var _WikiMemory = class _WikiMemory {
             const chunk = succeeded.slice(i, i + chunkSize);
             const placeholders = chunk.map(() => "?").join(",");
             const entryResult = await this.db.runAsync(
-              `DELETE FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at < ? AND id IN (${placeholders})`,
+              `DELETE FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at <= ? AND id IN (${placeholders})`,
               [entityId, cutoff, ...chunk.map((r) => r.id)]
             );
             deletedEntries += entryResult.changes;
@@ -858,7 +918,7 @@ var _WikiMemory = class _WikiMemory {
         }
         const taskResult = await this.db.runAsync(
           `DELETE FROM ${this.prefix}tasks
-           WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at < ?`,
+           WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at <= ?`,
           [entityId, cutoff]
         );
         deletedTasks = taskResult.changes;
@@ -896,7 +956,7 @@ var _WikiMemory = class _WikiMemory {
         const cutoff = now - retainEventsFor * 864e5;
         const eventResult = await this.db.runAsync(
           `DELETE FROM ${this.prefix}events
-           WHERE entity_id = ? AND created_at < ?`,
+           WHERE entity_id = ? AND created_at <= ?`,
           [entityId, cutoff]
         );
         deletedEvents = eventResult.changes;
@@ -1523,7 +1583,11 @@ var _WikiMemory = class _WikiMemory {
       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);
+        });
       }
     }
   }
@@ -1542,6 +1606,7 @@ var _WikiMemory = class _WikiMemory {
       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(`
@@ -1551,6 +1616,7 @@ var _WikiMemory = class _WikiMemory {
           `, [entityId, currentEventCount, currentEventCount]);
         } finally {
           this.activeMaintenanceJobs.delete(healKey);
+          this._notifyStatusSubscribers(entityId);
         }
       }
     }
@@ -1597,7 +1663,7 @@ ${JSON.stringify(currentFacts, null, 2)}`;
         let skip = false;
         if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
           for (const existing of currentFactsRows) {
-            if (existing.source_type !== "agent_inferred") continue;
+            if (existing.source_type !== "librarian_inferred") continue;
             const existingTokens = titleTokens(existing.title);
             if (existingTokens.size >= MIN_TOKENS_TO_QUALIFY) {
               if (jaccardScore(newTokens, existingTokens) >= FUZZY_THRESHOLD) {
@@ -1612,7 +1678,7 @@ ${JSON.stringify(currentFacts, null, 2)}`;
         await this.db.runAsync(`
           INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, created_at, updated_at)
           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-        `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "agent_inferred", now, now]);
+        `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "librarian_inferred", now, now]);
         insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
       }
       for (const task of validTasks) {
@@ -1645,25 +1711,25 @@ ${JSON.stringify(currentFacts, null, 2)}`;
       if (orphanAfterDays !== null) {
         const orphanThreshold = now - orphanAfterDays * MS_PER_DAY;
         await this.db.runAsync(`
-          UPDATE ${this.prefix}entries 
-          SET deleted_at = ?, updated_at = ? 
-          WHERE entity_id = ? AND access_count = 0 AND created_at < ? AND source_type != 'user_document' AND deleted_at IS NULL
+          UPDATE ${this.prefix}entries
+          SET deleted_at = ?, updated_at = ?
+          WHERE entity_id = ? AND access_count = 0 AND created_at <= ? AND source_type != 'immutable_document' AND deleted_at IS NULL
         `, [now, now, entityId, orphanThreshold]);
       }
       if (staleInferredAfterDays !== null) {
         const staleThreshold = now - staleInferredAfterDays * MS_PER_DAY;
         await this.db.runAsync(`
-          UPDATE ${this.prefix}entries 
-          SET confidence = 'tentative', updated_at = ? 
-          WHERE entity_id = ? AND confidence = 'inferred' AND (last_accessed_at < ? OR (last_accessed_at IS NULL AND created_at < ?)) AND source_type != 'user_document' AND deleted_at IS NULL
+          UPDATE ${this.prefix}entries
+          SET confidence = 'tentative', updated_at = ?
+          WHERE entity_id = ? AND confidence = 'inferred' AND (last_accessed_at <= ? OR (last_accessed_at IS NULL AND created_at <= ?)) AND source_type != 'immutable_document' AND deleted_at IS NULL
         `, [now, entityId, staleThreshold, staleThreshold]);
       }
     });
     const allFactsRows = await this.db.getAllAsync(`SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`, [entityId]);
     const allTasks = await this.db.getAllAsync(`SELECT * FROM ${this.prefix}tasks WHERE entity_id = ? AND status IN ('pending', 'in_progress') AND deleted_at IS NULL`, [entityId]);
     const recentEvents = await this.db.getAllAsync(`SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at DESC LIMIT 20`, [entityId]);
-    const healCandidates = allFactsRows.filter((f) => f.source_type !== "user_document");
-    const documentAnchors = allFactsRows.filter((f) => f.source_type === "user_document").map(({ id, title, source_ref }) => ({ id, title, source_ref }));
+    const healCandidates = allFactsRows.filter((f) => f.source_type !== "immutable_document");
+    const documentAnchors = allFactsRows.filter((f) => f.source_type === "immutable_document").map(({ id, title, source_ref }) => ({ id, title, source_ref }));
     const userPrompt = `Heal Candidates:
 ${JSON.stringify(healCandidates.map((f) => {
       const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
@@ -1706,7 +1772,7 @@ The following document anchors are provided for contradiction detection only. Do
         await this.db.runAsync(`
           INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, created_at, updated_at)
           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-        `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "agent_inferred", now, now]);
+        `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "librarian_inferred", now, now]);
         insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
       }
     });
@@ -1742,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) {
@@ -1766,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) {
@@ -1909,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();
   }
@@ -2006,6 +2110,7 @@ The following document anchors are provided for contradiction detection only. Do
       this.activeMaintenanceJobs.add(this._importKey(entityId));
     }
     try {
+      await this.assertNoLegacySourceTypes();
       for (const [entityId, bundle] of Object.entries(dump.entities)) {
         await this._doImportEntity(entityId, bundle, merge);
       }
@@ -2059,6 +2164,10 @@ The following document anchors are provided for contradiction detection only. Do
         }
       }
       for (const fact of bundle.facts) {
+        const sourceType = this._normalizeImportedSourceType(String(fact.source_type), {
+          entityId,
+          factId: fact.id
+        });
         const tagsJson = JSON.stringify(Array.isArray(fact.tags) ? fact.tags : []);
         const safeUpdatedAt = Number.isFinite(fact.updated_at) ? fact.updated_at : 0;
         const existing = existingFactsById.get(fact.id);
@@ -2107,14 +2216,14 @@ The following document anchors are provided for contradiction detection only. Do
           if (blobData != null) {
             await this.db.runAsync(
               `UPDATE ${this.prefix}entries SET entity_id = ?, title = ?, body = ?, tags = ?, confidence = ?, source_type = ?, source_hash = ?, source_ref = ?, created_at = ?, updated_at = ?, last_accessed_at = ?, access_count = ?, deleted_at = ?, embedding_blob = ?, embedding = NULL WHERE id = ?`,
-              [entityId, fact.title, fact.body, tagsJson, fact.confidence, fact.source_type, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, blobData, fact.id]
+              [entityId, fact.title, fact.body, tagsJson, fact.confidence, sourceType, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, blobData, fact.id]
             );
             factsWithPreservedBlob.set(fact.id, blobData);
             if (!fact.deleted_at) preservedBlobDims.add(blobData.byteLength / 4);
           } else {
             await this.db.runAsync(
               `UPDATE ${this.prefix}entries SET entity_id = ?, title = ?, body = ?, tags = ?, confidence = ?, source_type = ?, source_hash = ?, source_ref = ?, created_at = ?, updated_at = ?, last_accessed_at = ?, access_count = ?, deleted_at = ?, embedding_blob = NULL, embedding = NULL WHERE id = ?`,
-              [entityId, fact.title, fact.body, tagsJson, fact.confidence, fact.source_type, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, fact.id]
+              [entityId, fact.title, fact.body, tagsJson, fact.confidence, sourceType, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, fact.id]
             );
           }
           existingFactsById.set(fact.id, { id: fact.id, entity_id: entityId, updated_at: safeUpdatedAt });
@@ -2124,14 +2233,14 @@ The following document anchors are provided for contradiction detection only. Do
           if (blobData != null) {
             await this.db.runAsync(
               `INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, source_hash, source_ref, created_at, updated_at, last_accessed_at, access_count, deleted_at, embedding_blob) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-              [fact.id, entityId, fact.title, fact.body, tagsJson, fact.confidence, fact.source_type, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, blobData]
+              [fact.id, entityId, fact.title, fact.body, tagsJson, fact.confidence, sourceType, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, blobData]
             );
             factsWithPreservedBlob.set(fact.id, blobData);
             if (!fact.deleted_at) preservedBlobDims.add(blobData.byteLength / 4);
           } else {
             await this.db.runAsync(
               `INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, source_hash, source_ref, created_at, updated_at, last_accessed_at, access_count, deleted_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-              [fact.id, entityId, fact.title, fact.body, tagsJson, fact.confidence, fact.source_type, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at]
+              [fact.id, entityId, fact.title, fact.body, tagsJson, fact.confidence, sourceType, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at]
             );
           }
           existingFactsById.set(fact.id, { id: fact.id, entity_id: entityId, updated_at: safeUpdatedAt });
@@ -2429,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) {
@@ -2478,7 +2588,7 @@ ${chunk}`;
           await this.db.runAsync(
             `INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, source_hash, source_ref, created_at, updated_at)
            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-            [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "user_document", sourceHash, sourceRef, now, now]
+            [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "immutable_document", sourceHash, sourceRef, now, now]
           );
           insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
         }
@@ -2500,6 +2610,7 @@ ${chunk}`;
       return { truncated, chunks: chunks.length };
     } finally {
       this.activeIngestJobs.delete(jobKey);
+      this._notifyStatusSubscribers(entityId);
     }
   }
 };
@@ -2743,5 +2854,6 @@ exports.WikiMemory = WikiMemory;
 exports.createWiki = createWiki;
 exports.formatContext = formatContext;
 exports.formatMemoryDump = formatMemoryDump;
+exports.parseEmbedding = parseEmbedding;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map