@equationalapplications/core-llm-wiki 3.2.0 → 4.0.0

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;
@@ -358,6 +366,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.
@@ -470,6 +481,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;
@@ -358,6 +366,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.
@@ -470,6 +481,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,
@@ -593,6 +593,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 +732,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
@@ -830,7 +871,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 +891,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 +899,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 +937,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;
@@ -1597,7 +1638,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 +1653,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 +1686,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 +1747,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) });
       }
     });
@@ -2006,6 +2047,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 +2101,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 +2153,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 +2170,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 });
@@ -2478,7 +2524,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) });
         }
@@ -2743,5 +2789,6 @@ exports.WikiMemory = WikiMemory;
 exports.createWiki = createWiki;
 exports.formatContext = formatContext;
 exports.formatMemoryDump = formatMemoryDump;
+exports.parseEmbedding = parseEmbedding;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map